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.

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.