API reference

File details

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

Jump to an operation

GET/v1/audio/{audioId}/cover

Download the cover image of a file

Free and paid accounts

API key required
Free and paid accounts
No token cost

Returns the cover image of one of your files. The response body is the image itself (image/jpeg, image/png or image/webp), not JSON, and may be cached privately for five minutes. Works for files in the trash too. A file with no cover is 404 cover_not_found; a file that is not yours or does not exist is 404 not_found. If the database is briefly unavailable the route answers 503 db_unavailable; retry after a short wait.

Cost. Free of charge.

AUDIOID="YOUR_AUDIOID"
curl "https://api.scarleta.ai/v1/audio/$AUDIOID/cover" \
  -H "Authorization: Bearer $SCARLETA_API_KEY" \
  --fail \
  -o output.jpg

Parameters

Name	Type	Required	Description
audioIdpath	string	Required	The `audio_id` or the file id of one of your files.

Errors

Status	Code	Description
401	invalid_key	Missing, malformed, unknown or revoked API key.
404	cover_not_found	The file has no cover (`cover_not_found`), or it does not exist or is not yours (`not_found`).
429	rate_limit_exceeded	Over the account request budget or the per-minute cap of this route. Wait for the `Retry-After` header, then retry.
503	auth_unavailable	Temporary platform condition; retry shortly.

Example responses

Binary file
Content-Type: image/jpeg | image/png | image/webp

200 The cover image. The body is binary, not JSON.
401 Missing, malformed, unknown or revoked API key.
404 The file has no cover (`cover_not_found`), or it does not exist or is not yours (`not_found`).
429 Over the account request budget or the per-minute cap of this route. Wait for the `Retry-After` header, then retry.
503 Temporary platform condition; retry shortly.

Try it

This operation returns a stream or a file, which the response panel cannot show. Use the cURL sample.

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

PUT/v1/audio/{audioId}/cover

Set the cover image of a file

Free and paid accounts

API key required
Free and paid accounts
No token cost

Stores a cover image for one of your files, replacing any earlier one. The request body is the image itself, not JSON: a JPEG, PNG or WebP of at most 4 MiB (4194304 bytes). Send the matching Content-Type; the format is recognised from the bytes, so a file in another format, or an empty body, is 400 invalid_image, and a larger one is 413 image_too_large. A file that is not yours, does not exist or is in the trash is 404 not_found. The answer is the address to fetch the cover from. If storage or the database is briefly unavailable the route answers 503 upload_unavailable; retry after a short wait. Success is { data } without meta.

Cost. Free of charge.

AUDIOID="YOUR_AUDIOID"
curl -X PUT "https://api.scarleta.ai/v1/audio/$AUDIOID/cover" \
  -H "Authorization: Bearer $SCARLETA_API_KEY" \
  -H "Content-Type: image/jpeg" \
  --data-binary @./upload.jpg

Parameters

Name	Type	Required	Description
audioIdpath	string	Required	The `audio_id` or the file id of one of your files.

Response fields

Field	Type	Description
cover_url	string	Address to fetch the cover from. Send your API key with the request.

Errors

Status	Code	Description
400	invalid_image	The body is empty or is not a JPEG, PNG or WebP image.
401	invalid_key	Missing, malformed, unknown or revoked API key.
404	not_found	The file does not exist, is in the trash, or is not yours.
413	image_too_large	The image is larger than 4 MiB.
429	rate_limit_exceeded	Over the account request budget or the per-minute cap of this route. Wait for the `Retry-After` header, then retry.
503	auth_unavailable	Temporary platform condition; retry shortly.

Example responses

{
  "data": {
    "cover_url": "https://api.scarleta.ai/v1/audio/audio_3f9c1a7d2b60/cover"
  }
}

200 The cover is stored.
400 The body is empty or is not a JPEG, PNG or WebP image.
401 Missing, malformed, unknown or revoked API key.
404 The file does not exist, is in the trash, or is not yours.
413 The image is larger than 4 MiB.
429 Over the account request budget or the per-minute cap of this route. Wait for the `Retry-After` header, then retry.
503 Temporary platform condition; retry shortly.

Try it

This operation uploads a file or binary body, which a browser form cannot build. Use the cURL sample.

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

DELETE/v1/audio/{audioId}/cover

Remove the cover image of a file

Free and paid accounts

API key required
Free and paid accounts
No token cost

