> This page is for version v1.3 (default).
> For other versions, use one of these documentation indexes:
> - v1.3 (default): https://docs.virtuosis.ai/v-1-3/llms.txt
> - v1.2: https://docs.virtuosis.ai/v-1-2/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.virtuosis.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.virtuosis.ai/_mcp/server.

# API Reference

> Machine-readable reference for the Virtuosis REST API v1.3.

The Virtuosis REST API v1.3 lets third-party applications create user accounts, upload Base64-encoded audio recordings, poll health analysis results, and inspect analysis usage.

## Environments

| Environment | Base URL                        | Purpose                                      |
| ----------- | ------------------------------- | -------------------------------------------- |
| Production  | `https://api.virtuosis.ai/v1.3` | Live integrations and production recordings. |

## Authentication

Need an API key? [Get started](https://app.virtuosis.ai/) in the Virtuosis app to provision API access.

All requests require a bearer token:

```http
Authorization: Bearer <API_KEY>
```

Requests with JSON bodies must also include:

```http
Content-Type: application/json
```

## Processing guidance

* Create one account per user. Accounts are scoped to the API key's organisation and are always assigned the `speaker` role.
* Upload audio as a Base64-encoded string in the JSON `audio` field.
* Specify which analysis types to run (`wellbeing`, `parkinsons`, `alzheimers`, `communication_coach`). The `analysis` array is required and must contain at least one type.
* Do not send multipart file uploads to the recording endpoint.
* Use at least 30 seconds of free speech. If needed, prompt the speaker with an open-ended question such as "How's your day going?" or "Can you introduce yourself?"
* For multi-speaker clips, set `isolate_oldest_speaker` to `true` to analyse only the speaker estimated to be oldest. The retained speaker's speech must still meet the 30-second minimum, and recordings must be no longer than 10 minutes when this option is enabled.
* Poll analysis results every 15 to 30 seconds.
* Do not poll more frequently than every 5 seconds.
* Use a five-minute timeout for analysis processing.

## Usage and billing

* Uploads consume credits. `GET /usage/recordings` returns remaining trial, monthly included, and purchased credit balances, plus the originally granted trial and monthly included allotments and the current subscription tier.
* Requests are rejected once the balance is exhausted (`UploadLimitExceeded`), while access is suspended (`Suspended`), or when API billing has not been provisioned for the organisation (`ApiNotProvisioned`).

## Error guidance

All endpoints use the same error response shape. Error `type` values are documented in the OpenAPI schema and may expand over time. Internal server errors may not include a detailed message, but are recorded by Virtuosis error tracking for debugging.