Developer documentation

ActaScribe API v1

You send a URL. We do the work. You get plain transcript text back.

Stable · v1REST · JSONapi.actascribe.ai/v1

Overview

What this API does

The ActaScribe API lets your application send audio files and YouTube videos to ActaScribe, then receive the transcripts back. It returns transcript text only — no summaries, action items, or key points like you see in the web app. If you want only the transcript, this is the right tool. For the full structured output, use the web app or contact us about a custom plan.

Three types of input are supported. All three return the same shape of transcript when complete:

Audio file — a direct link to mp3, m4a, wav, mp4, or similar formats.
YouTube video — a single standard YouTube video URL or short URL.
YouTube playlist — every video in the playlist is processed, up to 100 per request.

Reference

Base URL

All endpoints live under a single versioned host:

https://api.actascribe.ai/v1

Getting started

Getting an API key

Sign in to ActaScribe.
Open Settings, then API keys.
Click Create new key.
Give the key a name, for example Production backend.
Pick the permissions you want this key to have. For most uses you need transcripts:read and transcripts:write.
Optionally set an expiry date and an IP allowlist.
Copy the key when it appears. It starts with as_live_.

You will only see the full key once. If you lose it, create a new one — the old value cannot be recovered.

Security

Authenticating requests

Send your API key as a Bearer token in the Authorization header on every request.

Authorization: Bearer as_live_yourkeyhere

Requests without a valid key receive a 401 response.

Access control

Permissions (scopes)

Each key carries a list of permissions. The API enforces them per endpoint. For typical use, request a key with both transcripts:write and transcripts:read.

Scope	Lets the key
`transcripts:write`	Submit new transcripts (`POST /v1/transcripts`)
`transcripts:read`	Read existing transcripts (`GET /v1/transcripts/{id}`)
`talkbase:query`	Reserved for a future TalkBase endpoint
`admin`	Acts as a superset. Satisfies any scope check.

Lifecycle

How transcripts move through the system

Every transcript you create moves through four states. Until the status is complete, the transcript field in the GET response is null.

Status	Meaning
`pending`	Accepted, waiting to start.
`processing`	We are fetching the audio or captions and transcribing.
`complete`	The transcript text is ready to read.
`failed`	Something went wrong. The transcript will not retry on its own.

A short audio file usually completes in under a minute. A long YouTube video can take a few minutes. Playlists complete one video at a time, in parallel where possible.

Endpoint

Create a transcript

POST/v1/transcripts

Sends a new audio file, video, or playlist to ActaScribe for transcription. Requires transcripts:write. The request body must include exactly one of audio_url, youtube_url, or youtube_playlist_url. Sending more than one returns a 400 error.

Request fields

Field	Type	Required	Notes
`audio_url`	string	one of three	Public HTTPS URL to an audio file. Must be reachable from the public internet. Private network addresses are rejected.
`youtube_url`	string	one of three	A standard YouTube video URL or short URL.
`youtube_playlist_url`	string	one of three	A YouTube playlist URL. Up to 100 videos are processed per request.
`language`	string	optional	ISO language code such as `en`, `es`, `fr`. Improves accuracy when set.
`title`	string	optional	Custom title to store on the transcript. Defaults to a sensible value based on the source.

Example: single audio file

Request · curl

curl -X POST https://api.actascribe.ai/v1/transcripts \
  -H "Authorization: Bearer as_live_yourkeyhere" \
  -H "Content-Type: application/json" \
  -d '{
    "audio_url": "https://example.com/podcasts/episode-42.mp3",
    "language": "en",
    "title": "Episode 42"
  }'

Response · 202 Accepted

{
  "id": "5b8a3f1c-7d2e-4f6a-9b1c-3e5d8a7f0c2b",
  "status": "pending",
  "source": {
    "type": "audio",
    "url": "https://example.com/podcasts/episode-42.mp3"
  }
}

Save the id. You will use it to fetch the transcript once processing finishes.

Example: single YouTube video

Request · curl

curl -X POST https://api.actascribe.ai/v1/transcripts \
  -H "Authorization: Bearer as_live_yourkeyhere" \
  -H "Content-Type: application/json" \
  -d '{
    "youtube_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
  }'

Response · 202 Accepted

{
  "id": "8c4d2a1f-6b3e-4d5a-8f7c-1d2e3f4a5b6c",
  "status": "pending",
  "source": {
    "type": "youtube",
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
  }
}

Example: YouTube playlist

Request · curl

curl -X POST https://api.actascribe.ai/v1/transcripts \
  -H "Authorization: Bearer as_live_yourkeyhere" \
  -H "Content-Type: application/json" \
  -d '{
    "youtube_playlist_url": "https://www.youtube.com/playlist?list=PLrAXtmErZgOdP_8GztsuKi9nrraNbKKp4"
  }'

Response · 202 Accepted

{
  "playlist_url": "https://www.youtube.com/playlist?list=PLrAXtmErZgOdP_8GztsuKi9nrraNbKKp4",
  "total_in_playlist": 23,
  "accepted": 23,
  "truncated": false,
  "items": [
    {
      "id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
      "status": "pending",
      "source": { "type": "youtube", "url": "https://www.youtube.com/watch?v=AAAAA" }
    },
    {
      "id": "2b3c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e",
      "status": "pending",
      "source": { "type": "youtube", "url": "https://www.youtube.com/watch?v=BBBBB" }
    }
  ]
}

