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 follow the format ck_live_{hex}.

Bearer Token Authentication (Developer endpoints)

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

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

bash

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": { ... }
}

json

Error responses return a structured error object:

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

json

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 upload is complete and start processing
`GET`	`/sdk/session/{sessionId}/result`	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
Python SDK — REST Client — Drive these endpoints from a typed Python client