POST/v1/audio/archive

Archive or unarchive files

Free and paid accounts

API key required
Free and paid accounts
No token cost

Moves up to 100 files into the archive (hidden from the main library, kept in storage) or back out of it with archived: false. Archiving is not deleting: the files still count toward your storage. Ids that are not your files are skipped, and updated counts the files the call was applied to (files already in the requested state are counted too). 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/archive" \
  -H "Authorization: Bearer $SCARLETA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "audio_ids": [
      "audio_bbb14949dc19"
    ],
    "archived": true
  }'

Request body

Name	Type	Required	Description
audio_idsbody	array<string>	Required	The files: library identifiers (`audio_id`) or storage identifiers (`file_id`) of your files, 1 to 100.
archivedbody	boolean	Optional	`true` (the default) to archive, `false` to bring the files back.

Response fields

Field	Type	Description
updated	integer	Your files the call was applied to. Allowed: -9007199254740991 to 9007199254740991.
requested	integer	Distinct files named in the request, after ids that name the same file are merged. Allowed: -9007199254740991 to 9007199254740991.
archived	boolean	The state that was applied.

Errors

Status	Code	Description
400	invalid_archived	The body is invalid JSON, `archived` is not a boolean, or `audio_ids` is missing, empty (`missing_audio_ids`) or too long (`too_many_ids`).
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	db_unavailable	The change could not be saved. Retry shortly.

Example responses

{
  "data": {
    "updated": 2,
    "requested": 2,
    "archived": true
  }
}

200 The call was applied. The body is `{ data }` without `meta`.
400 The body is invalid JSON, `archived` is not a boolean, or `audio_ids` is missing, empty (`missing_audio_ids`) or too long (`too_many_ids`).
401 Missing, malformed, unknown or revoked API key.
429 Over the account request budget. Wait for the `Retry-After` header, then retry.
503 The change could not be saved. 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, invalid_auth_format, invalid_json, invalid_key_format, missing_api_key, missing_audio_ids, missing_auth, rate_limit_unavailable, too_many_ids, unauthorized.

POST/v1/audio/best

Mark a file as the best version

Free and paid accounts

API key required
Free and paid accounts
No token cost

Marks one file as the best version of its track: every other version of the same track loses the mark. A file that is not part of a track is simply marked. Only your own, current files qualify: an id that is not yours, a file in the archive and a temporary file return 404. Use the audio_id (a file_id is not accepted here). 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/best" \
  -H "Authorization: Bearer $SCARLETA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "audio_id": "audio_bbb14949dc19"
  }'

Request body

Name	Type	Required	Description
audio_idbody	string	Required	Library identifier (`audio_id`) of the file. Allowed: at least 1 character.

Response fields

Field	Type	Description
audio_id	string
is_best	true

Errors

Status	Code	Description
400	missing_audio_id	The body is invalid JSON or has no `audio_id`.
401	invalid_key	Missing, malformed, unknown or revoked API key.
404	not_found	No current file of yours has this id.
429	rate_limit_exceeded	Over the account request budget. Wait for the `Retry-After` header, then retry.
503	db_unavailable	The mark could not be saved. Retry shortly.

Example responses

{
  "data": {
    "audio_id": "audio_bbb14949dc19",
    "is_best": true
  }
}

200 The file is now the best version. The body is `{ data }` without `meta`.
400 The body is invalid JSON or has no `audio_id`.
401 Missing, malformed, unknown or revoked API key.
404 No current file of yours has this id.
429 Over the account request budget. Wait for the `Retry-After` header, then retry.
503 The mark could not be saved. 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, invalid_auth_format, invalid_json, invalid_key_format, missing_api_key, missing_auth, rate_limit_unavailable, unauthorized.

POST/v1/audio/bulk-delete

Delete several files

Free and paid accounts

API key required
Free and paid accounts
No token cost

Moves up to 100 files to the trash in one call, with one result per id. Like deleting a single file, this is not final: trashed files stay recoverable for 7 days. An id that is not one of your files returns deleted: false with reason: "not_found", and a file already in the trash returns reason: "already_trashed"; neither fails the call. If the database is unavailable the call still returns 200 with reason: "db_unavailable" on every id, so check each result. 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/bulk-delete" \
  -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	The files to delete: library identifiers (`audio_id`) or storage identifiers (`file_id`) of your files, 1 to 100.

Response fields

Field	Type	Description
results	array<object>
results[].audio_id	string	The file that was trashed, or the id you sent when it was not.
results[].deleted	boolean
results[].reason	"not_found" \| "already_trashed" \| "db_unavailable"	Why `deleted` is false.

Errors

