Model API

Submit audio against a named multi-sign model bundle.

POST /v2/models/{model_name}/analyze runs a named sign bundle. These docs use pulse (General Wellness) in examples. Done result: summary, signals[], audio_quality, extended_metrics. One sign: Sign API.

Valid model names

pulse (General Wellness; the primary example in these docs), haven, apex, aria, breath, clarity, harbor, tide.

Each model’s domain, sign composition, and the scenarios it is tuned for are listed in the Model Catalog. To decide between a named model and a single sign, see Choosing a Model or Sign.

Some signs included in a model — for example cognitive-load, cardiovascular-strain, emotional-destabilization, dry-mouth — are model-internal and are not available as standalone targets via POST /v2/signs/{sign_name}/analyze. They appear in the model’s sign list but are not returned by GET /v2/signs. See Sign Catalog — model-internal signs.

List models

GET /v2/models

Named models and the signs in each.

Response

Field	Type	Description
`models`	array	List of model objects.

Each object in models:

Field	Type	Description
`name`	string	Named model identifier (e.g. `"pulse"`). Use as the `model_name` path parameter on detail and analyze endpoints.
`signs`	string[]	Signs included in this model. Some entries are model-internal — see Sign Catalog — model-internal signs.

Example

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

const response = await fetch("https://api.amplifierhealth.com/v2/models", {
  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/models",
  headers={
      "X-Account-ID": os.environ["AMPLIFIER_ACCOUNT_ID"],
      "X-API-Key": os.environ["AMPLIFIER_API_KEY"],
  },
)

data = response.json()

Example response

{
  "models": [
    { "name": "pulse",   "signs": ["mood-disruption","anxiety","stress","fatigue","dehydration","elevated-blood-pressure"] },
    { "name": "haven",   "signs": ["mood-disruption","anxiety","stress","hypervigilance","attention-dysregulation","fatigue"] },
    { "name": "apex",    "signs": ["head-impact","cognitive-load","fatigue","dehydration","stress","anxiety","cardiovascular-strain"] },
    { "name": "aria",    "signs": ["elevated-androgens","iron-deficiency","dehydration","mood-disruption","fatigue","anxiety","elevated-blood-pressure"] },
    { "name": "breath",  "signs": ["airway-obstruction-pattern","allergy"] },
    { "name": "clarity", "signs": ["cognitive-impairment"] },
    { "name": "harbor",  "signs": ["alcohol-use-pattern","substance-use-pattern","emotional-destabilization","anxiety","stress","fatigue"] },
    { "name": "tide",    "signs": ["elevated-blood-pressure","metabolic-load","dehydration","iron-deficiency","fatigue","dry-mouth"] }
  ]
}

Errors

For authentication errors (401) and other codes, see Errors.

Get a model

GET /v2/models/{model_name}

Return the details for a single named model, including the signs it includes.

Path Parameters

Parameter	Type	Description
`model_name`	string	The name of the model to retrieve. See Valid model names.

Response

Field	Type	Description
`name`	string	Named model identifier.
`signs`	string[]	Signs included in this model.

Example

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

const response = await fetch("https://api.amplifierhealth.com/v2/models/pulse", {
  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/models/pulse",
  headers={
      "X-Account-ID": os.environ["AMPLIFIER_ACCOUNT_ID"],
      "X-API-Key": os.environ["AMPLIFIER_API_KEY"],
  },
)

data = response.json()

Example response

{ "name": "pulse", "signs": ["mood-disruption","anxiety","stress","fatigue","dehydration","elevated-blood-pressure"] }

Errors

HTTP	Code	Condition
404	`NOT_FOUND`	`model_name` is not a recognized model. Check the name against Valid model names.

For other codes, see Errors.

Analyze with a model

POST /v2/models/{model_name}/analyze

Submit audio for analysis using a named model. Returns a job object immediately; poll GET /v2/jobs/{job_id} or use a webhook for the completed result.

Requests use Content-Type: multipart/form-data. The job object is returned immediately with status: "queued" and result: null. When analysis completes, the result contains multi-sign output: a summary wrapper, a signals[] array (one entry per sign in the bundle), audio_quality, and extended_metrics.

Path Parameters

Parameter	Description
`model_name`	The named model to run. See Valid model names.

Request Body

Field	Type	Required	Description
`audio`	file	No	Audio file (WAV, FLAC, MP3, or M4A). Max 32 MB per file. Provide this or `audio_upload_ref`. For longer recordings, MP3, M4A, or FLAC usually keep the file under the limit. See Audio Requirements.
`audio_upload_ref`	string	No	The `upload_ref` value from `POST /v2/audio/uploads`. Provide this or an `audio` file.
`diarize`	boolean	No	Whether to apply speaker diarization. Default: false. See Speaker Diarization for when to use it, and Billing and Cost for the add-on cost.
`webhook_url`	string	No	Per-request webhook URL. Overrides the account-level webhook for this job. Optional on its own in the schema. When you set it, also send `webhook_secret_key`.
`webhook_secret_key`	string	No	Optional on its own in the schema. Required in practice when `webhook_url` is provided — used to sign the webhook payload (HMAC-SHA256).

Webhook delivery, the request format, and signature verification are described in Jobs, Polling, and Webhooks.

Response

The job object, returned immediately. status is queued and result is null until processing completes. Field definitions are in Response Schema; enumerated values for status and job_type are in Enumerations.

When status is done, result contains summary + signals[] + audio_quality + extended_metrics — see Response Schema. Each signal’s level value is defined in Interpreting Results.

Example

curl -X POST https://api.amplifierhealth.com/v2/models/pulse/analyze \
  -H "X-Account-ID: your-account-id" \
  -H "X-API-Key: your-api-key" \
  -F "audio=@recording.wav;type=audio/wav"

const fs = require("fs");

const form = new FormData();
form.append("audio", new Blob([fs.readFileSync("recording.wav")], { type: "audio/wav" }), "recording.wav");

const response = await fetch("https://api.amplifierhealth.com/v2/models/pulse/analyze", {
  method: "POST",
  headers: {
    "X-Account-ID": process.env.AMPLIFIER_ACCOUNT_ID,
    "X-API-Key": process.env.AMPLIFIER_API_KEY,
  },
  body: form,
});

const data = await response.json();

# Requires httpx: pip install httpx
import os
import httpx

with open("recording.wav", "rb") as f:
    audio_bytes = f.read()

response = httpx.post(
  "https://api.amplifierhealth.com/v2/models/pulse/analyze",
  headers={
      "X-Account-ID": os.environ["AMPLIFIER_ACCOUNT_ID"],
      "X-API-Key": os.environ["AMPLIFIER_API_KEY"],
  },
  files={"audio": ("recording.wav", audio_bytes, "audio/wav")},
)

data = response.json()

Example response

{
  "job_id": "7c3d91fa-b04e-4a18-832d-dc4f6e2a9b5c",
  "status": "queued",
  "created_at": "2026-05-22T10:30:00Z",
  "completed_at": null,
  "result": null,
  "audio_content_type": "audio/wav",
  "audio_size_bytes": 876032,
  "audio_duration_seconds": 27.4,
  "audio_sample_rate": 16000,
  "job_type": "model",
  "api_version": "v2",
  "model_name": "pulse"
}

Retrieve the completed result with GET /v2/jobs/{job_id}.

Errors

HTTP	Code	Condition
404	`NOT_FOUND`	`model_name` is not a recognized model. Check the name against Valid model names.

Audio validation codes (AUDIO_TOO_SHORT, AUDIO_TOO_LONG, UNSUPPORTED_FORMAT, AUDIO_POOR_QUALITY) are listed on Errors.

If you send webhook_url, also send webhook_secret_key. The published schema lists both as independently optional; the webhook_secret_key description requires the secret whenever a URL is present. A URL without a secret is not a usable override.

For other codes and retry guidance, see Errors.

Audio Uploads — mint a signed PUT URL and analyze with audio_upload_ref.
Longitudinal API — submit to a model and register the job into a group, or score it against the group’s history.
Groups API — create groups and manage job membership.
Model Catalog — domain, sign composition, and scenarios for each named model.
Audio Requirements — formats, size, duration, and recording guidance.