REST API Overview

Circadify REST API reference for contactless vital signs. Authenticate with API keys, create sessions, and retrieve heart rate, HRV, respiratory rate, and configured results.

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

text

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_live_your_key_here" \
  -H "Content-Type: application/json"

bash

API keys are the prefix ck_live_ (production) or ck_test_ (sandbox) followed by 40 lowercase hex characters.

Bearer Token Authentication (Developer endpoints)

Developer account endpoints (/developer/*) use a developer ID token in the Authorization header:

curl https://<developer-portal-api>/developer/profile \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

bash

These endpoints are not served at api.circadify.com — they belong to the separate developer-portal API that backs developer.circadify.com. See Developer Account Endpoints below.

Request Format

All request bodies must be JSON with Content-Type: application/json
Responses are flat JSON objects (no envelope wrapper)
Timestamps (e.g. expires_at, completed_at) are ISO-8601 date-time strings

Response Format

Successful responses return the relevant data directly:

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

json

Error responses return a structured error object:

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

json

CORS

CORS behavior differs by surface:

Vitals API (api.circadify.com, the /sdk/* endpoints) — cross-origin requests are allowed from any origin:

Allowed Origins: *
Allowed Methods: GET, HEAD, PUT, PATCH, POST, DELETE
Allowed Headers: reflected per-request (whatever headers the preflight asks for are allowed)
No Access-Control-Max-Age header is set

All vitals API endpoints respond to OPTIONS preflight requests.

Developer-portal API (/developer/*) — a strict origin allowlist (developer.circadify.com, plus localhost for development) with credentials mode. It is not callable from arbitrary origins; use the developer portal UI instead.

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 upload is complete and start processing
`GET`	`/sdk/session/{sessionId}/result`	Retrieve session results

Developer Account Endpoints

Caution

The /developer/* endpoints are not served at api.circadify.com — that host serves only the vitals API. They belong to the developer-portal API, the separate service used by the portal frontend at developer.circadify.com. Treat them as the portal's own API rather than a public integration surface, and manage your account, keys, and billing through developer.circadify.com.

Authenticated with Authorization: Bearer token (developer ID 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. Also served by the developer-portal API, not api.circadify.com.

Method	Path	Description
`POST`	`/developer/signup`	Register a new developer account
`POST`	`/developer/forgot-password`	Request a password reset email
`POST`	`/developer/redeem-reset-token`	Redeem a password setup/reset token

There is no login endpoint — sign-in happens client-side in the portal via Firebase Auth (POST /developer/auth/login exists only as a 410 Gone tombstone). GET /developer/verify is a Firebase-era stub that returns a static message; email verification is handled by Firebase Auth.

Next Steps

Sessions — Create and manage measurement sessions
Results — Retrieve and interpret vital signs
Errors — Handle error responses
Rate Limits — Understand usage limits
Python SDK — REST Client — Drive these endpoints from a typed Python client