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.jsonSends 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.
Authorization: Bearer mk_sandbox_medera_public- Sandbox.
mk_sandbox_medera_publicis 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.
{
"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
| Endpoint | Takes | Returns |
|---|---|---|
POST /v1/vocal/analyze | WAV audio, multipart or raw | Vocal panel per speaker |
POST /v1/physiological/analyze | RR or PPG, EDA, sleep, activity (JSON) | HRV, EDA, sleep and rhythm |
POST /v1/facial/analyze | Blendshape frames (JSON) | Expression, gaze, blinks, head motion |
POST /v1/clinical-context/analyze | Instruments, transcript, codes (JSON) | Scores, bands, language, safety |
POST /v1/inference | Biomarkers, baseline, instruments, setting | Change, tiers, probabilities, safety |
POST /v1/analyze | Any of the above in one call | Every modality plus inference |
GET /v1/samples/{kind} | Nothing | A ready-to-send sample request |
GET /v1/biomarkers | Optional ?modality= | The catalog |
Every field, type and constraint is in the API reference and the OpenAPI document.
Limits
| Limit | Sandbox | Live |
|---|---|---|
| Requests per minute | 30 | 600 |
| Request body | 2 MB | 4 MB |
| Audio per request | 30 s | 120 s |
| RR intervals | 5,000 | 50,000 |
| Face frames | 3,600 | 20,000 |
| Samples per series (PPG, EDA, sleep epochs) | 120,000 | 1,000,000 |
| Baseline sessions | 60 | 400 |
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-Idon 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-RemainingandRateLimit-Resetreport your current window; a 429 addsRetry-After.Medera-Mode:sandboxorlive.Server-Timingreports the time spent in the engine.Cache-Control: no-storeon 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.
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.