Reference / API referenceSign inRequest access

API reference

Every endpoint, parameter and response, generated from the API contract. Requests go to your project's API address with your key as a bearer token.

Transcriptions

Long recordings: upload, start a transcription, then poll or receive a webhook.

POST/v1/transcriptions

Start a transcription

Parameters

Idempotency-Keyheader
Retry safely: the same key with the same request returns the original transcription.

Request body · application/json

audioobject
Required
The audio to transcribe.
upload_idstring
Required
A `complete` upload in this project.
languagestring
Required
A language code from /v1/models, e.g. hi-IN, ta-IN, en-IN.
modeenum
How the transcript is written: native script, code-mixed (English words in English) or verbatim.
native · codemix · verbatim
Default "native"
timestampsenum
Segment start and end times, or none. Word timestamps are coming soon.
none · segment · wordSOON
Default "segment"
diarizationboolean | object
Label segments with speakers.
Default false
channel_modeenum
`separate` transcribes each channel of a stereo recording on its own (billed per channel).
mix · separate
Default "mix"
webhook_endpoint_idstring
Endpoint to notify when the transcription finishes.
modelstring
Optional. The model ID from /v1/models; defaults to the current model.

Responses

200
Idempotent replay of an earlier request.
202
Accepted; credit is reserved and the work is queued.
4xx · 5xx
An error object — see Errors and retries.
Response fields
idstring
Required
object"transcription"
Required
modelstring
Required
versionstring
Required
stateenum
Required
queued · preparing · transcribing · finalizing · completed · partial · failed · cancelled
requestobject
Required
languagestring
Required
modeenum
Required
native · codemix · verbatim
timestampsenum
Required
none · segment · wordSOON
diarizationboolean
Required
channel_modeenum
Required
mix · separate
created_atstring
Required
finished_atstring | null
Required
result_urlstring
errorobject
codestring
Required
messagestring
Required
content_deleted_atstring
progressinteger | null
Percent of the audio transcribed: 0 before work starts, measured progress while transcribing (null until the first report), 100 when a result exists; null for failed or cancelled.
GET/v1/transcriptions

List transcriptions

Parameters

limitquery
Page size (1–100).
afterquery
ID of the last item of the previous page.
statequery
Comma-separated states.

Responses

200
Newest first.
4xx · 5xx
An error object — see Errors and retries.
Response fields
object"list"
Required
dataobject[]
Required
nextstring | null
Required
GET/v1/transcriptions/{transcription_id}

Get a transcription

Parameters

transcription_idpath
Required
Identifier.

Responses

200
Current state.
4xx · 5xx
An error object — see Errors and retries.
Response fields
idstring
Required
object"transcription"
Required
modelstring
Required
versionstring
Required
stateenum
Required
queued · preparing · transcribing · finalizing · completed · partial · failed · cancelled
requestobject
Required
languagestring
Required
modeenum
Required
native · codemix · verbatim
timestampsenum
Required
none · segment · wordSOON
diarizationboolean
Required
channel_modeenum
Required
mix · separate
created_atstring
Required
finished_atstring | null
Required
result_urlstring
errorobject
codestring
Required
messagestring
Required
content_deleted_atstring
progressinteger | null
Percent of the audio transcribed: 0 before work starts, measured progress while transcribing (null until the first report), 100 when a result exists; null for failed or cancelled.
DELETE/v1/transcriptions/{transcription_id}

Delete a transcription’s audio and transcript

Parameters

transcription_idpath
Required
Identifier.

Responses

200
Content deleted; the record and its usage remain.
4xx · 5xx
An error object — see Errors and retries.
Response fields
idstring
Required
object"transcription"
Required
modelstring
Required
versionstring
Required
stateenum
Required
queued · preparing · transcribing · finalizing · completed · partial · failed · cancelled
requestobject
Required
languagestring
Required
modeenum
Required
native · codemix · verbatim
timestampsenum
Required
none · segment · wordSOON
diarizationboolean
Required
channel_modeenum
Required
mix · separate
created_atstring
Required
finished_atstring | null
Required
result_urlstring
errorobject
codestring
Required
messagestring
Required
content_deleted_atstring
progressinteger | null
Percent of the audio transcribed: 0 before work starts, measured progress while transcribing (null until the first report), 100 when a result exists; null for failed or cancelled.
GET/v1/transcriptions/{transcription_id}/result

