REST API Overview

The Circadify REST API provides programmatic access to vital signs measurement sessions, API key management, usage tracking, and account operations.

Base URL

https://api.circadify.com

All endpoints are served over HTTPS. There is no version prefix in the URL path.

Authentication

The API uses two authentication methods depending on the endpoint:

API Key Authentication (SDK endpoints)

SDK session endpoints use your API key passed via the X-API-Key header:

curl -X POST https://api.circadify.com/sdk/session/start \
  -H "X-API-Key: ck_test_your_key_here" \
  -H "Content-Type: application/json"

API keys follow the format ck_{environment}_{hex} where environment is test or live.

Bearer Token Authentication (Developer endpoints)

Developer account endpoints use a Firebase ID token in the Authorization header:

curl https://api.circadify.com/developer/profile \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

Request Format

• All request bodies must be JSON with Content-Type: application/json
• Responses are flat JSON objects (no envelope wrapper)
• Timestamps are Unix timestamps (seconds) unless noted otherwise

Response Format

Successful responses return the relevant data directly:

{
  "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "completed",
  "vitals": { ... }
}

Error responses return a structured error object:

{
  "error": "RATE_LIMIT_EXCEEDED",
  "message": "Rate limit exceeded",
  "retryable": true
}

CORS

The API supports cross-origin requests from any origin:

• Allowed Origins: *
• Allowed Methods: GET, POST, PUT, PATCH, DELETE, OPTIONS
• Allowed Headers: Content-Type, Authorization, X-API-Key
• Max Age: 86400 seconds (24 hours)

All endpoints respond to OPTIONS preflight requests.

Endpoint Reference

SDK Session Endpoints

Authenticated with X-API-Key header.

Method	Path	Description
POST	/sdk/session/start	Create a new measurement session
POST	/sdk/session/upload-complete	Notify that tensor upload is complete
GET	/sdk/session/result/{sessionId}	Retrieve session results

Developer Account Endpoints

Authenticated with Authorization: Bearer token.

Method	Path	Description
GET	/developer/profile	Get your developer profile
PATCH	/developer/profile	Update name or company
GET	/developer/keys	List your API keys
POST	/developer/keys	Create a new API key
DELETE	/developer/keys/{id}	Revoke an API key
GET	/developer/usage	Get current month usage
GET	/developer/usage/history	Get usage history (last 6 months)
POST	/developer/checkout	Create a Stripe checkout session
POST	/developer/billing-portal	Open Stripe billing portal

Public Endpoints

No authentication required.

Method	Path	Description
POST	/developer/signup	Register a new developer account
POST	/developer/login	Log in with email and password
POST	/developer/forgot-password	Request a password reset email
POST	/developer/reset-password	Reset password with token
GET	/developer/verify	Verify email address

Next Steps

• Sessions — Create and manage measurement sessions
• Results — Retrieve and interpret vital signs
• Errors — Handle error responses
• Rate Limits — Understand usage limits