Status	Code	Description
400	missing_audio_ids	The body is invalid JSON, `audio_ids` is missing or empty, or it names more files than the limit (`too_many_ids`).
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.

Example responses

{
  "data": {
    "results": [
      {
        "audio_id": "audio_bbb14949dc19",
        "deleted": true
      },
      {
        "audio_id": "audio_000000000000",
        "deleted": false,
        "reason": "not_found"
      }
    ]
  }
}

200 One result per id. The body is `{ data }` without `meta`.
400 The body is invalid JSON, `audio_ids` is missing or empty, or it names more files than the limit (`too_many_ids`).
401 Missing, malformed, unknown or revoked API key.
429 Over the account request budget. Wait for the `Retry-After` header, then retry.

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, invalid_auth_format, invalid_json, invalid_key_format, missing_api_key, missing_auth, rate_limit_unavailable, too_many_ids, unauthorized.

POST/v1/audio/rename

Rename a file

Free and paid accounts

API key required
Free and paid accounts
No token cost

Sets the display name of one of your files (at most 200 characters, surrounding spaces removed). The stored audio is not touched. audio_id may be the library identifier or the storage file_id; the response returns the audio_id. 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/rename" \
  -H "Authorization: Bearer $SCARLETA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "audio_id": "audio_bbb14949dc19",
    "name": "Morning session v2"
  }'

Request body

Name	Type	Required	Description
audio_idbody	string	Required	Library identifier (`audio_id`) or storage identifier (`file_id`) of the file. Allowed: at least 1 character.
namebody	string	Required	The new name, 1 to 200 characters after trimming.

Response fields

Field	Type	Description
audio_id	string
name	string

Errors

Status	Code	Description
400	missing_name	The body is invalid JSON, `audio_id` or `name` is missing or blank (`missing_audio_id`), the name is too long (`name_too_long`), or it contains a NUL character (`invalid_name`).
401	invalid_key	Missing, malformed, unknown or revoked API key.
404	not_found	No file of yours has this id.
429	rate_limit_exceeded	Over the account request budget. Wait for the `Retry-After` header, then retry.
503	db_unavailable	The name could not be saved. Retry shortly.

Example responses

{
  "data": {
    "audio_id": "audio_bbb14949dc19",
    "name": "Morning session v2"
  }
}

200 The file was renamed. The body is `{ data }` without `meta`.
400 The body is invalid JSON, `audio_id` or `name` is missing or blank (`missing_audio_id`), the name is too long (`name_too_long`), or it contains a NUL character (`invalid_name`).
401 Missing, malformed, unknown or revoked API key.
404 No file of yours has this id.
429 Over the account request budget. Wait for the `Retry-After` header, then retry.
503 The name could not be saved. 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, invalid_auth_format, invalid_json, invalid_key_format, invalid_name, missing_api_key, missing_audio_id, missing_auth, name_too_long, rate_limit_unavailable, unauthorized.

POST/v1/audio/star

Star or unstar files

Free and paid accounts

API key required
Free and paid accounts
No token cost

Sets the star on up to 5000 files at once. Only files whose star actually changes are counted, so starring files that are already starred returns updated: 0. Ids that are not your files, and files in the trash, are skipped. 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/star" \
  -H "Authorization: Bearer $SCARLETA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "audio_ids": [
      "audio_bbb14949dc19"
    ],
    "starred": true
  }'

Request body

Name	Type	Required	Description
audio_idsbody	array<string>	Required	The files: library identifiers (`audio_id`) or storage identifiers (`file_id`) of your files, 1 to 5000.
starredbody	boolean	Required	`true` to star, `false` to remove the star.

Response fields

Field	Type	Description
updated	integer	Files whose star changed. Allowed: -9007199254740991 to 9007199254740991.

Errors

Status	Code	Description
400	invalid_starred	The body is invalid JSON, `starred` is not a boolean, or `audio_ids` is missing, empty or too long (`missing_audio_ids`, `too_many_audio_ids`).
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	db_unavailable	The star could not be saved. Retry shortly.

Example responses

{
  "data": {
    "updated": 3
  },
  "meta": {
    "request_id": "req_0b7a3c2e-6f1d-4d9a-8e55-3a4b5c6d7e8f"
  }
}

200 The number of files changed.
400 The body is invalid JSON, `starred` is not a boolean, or `audio_ids` is missing, empty or too long (`missing_audio_ids`, `too_many_audio_ids`).
401 Missing, malformed, unknown or revoked API key.
429 Over the account request budget. Wait for the `Retry-After` header, then retry.
503 The star could not be saved. 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, invalid_auth_format, invalid_json, invalid_key_format, missing_api_key, missing_audio_ids, missing_auth, rate_limit_unavailable, too_many_audio_ids, unauthorized.