Get the result

Parameters

transcription_idpath
Required
Identifier.
formatquery
`json` (default) or `txt` (plain text). `srt` and `vtt` are coming soon.
json · txt · srt · vtt

Responses

200
Transcript with segments.
4xx · 5xx
An error object — see Errors and retries.
Response fields
idstring
Required
object"transcription.result"
Required
modelstring
Required
versionstring
Required
statusenum
Required
completed · partial
modeenum
Required
native · codemix · verbatim
duration_secondsnumber
Required
channelsinteger
Required
languagesstring[]
Required
textstring
Required
segmentsobject[]
Required
warningsenum[]
Required
gapsobject[]
POST/v1/transcriptions/{transcription_id}/cancel

Cancel a transcription

Parameters

transcription_idpath
Required
Identifier.

Responses

200
Cancelled (or already finished). Cancelled work is not charged.
4xx · 5xx
An error object — see Errors and retries.
Response fields
idstring
Required
object"transcription"
Required
modelstring
Required
versionstring
Required
stateenum
Required
queued · preparing · transcribing · finalizing · completed · partial · failed · cancelled
requestobject
Required
languagestring
Required
modeenum
Required
native · codemix · verbatim
timestampsenum
Required
none · segment · wordSOON
diarizationboolean
Required
channel_modeenum
Required
mix · separate
created_atstring
Required
finished_atstring | null
Required
result_urlstring
errorobject
codestring
Required
messagestring
Required
content_deleted_atstring
progressinteger | null
Percent of the audio transcribed: 0 before work starts, measured progress while transcribing (null until the first report), 100 when a result exists; null for failed or cancelled.

Synchronous

Short audio in one request.

POST/v1/audio/transcriptions

Transcribe short audio in one request

For short audio (see `limits` in /v1/models). Returns the finished result. When capacity is not immediately available it returns 503 with Retry-After; use the asynchronous flow for long recordings.

Parameters

Idempotency-Keyheader
Retry safely: the same key with the same request returns the original transcription.

Request body · multipart/form-data

filefile
Required
The audio file.
languagestring
Required
A language code from /v1/models, e.g. hi-IN.
modeenum
How the transcript is written: native script, code-mixed (English words in English) or verbatim.
native · codemix · verbatim
timestampsenum
Segment start and end times, or none. Word timestamps are coming soon.
none · segment · wordSOON
diarizationboolean
Label segments with speakers.
channel_modeenum
`separate` transcribes each channel of a stereo recording on its own (billed per channel).
mix · separate
modelstring
Optional. The model ID from /v1/models; defaults to the current model.

Responses

200
Finished transcript.
4xx · 5xx
An error object — see Errors and retries.
Response fields
idstring
Required
object"transcription.result"
Required
modelstring
Required
versionstring
Required
statusenum
Required
completed · partial
modeenum
Required
native · codemix · verbatim
duration_secondsnumber
Required
channelsinteger
Required
languagesstring[]
Required
textstring
Required
segmentsobject[]
Required
warningsenum[]
Required
gapsobject[]

Uploads

Send audio straight to storage with a signed URL (or resumable upload for large files).

POST/v1/uploads

Create an upload

Request body · application/json

bytesinteger
Required
Exact size of the file in bytes.
sha256string
Optional SHA-256 of the file (lower-case hex); the upload is rejected if the stored bytes differ.

Responses

201
Where to send the file.
4xx · 5xx
An error object — see Errors and retries.
Response fields
idstring
Required
object"upload"
Required
state"allocated"
Required
bytesinteger
Required
expires_ininteger
Required
uploadobject
Required
methodstring
Required
urlstring
Required
headersobject
Required
resumable_uploadobject
Present when resumable (tus) upload is available; recommended above 50 MB.
protocol"tus"
endpointstring
chunk_sizeinteger
headersobject
metadataobject
POST/v1/uploads/{upload_id}/complete

