GET/v1/audio/ungrouped

Find files that are not yet a version of a track

Free and paid accounts

API key required
Free and paid accounts
No token cost

Lists your own top-level files that do not belong to any track group, optionally filtered by a name search. Use it to pick files to add as versions of a track. Only your own files are ever returned. limit defaults to 50 and larger values are lowered to 100.

This route answers with the older body shape: success is { data } with no meta.

Cost. Free of charge.

curl "https://api.scarleta.ai/v1/audio/ungrouped" \
  -H "Authorization: Bearer $SCARLETA_API_KEY"

Parameters

Name	Type	Required	Description
qquery	string	Optional	Keep files whose file name or display name contains this text.
excludequery	string	Optional	An `audio_id` to leave out of the result.
limitquery	integer	Optional	Files to return. Defaults to 50; larger values are lowered to 100. Allowed: 1 to 100.

Response fields

Field	Type	Description
[].audio_id	string
[].name	string
[].uploaded_at	string	Upload time in milliseconds since the Unix epoch, as a string.
[].file_size_bytes	number \| string \| null
[].format	string \| null

Errors

Status	Code	Description
401	invalid_key	Missing, malformed, unknown or revoked API key.
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",
      "name": "demo-mix.wav",
      "uploaded_at": "1791333870854",
      "file_size_bytes": 5290044,
      "format": "wav"
    }
  ]
}

200 The matching files. This response has no `meta`.
401 Missing, malformed, unknown or revoked API key.
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: invalid_auth_format, invalid_key_format, missing_api_key, missing_auth, rate_limit_unavailable, unauthorized.

GET/v1/audio/versions/{versionId}/audio-url

Get the audio URL of one version

Free and paid accounts

API key required
Free and paid accounts
No token cost

Returns the URL to pass as audio_url when running an analysis on one version of a track. versionId is the version's id or audio_id from the library list. audio_url is null when the original file is not stored. Only your own files are ever returned. On success this route answers { data } without meta; errors use the standard error body.

Cost. Free of charge.

VERSIONID="YOUR_VERSIONID"
curl "https://api.scarleta.ai/v1/audio/versions/$VERSIONID/audio-url" \
  -H "Authorization: Bearer $SCARLETA_API_KEY"

Parameters

Name	Type	Required	Description
versionIdpath	string	Required	The `id` or `audio_id` of a version in your library.

Response fields

Field	Type	Description
audio_url	string \| null	URL of the stored file, or null when only a link was stored.

Errors

Status	Code	Description
401	invalid_key	Missing, malformed, unknown or revoked API key.
404	file_not_found	No version with this id exists in your library.
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_url": "https://api.scarleta.ai/v1/audio/media/9b2c7d1e-5a40-4f83-b6c9-0d1e2f3a4b5c.wav"
  }
}

200 The URL of that version. This response has no `meta`.
401 Missing, malformed, unknown or revoked API key.
404 No version with this id exists in your library.
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, invalid_version_id, missing_api_key, missing_auth, rate_limit_unavailable, unauthorized.

POST/v1/audio/versions/add

Make a file a version of a track

Free and paid accounts

API key required
Free and paid accounts
No token cost

Groups source_audio_id as another version of the track that target_audio_id belongs to. If the target is not in a group yet, a group is created. Both files must be your own top-level files; a file that is already in a group, or the same file twice, is refused with 400 invalid_grouping. On success this route answers { data } without meta; errors use the standard error body.

Cost. Free of charge.

curl -X POST "https://api.scarleta.ai/v1/audio/versions/add" \
  -H "Authorization: Bearer $SCARLETA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "target_audio_id": "audio_3f9c1a7d2b60",
    "source_audio_id": "audio_a81e5c40d7f2"
  }'

Request body

Name	Type	Required	Description
target_audio_idbody	string	Required	A file of the track to add to. Allowed: at least 1 character.
source_audio_idbody	string	Required	The file that becomes a version of that track. Allowed: at least 1 character.

Response fields

Field	Type	Description
track_group_id	string	Identifier of the track group.
status	"grouped"

Errors

Status	Code	Description
400	invalid_grouping	A required field is missing or not a string (`invalid_body`), or the files cannot be grouped: the same file twice, a file already in a group, or a derived file (`invalid_grouping`).
401	invalid_key	Missing, malformed, unknown or revoked API key.
404	file_not_found	A file does not exist in your library.
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": {
    "track_group_id": "7d2c9e1a-4b3f-4c68-9a5d-1e0f8b7c6a52",
    "status": "grouped"
  }
}

200 The two files are now versions of one track. This response has no `meta`.
400 A required field is missing or not a string (`invalid_body`), or the files cannot be grouped: the same file twice, a file already in a group, or a derived file (`invalid_grouping`).
401 Missing, malformed, unknown or revoked API key.
404 A file does not exist in your library.
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_body, invalid_key_format, missing_api_key, missing_auth, rate_limit_unavailable, unauthorized.

POST/v1/audio/versions/remove

Remove a file from its track

Free and paid accounts

API key required
Free and paid accounts
No token cost

Takes a file out of its track group so it becomes a track of its own again. Calling it on a file that is not in a group succeeds and changes nothing. On success this route answers { data } without meta; errors use the standard error body.

Cost. Free of charge.

curl -X POST "https://api.scarleta.ai/v1/audio/versions/remove" \
  -H "Authorization: Bearer $SCARLETA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "audio_id": "audio_a81e5c40d7f2"
  }'

Request body

Name	Type	Required	Description
audio_idbody	string	Required	The file to take out of its track. Allowed: at least 1 character.

Response fields

Field	Type	Description
audio_id	string
status	"ungrouped"

Errors

Status	Code	Description
400	invalid_body	`audio_id` is missing or not a string, or the file cannot be ungrouped (`invalid_grouping`).
401	invalid_key	Missing, malformed, unknown or revoked API key.
404	file_not_found	The file does not exist in your library.
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_a81e5c40d7f2",
    "status": "ungrouped"
  }
}

200 The file is a track of its own. This response has no `meta`.
400 `audio_id` is missing or not a string, or the file cannot be ungrouped (`invalid_grouping`).
401 Missing, malformed, unknown or revoked API key.
404 The file does not exist in your library.
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_grouping, invalid_key_format, missing_api_key, missing_auth, rate_limit_unavailable, unauthorized.