GET/v1/audio/trash

List the trash

Free and paid accounts

API key required
Free and paid accounts
No token cost

Lists the files you moved to the trash, newest first. A trashed file is kept for 7 days, then removed for good; purge_after says when. Only your own files are ever returned.

Page with limit and cursor: pass next_cursor from one response as cursor in the next while it is not null. limit defaults to 100; larger values are lowered to 200, and a value that is not a positive number counts as the default. On success this route answers { data } without meta; errors use the standard error body.

Cost. Free of charge.

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

Parameters

Name	Type	Required	Description
limitquery	integer	Optional	Items per page, 1 to 200. Defaults to 100.
cursorquery	string	Optional	The `next_cursor` of the previous page. An unreadable cursor restarts from the first page.

Response fields

Field	Type	Description
items	array<object>
items[].audio_id	string
items[].file_id	string \| null	The file id of the stored file, when it has one.
items[].name	string \| null
items[].size_bytes	number \| null
items[].format	string \| null
items[].trashed_at	string	When the file was moved to the trash, as an ISO 8601 time.
items[].purge_after	string	When the file is removed for good, as an ISO 8601 time.
next_cursor	string \| null	Pass this as `cursor` to get the next page; null on the last page.

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": {
    "items": [
      {
        "audio_id": "audio_3f9c1a7d2b60",
        "file_id": "7d2c9e1a-4b3f-4c68-9a5d-1e0f8b7c6a52",
        "name": "old-take.wav",
        "size_bytes": 5290044,
        "format": "wav",
        "trashed_at": "2026-10-21T05:36:53.621Z",
        "purge_after": "2026-10-28T05:36:53.621Z"
      }
    ],
    "next_cursor": null
  }
}

200 A page of trashed 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: db_unavailable, invalid_auth_format, invalid_key_format, missing_api_key, missing_auth, rate_limit_unavailable, unauthorized.

POST/v1/audio/trash/delete-forever

Delete trashed files permanently

Free and paid accounts

API key required
Free and paid accounts
No token cost

Removes files from the trash for good: the stored audio and everything attached to it is deleted and cannot be restored. Only files that are already in your trash qualify; any other id comes back with deleted: false and nothing happens to it. Send 1 to 100 ids. 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/trash/delete-forever" \
  -H "Authorization: Bearer $SCARLETA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "audio_ids": [
      "audio_3f9c1a7d2b60"
    ]
  }'

Request body

Name	Type	Required	Description
audio_idsbody	array<string>	Required	Ids of files in your trash, 1 to 100. Each is a file's `audio_id` or its file id.

Response fields

Field	Type	Description
results	array<object>
results[].audio_id	string
results[].deleted	boolean
results[].reason	string	Why a file could not be deleted, when it could not (`error` for a failed delete).

Errors

Status	Code	Description
400	missing_audio_ids	The body is not a JSON object, `audio_ids` is missing, empty or not a list of strings, or it names more ids than allowed.
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": {
    "results": [
      {
        "audio_id": "audio_3f9c1a7d2b60",
        "deleted": true
      }
    ]
  }
}

200 One result per id sent, in the order sent. This response has no `meta`.
400 The body is not a JSON object, `audio_ids` is missing, empty or not a list of strings, or it names more ids than allowed.
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: db_unavailable, invalid_auth_format, invalid_json, invalid_key_format, missing_api_key, missing_auth, rate_limit_unavailable, too_many_ids, unauthorized.

POST/v1/audio/trash/empty

Empty the trash

Free and paid accounts

API key required
Free and paid accounts
No token cost

Permanently deletes every file in your trash. It takes no body. This cannot be undone, and it acts on the whole trash, so check the trash list first. A file that cannot be removed stays in the trash and is counted in failed; the rest are still removed. 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/trash/empty" \
  -H "Authorization: Bearer $SCARLETA_API_KEY"

Response fields

Field	Type	Description
deleted	integer	Files removed for good. Allowed: -9007199254740991 to 9007199254740991.
failed	integer	Files that could not be removed and are still in the trash. Allowed: -9007199254740991 to 9007199254740991.

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": {
    "deleted": 3,
    "failed": 0
  }
}

200 How many files were removed, and how many could not be. 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: db_unavailable, invalid_auth_format, invalid_key_format, missing_api_key, missing_auth, rate_limit_unavailable, unauthorized.

POST/v1/audio/trash/restore

Restore files from the trash

Free and paid accounts

API key required
Free and paid accounts
No token cost

Moves files back out of the trash. Each file returns exactly as it was, with its tags, notes, analyses, versions and shares. Send 1 to 100 ids. The answer lists every id you sent with restored: false for an id that is not in your trash. 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/trash/restore" \
  -H "Authorization: Bearer $SCARLETA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "audio_ids": [
      "audio_3f9c1a7d2b60"
    ]
  }'

Request body

Name	Type	Required	Description
audio_idsbody	array<string>	Required	Ids of files in your trash, 1 to 100. Each is a file's `audio_id` or its file id.

Response fields

Field	Type	Description
results	array<object>
results[].audio_id	string
results[].restored	boolean	False when the id is not one of your trashed files.

Errors

Status	Code	Description
400	missing_audio_ids	The body is not a JSON object, `audio_ids` is missing, empty or not a list of strings, or it names more ids than allowed.
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": {
    "results": [
      {
        "audio_id": "audio_3f9c1a7d2b60",
        "restored": true
      }
    ]
  }
}

200 One result per id sent, in the order sent. This response has no `meta`.
400 The body is not a JSON object, `audio_ids` is missing, empty or not a list of strings, or it names more ids than allowed.
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: db_unavailable, invalid_auth_format, invalid_json, invalid_key_format, missing_api_key, missing_auth, rate_limit_unavailable, too_many_ids, unauthorized.