API reference

Archives

4 operations. Base URL https://api.scarleta.ai. Select an operation to see its parameters, samples and errors.

Jump to an operation

POST/v1/audio/archives

Download files as a zip

Free and paid accounts

API key required
Free and paid accounts
No token cost

Packs files you choose into a zip. Send up to 5000 audio_ids of your own files. A selection of at most 1000 files and 2 GiB is answered at once with mode: "stream" and a download_url: fetch it with a plain GET and no API key within 10 minutes; it works once and returns the zip. A larger selection returns 202 with mode: "async": the zip is built in the background in parts, read the archive until it is completed, then fetch each part (the archive stays downloadable for 7 days). Every id must be one of your files, otherwise nothing is packed and the call returns 404 files_not_found naming the ids it could not find. Counts against the hourly account request budget. Available to free and paid accounts.

Cost. Free of charge.

curl -X POST "https://api.scarleta.ai/v1/audio/archives" \
  -H "Authorization: Bearer $SCARLETA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "audio_ids": [
      "audio_bbb14949dc19"
    ]
  }'

Request body

Name	Type	Required	Description
audio_idsbody	array<string>	Required	Library identifiers (`audio_id`) of the files to pack, 1 to 5000.

Response fields

Field	Type	Description
mode	"stream"
job_id	string	Identifier of the archive.
download_url	string	Address to `GET` the zip from, with no API key. Works once.
expires_at	string	When the link stops working, as an ISO 8601 timestamp.

Errors

Status	Code	Description
400	invalid_audio_ids	`audio_ids` is empty, too long, or has an entry that is not a non-empty string.
401	invalid_key	Missing, malformed, unknown or revoked API key.
404	files_not_found	At least one id is not one of your files; `error.details.missing` lists them.
409	file_unavailable	A file in the selection has no readable content at the moment.
429	rate_limit_exceeded	Over the account request budget. Wait for the `Retry-After` header, then retry.
503	archive_unavailable	The background build could not start. Retry shortly.

Example responses

{
  "data": {
    "mode": "stream",
    "job_id": "5d7f9b1c-3e5a-4c7e-9b0d-1f2a3b4c5d6e",
    "download_url": "https://api.scarleta.ai/v1/audio/archives/stream/Zk3p0q8vN1x2Y4b6C8d0E2f4G6h8J0kL2mN4pQ6rS8t",
    "expires_at": "2026-10-20T12:03:45.938Z"
  }
}

200 A one-time download link. The body is `{ data }` without `meta`. The response carries `Cache-Control: no-store`.
202 The archive is being built. Read it until it is completed. Same body shape rules as the 200.
400 `audio_ids` is empty, too long, or has an entry that is not a non-empty string.
401 Missing, malformed, unknown or revoked API key.
404 At least one id is not one of your files; `error.details.missing` lists them.
409 A file in the selection has no readable content at the moment.
429 Over the account request budget. Wait for the `Retry-After` header, then retry.
503 The background build could not start. Retry shortly.

Try it

Sends this request from your browser to https://api.scarleta.ai with your own key. The key stays in this page only (never saved or put in the address) and is cleared when you leave. Revoke any key you have shared.

Other error codes this operation can return: auth_unavailable, db_unavailable, invalid_auth_format, invalid_json, invalid_key_format, missing_api_key, missing_auth, rate_limit_unavailable, unauthorized.

GET/v1/audio/archives/{jobId}

Get an archive

Free and paid accounts

API key required
Free and paid accounts
No token cost

Returns the state of an archive you requested: its status, progress and, once finished, its parts. Only your own archives can be read; any other id returns 404. Counts against the hourly account request budget. Available to free and paid accounts.

Cost. Free of charge.

JOBID="YOUR_JOBID"
curl "https://api.scarleta.ai/v1/audio/archives/$JOBID" \
  -H "Authorization: Bearer $SCARLETA_API_KEY"

Parameters

Name	Type	Required	Description
jobIdpath	string	Required	The `job_id` returned when the archive was requested.

Response fields

Field	Type	Description
job_id	string	Identifier of the archive.
kind	"selection" \| "takeout"	`selection` for files you chose, `takeout` for your whole library.
mode	"stream" \| "async"	`stream` is a one-time download link; `async` is built in the background in parts.
status	"queued" \| "running" \| "completed" \| "failed" \| "expired"
file_count	integer	Allowed: -9007199254740991 to 9007199254740991.
total_bytes	number	Total size of the files in bytes.
progress_bytes	number	Bytes processed so far.
parts	array<object>	The finished zip parts, once `completed`.
parts[].n	integer	Allowed: -9007199254740991 to 9007199254740991.
parts[].bytes	number
parts[].file_count	integer	Allowed: -9007199254740991 to 9007199254740991.
error	string \| null
created_at	string	ISO 8601 timestamp.
completed_at	string \| null
expires_at	string \| null	When the download stops working.

Errors

Status	Code	Description
401	invalid_key	Missing, malformed, unknown or revoked API key.
404	archive_not_found	No archive with this id in your account.
429	rate_limit_exceeded	Over the account request budget. Wait for the `Retry-After` header, then retry.
503	db_unavailable	The archive could not be read. Retry shortly.

Example responses

