TeraRx API (1.0.0)

• Sandbox: the sandbox server answers every operation with the examples on this page. It checks that a token is present but not its signature, validates request bodies and stores nothing.
• Postman: import the collection and the sandbox environment. A pre-request script gets each caller its token.
• Guides and samples: quickstart, guides and Node and Python code for signing the patient assertion, verifying webhook signatures and enrolling a patient, on the docs site at docs.tera.health.

All paths start with the major version, /v1. Within a version, changes are additive only: new endpoints, new optional request fields, new response fields, new enum values and new event types. Build clients that ignore fields and values they do not know.

A breaking change means a new version (/v2), announced at least 6 months ahead. During that time the old version's responses carry Deprecation (RFC 9745) and Sunset (RFC 8594) headers with the dates, and both versions run side by side.

• JSON in and out (application/json; application/merge-patch+json for PATCH). UTF-8.
• Ids are UUID strings. Treat them as opaque.
• Timestamps are ISO 8601 in UTC (2026-10-26T14:05:00Z). Log dates (log_date) are calendar dates in the patient's time zone.
• Measurements are always metric (kg, cm, ml, g, kcal). units on the patient is a display preference only.
• Field names are snake_case. In responses, absent and null both mean "no value". In a PATCH (merge patch), null clears a field and an absent field is left unchanged.

Every response has an X-Request-Id header, errors included. Ours are req_ followed by a UUIDv7. Send your own X-Request-Id to have it echoed, which makes logs easy to join: a UUID, or req_ followed by up to 60 letters, digits, _ or -. Any other value is replaced with a new id. Quote it when you write to support@hellotera.com.

Every 4xx and 5xx response is RFC 9457 problem details (application/problem+json):

{
  "type": "about:blank",
  "title": "Unprocessable Content",
  "status": 422,
  "detail": "1 field is invalid.",
  "code": "validation_failed",
  "request_id": "req_019a3b2c-4d5e-7f60-8a1b-2c3d4e5f6a7b",
  "errors": [{ "pointer": "/patient/state_code", "code": "invalid_format", "detail": "Must be a two-letter USPS state code." }]
}

Branch on code, which is stable; title and detail may change. Errors never contain patient data: no names, no values you sent, no free text. A resource from another brand or another patient returns 404 exactly like one that does not exist.

Each operation lists the codes specific to it.

Every POST that creates something (answers 201) requires an Idempotency-Key header of 8 to 255 characters (a UUID is a good choice); without it the request is refused with 400 idempotency_key_missing. Most other POST actions accept one; each operation in the reference lists the header when it does.

• The same key and the same body within 24 hours returns the first response, with Idempotent-Replayed: true, and creates nothing new.
• The same key with a different body is refused with 422 idempotency_key_reused.
• While the first request with a key is still running, a second one gets 409 idempotency_key_in_use; retry shortly.

Keys are scoped to the caller: your client, or the patient for patient tokens. Logs your server sends also carry your own external_id, which dedupes them permanently.

Lists that can grow are cursor-paginated: ?limit= (1 to 100, default 25) and ?cursor=. The response is { "data": [...], "next_cursor": "..." }; pass next_cursor back as cursor until it is null. Cursors are opaque and expire after 24 hours. Short, bounded lists return { "data": [...] } without a cursor.

Limits are per client (600 requests per minute by default, set per contract), per brand for a platform partner's client (each brand under it has its own limit), and per patient for patient tokens. Every response carries:

Over the limit you get 429 with Retry-After in seconds. The AI Coach also has a daily message cap per patient, set on the brand's plan (429 daily_message_cap_reached).

Patient endpoints say which plans they work on (the x-plans extension, and "Plans" at the end of each description). ai_health_fitness is the coached plan; ai_only has the AI Coach and no coaches, and its escalations go to the brand's prescriber as clinical flags. Calling a coached-plan endpoint for an ai_only patient returns 403 plan_not_eligible.

• A patient's records belong to one brand. Nothing is shared, matched or merged across brands.
• Brand servers read status and ids, never clinical content. Reports are aggregates with groups under 10 patients suppressed.
• Webhooks carry ids and the minimum needed to route (status, stage, severity, risk level), never message, form or protocol text. Fetch content through the API.
• Files are uploaded and downloaded through short-lived pre-signed URLs. Never store those URLs.
• Every read or change of a coaching record is audit-logged.

Coaching is not emergency care. Wherever a patient can type (care messages, the AI Coach, symptom logging), show this guidance: in an emergency call 911; in a mental health crisis call or text 988. When a symptom log comes back with is_red_flag: true, or an AI Coach reply with show_emergency_guidance: true, show it before anything else.

Each environment has its own clients, keys and webhook secret.

Three kinds of caller use this API, each with its own token. The tokens are not interchangeable: a brand-server token cannot call patient endpoints, and a patient token cannot call brand-server or clinical endpoints. Coaches use the TeraRx portal, which is not part of this contract.

Each operation lists the scheme and the scope it needs. All tokens go in Authorization: Bearer <token>.

A platform partner that hosts several brands holds one client for all of them and names the brand on every token request, so each token is still for one brand. See Platform partners.

