---
title: Model API
description: Submit audio against a named multi-sign model bundle.
type: doc
icon: layers
sidebar:
  label: Model API
  order: 2
  icon: layers
search:
  tags: [api]
---
`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](/reference/signs).


## 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](/catalogs/models). To decide between a named model and a single sign, see [Choosing a Model or Sign](/guides/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](/catalogs/signs#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](/catalogs/signs#model-internal-signs). |

### Example

<CodeGroup param="lang">

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

```javascript JavaScript
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();
```

```python Python
# 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()
```

</CodeGroup>

### Example response

```json
{
  "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](/reference/errors#error-codes).

## 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](#valid-model-names). |

### Response

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

### Example

<CodeGroup param="lang">

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

```javascript JavaScript
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();
```

```python Python
# 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()
```

</CodeGroup>

### Example response

```json
{ "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](#valid-model-names). |

For other codes, see [Errors](/reference/errors#error-codes).

## 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](#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](/guides/audio-requirements#file-size). |
| `audio_upload_ref` | string | No | The `upload_ref` value from [`POST /v2/audio/uploads`](/reference/audio). Provide this **or** an `audio` file. |
| `diarize` | boolean | No | Whether to apply speaker diarization. Default: false. See [Speaker Diarization](/guides/audio-requirements#speaker-diarization) for when to use it, and [Billing and Cost](/guides/billing#token-rates) 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](/guides/jobs#webhooks).

### Response

The job object, returned immediately. `status` is `queued` and `result` is `null` until processing completes. Field definitions are in [Response Schema](/reference/response-schema); enumerated values for `status` and `job_type` are in [Enumerations](/reference/enumerations#job-status).

When `status` is `done`, `result` contains `summary` + `signals[]` + `audio_quality` + `extended_metrics` — see [Response Schema](/reference/response-schema#signals-array). Each signal's `level` value is defined in [Interpreting Results](/guides/interpreting-results#signal-levels).

### Example

<CodeGroup param="lang">

```bash cURL
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"
```

```javascript JavaScript
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();
```

```python Python
# 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()
```

</CodeGroup>

### Example response

```json
{
  "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}`](/reference/jobs#retrieve-a-job).

### Errors

| HTTP | Code | Condition |
|---|---|---|
| 404 | `NOT_FOUND` | `model_name` is not a recognized model. Check the name against [Valid model names](#valid-model-names). |

Audio validation codes (`AUDIO_TOO_SHORT`, `AUDIO_TOO_LONG`, `UNSUPPORTED_FORMAT`, `AUDIO_POOR_QUALITY`) are listed on [Errors](/reference/errors#error-codes).

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](/reference/errors#error-codes).

## Related pages

- [Audio Uploads](/reference/audio) — mint a signed PUT URL and analyze with `audio_upload_ref`.
- [Longitudinal API](/reference/longitudinal-api) — submit to a model and register the job into a group, or score it against the group's history.
- [Groups API](/reference/groups) — create groups and manage job membership.
- [Model Catalog](/catalogs/models) — domain, sign composition, and scenarios for each named model.
- [Audio Requirements](/guides/audio-requirements) — formats, size, duration, and recording guidance.