Migrating from v1 to v2

The v2 API is recommended for all new integrations. This guide explains what changes between v1 and v2 so you can update an existing v1 integration.

What changes

	v1 (Legacy)	v2
Flow	Asynchronous: submit → receive `job_id` → poll or webhook	Both use-case and condition analyze return a job object immediately; completed result via `GET /v2/jobs/{job_id}` or webhook.
Endpoint selection	Condition-specific paths (`/api/v1/wellness/`, `/api/v1/cognitive/`, `/api/v1/anemia/`)	Use-case bundles (`/v2/use-case/analyze`) or single conditions (`/v2/condition/analyze`)
Audio submission	Multipart form upload or URL	Both use `multipart/form-data` with file field `audio`. Use-case passes `use_case`, condition passes `condition`.
Result shape	Varies by condition	Both return the same job object with `result` containing analysis output. Retrieve via `GET /v2/jobs/{job_id}`.

Authentication

X-Account-ID is required for both versions. The second credential header differs:

Version	Second header
v1	`X-Secret-Key`
v2	`X-API-Key`

# v1
X-Account-ID: your-account-id
X-Secret-Key: your-secret-key

# v2
X-Account-ID: your-account-id
X-API-Key: your-api-key

See API Overview.

Mapping v1 Conditions to v2 Use Cases

v1 Condition	Closest v2 `use_case`	Notes
`wellness`	`behavioral-health` or `wellness`	Choose based on your deployment context
`cognitive`	`cognitive`	See Models
`anemia`	`womens-health`	Includes the `anemia` Investigational model

If your v1 condition does not map cleanly to a v2 use case, contact support@amplifierhealth.com to confirm the right bundle for your context.

Audio Submission

v1: Upload audio as a multipart form file or provide a public URL.

v2: Upload audio as a multipart form file to POST /v2/models/{model_name}/analyze.

import httpx

with open("recording.wav", "rb") as f:
    audio_bytes = f.read()

response = httpx.post(
    "https://api.amplifierhealth.com/v2/models/apex/analyze",
    headers={
        "X-Account-ID": "your-account-id",
        "X-API-Key": "your-api-key",
    },
    files={"audio": ("recording.wav", audio_bytes, "audio/wav")},
)

job_id = response.json()["job_id"]

See Audio Requirements for format and duration guidelines.

Response Structure

v1 result shape varies by condition and is nested inside a job object retrieved by polling or webhook.

v2 returns a completed result via GET /v2/jobs/{job_id}. The completed job response has a consistent structure:

{
  "job_id": "189bce4a-52cb-4e60-8586-cef89e719109",
  "status": "done",
  "created_at": "2026-02-22T09:14:00Z",
  "completed_at": "2026-02-22T09:14:03Z",
  "use_case": "behavioral-health",
  "audio_content_type": "audio/wav",
  "audio_size_bytes": 876032,
  "audio_duration_seconds": 27.4,
  "result": {
    "summary": {
      "overall_level": "elevated",
      "recommended_action": "escalate",
      "flagged_count": 2,
      "primary_signals": ["depression", "anxiety"],
      "description": { "summary": "...", "vocal_features": [ "..." ] }
    },
    "signals": [ "..." ],
    "audio_quality": { "..." },
    "extended_metrics": [ "..." ]
  }
}

See Response Schema for the full field reference.

Polling and Webhooks

v1 requires polling GET /api/v1/account/jobs/{job_id} or configuring a webhook to receive results asynchronously.

v2 uses the async job flow described in What changes above. If your architecture needs push-based delivery, configure a v2 webhook via POST /v2/account/webhook. The v2 webhook payload has the same structure as the job result.

v1 Endpoints Remain Available

v1 endpoints remain available for existing integrations. New features are available in v2 only.

Contact support@amplifierhealth.com for migration assistance.