{
  "data": {
    "job_id": "5d7f9b1c-3e5a-4c7e-9b0d-1f2a3b4c5d6e",
    "kind": "selection",
    "mode": "stream",
    "status": "queued",
    "file_count": 1,
    "total_bytes": 1920044,
    "progress_bytes": 0,
    "parts": [],
    "error": null,
    "created_at": "2026-10-20T11:53:45.938Z",
    "completed_at": null,
    "expires_at": "2026-10-20T12:03:45.938Z"
  }
}

200 The archive. The body is `{ data }` without `meta`.
401 Missing, malformed, unknown or revoked API key.
404 No archive with this id in your account.
429 Over the account request budget. Wait for the `Retry-After` header, then retry.
503 The archive could not be read. Retry shortly.

Try it

Other error codes this operation can return: auth_unavailable, invalid_auth_format, invalid_key_format, missing_api_key, missing_auth, rate_limit_unavailable, unauthorized.

GET/v1/audio/archives/{jobId}/parts/{n}/url

Get the download link of an archive part

Free and paid accounts

API key required
Free and paid accounts
No token cost

For an archive that is built in the background (mode: "async"), returns a link for one finished zip part. Fetch url with a plain GET and no API key within 60 minutes; ask again for a fresh link when it expires. Part numbers start at 1 and are listed in the archive's parts. A one-time download link (mode: "stream") has no parts. The response carries Cache-Control: no-store. Counts against the hourly account request budget. Available to free and paid accounts.

Cost. Free of charge.

JOBID="YOUR_JOBID"
N="YOUR_N"
curl "https://api.scarleta.ai/v1/audio/archives/$JOBID/parts/$N/url" \
  -H "Authorization: Bearer $SCARLETA_API_KEY"

Parameters

Name	Type	Required	Description
jobIdpath	string	Required	The `job_id` of the archive.
npath	string	Required	Part number, starting at 1.

Response fields

Field	Type	Description
url	string	Where to `GET` the part. Opaque; use it as returned.
expires_at	string	ISO 8601 timestamp.

Errors

Status	Code	Description
401	invalid_key	Missing, malformed, unknown or revoked API key.
404	archive_part_not_found	No archive with this id in your account (`archive_not_found`), or it has no such part.
409	archive_not_ready	The archive has not finished building. Read it until its status is `completed`.
410	archive_expired	The archive is past its retention time. Start a new one.
429	rate_limit_exceeded	Over the account request budget. Wait for the `Retry-After` header, then retry.
503	storage_unavailable	Storage cannot create the link at the moment (`storage_unavailable`), or the database is unavailable (`db_unavailable`). Retry shortly.

Example responses

{
  "data": {
    "url": "https://storage.example.com/archives/part-1.zip?signature=…",
    "expires_at": "2026-10-21T05:00:00.000Z"
  }
}

200 A link for the part. The body is `{ data }` without `meta`.
401 Missing, malformed, unknown or revoked API key.
404 No archive with this id in your account (`archive_not_found`), or it has no such part.
409 The archive has not finished building. Read it until its status is `completed`.
410 The archive is past its retention time. Start a new one.
429 Over the account request budget. Wait for the `Retry-After` header, then retry.
503 Storage cannot create the link at the moment (`storage_unavailable`), or the database is unavailable (`db_unavailable`). Retry shortly.

Try it

Other error codes this operation can return: archive_not_found, auth_unavailable, db_unavailable, invalid_auth_format, invalid_key_format, missing_api_key, missing_auth, rate_limit_unavailable, unauthorized.

POST/v1/audio/archives/takeout

Download your whole library

Free and paid accounts

API key required
Free and paid accounts
No token cost

Starts a background build of a zip of your entire library (originals and their renders), split into parts of at most 50 GiB. Read the archive with the returned job_id until it is completed, then fetch each part with the part URL route; the parts stay downloadable for 7 days. Only one takeout can be in progress at a time: asking again while one is queued or running returns the same job_id with HTTP 200 instead of 202. Counts against the hourly account request budget. Available to free and paid accounts.

Cost. Free of charge.

curl -X POST "https://api.scarleta.ai/v1/audio/archives/takeout" \
  -H "Authorization: Bearer $SCARLETA_API_KEY"

Response fields

Field	Type	Description
job_id	string	Identifier of the takeout already in progress.
status	"queued" \| "running"

Errors

Status	Code	Description
401	invalid_key	Missing, malformed, unknown or revoked API key.
429	rate_limit_exceeded	Over the account request budget. Wait for the `Retry-After` header, then retry.
503	archive_unavailable	The background build could not start. Retry shortly.

Example responses

{
  "data": {
    "job_id": "5d7f9b1c-3e5a-4c7e-9b0d-1f2a3b4c5d6e",
    "status": "running"
  }
}

200 A takeout is already in progress; this is its identifier.
202 A new takeout was started. The body is `{ data }` without `meta`.
401 Missing, malformed, unknown or revoked API key.
429 Over the account request budget. Wait for the `Retry-After` header, then retry.
503 The background build could not start. Retry shortly.

Try it

Other error codes this operation can return: auth_unavailable, db_unavailable, invalid_auth_format, invalid_key_format, missing_api_key, missing_auth, rate_limit_unavailable, unauthorized.