Aqua API reference

Aqua API creates Aqua dictations and voice edits, reads stored dictations and recordings, manages transcript customizations and supported app settings, and transcribes audio with Avalon.

The API has two route families. Product routes use Aqua object shapes, the ErrorEnvelope error format, and X-RateLimit-* response headers. Transcription routes are OpenAI-compatible: they keep OpenAI request, response, and error shapes so the official OpenAI SDKs work unchanged, which is why some field names (for example duration) and the free-form language string differ from the product routes.

Base URL

https://api.aquavoice.com/v1

Authentication

API key as Bearer token on every route

Specification

OpenAPI YAML

Authentication

Send your API key as a Bearer token on every route. Create keys in the API dashboard at https://app.aquavoice.com/api-dashboard. A key has full access: dictation, transcription, sessions, customizations, settings, and MCP. Legacy ava_ keys keep working. OAuth tokens (MCP) carry read and write scopes; the scope shown on an operation applies to OAuth only.

A key that belongs to an organization acts as one member on the product and dictation routes. Send the header Aqua-User: usr_<id> with the member's user id, the same id GET /me returns. A missing header returns 400 user_required. A user who is not an active member returns 403 user_not_member. Transcription routes and personal keys ignore the header. A disabled account returns 403 account_disabled.

Billing

Your account activates when you create your first key. The first $1.00 of usage is free. After that, add a payment method in the API dashboard. Usage bills per second at $0.49 per hour of dictation and $0.39 per hour of transcription, with a 10-second minimum. Stripe invoices monthly, or when usage reaches $200. Failed requests and idempotent replays are not billed.

Billing errors are 402 payment_method_required, 402 billing_past_due, and 403 subscription_required. Their bodies carry billing_url, which opens the API dashboard billing page.

Connect with MCP

Use Aqua sessions, transcript customizations, and settings from an AI assistant.

01Copy the connection URL: https://api.aquavoice.com/mcp
02Add it as a remote MCP server. In Claude, use Settings > Connectors. In ChatGPT, use Settings > Apps with Developer mode enabled.
03Sign in to Aqua, approve access, and enable Aqua in your conversation.

MCP endpoint

https://api.aquavoice.com/mcp

Aqua MCP is in limited access. Your AI provider must support remote MCP and may require workspace admin approval. Read access is requested first; write access requires separate approval.

Account

Current user, credential, and history availability.

Get the current user

GET/me

This operation remains available when privacy or enterprise retention policy blocks stored history; in that case history_available is false.

Parameters

Aqua-User string: Header. Required with an organization key on product and dictation routes: the member's user id, the same id GET /me returns. A missing header returns 400 user_required; a user who is not an active member returns 403 user_not_member. Transcription routes and personal keys ignore the header.
Pattern: ^usr_[0-9a-f]{32}$

bash

curl https://api.aquavoice.com/v1/me \
  -H "Authorization: Bearer <api-key>"

json

{
  "id": "usr_1daef426873f44baaf2096903dc7283e",
  "object": "user",
  "email": "maya@northstar.studio",
  "name": "Maya Chen",
  "created_at": "2026-08-11T17:03:00Z",
  "credential": {
    "id": "key_7d4d4d5ad69942fe9ceef628f5ba7bdd",
    "method": "api_key",
    "scopes": [
      "read"
    ]
  },
  "privacy_mode": false,
  "history_available": true
}

Sessions

Stored dictations and recordings, including transcripts and recording analysis.

List or search stored sessions

GET/sessions

OAuth scope: read

Returns the user's visible stored dictations and recordings, newest first. Redacted and deleted sessions and history cleared by the user are excluded. Privacy mode stops future storage but does not hide earlier history. Enterprise zero-data-retention policy blocks product history. Results include stored summaries and action item counts. Search requires all meaningful query words to occur in one transcript, title, or stored summary. Results identify the matching source and include a centered snippet. Reads never start new AI work.

