API Reference

Base URL, authentication, limits, and the endpoint map.

Analyze calls are asynchronous: they return a job immediately. Read it from Jobs API or a webhook — Jobs, Polling, and Webhooks.

Base URL

https://api.amplifierhealth.com

Endpoints use the /v2 prefix — for example /v2/models/pulse/analyze.

Authentication

All requests require two headers.

Sign up at console.amplifierhealth.com, open the console, and create an API key: API Keys → Provide Name for Key → Create Key. Your account ID is shown in the console. See Quickstart for the full walkthrough.

curl -X GET "https://api.amplifierhealth.com/v2/account/credits" \
  -H "X-Account-ID: your-account-id" \
  -H "X-API-Key: your-api-key"

const response = await fetch("https://api.amplifierhealth.com/v2/account/credits", {
  headers: {
    "X-Account-ID": process.env.AMPLIFIER_ACCOUNT_ID,
    "X-API-Key": process.env.AMPLIFIER_API_KEY,
  },
});

const data = await response.json();

# Requires httpx: pip install httpx
import os
import httpx

response = httpx.get(
  "https://api.amplifierhealth.com/v2/account/credits",
  headers={
      "X-Account-ID": os.environ["AMPLIFIER_ACCOUNT_ID"],
      "X-API-Key": os.environ["AMPLIFIER_API_KEY"],
  },
)

data = response.json()

Request and response conventions

• All endpoints return JSON.
• Analyze endpoints accept Content-Type: multipart/form-data. JSON bodies: POST /v2/audio/uploads, Groups create/membership, and POST /v2/account/webhook. GET endpoints have no body.
• Analyze submit and GET /v2/jobs/{job_id} return HTTP 200 with a job object. POST /v2/groups returns 201 Created. Trajectory and aggregate GETs return a running / done envelope, not a job — see Longitudinal API.
• A job’s outcome is in status (queued, running, done, failed, timed-out), not only HTTP codes. See Jobs API.
• Field definitions: Response Schema. Enumerated values: Enumerations.
• Errors: HTTP status plus JSON code, message, and status. See Errors.

Model versions

Note The model_version parameter is available starting November 5, 2026.

A model version names the release of the analysis models that scores your audio. Versions are written X.Y.Z with digits only, for example 2.0.0. Two versions are available: 2.0.0 and 2.1.0. 2.0.0 is the default.

Pin a version

To pin a request (fix it to one version), send the optional model_version form field on an analyze call.

The value must be three numbers separated by dots. A v prefix (v2.0.0), two-part versions (2.0), and surrounding spaces are rejected.

The field is accepted on these analyze calls:

• POST /v2/models/{model_name}/analyze
• POST /v2/signs/{sign_name}/analyze
• The four group analyze calls: POST /v2/models/{model_name}/groups/{group_id}/analyze and POST /v2/signs/{sign_name}/groups/{group_id}/analyze, each also with the /longitudinal suffix. See Longitudinal API.

Read the version on a job

Every job response and webhook payload includes model_version: the version the job was submitted with. If you omitted the field, it holds the default version that ran. It is null for jobs created before model versions were introduced. See Response Schema.

Groups

A group’s model version is fixed when the group is created and never changes. Create a group with the optional model_version field on POST /v2/groups, or let the first analyze call into a new group_id create it: that call’s model_version, if sent, becomes the group’s version. If neither sends one, the group gets the current default version. Groups created before November 10, 2026 stay on 2.0.0.

On a group call, model_version is optional. Omitted means the group’s version. A different version returns 400 GROUP_VERSION_MISMATCH. Adding existing jobs with POST /v2/groups/{group_id}/jobs is rejected the same way if any listed job ran on a different version than the group. GET /v2/groups returns each group’s model_version.

Model version errors

All of these are 400 responses. They are not transient, so do not retry them unchanged. A rejected request creates no job.

Exact message text is on Errors.

Release 2.1.0

Note Release 2.1.0 is available now. Send model_version=2.1.0 on the single-audio analyze calls to use it. The default is still 2.0.0.

Results can differ between 2.0.0 and 2.1.0 for the same audio. From November 18, 2026, calls that send no model_version get 2.1.0. To stay on 2.0.0, send model_version=2.0.0 on every analyze call.

What changes in 2.1.0:

• Two new optional form fields for the speaker’s age and sex. Requests without them still work.
• No new use cases, conditions, models, or signs. The catalog is the same as in 2.0.0.
• No response field or enumeration value changes.

Speaker age and sex

Both fields are optional. Send either one, both, or neither. They are accepted on every analyze call:

• POST /v2/models/{model_name}/analyze
• POST /v2/signs/{sign_name}/analyze
• The four group analyze calls on the Longitudinal API.

They need model version 2.1.0 or later. A request that sends either field and runs 2.0.0 returns 400 and creates no job. For a group call, that means the group is on 2.0.0. Send model_version=2.1.0 with them on single-audio calls. provided_age and provided_sex work on groups pinned to 2.1.0 or later. A bad value returns 400 on any version. The codes are PARAM_REQUIRES_MODEL_VERSION, INVALID_PROVIDED_AGE, and INVALID_PROVIDED_SEX — see Errors.

Group calls follow the group’s version, so you do not need to send model_version with these fields. To use them in a group, create the group with model_version 2.1.0. Groups pinned to 2.0.0 reject them.

Compatibility

The parameter is additive. Requests that do not send model_version are unchanged. One case differs: if your client already sent a form field named model_version, the API ignored it before. It is now validated, so a value that is not an available version in X.Y.Z form returns 400.

Limits

For longer recordings, MP3 or FLAC typically keep file size under the 32 MB limit. See Audio Requirements for recording guidance.

Rate limits

The API enforces per-account rate limits using a sliding 60-second window. Limits vary by rate limit plan:

Upload / analyze endpoints: POST /v2/audio/uploads; POST /v2/models/{model_name}/analyze; POST /v2/signs/{sign_name}/analyze; the four group-aware analyze routes on the Longitudinal API (.../analyze and .../analyze/longitudinal for models and signs).

Job status polling: GET /v2/jobs/{job_id} has its own limit, sized for the recommended 2–5 second polling cadence described in Jobs, Polling, and Webhooks.

General endpoints (everything else documented here): catalog reads (GET /v2/models, GET /v2/signs, and their {name} variants), GET /v2/jobs, GET /v2/account/credits, POST /v2/account/webhook, Groups API lifecycle and membership, and GET /v2/groups/{group_id}/longitudinal plus GET /v2/groups/{group_id}/aggregate.

When a rate limit is exceeded, the API returns 429 Too Many Requests with a Retry-After header indicating seconds until the window resets. See Errors for retry guidance.

To request rate limit changes, contact sales@amplifierhealth.com.

Endpoints by resource

Shared lookups: Response Schema, Enumerations, Errors.