Removes the cover image of one of your files. The answer is 204 with no body. Removing a cover that is not there also answers 204. A file that is not yours, does not exist or is in the trash is 404 not_found. If the database is briefly unavailable the route answers 503 db_unavailable; retry after a short wait.

Cost. Free of charge.

AUDIOID="YOUR_AUDIOID"
curl -X DELETE "https://api.scarleta.ai/v1/audio/$AUDIOID/cover" \
  -H "Authorization: Bearer $SCARLETA_API_KEY" \
  -i

Parameters

Name	Type	Required	Description
audioIdpath	string	Required	The `audio_id` or the file id of one of your files.

Errors

Status	Code	Description
401	invalid_key	Missing, malformed, unknown or revoked API key.
404	not_found	The file does not exist, is in the trash, or is not yours.
429	rate_limit_exceeded	Over the account request budget or the per-minute cap of this route. Wait for the `Retry-After` header, then retry.
503	auth_unavailable	Temporary platform condition; retry shortly.

Example responses

(empty body)

204 The cover is removed. There is no body.
401 Missing, malformed, unknown or revoked API key.
404 The file does not exist, is in the trash, or is not yours.
429 Over the account request budget or the per-minute cap of this route. Wait for the `Retry-After` header, then retry.
503 Temporary platform condition; 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: db_unavailable, invalid_auth_format, invalid_key_format, missing_api_key, missing_auth, rate_limit_unavailable, unauthorized.

GET/v1/audio/{audioId}/details

Get the details of a file

Free and paid accounts

API key required
Free and paid accounts
No token cost

Returns the editable details of one of your files (title, artist, album, project, credits, tempo and key you entered) next to the tempo and key the analyses found, so you can show either. Works for files in the trash too, so the file page of a trashed file still loads. A file that is not yours or does not exist is 404 not_found. cover_url is where to fetch the cover image; it is null when the file has none. If the database is briefly unavailable the route answers 503 db_unavailable; retry after a short wait. Success is { data } without meta.

Cost. Free of charge.

AUDIOID="YOUR_AUDIOID"
curl "https://api.scarleta.ai/v1/audio/$AUDIOID/details" \
  -H "Authorization: Bearer $SCARLETA_API_KEY"

Parameters

Name	Type	Required	Description
audioIdpath	string	Required	The `audio_id` or the file id of one of your files.

Response fields

Field	Type	Description
audio_id	string	Registry identifier of the file; it starts with `audio_`.
title	string \| null	Title you set, or null.
artist	string \| null	Artist you set, or null.
album	string \| null	Album you set, or null.
project	string \| null	Project you set, or null.
credits	string \| null	Free-text credits you set, or null.
user_bpm	number \| null	Tempo you entered by hand, or null.
user_key_label	string \| null	Musical key you entered by hand, for example `A minor`, or null.
analysis_bpm	number \| null	Tempo found by the rhythm analysis, or null when the file has none.
analysis_key_label	string \| null	Key found by the harmony analysis, or null when the file has none.
embedded	object \| null	Tags read from inside the uploaded file (title, artist and so on), or null.
archived_at	string \| number \| null	When the file was archived, or null.
trashed_at	string \| number \| null	When the file was moved to the trash, or null.
cover_url	string \| null	Address of the cover image, or null when the file has no cover. Fetch it with your API key.

Errors

Status	Code	Description
401	invalid_key	Missing, malformed, unknown or revoked API key.
404	not_found	The file does not exist or is not yours.
429	rate_limit_exceeded	Over the account request budget or the per-minute cap of this route. Wait for the `Retry-After` header, then retry.
503	auth_unavailable	Temporary platform condition; retry shortly.

Example responses

{
  "data": {
    "audio_id": "audio_3f9c1a7d2b60",
    "title": "Morning Session",
    "artist": "Example Artist",
    "album": null,
    "project": "Demo EP",
    "credits": "Recorded at home",
    "user_bpm": 120,
    "user_key_label": "A minor",
    "analysis_bpm": 119.8,
    "analysis_key_label": "A minor",
    "embedded": null,
    "archived_at": null,
    "trashed_at": null,
    "cover_url": null
  }
}

200 The details of the file.
401 Missing, malformed, unknown or revoked API key.
404 The file does not exist or is not yours.
429 Over the account request budget or the per-minute cap of this route. Wait for the `Retry-After` header, then retry.
503 Temporary platform condition; retry shortly.

Try it

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

PATCH/v1/audio/{audioId}/details

Edit the details of a file

Free and paid accounts

API key required
Free and paid accounts
No token cost