Parameters

Aqua-User string: Header. Required with an organization key on product and dictation routes: the member's user id, the same id GET /me returns. A missing header returns 400 user_required; a user who is not an active member returns 403 user_not_member. Transcription routes and personal keys ignore the header.
Pattern: ^usr_[0-9a-f]{32}$
cursor string: Query parameter. Opaque next_cursor from the previous page. Cursors expire after 30 days and are bound to the original filters. A changed or expired cursor returns invalid_cursor.
Length: 0–2048
limit integer: Query parameter.
Default: 25 · Range: 1–100
query string: Query parameter.
Length: 1–500
kind string enum: Query parameter.
One of: dictation recording
since string: Query parameter.
until string: Query parameter.

bash

curl https://api.aquavoice.com/v1/sessions \
  -H "Authorization: Bearer <api-key>"

json

{
  "object": "list",
  "data": [
    {
      "object": "session",
      "id": "ses_a1e2c85b1cbf43af9dc678a1a7423dcc",
      "kind": "recording",
      "created_at": "2026-08-11T17:03:00Z",
      "updated_at": "2026-08-11T17:03:00Z",
      "status": "stopped",
      "title": "Weekly product review",
      "app": "Zoom",
      "duration_seconds": 1842.7,
      "word_count": 4218,
      "preview": "The beta is stable enough to expand next week.",
      "summary": "The team approved a wider beta and assigned the launch checklist.",
      "action_items_count": 3
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Get a stored session

GET/sessions/{session_id}

OAuth scope: read

Parameters

session_id stringrequired: Path parameter. A missing session and a session owned by another user both return 404 session_not_found.
Pattern: ^ses_[0-9a-f]{32}$
Aqua-User string: Header. Required with an organization key on product and dictation routes: the member's user id, the same id GET /me returns. A missing header returns 400 user_required; a user who is not an active member returns 403 user_not_member. Transcription routes and personal keys ignore the header.
Pattern: ^usr_[0-9a-f]{32}$

bash

curl https://api.aquavoice.com/v1/sessions/ses_a1e2c85b1cbf43af9dc678a1a7423dcc \
  -H "Authorization: Bearer <api-key>"

json

{
  "object": "session",
  "id": "ses_a1e2c85b1cbf43af9dc678a1a7423dcc",
  "kind": "recording",
  "created_at": "2026-08-11T17:03:00Z",
  "updated_at": "2026-08-11T17:03:00Z",
  "status": "stopped",
  "title": "Weekly product review",
  "app": "Zoom",
  "duration_seconds": 1842.7,
  "word_count": 4218,
  "preview": "The beta is stable enough to expand next week.",
  "summary": "The team approved a wider beta and assigned the launch checklist.",
  "action_items": [
    "Send the revised launch checklist by Friday."
  ],
  "action_items_count": 3
}

Get a stored session transcript

GET/sessions/{session_id}/transcript

OAuth scope: read

Returns the complete final text and, when stored, the complete raw ASR text.

Parameters

session_id stringrequired: Path parameter. A missing session and a session owned by another user both return 404 session_not_found.
Pattern: ^ses_[0-9a-f]{32}$
Aqua-User string: Header. Required with an organization key on product and dictation routes: the member's user id, the same id GET /me returns. A missing header returns 400 user_required; a user who is not an active member returns 403 user_not_member. Transcription routes and personal keys ignore the header.
Pattern: ^usr_[0-9a-f]{32}$

bash

curl https://api.aquavoice.com/v1/sessions/ses_a1e2c85b1cbf43af9dc678a1a7423dcc/transcript \
  -H "Authorization: Bearer <api-key>"

json

{
  "object": "transcript",
  "session_id": "ses_a1e2c85b1cbf43af9dc678a1a7423dcc",
  "final_text": "The beta is stable enough to expand next week.",
  "raw_text": "the beta is stable enough to expand next week"
}

Set session feedback

POST/sessions/{session_id}/feedback

OAuth scope: write

Creates or replaces feedback for one owned session. corrected_text is the exact text the user wanted instead of Aqua's output. When learned preferences are enabled, comments and corrections are eligible for Aqua's continual-learning feedback pipeline.

Parameters

session_id stringrequired: Path parameter. A missing session and a session owned by another user both return 404 session_not_found.
Pattern: ^ses_[0-9a-f]{32}$
Aqua-User string: Header. Required with an organization key on product and dictation routes: the member's user id, the same id GET /me returns. A missing header returns 400 user_required; a user who is not an active member returns 403 user_not_member. Transcription routes and personal keys ignore the header.
Pattern: ^usr_[0-9a-f]{32}$

Body

feedback_type string enumrequired: One of: positive negative
message string: What Aqua got right or wrong.
Length: 0–5000
corrected_text string: Exact corrected output.
Length: 0–40000

bash

curl -X POST https://api.aquavoice.com/v1/sessions/ses_a1e2c85b1cbf43af9dc678a1a7423dcc/feedback \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{"feedback_type":"positive","message":"...","corrected_text":"..."}'

json

{
  "object": "session_feedback",
  "session_id": "ses_a1e2c85b1cbf43af9dc678a1a7423dcc",
  "feedback_type": "positive",
  "message": "Keep the product name capitalized.",
  "corrected_text": "Send this from Aqua Voice.",
  "updated_at": "2026-08-11T17:03:00Z"
}

Clear session feedback

DELETE/sessions/{session_id}/feedback

OAuth scope: write

Removes any feedback stored for the session.

Parameters

session_id stringrequired: Path parameter. A missing session and a session owned by another user both return 404 session_not_found.
Pattern: ^ses_[0-9a-f]{32}$
Aqua-User string: Header. Required with an organization key on product and dictation routes: the member's user id, the same id GET /me returns. A missing header returns 400 user_required; a user who is not an active member returns 403 user_not_member. Transcription routes and personal keys ignore the header.
Pattern: ^usr_[0-9a-f]{32}$

bash

curl -X DELETE https://api.aquavoice.com/v1/sessions/ses_a1e2c85b1cbf43af9dc678a1a7423dcc/feedback \
  -H "Authorization: Bearer <api-key>"

Dictation

Aqua dictation and voice editing with the user's preferences and customizations.

Dictate or edit text

POST/dictations

OAuth scope: write

Runs Aqua's normal dictation pipeline and returns when the text is ready. The request stays open while Aqua transcribes and formats the audio, for up to 210 seconds. It does not create a public background job. Send an Idempotency-Key and retry the same request with the same key if the connection closes. A terminal result replays for 24 hours without another inference or charge. After Aqua dispatches the audio, an uncertain upstream failure is terminal for that key so a retry cannot create a second dictation.

Aqua applies the user's language setting, dictionary, replacements, custom instructions, casual messaging preference, and learned preferences. A request language overrides the saved language for this dictation. The returned session_id identifies the session stored in Aqua history. Privacy and zero-data-retention settings still apply: the text is returned to the caller but is not stored when retention is off.

An organization key acts as one member: send Aqua-User with the member's user id. The dictation is billed to the account that owns the key.

Use operation=edit with selected_text to run Edit Mode. The optional text and app fields give Aqua the same surrounding context it uses when dictating into an app.

Dictate and Edit Mode bill at the same rate; see Billing.

Parameters

Idempotency-Key string: Header. Optional idempotency value. Use the same value of 1–255 printable ASCII characters for retries of one logical request. Terminal results replay for 24 hours; different request content returns 409 idempotency_conflict.
Length: 1–255
Aqua-User string: Header. Required with an organization key on product and dictation routes: the member's user id, the same id GET /me returns. A missing header returns 400 user_required; a user who is not an active member returns 403 user_not_member. Transcription routes and personal keys ignore the header.
Pattern: ^usr_[0-9a-f]{32}$

Body (multipart/form-data)

audio

filerequired

A canonical 16 kHz mono PCM16 WAV file, up to 25 MiB and 10 minutes.

operation

string enum

Use edit to apply the spoken instruction to selected_text.

One of: dictate edit

Default: dictate

selected_text

string

Required when operation is edit.

Length: 0–6000

language

LanguageCode

One of: auto ar be bn bg yue ca hr cs da nl en et fi fr gl de el he hi hu id ga it ja ko lv lt ms mt cmn mr mn no fa pl pt ro ru sl es sw sv ta th tr uk ur vi cy yi

app

string

Name of the app where the text will be used.

Length: 0–255

app_bundle_id

string

Bundle ID or package name for the app.

Length: 0–255

text_before

string

Text immediately before the insertion or selection.

Length: 0–6000

text_after

string

Text immediately after the insertion or selection.

Length: 0–6000

focused_element_description

string

Accessible description of the target text field.

Length: 0–1000

bash

curl -X POST https://api.aquavoice.com/v1/dictations \
  -H "Authorization: Bearer <api-key>" \
  -F "audio=@audio.wav" \
  -F "operation=dictate" \
  -F "language=auto"

json

{
  "object": "dictation",
  "session_id": "ses_a1e2c85b1cbf43af9dc678a1a7423dcc",
  "operation": "dictate",
  "raw_text": "hello aqua can you send the update",
  "text": "Hello, Aqua! Can you send the update?",
  "language": "auto",
  "duration_seconds": 2.84,
  "edit_unclear": false,
  "edit_deleted": false
}

Customizations

Dictionary terms, text replacements, and custom transcript instructions.

Get transcript customizations

GET/customizations

OAuth scope: read

Parameters

Aqua-User string: Header. Required with an organization key on product and dictation routes: the member's user id, the same id GET /me returns. A missing header returns 400 user_required; a user who is not an active member returns 403 user_not_member. Transcription routes and personal keys ignore the header.
Pattern: ^usr_[0-9a-f]{32}$

bash

curl https://api.aquavoice.com/v1/customizations \
  -H "Authorization: Bearer <api-key>"

json

{
  "object": "customizations",
  "revision": 12,
  "updated_at": "2026-08-11T17:03:00Z",
  "dictionary": [
    "Aquaphone"
  ],
  "replacements": [
    {
      "from": "AV",
      "to": "Aqua Voice"
    }
  ],
  "custom_instructions": "Keep issue keys such as AQUA-142 in uppercase."
}

Apply transcript customization operations

PATCH/customizations

OAuth scope: write

Applies all operations atomically. expected_revision prevents a caller from overwriting a newer change. A stale revision returns 409 transcript_customizations_conflict; read the latest state, merge, and retry.

Parameters

Aqua-User string: Header. Required with an organization key on product and dictation routes: the member's user id, the same id GET /me returns. A missing header returns 400 user_required; a user who is not an active member returns 403 user_not_member. Transcription routes and personal keys ignore the header.
Pattern: ^usr_[0-9a-f]{32}$

Body

expected_revision integerrequired: Range: 0–…
operations array of CustomizationOperationrequired: Items: 1–100

bash

curl -X PATCH https://api.aquavoice.com/v1/customizations \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{"expected_revision":42,"operations":[{"type":"dictionary_add","word":"..."}]}'

json

{
  "object": "customizations",
  "revision": 12,
  "updated_at": "2026-08-11T17:03:00Z",
  "dictionary": [
    "Aquaphone"
  ],
  "replacements": [
    {
      "from": "AV",
      "to": "Aqua Voice"
    }
  ],
  "custom_instructions": "Keep issue keys such as AQUA-142 in uppercase."
}

Settings

Aqua app preferences supported by the public API.

Get app settings

GET/settings

OAuth scope: read

Parameters

Aqua-User string: Header. Required with an organization key on product and dictation routes: the member's user id, the same id GET /me returns. A missing header returns 400 user_required; a user who is not an active member returns 403 user_not_member. Transcription routes and personal keys ignore the header.
Pattern: ^usr_[0-9a-f]{32}$

bash

curl https://api.aquavoice.com/v1/settings \
  -H "Authorization: Bearer <api-key>"

json

{
  "object": "settings",
  "language": "auto",
  "casual_messaging": true
}

Update app settings

PATCH/settings

OAuth scope: write

Only fields present in the request change. Null values and unknown fields are rejected.

Parameters

Aqua-User string: Header. Required with an organization key on product and dictation routes: the member's user id, the same id GET /me returns. A missing header returns 400 user_required; a user who is not an active member returns 403 user_not_member. Transcription routes and personal keys ignore the header.
Pattern: ^usr_[0-9a-f]{32}$

Body

language LanguageCode: One of: auto ar be bn bg yue ca hr cs da nl en et fi fr gl de el he hi hu id ga it ja ko lv lt ms mt cmn mr mn no fa pl pt ro ru sl es sw sv ta th tr uk ur vi cy yi
casual_messaging boolean

bash

curl -X PATCH https://api.aquavoice.com/v1/settings \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{"language":"auto","casual_messaging":true}'

json

{
  "object": "settings",
  "language": "auto",
  "casual_messaging": true
}

Transcription (Avalon)

Avalon batch speech-to-text. OpenAI-compatible.

Compatibility: Use the official OpenAI Python or JavaScript SDK with the base URL https://api.aquavoice.com/v1 and model avalon-v1.5.
Timeouts: Synchronous requests wait up to 210 seconds. If a stored job returns 504 request_timeout, its body carries error.job_id; poll that job to follow its status.
Retries: Send a 1–255-character Idempotency-Key with retries. Matching results replay for 24 hours without another inference or charge. Different request content with the same key returns 409.
Limits: Responses include x-should-retry and, when applicable, Retry-After and x-ratelimit-* headers. Rates are listed under Billing.

Transcribe audio synchronously

POST/audio/transcriptions

Uses a 210-second overall deadline. If the wait times out after the job is stored, processing continues and the 504 request_timeout error body carries error.job_id; poll that job to follow its status. The x-request-id response header carries the same value.

Parameters

Idempotency-Key string: Header. Optional idempotency value. Use the same value of 1–255 printable ASCII characters for retries of one logical request. Terminal results replay for 24 hours; different request content returns 409 idempotency_conflict.
Length: 1–255
X-Client-Request-Id string: Header. Optional printable ASCII correlation value of up to 512 characters. It does not provide idempotency.
Length: 0–512

Body (multipart/form-data)

file

filerequired

Audio in flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, or webm format. Maximum 25 MiB and one hour of decoded audio.

model

string enumrequired

The Avalon model to use.

One of: avalon-v1.5

language

string

ISO 639-1 language code. Omit it or use auto to detect the language.

prompt

string

Context or vocabulary hints for the transcription.

response_format

string enum

Response format. Defaults to json.

One of: json text srt vtt verbose_json

Default: json

temperature

number enum

Compatibility no-op. Nonzero values are unsupported.

One of: 0

stream

boolean enum

Avalon is batch-only, so only false is accepted.

One of: false

Default: false

timestamp_granularities

array of string enum

Only segment is supported, and only with verbose_json.

bash

curl -X POST https://api.aquavoice.com/v1/audio/transcriptions \
  -H "Authorization: Bearer <api-key>" \
  -F "file=@audio.mp3" \
  -F "model=avalon-v1.5" \
  -F "language=auto"

json

{
  "text": "The beta is stable enough to expand next week.",
  "usage": {
    "type": "duration",
    "seconds": 17.8
  }
}

Start an asynchronous transcription

POST/audio/transcription-jobs

Returns after the audio is validated and the job is stored. Poll the returned job ID or fetch its result when result_url is present.

Parameters

Idempotency-Key string: Header. Optional idempotency value. Use the same value of 1–255 printable ASCII characters for retries of one logical request. Terminal results replay for 24 hours; different request content returns 409 idempotency_conflict.
Length: 1–255
X-Client-Request-Id string: Header. Optional printable ASCII correlation value of up to 512 characters. It does not provide idempotency.
Length: 0–512

Body (multipart/form-data)

file

filerequired

Audio in flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, or webm format. Maximum 25 MiB and one hour of decoded audio.

model

string enumrequired

The Avalon model to use.

One of: avalon-v1.5

language

string

ISO 639-1 language code. Omit it or use auto to detect the language.

prompt

string

Context or vocabulary hints for the transcription.

response_format

string enum

Response format. Defaults to json.

One of: json text srt vtt verbose_json

Default: json

temperature

number enum

Compatibility no-op. Nonzero values are unsupported.

One of: 0

stream

boolean enum

Avalon is batch-only, so only false is accepted.

One of: false

Default: false

timestamp_granularities

array of string enum

Only segment is supported, and only with verbose_json.

bash

curl -X POST https://api.aquavoice.com/v1/audio/transcription-jobs \
  -H "Authorization: Bearer <api-key>" \
  -F "file=@audio.mp3" \
  -F "model=avalon-v1.5" \
  -F "language=auto"

json

{
  "id": "req_01k2j4wr1ns8h4f7s2ckm6h1p9",
  "object": "transcription.job",
  "status": "queued",
  "created_at": "2026-08-11T17:03:00Z",
  "completed_at": null,
  "audio_duration_seconds": 17.8,
  "error_code": null,
  "result_url": null
}

Get an asynchronous transcription job

GET/audio/transcription-jobs/{job_id}

Parameters

job_id stringrequired: Path parameter.

bash

curl https://api.aquavoice.com/v1/audio/transcription-jobs/... \
  -H "Authorization: Bearer <api-key>"

json

{
  "id": "req_01k2j4wr1ns8h4f7s2ckm6h1p9",
  "object": "transcription.job",
  "status": "queued",
  "created_at": "2026-08-11T17:03:00Z",
  "completed_at": null,
  "audio_duration_seconds": 17.8,
  "error_code": null,
  "result_url": null
}

Get a completed transcription result

GET/audio/transcription-jobs/{job_id}/result

Returns 409 job_not_complete while the job is queued. The error is retryable and includes the standard retry headers.

Parameters

job_id stringrequired: Path parameter.

bash

curl https://api.aquavoice.com/v1/audio/transcription-jobs/.../result \
  -H "Authorization: Bearer <api-key>"

json

{
  "text": "The beta is stable enough to expand next week.",
  "usage": {
    "type": "duration",
    "seconds": 17.8
  }
}

List transcription models

GET/models

bash

curl https://api.aquavoice.com/v1/models \
  -H "Authorization: Bearer <api-key>"

json

{
  "object": "list",
  "data": [
    {
      "id": "avalon-v1.5",
      "object": "model",
      "created": 1754870400,
      "owned_by": "aqua"
    }
  ]
}

Get a transcription model

GET/models/{model}

Parameters

model stringrequired: Path parameter.

bash

curl https://api.aquavoice.com/v1/models/avalon-v1.5 \
  -H "Authorization: Bearer <api-key>"

json

{
  "id": "avalon-v1.5",
  "object": "model",
  "created": 1754870400,
  "owned_by": "aqua"
}

Objects

Request and response objects. Treat enum values as open sets.

Principal

id stringrequired: Pattern: ^usr_[0-9a-f]{32}$
object "user"required
email stringrequired
name string, nullablerequired
created_at string, nullablerequired
credential Credentialrequired
privacy_mode booleanrequired
history_available booleanrequired: True when enterprise policy permits stored history.

json

{
  "id": "usr_1daef426873f44baaf2096903dc7283e",
  "object": "user",
  "email": "maya@northstar.studio",
  "name": "Maya Chen",
  "created_at": "2026-08-11T17:03:00Z",
  "credential": {
    "id": "key_7d4d4d5ad69942fe9ceef628f5ba7bdd",
    "method": "api_key",
    "scopes": [
      "read"
    ]
  },
  "privacy_mode": false,
  "history_available": true
}

SessionSummary

object "session"required
id stringrequired: Pattern: ^ses_[0-9a-f]{32}$
kind string enumrequired: One of: dictation recording
created_at stringrequired
updated_at stringrequired
status stringrequired
title string, nullablerequired
app string, nullablerequired
duration_seconds number, nullablerequired
word_count integerrequired
preview stringrequired
summary string, nullablerequired
action_items_count integerrequired: Range: 0–…
match SessionSearchMatch

json

{
  "object": "session",
  "id": "ses_a1e2c85b1cbf43af9dc678a1a7423dcc",
  "kind": "recording",
  "created_at": "2026-08-11T17:03:00Z",
  "updated_at": "2026-08-11T17:03:00Z",
  "status": "stopped",
  "title": "Weekly product review",
  "app": "Zoom",
  "duration_seconds": 1842.7,
  "word_count": 4218,
  "preview": "The beta is stable enough to expand next week.",
  "summary": "The team approved a wider beta and assigned the launch checklist.",
  "action_items_count": 3,
  "match": {
    "source": "summary",
    "snippet": "The team approved a wider beta for Tuesday."
  }
}

SessionDetail

object "session"required
id stringrequired: Pattern: ^ses_[0-9a-f]{32}$
kind string enumrequired: One of: dictation recording
created_at stringrequired
updated_at stringrequired
status stringrequired
title string, nullablerequired
app string, nullablerequired
duration_seconds number, nullablerequired
word_count integerrequired
preview stringrequired
summary string, nullablerequired
action_items array of stringrequired
action_items_count integerrequired: Range: 0–…

json

{
  "object": "session",
  "id": "ses_a1e2c85b1cbf43af9dc678a1a7423dcc",
  "kind": "recording",
  "created_at": "2026-08-11T17:03:00Z",
  "updated_at": "2026-08-11T17:03:00Z",
  "status": "stopped",
  "title": "Weekly product review",
  "app": "Zoom",
  "duration_seconds": 1842.7,
  "word_count": 4218,
  "preview": "The beta is stable enough to expand next week.",
  "summary": "The team approved a wider beta and assigned the launch checklist.",
  "action_items": [
    "Send the revised launch checklist by Friday."
  ],
  "action_items_count": 3
}

SessionTranscript

object "transcript"required
session_id stringrequired: Pattern: ^ses_[0-9a-f]{32}$
final_text stringrequired
raw_text string, nullablerequired

json

{
  "object": "transcript",
  "session_id": "ses_a1e2c85b1cbf43af9dc678a1a7423dcc",
  "final_text": "The beta is stable enough to expand next week.",
  "raw_text": "the beta is stable enough to expand next week"
}

DictationResult

object "dictation"required
session_id stringrequired: Pattern: ^ses_[0-9a-f]{32}$
operation string enumrequired: One of: dictate edit
raw_text stringrequired: Speech recognition output before Aqua formatting.
text stringrequired: Final Aqua text, ready to insert or use as the edit replacement.
language LanguageCoderequired: One of: auto ar be bn bg yue ca hr cs da nl en et fi fr gl de el he hi hu id ga it ja ko lv lt ms mt cmn mr mn no fa pl pt ro ru sl es sw sv ta th tr uk ur vi cy yi
duration_seconds numberrequired: Range: 0–…
edit_unclear booleanrequired: True when Edit Mode could not determine the requested change.
edit_deleted booleanrequired: True when Edit Mode intentionally removed the selected text.

json

{
  "object": "dictation",
  "session_id": "ses_a1e2c85b1cbf43af9dc678a1a7423dcc",
  "operation": "dictate",
  "raw_text": "hello aqua can you send the update",
  "text": "Hello, Aqua! Can you send the update?",
  "language": "auto",
  "duration_seconds": 2.84,
  "edit_unclear": false,
  "edit_deleted": false
}

SessionFeedback

object "session_feedback"required
session_id stringrequired: Pattern: ^ses_[0-9a-f]{32}$
feedback_type string enumrequired: One of: positive negative
message string, nullablerequired
corrected_text string, nullablerequired
updated_at stringrequired

json

{
  "object": "session_feedback",
  "session_id": "ses_a1e2c85b1cbf43af9dc678a1a7423dcc",
  "feedback_type": "positive",
  "message": "Keep the product name capitalized.",
  "corrected_text": "Send this from Aqua Voice.",
  "updated_at": "2026-08-11T17:03:00Z"
}

Customizations

object "customizations"required
revision integerrequired: Range: 0–…
updated_at string, nullablerequired
dictionary array of stringrequired
replacements array of Replacementrequired
custom_instructions stringrequired

json

{
  "object": "customizations",
  "revision": 12,
  "updated_at": "2026-08-11T17:03:00Z",
  "dictionary": [
    "Aquaphone"
  ],
  "replacements": [
    {
      "from": "AV",
      "to": "Aqua Voice"
    }
  ],
  "custom_instructions": "Keep issue keys such as AQUA-142 in uppercase."
}

Settings

object "settings"required
language LanguageCode | nullrequired
casual_messaging boolean, nullablerequired

json

{
  "object": "settings",
  "language": "auto",
  "casual_messaging": true
}

ErrorEnvelope

error ErrorDetailrequired

json

{
  "error": {
    "code": "payment_method_required",
    "message": "Add a payment method to continue",
    "details": {},
    "docs_url": "https://aquavoice.com/docs/api#billing",
    "billing_url": "https://app.aquavoice.com/api-dashboard?tab=billing"
  }
}

Transcription

task "transcribe"
text stringrequired
language string
duration number
segments array of object
usage objectrequired

json

{
  "task": "transcribe",
  "text": "The beta is stable enough to expand next week.",
  "language": "en",
  "duration": 17.8,
  "segments": [
    {
      "start": 0,
      "end": 4.2,
      "text": "The beta is stable enough to expand next week."
    }
  ],
  "usage": {
    "type": "duration",
    "seconds": 17.8
  }
}

TranscriptionJob

id stringrequired
object "transcription.job"required
status string enumrequired: One of: queued succeeded failed cancelled abandoned
created_at stringrequired
completed_at string, nullablerequired
audio_duration_seconds number, nullablerequired
error_code string, nullablerequired
result_url string, nullablerequired

json

{
  "id": "req_01k2j4wr1ns8h4f7s2ckm6h1p9",
  "object": "transcription.job",
  "status": "queued",
  "created_at": "2026-08-11T17:03:00Z",
  "completed_at": null,
  "audio_duration_seconds": 17.8,
  "error_code": null,
  "result_url": null
}

Model

id stringrequired
object "model"required
created integerrequired
owned_by "aqua"required

json

{
  "id": "avalon-v1.5",
  "object": "model",
  "created": 1754870400,
  "owned_by": "aqua"
}

AvalonError

error objectrequired

json

{
  "error": {
    "message": "The audio file is larger than 25 MiB.",
    "type": "invalid_request_error",
    "param": "file",
    "code": "file_too_large",
    "job_id": "req_01k2j4wr1ns8h4f7s2ckm6h1p9",
    "docs_url": "...",
    "billing_url": "..."
  }
}