---
title: Sign API
description: Analyze a single sign and return one signal plus audio quality.
type: doc
icon: audio-lines
sidebar:
  label: Sign API
  order: 3
  icon: audio-lines
search:
  tags: [api]
---
`GET /v2/signs`, `GET /v2/signs/{sign_name}`, and `POST /v2/signs/{sign_name}/analyze`. A sign is one analysis target. Bundles: [Model API](/reference/models).


## Valid sign names

Standalone signs:

`airway-obstruction-pattern`, `alcohol-use-pattern`, `allergy`, `anxiety`, `attention-dysregulation`, `cognitive-impairment`, `dehydration`, `elevated-androgens`, `elevated-blood-pressure`, `fatigue`, `head-impact`, `hypervigilance`, `iron-deficiency`, `metabolic-load`, `mood-disruption`, `stress`, `substance-use-pattern`.

Display labels, evidence tiers, acoustic indicators, and rationale for each sign are in the [Sign Catalog](/catalogs/signs).

## Model-internal signs

Some signs appear in the `signs` list of named models returned by `GET /v2/models/{model_name}` but are not available for standalone analysis through this API. They are not returned by `GET /v2/signs` and cannot be used as a `sign_name` here — for results on those signals, use the named model that includes them via [`POST /v2/models/{model_name}/analyze`](/reference/models#analyze-with-a-model). The list is maintained in [Sign Catalog — model-internal signs](/catalogs/signs#model-internal-signs).

## List signs

`GET /v2/signs`

Return the list of all signs available for individual analysis.

### Response

| Field | Type | Description |
|---|---|---|
| `signs` | array | List of sign objects. |

Each object in `signs`:

| Field | Type | Description |
|---|---|---|
| `name` | string | Sign identifier. Use as the `sign_name` path parameter on detail and analyze endpoints. |
| `label` | string | Human-readable sign name for display. |

### Example

<CodeGroup param="lang">

```bash cURL
curl -X GET "https://api.amplifierhealth.com/v2/signs" \
  -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/signs", {
  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/signs",
  headers={
      "X-Account-ID": os.environ["AMPLIFIER_ACCOUNT_ID"],
      "X-API-Key": os.environ["AMPLIFIER_API_KEY"],
  },
)

data = response.json()
```

</CodeGroup>

### Example response

```json
{
  "signs": [
    { "name": "airway-obstruction-pattern", "label": "Airway Obstruction Pattern" },
    { "name": "alcohol-use-pattern",        "label": "Alcohol Use Pattern" },
    { "name": "allergy",                    "label": "Allergy" },
    { "name": "anxiety",                    "label": "Anxiety" },
    { "name": "attention-dysregulation",    "label": "Attention Dysregulation" },
    { "name": "cognitive-impairment",       "label": "Cognitive Impairment" },
    { "name": "dehydration",                "label": "Dehydration" },
    { "name": "elevated-androgens",         "label": "Elevated Androgens" },
    { "name": "elevated-blood-pressure",    "label": "Elevated Blood Pressure" },
    { "name": "fatigue",                    "label": "Fatigue" },
    { "name": "head-impact",                "label": "Head Impact" },
    { "name": "hypervigilance",             "label": "Hypervigilance" },
    { "name": "iron-deficiency",            "label": "Iron Deficiency" },
    { "name": "metabolic-load",             "label": "Metabolic Load" },
    { "name": "mood-disruption",            "label": "Mood Disruption" },
    { "name": "stress",                     "label": "Stress" },
    { "name": "substance-use-pattern",      "label": "Substance Use Pattern" }
  ]
}
```

### Errors

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

## Get a sign

`GET /v2/signs/{sign_name}`

Return details for a single sign, including its display label.

### Path Parameters

| Parameter | Type | Description |
|---|---|---|
| `sign_name` | string | The name of the sign to retrieve. See [Valid sign names](#valid-sign-names). |

### Response

| Field | Type | Description |
|---|---|---|
| `name` | string | Sign identifier. |
| `label` | string | Human-readable sign name. |
| `condition` | string or null | Back-reference to the corresponding model identifier (e.g. `"acute-stress"`). Populated when the sign has a mapped identifier; null otherwise. |

### Example

<CodeGroup param="lang">

```bash cURL
curl -X GET "https://api.amplifierhealth.com/v2/signs/stress" \
  -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/signs/stress", {
  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/signs/stress",
  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": "stress", "label": "Stress", "condition": "acute-stress" }
```

### Errors

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

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

## Analyze with a sign

`POST /v2/signs/{sign_name}/analyze`

Submit audio to analyze a single sign. 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 a singular `signal` object plus `audio_quality`.

### Path Parameters

| Parameter | Description |
|---|---|
| `sign_name` | The sign to analyze. Must be a sign available for standalone analysis — see [Valid sign names](#valid-sign-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 a singular `signal` object plus `audio_quality` — see [Response Schema](/reference/response-schema#signal-object). The 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/signs/stress/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/signs/stress/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/signs/stress/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": "a2e4c7f1-3d9b-4e6a-b8c2-1f5d8e3a7b9c",
  "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": "sign",
  "api_version": "v2",
  "sign_name": "stress"
}
```

Retrieve the completed result with [`GET /v2/jobs/{job_id}`](/reference/jobs#retrieve-a-job).

### Errors

| HTTP | Code | Condition |
|---|---|---|
| 404 | `NOT_FOUND` | `sign_name` is not a recognized sign or is not available for standalone analysis. Check the name against [Valid sign names](#valid-sign-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 a sign job into a group, or score it against the group's history.
- [Groups API](/reference/groups) — create groups and manage job membership.
- [Sign Catalog](/catalogs/signs) — every sign by evidence tier, with labels, acoustic indicators, and rationale.
- [Audio Requirements](/guides/audio-requirements) — formats, size, duration, and recording guidance.