Response Schema

The Amplifier API produces two response shapes:

• Model jobs (POST /v2/models/{model_name}/analyze) — multi-sign result with a summary wrapper, a signals[] array, audio_quality, and extended_metrics. See Model API.

• Sign jobs (POST /v2/signs/{sign_name}/analyze) — single-signal result with a singular signal object and audio_quality. See Sign API.

Both endpoints return the full job object immediately (job_id, status: running, result: null). Retrieve the completed result with GET /v2/jobs/{job_id}, or receive it via webhook.

• Errors: When a request fails, the API returns a JSON object with code, message, and status — see Error Reference.

For workflow and display rules, see Interpreting Results.

Model Response

Submit Response

POST /v2/models/{model_name}/analyze returns the job object immediately. status is running and result is null until processing completes. Use GET /v2/jobs/{job_id} to retrieve the completed result.

{
  "job_id": "189bce4a-52cb-4e60-8586-cef89e719109",
  "status": "running",
  "created_at": "2026-02-22T09:14: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"
}

Job Response

GET /v2/jobs/{job_id} returns the job status and, when complete, the full analysis result.

Each response includes exactly one discriminator field, selected by job_type:

Discriminator fields by job_type. A V2 job response includes only the discriminator field that matches its job_type: use_case jobs include use_case; condition jobs include condition; model jobs include model_name; sign jobs include sign_name. The other discriminator fields are omitted. pipeline_type is not part of the V2 response. The shared fields above are always present (the nullable ones — completed_at, result, audio_sample_rate — may be null).

result contains:

{
  "job_id": "189bce4a-52cb-4e60-8586-cef89e719109",
  "status": "done",
  "created_at": "2026-02-22T09:14:00Z",
  "completed_at": "2026-02-22T09:14:03Z",
  "job_type": "model",
  "api_version": "v2",
  "model_name": "apex",
  "audio_content_type": "audio/wav",
  "audio_size_bytes": 876032,
  "audio_duration_seconds": 27.4,
  "result": {
    "summary": { ... },
    "signals": [ ... ],
    "audio_quality": { ... },
    "extended_metrics": [ ... ]
  }
}

Timestamps

Type: created_at and completed_at are ISO 8601 datetimes; RFC 3339–compatible parsing is recommended.

Variability: The API may return:

• A timezone designator: Z (UTC) or numeric offset ±hh:mm, or omit the designator in some responses.
• Fractional seconds at variable precision (milliseconds, microseconds, etc.).

UTC: Values with a Z suffix are UTC. When no offset appears, treat the timestamp as UTC.

Client guidance: Use a standard ISO 8601-compatible datetime parser. Avoid string-comparing timestamps or assuming a fixed number of fractional digits.

Examples (both valid):

With Z, no fractional seconds:

"created_at": "2026-02-22T09:14:00Z",
"completed_at": "2026-02-22T09:14:03Z"

With fractional seconds, no Z:

"created_at": "2026-03-28T01:05:35.943000",
"completed_at": "2026-03-28T01:05:38.120500"

Job Status: Failed

When status is "failed", processing ended unsuccessfully. For a valid job_id on your account, GET /v2/jobs/{job_id} still returns 200 OK with a job object — failure is expressed in status, not via a 4xx HTTP code.

Poll until status is done or failed, then branch:

• done: result contains the full analysis.
• failed: result is typically null; completed_at may also be null. If you need the failure reason, check your operational logs or contact support — the job object does not include a structured error code in this API version.

404 Not Found applies when the job is unknown or belongs to a different account — see Jobs — Error handling.

summary Object

result.summary is the primary object for routing decisions. Read it first.

overall_level reflects the highest level value across all signals in the bundle. recommended_action is derived from the full distribution of signal levels — not from overall_level alone. See Levels & Actions for the derivation logic.

{
  "overall_level": "elevated",
  "recommended_action": "escalate",
  "flagged_count": 3,
  "primary_signals": ["stress", "anxiety", "fatigue"],
  "description": {
    "summary": "Voice patterns suggest elevated indicators for stress and anxiety...",
    "vocal_features": [ ... ]
  }
}

signals Array

signals contains one entry per sign in the model bundle.