If a playlist contains more than 100 videos, the first 100 are accepted and truncated is set to true. Resubmit with a different starting point, or split the playlist into smaller ones before submitting.

Endpoint

Get a transcript

GET/v1/transcripts/{id}

Returns the transcript record. Requires transcripts:read. While the transcript is still processing, the response shape is the same but the transcript field is null. Once status becomes complete, it contains the text.

Request · curl

curl https://api.actascribe.ai/v1/transcripts/5b8a3f1c-7d2e-4f6a-9b1c-3e5d8a7f0c2b \
  -H "Authorization: Bearer as_live_yourkeyhere"

Response · while processing

Response · 200 · processing

{
  "id": "5b8a3f1c-7d2e-4f6a-9b1c-3e5d8a7f0c2b",
  "status": "processing",
  "source": {
    "type": "audio",
    "url": "https://example.com/podcasts/episode-42.mp3"
  },
  "language": "en",
  "duration_seconds": null,
  "transcript": null,
  "created_at": "2026-06-25T14:12:08.213Z",
  "updated_at": "2026-06-25T14:12:09.041Z"
}

Response · when complete

Response · 200 · complete

{
  "id": "5b8a3f1c-7d2e-4f6a-9b1c-3e5d8a7f0c2b",
  "status": "complete",
  "source": {
    "type": "audio",
    "url": "https://example.com/podcasts/episode-42.mp3"
  },
  "language": "en",
  "duration_seconds": 1842,
  "transcript": {
    "text": "Welcome to episode 42. Today we are talking about ...",
    "segments": [
      { "start": 0.0, "end": 4.2, "speaker": "0",
        "text": "Welcome to episode 42." },
      { "start": 4.2, "end": 9.8, "speaker": "0",
        "text": "Today we are talking about supply chain analytics." }
    ]
  },
  "created_at": "2026-06-25T14:12:08.213Z",
  "updated_at": "2026-06-25T14:14:51.882Z"
}

The text field contains the full transcript as one continuous string. The segments array breaks it into time-stamped lines with speaker labels when available. Use whichever fits your application.

Response fields

Field	Notes
`id`	The transcript id you received from POST.
`status`	One of `pending`, `processing`, `complete`, `failed`.
`source.type`	One of `audio`, `youtube`.
`source.url`	The original URL you submitted.
`language`	ISO language code, detected during transcription if not supplied.
`duration_seconds`	Total length of the audio in seconds. Populated once known.
`transcript.text`	Full transcript text. `null` until status is `complete`.
`transcript.segments`	Time-stamped lines with speaker labels. May be empty for YouTube videos that only return continuous text.
`created_at`	When the transcript was submitted.
`updated_at`	When the row last changed.

Workflow

Polling for completion

There is no webhook callback today. To know when a transcript is ready, poll the GET endpoint. A reasonable pattern:

Wait 30 seconds.
Call GET /v1/transcripts/{id}.
If status is pending or processing, wait another 30 seconds and repeat.
If status is complete, read the transcript field.
If status is failed, log the failure and stop polling. Submit a new request if you want to retry.

Stop polling after a reasonable maximum, for example 30 minutes. If a transcript has not completed by then, something is wrong and a retry is unlikely to help.

Errors

Error responses

All errors return a JSON body in the RFC 9457 problem+json format. The HTTP status code matches the status field in the body.

Example · 403

{
  "type": "https://actascribe.ai/errors/insufficient-scope",
  "title": "API key does not have the required scope",
  "status": 403,
  "detail": "This endpoint requires the 'transcripts:write' scope."
}

Common errors

Status	Type	When it happens
400	`bad-request`	Missing field, malformed JSON, or invalid URL.
401	`missing-auth`	No `Authorization` header was sent.
401	`invalid-key`	The key was not recognized, has expired, or was revoked.
403	`ip-not-allowed`	The request came from an IP not on the key's allowlist.
403	`insufficient-scope`	The key does not have the permission this endpoint requires.
404	`not-found`	No transcript with that id exists in your workspace.
502	`upstream-failure`	A service we depend on (YouTube playlist resolver, transcription provider) failed.
500	`internal`	An unexpected error on our side. Retry once; contact us if it persists.

Constraints

Limits and behavior

Playlists are capped at 100 videos per request. Larger playlists are accepted up to that limit and the response includes truncated: true.
Audio URLs must be public. Private network addresses (localhost, 10.x, 192.168.x, and similar) are rejected to prevent misuse.
Audio URLs must stay reachable until processing starts. Once we have fetched the file, you can delete or move it.
Concurrency is shared across all keys in your workspace. If you submit many requests at once, some will queue behind others.
There is no rate limit enforced today. Reasonable use is expected. We will publish hard limits before introducing them.
There is no list endpoint today. Keep track of the ids returned by POST in your own system.

Status of the API

This is version 1

We will publish version 2 if and when breaking changes are required. Older versions will continue to receive security updates and bug fixes.

Help, bug reports, or feature requests: support@actascribe.ai.

ActaScribe AI · API v1 Reference · api.actascribe.ai/v1