Mark an upload complete

Parameters

upload_idpath
Required
Identifier.

Responses

200
Verified.
202
Large file: verification continues in the background; poll GET /v1/uploads/{upload_id}.
4xx · 5xx
An error object — see Errors and retries.
Response fields
idstring
Required
object"upload"
Required
stateenum
Required
allocated · verifying · complete · rejected
bytesinteger
duration_secondsnumber
channelsinteger
deletedboolean
errorobject
codeenum
audio_decode_failed · upload_rejected
GET/v1/uploads/{upload_id}

Get an upload

Parameters

upload_idpath
Required
Identifier.

Responses

200
Upload state.
4xx · 5xx
An error object — see Errors and retries.
Response fields
idstring
Required
object"upload"
Required
stateenum
Required
allocated · verifying · complete · rejected
bytesinteger
duration_secondsnumber
channelsinteger
deletedboolean
errorobject
codeenum
audio_decode_failed · upload_rejected

Account

Models, usage and credit, webhooks.

GET/v1/models

List models and capabilities

Responses

200
Languages, modes, capabilities (available or coming soon) and limits.
4xx · 5xx
An error object — see Errors and retries.
Response fields
object"list"
Required
dataobject[]
Required
GET/v1/usage

Usage events and credit

Parameters

limitquery
Page size (1–100).
afterquery
Return items older than this ID — the `next` value of the previous page.

Responses

200
One event per finished transcription.
4xx · 5xx
An error object — see Errors and retries.
Response fields
object"usage"
Required
currency"INR"
Required
price_paise_per_audio_hourinteger
Required
creditobject
Required
balance_paiseinteger
Required
reserved_paiseinteger
Required
available_paiseinteger
Required
dataobject[]
Required
nextstring | null
Required
POST/v1/webhook_endpoints

Register a webhook endpoint

Request body · application/json

urlstring
Required
HTTPS URL that receives events.

Responses

201
Created. A signed verification event is sent to the URL first; `verified` reports whether it was answered with a 2xx.
4xx · 5xx
An error object — see Errors and retries.
Response fields
idstring
Required
object"webhook_endpoint"
Required
urlstring
Required
verifiedboolean
Required
A signed verification event was answered with a 2xx. Transcriptions can name only verified endpoints.
disabledboolean
Required
created_atstring
Required
secretstring
Signing secret. Returned only when created or rotated.
secret_rotated_atstring | null
previous_secret_expires_atstring | null
After a rotation, deliveries are also signed with the previous secret until this time.
verification_passedboolean
Only on POST …/verify: whether this verification attempt succeeded.
GET/v1/webhook_endpoints

List webhook endpoints

Responses

200
Endpoints of this project (no secrets).
4xx · 5xx
An error object — see Errors and retries.
Response fields
object"list"
dataobject[]
GET/v1/webhook_endpoints/{webhook_id}

Get a webhook endpoint

Parameters

webhook_idpath
Required
Identifier.

Responses

200
The endpoint.
4xx · 5xx
An error object — see Errors and retries.
Response fields
idstring
Required
object"webhook_endpoint"
Required
urlstring
Required
verifiedboolean
Required
A signed verification event was answered with a 2xx. Transcriptions can name only verified endpoints.
disabledboolean
Required
created_atstring
Required
secretstring
Signing secret. Returned only when created or rotated.
secret_rotated_atstring | null
previous_secret_expires_atstring | null
After a rotation, deliveries are also signed with the previous secret until this time.
verification_passedboolean
Only on POST …/verify: whether this verification attempt succeeded.
DELETE/v1/webhook_endpoints/{webhook_id}

Disable a webhook endpoint

Parameters

webhook_idpath
Required
Identifier.

Responses