[
  {"name": "stress", "label": "Stress", "score": 0.81, "level": "elevated", "flagged": true},
  {"name": "anxiety", "label": "Anxiety", "score": 0.71, "level": "elevated", "flagged": true},
  {"name": "fatigue", "label": "Fatigue", "score": 0.54, "level": "consider", "flagged": true}
]

For display rules and field usage guidance, see Interpreting Results — Display Guidelines.

description Object

description is nested inside summary. It contains a machine-generated plain-text summary and a structured array of annotated vocal feature values.

Display and compliance

Surface description in care-staff interfaces only. For the full display and compliance rules, see Interpreting Results — Display Guidelines.

vocal_features Array

Each entry in vocal_features describes a single acoustic measurement extracted from the recording.

{
  "summary": "Voice patterns suggest elevated stress and fatigue indicators...",
  "vocal_features": [
    {
      "feature": "speech_rate",
      "label": "Speech Rate",
      "value": 3.2,
      "unit": "syllables/s",
      "value_interpretation": "reduced"
    },
    {
      "feature": "voice_shimmer",
      "label": "Voice Shimmer",
      "value": 0.041,
      "unit": "dB",
      "value_interpretation": "slightly elevated"
    }
  ]
}

audio_quality Object

audio_quality provides quality scores for the submitted recording and flags any conditions so you can assess when to use the result or re-record. File-level metadata (size, duration, and format) is available on the job object fields (audio_size_bytes, audio_duration_seconds, audio_content_type).

issues, voice_percentage, and audio_clarity are coherent: when a score is below its threshold, the corresponding issue code will typically be present in issues.

{
  "issues": [],
  "voice_percentage": 82.4,
  "audio_clarity": 74.1
}

Example with quality issues detected:

{
  "issues": ["high_background_noise", "insufficient_speech"],
  "voice_percentage": 21.3,
  "audio_clarity": 38.6
}

When issues is non-empty, signals may still be returned. Use the issue codes to decide whether to act on the result or re-record — see Audio Requirements for recommended actions for each code.

extended_metrics Array

extended_metrics contains wellness metric scores derived from the voice recording. The set of metrics returned depends on the model. For metric definitions, see Wellness.

[
  {
    "metric_id": "anxious-mood",
    "label": "Anxious Mood",
    "score_mean": 0.72,
    "score_std": 0.08,
    "low_anchor": "tranquil",
    "high_anchor": "panicked"
  },
  {
    "metric_id": "vad-valence",
    "label": "Emotional Valence",
    "score_mean": 0.38,
    "score_std": 0.05,
    "low_anchor": "negative",
    "high_anchor": "positive"
  }
]

Sign Response

POST /v2/signs/{sign_name}/analyze returns the same job object envelope (see Job Response above), but with job_type: "sign", the sign_name discriminator field, and the result interior is structurally different. (model_name is omitted for sign jobs — see Discriminator fields by job_type.)

The result object uses a singular signal object instead of summary + signals[]:

{
  "job_id": "4a8f12c9-e7b2-4d3a-9f1c-8b6d2e5a7c0f",
  "status": "done",
  "job_type": "sign",
  "api_version": "v2",
  "sign_name": "stress",
  "result": {
    "signal": { ... },
    "audio_quality": { ... },
    "extended_metrics": [ ... ]
  }
}

signal Object

signal is a single object (not an array) containing the full result for the requested sign. Unlike the model response — where description and recommended_action live on the summary wrapper — the sign response places them directly on signal.

recommended_action is derived from this sign's level alone — not aggregated across a bundle. See Levels & Actions for the derivation logic.

description contains an LLM-generated plain-text summary of the acoustic findings and a structured vocal_features array. The same display and compliance rules apply: surface in care-staff interfaces only, not in automated alerts or patient-facing output. On the inconclusive path, summary contains a standard inconclusive message and vocal_features is empty.

{
  "name": "stress",
  "label": "Stress",
  "score": 0.81,
  "level": "elevated",
  "flagged": true,
  "recommended_action": "escalate",
  "description": {
    "summary": "Voice patterns suggest elevated stress indicators...",
    "vocal_features": [
      {
        "feature": "speech_rate",
        "label": "Speech Rate",
        "value": 3.2,
        "unit": "syllables/s",
        "value_interpretation": "reduced"
      }
    ]
  }
}

Use job_type to select the correct result parser:

For display rules, see Interpreting Results — Display Guidelines.