Speak AI API reference for audio, video, and text data

Reference for the Speak AI REST API: base URL, API key authentication, error format, and every endpoint for media, folders, recorders, and more.

The Speak AI API is a REST API for uploading audio, video, and text, reading the transcripts and insights Speak AI generates from them, and managing the folders, recorders, webhooks, and automations around them. It covers 185 endpoints across 27 resources.

What is the base URL for the Speak AI API?

The base URL for the Speak AI API is https://api.speakai.co/v1. Every path on this reference is relative to that base URL, so GET /media means GET https://api.speakai.co/v1/media.

How is the Speak AI API versioned?

The Speak AI API is versioned in the URL path. The base URL is https://api.speakai.co/[version] and the current version is v1, so every request goes to https://api.speakai.co/v1. The spec does not document a deprecation policy or any version other than v1.

How do you authenticate with the Speak AI API?

Send your API key on every Speak AI API call, in the x-speakai-key header. The API authenticates the request from the key alone, so you do not need an access token. Get your API key from the developer page in your Speak AI account.

curl -X GET 'https://api.speakai.co/v1/media' \
  -H 'x-speakai-key: sk_test_speak_0000000000000000'

You can send the same key as Authorization: Bearer instead of x-speakai-key. The API treats the two the same way.

What are the rate limits on the Speak AI API?

The two authentication endpoints, POST /auth/accessToken and POST /auth/refreshToken, are limited to 5 requests per 60 seconds, and going over returns 429 Too Many Requests. Back off and retry when you see a 429.

POST /live-transcription/token is limited the same way, to 5 requests per 60 seconds per IP address. It returns 429 with a plain text body rather than the usual JSON error, so mint one token per session and reuse it.

What does a Speak AI API error look like?

A failed Speak AI API call returns a JSON body with a status of failed, a requestId you can quote to support, a numeric code, a human readable message, and sometimes a hints array. This example is the response to a call made with an invalid API key.

{
  "status": "failed",
  "requestId": "ca665625-645e-438a-867d-366a6e3f133a",
  "code": 401,
  "message": "The authorization api key provided for the request is invalid.",
  "hints": [
    "The authorization api key provided for the request is invalid."
  ]
}

A successful call returns status: "success" with the payload under data. Note that the HTTP status line and the code field in the body do not always agree, so read the code field as well as the HTTP status.

Which endpoints does the Speak AI API have?

Speak AI groups its 185 endpoints into 27 resources, one page each. Each page lists every endpoint in that resource with its parameters, an example request, and the response shape.

Core API

Resource	Endpoints	What it covers
Authentication	2	Send your Speak AI API key in the x-speakai-key header or as a Bearer token on every request. Older integrations can keep using the access token flow.
Media	13	Upload audio and video to Speak AI, list your media library, poll processing status, read the transcript and insights, and run the analysis again.
Live transcription	3	Open a live transcription session in Speak AI, mint the token that authorizes the streaming connection, and send words and the recording back as it runs.
Text	4	Create a text note in Speak AI, read the insights generated from it, update the note when its content changes, and delete it when you are finished.
Exports	4	Export a transcript or its insights from Speak AI as PDF, DOCX, TXT, SRT, VTT, CSV, or JSON, one file at a time or several files in one request.
Folders	12	Create, list, clone, update, and delete Speak AI folders, and manage the saved views that control how the media inside a folder is filtered.
Recorders and surveys	11	Create and clone Speak AI recorders, set their questions and settings, generate share URLs, and read the recordings that respondents submit.
Media embeds	10	Create, check and update Speak AI media embeds, get the iframe URL for your page, and read each viewing session: who watched, how long, and what they did.
AI chat	3	Ask a question about the media stored in Speak AI and read the answer back, and list the AI chat prompts that have already run in your account.
Meeting assistant	4	Schedule the Speak AI meeting assistant to join a call, list your scheduled and past meeting events, and remove or delete an assistant booking.
Fields	4	Create custom fields in Speak AI, list every field defined in your account, and update a single field or a whole batch of fields in one request.
Labels	11	Manage your company’s labels and groups, add Speak label sets, and apply, move or remove labels on passages of a transcript without losing edits.
Comments	4	Post comment threads on a passage of a Speak AI transcript or on the whole file, reply, resolve and reopen threads, and edit or delete comments.
Notifications	2	List the in-app notifications in your Speak AI account, filter them by category such as label or comment activity, and mark your own as read.
Dashboards	3	Create and update Speak AI analytics dashboards, and choose what their share link shows: custom fields, feedback, labels, comments and reviewers.
Shared links	10	Read labels and comments through a dashboard share link or embed token, and let listed reviewers label passages and comment without signing in.
Automations	6	Create, read, update, and delete Speak AI automations, and turn an automation on or off without changing the trigger and action it is built from.
Admin	3	Create users in your Speak AI account, update an existing user, and list every user the account contains. These endpoints are for account admins.
Webhooks	5	Register a webhook so Speak AI posts events to your server, list and update the webhooks on your account, send a test payload, and delete a webhook.
Knowledge base	14	Create and manage document collections, add text documents to one, and attach it to a folder or agent so its content gets pulled into chats and calls.

Voice Agents

Resource	Endpoints	What it covers
Voice agents	9	Create, list, update, and delete voice agents; the avatar and voice catalogs they draw from; and generating or refining a config from a prompt.
Testing	13	Define scenarios for a voice agent, start and control test runs, read run history and score trends, and apply a run’s recommendations back to the agent.
Questions	8	Attach question templates to an agent, reorder them, and map a question’s answer onto a company Field. Manage the shared question-template library too.
Intelligence	16	Self-improvement surfaced from real calls: knowledge base gaps, FAQ suggestions, instruction gaps in the agent’s prompt, and its knowledge base links.
Conversations	3	List and inspect calls handled by your voice agents, including the event log for a single call. Completed calls link to a Media record via mediaId.
Sharing	4	Enable or disable an agent’s public share link, configure the embeddable widget’s look and copy, and upload a company logo for it to display.
Analytics	4	Workspace and per-agent call metrics: totals, completion rate, duration, engagement funnels, and a full per-agent report on audience, leads and outcomes.

How is this reference generated?

This reference is generated from an OpenAPI 3.0 specification committed to this repository at openapi/speak-api.json. That spec is hand-maintained and it is the source of truth. It started as an export from the Speak AI Postman collection, and the collection was dropped once it began describing paths the server does not serve. Do not edit these pages by hand, because the next generation run overwrites them. Edit the spec instead, check the change against the API server source, and re-run the generator.

Get an API key on the Speak AI developer page, then start with Authentication.