Changes the details of one of your files. Send only the fields you want to change; a field you leave out stays as it is, and null clears it. A blank text becomes null. title, artist, album and project take at most 200 characters, credits at most 2000. user_bpm is a number from 20 to 300. user_key_label is a key such as A minor or C# major; it is stored in that normal form. Fields the route does not know are ignored. The answer is the updated details, as GET returns them. A file that is not yours, does not exist or is in the trash is 404 not_found; the file is checked before the fields.

A text field that is not a string is invalid_field; a text field longer than its limit is field_too_long; a user_key_label that is not a valid key is invalid_key_label. If the database is briefly unavailable the route answers 503 db_unavailable; retry after a short wait. Success is { data } without meta.

Cost. Free of charge.

AUDIOID="YOUR_AUDIOID"
curl -X PATCH "https://api.scarleta.ai/v1/audio/$AUDIOID/details" \
  -H "Authorization: Bearer $SCARLETA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Morning Session (final)",
    "user_bpm": 120,
    "user_key_label": "A minor"
  }'

Parameters

Name	Type	Required	Description
audioIdpath	string	Required	The `audio_id` or the file id of one of your files.

Request body

Name	Type	Required	Description
titlebody	string \| null	Optional	Title, at most 200 characters, or null to clear.
artistbody	string \| null	Optional	Artist, at most 200 characters, or null to clear.
albumbody	string \| null	Optional	Album, at most 200 characters, or null to clear.
projectbody	string \| null	Optional	Project, at most 200 characters, or null to clear.
creditsbody	string \| null	Optional	Credits, at most 2000 characters, or null to clear.
user_bpmbody	number \| null	Optional	Tempo in beats per minute, from 20 to 300, or null to clear.
user_key_labelbody	string \| null	Optional	Musical key such as `A minor` or `C# major`, or null to clear.

Response fields

Field	Type	Description
audio_id	string	Registry identifier of the file; it starts with `audio_`.
title	string \| null	Title you set, or null.
artist	string \| null	Artist you set, or null.
album	string \| null	Album you set, or null.
project	string \| null	Project you set, or null.
credits	string \| null	Free-text credits you set, or null.
user_bpm	number \| null	Tempo you entered by hand, or null.
user_key_label	string \| null	Musical key you entered by hand, for example `A minor`, or null.
analysis_bpm	number \| null	Tempo found by the rhythm analysis, or null when the file has none.
analysis_key_label	string \| null	Key found by the harmony analysis, or null when the file has none.
embedded	object \| null	Tags read from inside the uploaded file (title, artist and so on), or null.
archived_at	string \| number \| null	When the file was archived, or null.
trashed_at	string \| number \| null	When the file was moved to the trash, or null.
cover_url	string \| null	Address of the cover image, or null when the file has no cover. Fetch it with your API key.

Errors

Status	Code	Description
400	field_too_long	The body is not valid JSON (`invalid_json`); a text field is not a string (`invalid_field`) or is too long (`field_too_long`); `user_bpm` is out of range (`invalid_bpm`); or `user_key_label` is not a valid key (`invalid_key_label`).
401	invalid_key	Missing, malformed, unknown or revoked API key.
404	not_found	The file does not exist, is in the trash, or is not yours.
413	payload_too_large	The request body is larger than 64 KB.
429	rate_limit_exceeded	Over the account request budget or the per-minute cap of this route. Wait for the `Retry-After` header, then retry.
503	auth_unavailable	Temporary platform condition; retry shortly.

Example responses

{
  "data": {
    "audio_id": "audio_3f9c1a7d2b60",
    "title": "Morning Session (final)",
    "artist": "Example Artist",
    "album": null,
    "project": "Demo EP",
    "credits": "Recorded at home",
    "user_bpm": 120,
    "user_key_label": "A minor",
    "analysis_bpm": 119.8,
    "analysis_key_label": "A minor",
    "embedded": null,
    "archived_at": null,
    "trashed_at": null,
    "cover_url": null
  }
}

200 The updated details.
400 The body is not valid JSON (`invalid_json`); a text field is not a string (`invalid_field`) or is too long (`field_too_long`); `user_bpm` is out of range (`invalid_bpm`); or `user_key_label` is not a valid key (`invalid_key_label`).
401 Missing, malformed, unknown or revoked API key.
404 The file does not exist, is in the trash, or is not yours.
413 The request body is larger than 64 KB.
429 Over the account request budget or the per-minute cap of this route. Wait for the `Retry-After` header, then retry.
503 Temporary platform condition; retry shortly.

Try it

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