Sign API

Analyze a single sign and return one signal plus audio quality.

GET /v2/signs, GET /v2/signs/{sign_name}, and POST /v2/signs/{sign_name}/analyze. A sign is one analysis target. Bundles: Model API.

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.

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. The list is maintained in Sign Catalog — 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

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

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();

# 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()

Example response

{
  "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.

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.

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

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

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();

# 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()

Example response

{ "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.

For other codes, see Errors.

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.

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 a singular signal object plus audio_quality — see Response Schema. The signal’s level value is defined in Interpreting Results.

Example

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"

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();

# 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()

Example response

{
  "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}.

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.

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 a sign job into a group, or score it against the group’s history.
Groups API — create groups and manage job membership.
Sign Catalog — every sign by evidence tier, with labels, acoustic indicators, and rationale.
Audio Requirements — formats, size, duration, and recording guidance.