200
Disabled; no further deliveries.
4xx · 5xx
An error object — see Errors and retries.
Response fields
idstring
Required
object"webhook_endpoint"
Required
urlstring
Required
verifiedboolean
Required
A signed verification event was answered with a 2xx. Transcriptions can name only verified endpoints.
disabledboolean
Required
created_atstring
Required
secretstring
Signing secret. Returned only when created or rotated.
secret_rotated_atstring | null
previous_secret_expires_atstring | null
After a rotation, deliveries are also signed with the previous secret until this time.
verification_passedboolean
Only on POST …/verify: whether this verification attempt succeeded.
POST/v1/webhook_endpoints/{webhook_id}/verify

Verify a webhook endpoint again

Sends a signed `webhook_endpoint.verification` event; any 2xx marks the endpoint verified.

Parameters

webhook_idpath
Required
Identifier.

Responses

200
Result of the verification.
4xx · 5xx
An error object — see Errors and retries.
Response fields
idstring
Required
object"webhook_endpoint"
Required
urlstring
Required
verifiedboolean
Required
A signed verification event was answered with a 2xx. Transcriptions can name only verified endpoints.
disabledboolean
Required
created_atstring
Required
secretstring
Signing secret. Returned only when created or rotated.
secret_rotated_atstring | null
previous_secret_expires_atstring | null
After a rotation, deliveries are also signed with the previous secret until this time.
verification_passedboolean
Only on POST …/verify: whether this verification attempt succeeded.
POST/v1/webhook_endpoints/{webhook_id}/rotate_secret

Rotate the signing secret

Returns a new secret once. For 24 hours deliveries carry signatures from both the new and the previous secret, so receivers can switch without missing events.

Parameters

webhook_idpath
Required
Identifier.

Responses

200
New secret (shown once).
4xx · 5xx
An error object — see Errors and retries.
Response fields
idstring
Required
object"webhook_endpoint"
Required
urlstring
Required
verifiedboolean
Required
A signed verification event was answered with a 2xx. Transcriptions can name only verified endpoints.
disabledboolean
Required
created_atstring
Required
secretstring
Signing secret. Returned only when created or rotated.
secret_rotated_atstring | null
previous_secret_expires_atstring | null
After a rotation, deliveries are also signed with the previous secret until this time.
verification_passedboolean
Only on POST …/verify: whether this verification attempt succeeded.
GET/v1/webhook_endpoints/{webhook_id}/deliveries

List deliveries

Parameters

webhook_idpath
Required
Identifier.
limitquery
Page size (1–200).

Responses

200
Most recent first.
4xx · 5xx
An error object — see Errors and retries.
Response fields
object"list"
dataobject[]
POST/v1/webhook_deliveries/{delivery_id}/replay

Replay a delivery

Sends the same event again with the same webhook-id, so receivers can de-duplicate. Not allowed while the delivery is still being retried.

Parameters

delivery_idpath
Required
Identifier.

Responses

200
Queued.
4xx · 5xx
An error object — see Errors and retries.
Response fields
idstring
Required
Also the webhook-id header value.
object"webhook_delivery"
Required
endpoint_idstring
Required
transcription_idstring
Required
event_typestring
Required
statusenum
Required
pending · delivered · failed
attemptsinteger
Required
replaysinteger
Required
last_errorstring | null
created_atstring
Required
next_attempt_atstring | null

Webhook events

POSTyour endpoint

A transcription finished

Sent to the endpoint named in a transcription's webhook_endpoint_id when it finishes: transcription.completed, transcription.partial, transcription.failed or transcription.cancelled. Fetch the result with GET /v1/transcriptions/{id}/result. Signed with headers webhook-id, webhook-timestamp and webhook-signature ("v1,<base64 HMAC-SHA256 of id.timestamp.body>").

Body

typeenum
Required
transcription.completed · transcription.partial · transcription.failed · transcription.cancelled
dataobject
Required
idstring
Required
statestring
Required
errorobject
Scriba is a product of 26AI Private Limited, Pune, India.© 2026 26AI Private Limited