Skip to main content

Getting started with the REST API

This page describes how to perform common operations with the REST API. Each endpoint is documented individually and grouped by the resource it interacts with, such as Transcript and LeMUR.

The AssemblyAI API uses REST with JSON-encoded request bodies and responses, and is available at the following URL:

Base URL
https://api.assemblyai.com
Streaming Speech-to-Text

This page explains the AssemblyAI REST API. If you want to use Streaming Speech-to-Text, see Streaming API reference.

Client SDKs

AssemblyAI provides official SDKs for popular programming languages, that make it simpler to interact with the API.

To get started using the SDKs, see the following resources:

Authorization

To make authorized calls the REST API, your app must provide an authorization header with an API key. You can find your API key in the AssemblyAI dashboard.

Authenticated request
curl https://api.assemblyai.com/v2/transcript \
--header 'Authorization: YOUR_API_KEY'
Your API key

The examples here contain a placeholder, YOUR_API_KEY, that you need to replace with your actual API key.

If you're signed in to your AssemblyAI account, all placeholders are instead replaced with your actual API key, so you can run any example right away.

Errors

The AssemblyAI API uses HTTP response codes to indicate whether a request was successful.

The response codes generally fall into the following ranges:

  • 2xx indicates the request was successful.
  • 4xx indicates the request may have omitted a required parameter, or have invalid information.
  • 5xx indicates an error on AssemblyAI's end.

Below is a summary of the HTTP response codes you may encounter:

200OKRequest was successful.
400Bad requestThe request failed due to an invalid request.
401UnauthorizedMissing or invalid API key.
404Not foundThe requested resource doesn't exist.
429Too many requestsToo many request were sent to the API. See Rate limits for more information.
500, 503, 504Server errorSomething went wrong on AssemblyAI's end.
Response with error
{
"error": "Authentication error, API token missing/invalid"
}
API status

To stay up-to-date with any known service disruptions, subscribe to updates on the Status page.

Failed transcriptions

Transcriptions may fail due to errors while processing the audio data.

When you query a transcription that has failed, the response will have a 200 code, along with status set to error and an error property with more details.

Failed transcription
{
"status": "error",
"error": "Download error to https://foo.bar, 403 Client Error: Forbidden for url: https://foo.bar",
...
}

Common reasons why a transcription may fail include:

  • Audio data is corrupted or in an unsupported format. See FAQ for supported formats.
  • Audio URL is a webpage rather than a file. Only the AssemblyAI Playground supports retrieving videos directly from YouTube links.
  • Audio URL isn't accessible from AssemblyAI's servers.
  • Audio duration is too short (less than 200 ms).

In the rare event of a transcription failure due to a server error, you may resubmit the file for transcription. If the problems persist after resubmitting, let us know.

Rate limits

To ensure the API remains available for all users, AssemblyAI limits the number of API requests you can make within a certain amount of time.

If you exceed the rate limit, the API will respond with a 429 status code.

Some endpoints may have more restrictive rate limits. To determine the rate limit for a specific endpoint, check the response for the following headers:

X-RateLimit-LimitMaximum number of allowed requests in a 60 second window.
X-RateLimit-RemainingNumber of remaining requests in the current time window.
X-RateLimit-ResetNumber of seconds until the remaining requests resets to the value of X-RateLimit-Limit.

If the response doesn't include X-RateLimit headers, the endpoint doesn't have rate limits.

Increasing rate limits

If you want to increase the rate limit for your account, contact us.

Pagination

Endpoints that support listing multiple resources use pagination to limit the number of results returned in a single response.

Paginated responses include a page_details JSON object with information about the results and links to navigate between pages.

page_details[i].limitMaximum number of resources in a page.
page_details[i].result_countTotal number of available resources.
page_details[i].current_urlURL to the current page.
page_details[i].prev_urlURL to the previous page.
page_details[i].next_urlURL to the next page.
Paginated response
{
"page_details": {
"limit": 1,
"result_count": 1,
"current_url": "https://api.assemblyai.com/v2/transcript?limit=1",
"prev_url": "https://api.assemblyai.com/v2/transcript?limit=1&before_id=bfc3622e-8c69-4497-9a84-fb65b30dcb07",
"next_url": "https://api.assemblyai.com/v2/transcript?limit=1&after_id=bfc3622e-8c69-4497-9a84-fb65b30dcb07"
},
"transcripts": [
{
// ...
}
]
}

Versioning

When AssemblyAI makes backwards-incompatible changes to the API, we release a new version. For information on API updates, see Changelog.

Endpoints are versioned using a path prefix, such as /v2.

Need help?

If you have any questions or need help using the API, you can talk to our Support team, or join our Discord community.