Developers

A first request in a minute.

The public sandbox key works on every endpoint with synthetic data, and every endpoint has a sample request to send. No sign-up. Live keys for real data are issued under agreement.

First request

Download the published sample for /v1/analyze (physiological, facial and clinical-context inputs with 24 baseline sessions, all synthetic) and send it back with the sandbox key. Or press the button and the browser does it for you.

# The published sample request (synthetic, no real person's data)
curl -s https://www.medera.info/api/v1/samples/analyze -o analyze.json

curl -s https://www.medera.info/api/v1/analyze \
  -H "Authorization: Bearer mk_sandbox_medera_public" \
  -H "Content-Type: application/json" \
  --data @analyze.json
POST/v1/analyze
Sample request

Sends the synthetic sample to the live sandbox with the public key and shows the full response. Nothing personal is sent and nothing is stored.

Authentication

Send a key as a bearer token on every POST. Catalog and service endpoints need no key.

Sandbox
Authorization: Bearer mk_sandbox_medera_public
  • Sandbox. mk_sandbox_medera_public is public and shared. Use it with synthetic data only; never send real personal data or PHI with it.
  • Live. Keys look like mk_live_… and are issued per organization under agreement, with a BAA. We store only a SHA-256 fingerprint of each key, so a lost key is replaced, not recovered. Request a live key.
  • Keep live keys on your servers. The API allows cross-origin calls so the sandbox works from a browser; a live key in a browser, a mobile app or a repository is a leaked key.

Responses

Every successful response is JSON with the same envelope. mode says which kind of key was used, engine pins the exact algorithm versions behind the numbers, and intended_use travels with every result.

The envelope (abridged)
{
  "object": "physiological.analysis",
  "id": "pa_…",
  "created": "2026-11-17T09:30:00.000Z",
  "api_version": "v1",
  "mode": "sandbox",
  "engine": { "name": "medera-inference", "version": "1.0.0", "vocal": "…" },
  "intended_use": "Measured biomarkers and within-person change for research and clinician review. Not a diagnosis and not a medical device.",
  "biomarkers": { "rmssdMs": 34.15, "lfPowerMs2": null, … },
  "quality": { … }
}

Field names are snake_case. Biomarker keys are the one exception: they are stable camelCase identifiers that carry their unit where they have one, such as f0MedianHz or rmssdMs, and they match the catalog, where each one has its unit, method, gate and references. The same entries are served at GET /v1/biomarkers.

Nulls and quality flags

A null value is an answer, not an error: the input could not support that measure, and quality.flags says why (for example too_short_for_voice_quality, too_short_for_lf or rates_and_language_require_transcript). The engine never estimates a gated value, and the inference engine simply leaves it out.

Endpoints

EndpointTakesReturns
POST /v1/vocal/analyzeWAV audio, multipart or rawVocal panel per speaker
POST /v1/physiological/analyzeRR or PPG, EDA, sleep, activity (JSON)HRV, EDA, sleep and rhythm
POST /v1/facial/analyzeBlendshape frames (JSON)Expression, gaze, blinks, head motion
POST /v1/clinical-context/analyzeInstruments, transcript, codes (JSON)Scores, bands, language, safety
POST /v1/inferenceBiomarkers, baseline, instruments, settingChange, tiers, probabilities, safety
POST /v1/analyzeAny of the above in one callEvery modality plus inference
GET /v1/samples/{kind}NothingA ready-to-send sample request
GET /v1/biomarkersOptional ?modality=The catalog

Every field, type and constraint is in the API reference and the OpenAPI document.

Limits

LimitSandboxLive
Requests per minute30600
Request body2 MB4 MB
Audio per request30 s120 s
RR intervals5,00050,000
Face frames3,60020,000
Samples per series (PPG, EDA, sleep epochs)120,0001,000,000
Baseline sessions60400

The sandbox limit applies per address; live limits apply per key. Over the limit, the API answers 429 with Retry-After. Enterprise limits are set by agreement.

Headers

  • X-Request-Id on every response. Send your own (8 to 128 letters, digits, dots, dashes or underscores) to trace a call end to end; otherwise one is generated.
  • RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset report your current window; a 429 adds Retry-After.
  • Medera-Mode: sandbox or live. Server-Timing reports the time spent in the engine.
  • Cache-Control: no-store on everything, so no proxy keeps a result.

Errors

Errors are RFC 9457 problem details with a stable code, a human detail, the request ID and, for validation errors, the exact path of every invalid field.

A validation error
HTTP/1.1 422 Unprocessable Content
Content-Type: application/problem+json; charset=utf-8
X-Request-Id: req_…

{
  "type": "https://www.medera.info/developers/errors#validation_failed",
  "title": "Validation failed",
  "status": 422,
  "code": "validation_failed",
  "detail": "An instrument response is invalid.",
  "request_id": "req_…",
  "errors": [{ "path": "instruments.phq9.items", "message": "…" }]
}

Every error code has its own anchor; the type URL points to it.

Versioning

Everything lives under /v1. Within a version, changes are additive: new endpoints, new optional fields, new biomarker keys. A change that would alter an existing value or field ships as a new version. The engine object in each response names the algorithm versions, currently medera-inference 1.0.0, so a result can always be traced to the code that produced it.

Data handling

Request bodies are processed in memory and discarded when the response is sent. Nothing a caller sends is stored, and logs hold the method, path, status, latency and request ID only. Baselines are yours: send earlier sessions with each request, or summary statistics. Live use is covered by a Business Associate Agreement; see the Trust Center.

Measured biomarkers and within-person change for research and clinician review. Not a diagnosis and not a medical device. The base URL for every call is https://www.medera.info/api/v1.