Model API

Models are named multi-sign analysis packages — each model bundles a fixed set of signs and runs them against submitted audio in a single call. Submit audio via POST /v2/models/{model_name}/analyze to receive a multi-sign result: summary, signals[], audio_quality, and extended_metrics. Use the Model API when you want a pre-defined multi-sign result without composing individual sign calls.

For individual sign analysis, see Sign API.

GET /v2/models

GET/v2/models

Return the list of all available named models and the signs each one includes.

Response

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

Each object in models:

Field	Type	Description
`name`	string	Named model identifier (e.g. `"apex"`). Use as the `model_name` path parameter on detail and analyze endpoints.
`signs`	string[]	Signs included in this model. Some entries are model-internal and are not available via `POST /v2/signs/{sign_name}/analyze` — see Sign API — 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"

Example response

{
  "models": [
    { "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"] },
    { "name": "haven",   "signs": ["mood-disruption","anxiety","stress","hypervigilance","attention-dysregulation","fatigue"] },
    { "name": "pulse",   "signs": ["mood-disruption","anxiety","stress","fatigue","dehydration","elevated-blood-pressure"] },
    { "name": "tide",    "signs": ["elevated-blood-pressure","metabolic-load","dehydration","iron-deficiency","fatigue"] }
  ]
}

Errors

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

GET /v2/models/{model_name}

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 below.

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/apex" \
-H "X-Account-ID: your-account-id" \
-H "X-API-Key: your-api-key"

Example response

{ "name": "apex", "signs": ["head-impact","cognitive-load","fatigue","dehydration","stress","anxiety","cardiovascular-strain"] }

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 Error Reference.

POST /v2/models/{model_name}/analyze

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: "running" 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

Requests use Content-Type: multipart/form-data.

API Parameters
Field	Type	Required	Description
audio	file	Required	Audio file (WAV, FLAC, MP3, or M4A). Max 32 MB per file. For longer recordings, MP3, M4A, or FLAC usually keep the file under the limit. See [Audio Requirements](/guides/audio-requirements#file-size).
diarize	boolean	Optional	Whether to apply speaker diarization. Default: false.
webhook_url	string	Optional	Per-request webhook URL. Overrides the account-level webhook for this job. The API sends an HTTP POST to this URL when analysis completes. Must be provided together with webhook_secret_key — omit both or include both.
webhook_secret_key	string	Optional	Required when webhook_url is provided. Used to sign the webhook payload (HMAC-SHA256) so your server can verify it came from Amplifier. Must be provided together with webhook_url — omit both or include both.

Valid model names

Model	Signs included	Sign count
`apex`	head-impact, cognitive-load, fatigue, dehydration, stress, anxiety, cardiovascular-strain	7
`aria`	elevated-androgens, iron-deficiency, dehydration, mood-disruption, fatigue, anxiety, elevated-blood-pressure	7
`breath`	airway-obstruction-pattern, allergy	2
`clarity`	cognitive-impairment	1
`harbor`	alcohol-use-pattern, substance-use-pattern, emotional-destabilization, anxiety, stress	5
`haven`	mood-disruption, anxiety, stress, hypervigilance, attention-dysregulation, fatigue	6
`pulse`	mood-disruption, anxiety, stress, fatigue, dehydration, elevated-blood-pressure	6
`tide`	elevated-blood-pressure, metabolic-load, dehydration, iron-deficiency, fatigue	5

Some signs listed above (e.g. cognitive-load, cardiovascular-strain, emotional-destabilization) 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 API — model-internal signs.

Code Examples

Submit

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

Example response

The API returns immediately with the job object. status is running and result is null until processing completes:

{
  "job_id": "7c3d91fa-b04e-4a18-832d-dc4f6e2a9b5c",
  "status": "running",
  "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": "apex"
}

Poll job

curl https://api.amplifierhealth.com/v2/jobs/7c3d91fa-b04e-4a18-832d-dc4f6e2a9b5c \
-H "X-Account-ID: your-account-id" \
-H "X-API-Key: your-api-key"

See Jobs for the full job response schema. When status is done, the result contains summary + signals[] + audio_quality + extended_metrics — see Response Schema — Model Response.

Errors

HTTP	Code	Condition
404	`NOT_FOUND`	`model_name` is not a recognized model. Check the name against Valid model names.
400	`AUDIO_TOO_SHORT`	Recording is under 15 seconds.
400	`AUDIO_TOO_LONG`	Recording exceeds 20 minutes.
400	`UNSUPPORTED_FORMAT`	Audio format is not WAV, FLAC, MP3, or M4A.
422	`AUDIO_POOR_QUALITY`	Recording conditions below the threshold used for analysis.

If only one of webhook_url or webhook_secret_key is provided, the request returns 400 Bad Request. Provide both or omit both.

For other codes and retry guidance, see Error Reference.