API Reference

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

Authentication

All requests require a bearer token:

1
Authorization: Bearer <API_KEY>

Requests with JSON bodies must also include:

1
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). 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?”
• 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 allotment 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.