---
title: "Kick off therapy plan generation from an uploaded audio recording. Returns immediately (202) with a therapy_session_i…"
method: POST
path: "/api/generate-therapy-plan"
tags: ["Therapy Planning"]
---

# Kick off therapy plan generation from an uploaded audio recording. Returns immediately (202) with a therapy_session_i…

`POST /api/generate-therapy-plan`

## Request

- Base URL: `https://platform.vocametrix.com`
- URL: `https://platform.vocametrix.com/api/generate-therapy-plan`
- Auth: API key in header `X-API-Key`

## Request body

- object
  - `fileId` string, required: REQUIRED. fileId from a prior /api/assignFileId upload.
  - `patientId` string, required: REQUIRED. Patient identifier matching ^[a-zA-Z0-9_-]{1,100}$. The literal "PT-UNKNOWN" is explicitly rejected.
  - `patientMetadata` object: Optional. Object describing the patient. Max 10,000 bytes when JSON-serialized. Optional sub-fields: demographics.age (0–120), clinical_history.severity ("Mild"|"Moderate"|"Severe"|"Very Severe"), current_goals (max 20 entries), recent_progress_notes (max 50), previous_exercises (max 30).
  - `maxIterations` integer: Optional integer 1–5, default 2. Max critic-agent iterations within the workflow.
  - `therapyAgentTemperature` number: Optional number, default 0.3. Generation temperature for the therapy-planner LLM.
  - `criticAgentTemperature` number: Optional number, default 0. Generation temperature for the critic LLM.
  - `classificationSessionId` string: Optional string. If present, links the new therapy session to a prior /api/classify-stuttering session so the workflow can use those classification results.
  - `useAzureML` boolean: Optional boolean, default true. Whether to use Azure ML inside the workflow.

## Response `200`

Successful response

- object
  - `success` boolean: Boolean — true when the job has been queued.
  - `message` string: Human-readable status message.
  - `therapy_session_id` string: Session ID of the form "THERAPY-<patientId>-<uuid>".
  - `status` string: "pending" — the initial state.
  - `status_url` string: Convenience URL to poll status (/api/therapy-status/<id>).
  - `result_url` string: Convenience URL to fetch result once complete (/api/therapy-result/<id>).
  - `estimated_time_seconds` string: Approximate wall-clock estimate (e.g., 120 s).
  - `timestamp` string, date-time: ISO 8601 timestamp.

## Other responses

- `400`: Bad request — missing or invalid parameter
- `401`: Unauthorized — missing or invalid API key
- `429`: Rate limit exceeded
- `500`: Server error

---

[API](https://skmtc.dev/vocametrix/apis/vocametrix-api.md) · [All operations](https://skmtc.dev/vocametrix/apis/vocametrix-api/llms.txt) · [OpenAPI document](https://skmtc.dev/vocametrix/apis/vocametrix-api/revisions/8a54d01bcc81?raw)