Scribewren API

The Scribewren API runs the same pipeline as the app: you upload a file, a transcription job runs, and you read the transcript or export it as text, a document or subtitles. It is plain HTTPS and JSON, so any language with an HTTP client works.

The API is part of the Unlimited plan at no extra price. It shares that plan’s limits and fair use, so there is no separate API quota. Free accounts get a 403 FEATURE_NOT_IN_PLAN response. See pricing for what each plan includes.

Quick facts

Topic	Detail
Base URL	https://api.scribewren.com/v1
Authentication	Authorization: Bearer with an API key. See Authentication
Plan	Unlimited only
Format	JSON in and out, with camelCase field names. Request bodies are application/json
Media bytes	Sent straight to storage with presigned URLs. The API never receives your audio or video
Cookies, CORS, CSRF	None. This host reads and sets no cookies, sends no CORS headers and needs no CSRF token. Call it from a server or script, not from browser JavaScript
Rate limits	Per key and per account. See Rate limits
Management	Keys and webhook endpoints are managed in Settings → API in the app, not through the API

Start here

Quickstart Upload a file, wait for the result and download subtitles with curl.

Authentication Create a key and send it with each request.

Webhooks Get a signed call when a transcription finishes.

Errors The error envelope and every error code.

Endpoints

Every path below is relative to the base URL. Anything not listed here is not served on this host and returns 404 NOT_FOUND. A listed path called with the wrong method returns 405 METHOD_NOT_ALLOWED.

Method and path	Purpose	Page
POST /media	Start an upload	Uploads
POST /media/{id}/parts	Get presigned URLs for file parts	Uploads
GET /media/{id}/parts	List the parts already stored	Uploads
POST /media/{id}/complete	Finish the upload and queue the transcription	Uploads
DELETE /media/{id}	Abort a pending upload	Uploads
GET /media?status=pending_upload	List uploads that are not finished	Uploads
GET /transcriptions	List and filter transcriptions	Transcriptions
GET /transcriptions/{id}	Read status, progress and metadata	Transcriptions
POST /transcriptions/{id}/cancel	Cancel a queued or running job	Transcriptions
POST /transcriptions/{id}/retry	Run a failed or canceled job again	Transcriptions
DELETE /transcriptions/{id}	Delete a transcription	Transcriptions
GET /transcriptions/{id}/segments	Read the transcript, page by page	Segments
GET /transcriptions/{id}/export	Download TXT, DOCX, PDF, SRT or VTT	Export
GET /me/usage	Read today’s and this month’s usage	Usage
GET /plans	List plans (no key needed)	Usage
GET /languages	List supported languages (no key needed)	Usage

Response envelope

Every response, success or error, uses one envelope.

{
  "success": true,
  "code": 200,
  "message": "OK",
  "data": {},
  "error": null,
  "meta": {
    "requestId": "019a4f30-1c22-7a10-b5d3-42f1c0a8e777",
    "timestamp": "2026-12-01T09:41:07.512Z"
  }
}

• code repeats the HTTP status. message is a short human-readable text. Do not branch on it. Branch on the HTTP status and, for errors, on error.code.
• On success error is null. On failure data is null and error is { "code": "…", "details": {} }. See Errors.
• meta.requestId also arrives as the X-Request-ID response header. You can send your own X-Request-ID (up to 64 characters from letters, digits, dot, underscore and hyphen) and it is echoed back. Any other value is replaced. Quote the request ID when you contact support.
• Export responses are the one exception: they return the file itself, not an envelope. See Export.

Pagination

List endpoints that use pages take page (from 1) and limit (1 to 100, default 25) and add four fields to meta: page, limit, totalItems and totalPages.

The segments endpoint pages by cursor instead, with fromSeq and nextSeq. See Segments.

Conventions

• IDs are UUIDs (version 7). Treat them as opaque strings.
• Timestamps are UTC, ISO 8601, ending in Z. Durations are integer milliseconds and fields that hold one end in Ms.
• Enum values are lowercase snake_case, such as pending_upload. Error codes are UPPER_SNAKE_CASE.
• Unknown fields in a request body are rejected with VALIDATION_ERROR, so a typo does not pass silently.
• A resource that belongs to another account returns 404 NOT_FOUND, the same as one that does not exist.
• Within /v1, changes are additive. See Versioning.

Lifecycles

Media (the uploaded file):

pending_upload → uploaded → processed, or rejected with a rejectReason.

Transcription (the job):

queued → running → succeeded, failed or canceled.

While a transcription is running, its stage moves through downloading, preprocessing, transcribing, diarizing and finalizing, and progress runs from 0 to 100.

Privacy

Scribewren does not use your data to train models. Original files are deleted within 24 hours of a terminal state. Webhook payloads and error messages never contain transcript text, titles or file names. See the Privacy Policy.