TeraRx issues one OAuth client per brand and environment (integration, production). The secret is shown once; TeraRx keeps only its hash. Keep it on your server, never in an app. The integration client works against the sandbox only; the production API answers it with unauthorized_client.

POST /v1/oauth/token
Authorization: Basic base64(client_id:client_secret)
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&scope=enrollments:read%20enrollments:write%20logs:write

A brand server reads status and ids only. It never reads clinical content: messages, form answers, protocol text and log values stay with the patient and the care team.

There are no patient passwords in the API. Your server vouches for the patient by signing a short-lived JWT with your own private key; TeraRx checks it against the public keys you registered (a JWKS URL or a JWKS document) and returns a patient token. TeraRx never holds a key that can mint patient sessions, and you can rotate keys yourself by publishing a new key in your JWKS.

1. Your app signs the patient in with your own login.
2. Your server signs a patient assertion (below) and hands it to the app.
3. The app (or your server) exchanges it:

POST /v1/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:token-exchange
&subject_token=<assertion>
&subject_token_type=urn:ietf:params:oauth:token-type:jwt

4. The response's access_token is valid for 15 minutes for that one patient and enrollment. There is no refresh token: sign a new assertion when it expires.

Patient assertion

A JWT (RFC 7519) signed with ES256, RS256 or EdDSA. The header names the key with kid, which must be in your registered JWKS.

TeraRx allows 30 seconds of clock skew on iat and exp. The assertion carries no names or health data.

If you registered a JWKS URL, TeraRx caches it for 10 minutes and fetches it again as soon as an assertion names a kid it has not seen (at most every 30 seconds). To rotate, publish the new key next to the old one, start signing with it, then remove the old one.

The 400 and 401 problems also carry the RFC 6749 error field (invalid_request, invalid_client, invalid_grant, unauthorized_client, unsupported_grant_type, invalid_scope, invalid_target) for OAuth libraries.

Your prescriber system gets its own OAuth client, separate from the brand server's, with clinical:read (read flags) and clinical:write (acknowledge and resolve). It authenticates with client credentials like a brand server.

A clinical client acts for many prescribers, so every clinical write names the individual in the request body:

{
  "on_behalf_of": { "npi": "1234567893", "prescriber_id": "dr-00417", "name": "Dr. Alex Morgan, NP" }
}

name is required, plus at least one of npi or prescriber_id. A write without on_behalf_of, or with an NPI whose check digit is wrong, is refused with 422 validation_failed and the field's pointer. TeraRx stores the prescriber and the client that sent it on the flag, shows the name to coaches, and records it in the audit log.

A platform partner hosts several telehealth brands and switches TeraRx on for them. The partner integrates once, with one set of credentials for all its brands. A brand that integrates directly keeps its own client and needs none of this.

Each brand stays its own tenant. Its patients, enrollments, logs and reports are separate from every other brand's, including brands under the same partner. Nothing is matched or shared across brands: a person enrolled with two of your brands is two patients.

TeraRx creates each brand at onboarding, with its plans, prices, retention and coaching rules, and gives you its tenant_id. You get:

Every token is for one brand. Name the brand with tenant_id when you ask for a token:

POST /v1/oauth/token
Authorization: Basic base64(client_id:client_secret)
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&tenant_id=a0000000-0000-4000-8000-000000000002&scope=enrollments:read%20enrollments:write

Keep one token per brand and reuse it for its hour. A call with brand A's token never sees brand B's patients; it answers 404 as if they did not exist.

tenant_not_permitted is the same answer for an unknown id and for another partner's brand. Rate limits count per brand: each brand has its own limit under your client, so one busy brand does not slow the others.

Sign every brand's assertions with the same key and issuer, and add a tenant_id claim naming the brand the patient is enrolled with:

{
  "iss": "https://partner.example.com",
  "sub": "brand-pt-48213",
  "aud": "https://sandbox.rx.tera.health",
  "tenant_id": "a0000000-0000-4000-8000-000000000002",
  "iat": 1793635200,
  "exp": 1793635500,
  "jti": "5f0c9a52-8a4e-4d4f-9a52-0f6e8b7c1d2e"
}

sub is the external_patient_id you sent on POST /v1/enrollments for that brand. Your ids may repeat across brands; TeraRx looks sub up within the brand named by tenant_id. An assertion without tenant_id is refused with assertion_invalid, one naming a brand you may not act for with tenant_not_permitted. Everything else is as in Authentication.

GET /v1/tenants (scope tenants:read) lists every brand under your partner account, whichever brand the token is for, with its id, slug, display_name and is_enabled (whether it is live), ordered by slug and paginated with limit and cursor. Use it to check your configuration against ours. You need one brand's tenant_id, from onboarding, to get the first token.

Events for all your brands go to your partner endpoint, signed with your secret, unless a brand has its own endpoint. Every event carries tenant_id: route on it. The payloads and signature are as in Webhooks.

GET /v1/reports/brand reports on the brand the token is for; ask once per brand. Under your agreement, TeraRx sends one monthly invoice for all your brands, with a section per brand.

A patient's enrollment in coaching with one brand. Brand servers create and manage them and read status only, never clinical content.