# Trash: Scarleta API reference

Page: https://www.scarleta.ai/docs/reference/trash
Base URL: https://api.scarleta.ai. Authentication: `Authorization: Bearer $SCARLETA_API_KEY`.
Operations: 4.

## GET /v1/audio/trash

Operation id: `list_trash`

**List the trash**

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.

Access: API key required; free and paid accounts. Cost: no token cost.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `limit` | query | integer | no | Items per page, 1 to 200. Defaults to 100. |
| `cursor` | query | string | no | The `next_cursor` of the previous page. An unreadable cursor restarts from the first page. |

### Response fields (inside `data`)

| 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. |

### Responses

200: A page of trashed files. This response has no `meta`.

```json
{
  "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
  }
}
```

401: Missing, malformed, unknown or revoked API key.

```json
{
  "error": {
    "code": "invalid_key",
    "message": "Invalid or revoked API key",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#invalid_key"
  }
}
```

429: Over the account request budget or the per-minute cap of this route. Wait for the `Retry-After` header, then retry.

```json
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#rate_limit_exceeded"
  }
}
```

503: Temporary platform condition; retry shortly.

```json
{
  "error": {
    "code": "auth_unavailable",
    "message": "Authentication service temporarily unavailable",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#auth_unavailable"
  }
}
```

### Error codes

[`auth_unavailable`](https://www.scarleta.ai/docs/errors#auth_unavailable), [`db_unavailable`](https://www.scarleta.ai/docs/errors#db_unavailable), [`invalid_auth_format`](https://www.scarleta.ai/docs/errors#invalid_auth_format), [`invalid_key`](https://www.scarleta.ai/docs/errors#invalid_key), [`invalid_key_format`](https://www.scarleta.ai/docs/errors#invalid_key_format), [`missing_api_key`](https://www.scarleta.ai/docs/errors#missing_api_key), [`missing_auth`](https://www.scarleta.ai/docs/errors#missing_auth), [`rate_limit_exceeded`](https://www.scarleta.ai/docs/errors#rate_limit_exceeded), [`rate_limit_unavailable`](https://www.scarleta.ai/docs/errors#rate_limit_unavailable), [`unauthorized`](https://www.scarleta.ai/docs/errors#unauthorized)

### Example

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

## POST /v1/audio/trash/delete-forever

Operation id: `delete_from_trash_forever`

**Delete trashed files permanently**

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.

Access: API key required; free and paid accounts. Cost: no token cost.

### Request body

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

### Response fields (inside `data`)

| 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). |

### Responses

200: One result per id sent, in the order sent. This response has no `meta`.

```json
{
  "data": {
    "results": [
      {
        "audio_id": "audio_3f9c1a7d2b60",
        "deleted": true
      }
    ]
  }
}
```

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.

```json
{
  "error": {
    "code": "missing_audio_ids",
    "message": "audio_ids must be a non-empty array",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#missing_audio_ids"
  }
}
```

401: Missing, malformed, unknown or revoked API key.

```json
{
  "error": {
    "code": "invalid_key",
    "message": "Invalid or revoked API key",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#invalid_key"
  }
}
```

429: Over the account request budget or the per-minute cap of this route. Wait for the `Retry-After` header, then retry.

```json
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#rate_limit_exceeded"
  }
}
```

503: Temporary platform condition; retry shortly.

```json
{
  "error": {
    "code": "auth_unavailable",
    "message": "Authentication service temporarily unavailable",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#auth_unavailable"
  }
}
```

### Error codes

[`auth_unavailable`](https://www.scarleta.ai/docs/errors#auth_unavailable), [`db_unavailable`](https://www.scarleta.ai/docs/errors#db_unavailable), [`invalid_auth_format`](https://www.scarleta.ai/docs/errors#invalid_auth_format), [`invalid_json`](https://www.scarleta.ai/docs/errors#invalid_json), [`invalid_key`](https://www.scarleta.ai/docs/errors#invalid_key), [`invalid_key_format`](https://www.scarleta.ai/docs/errors#invalid_key_format), [`missing_api_key`](https://www.scarleta.ai/docs/errors#missing_api_key), [`missing_audio_ids`](https://www.scarleta.ai/docs/errors#missing_audio_ids), [`missing_auth`](https://www.scarleta.ai/docs/errors#missing_auth), [`rate_limit_exceeded`](https://www.scarleta.ai/docs/errors#rate_limit_exceeded), [`rate_limit_unavailable`](https://www.scarleta.ai/docs/errors#rate_limit_unavailable), [`too_many_ids`](https://www.scarleta.ai/docs/errors#too_many_ids), [`unauthorized`](https://www.scarleta.ai/docs/errors#unauthorized)

### Example

```bash
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"
    ]
  }'
```

## POST /v1/audio/trash/empty

Operation id: `empty_trash`

**Empty the trash**

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.

Access: API key required; free and paid accounts. Cost: no token cost.

### Response fields (inside `data`)

| 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. |

### Responses

200: How many files were removed, and how many could not be. This response has no `meta`.

```json
{
  "data": {
    "deleted": 3,
    "failed": 0
  }
}
```

401: Missing, malformed, unknown or revoked API key.

```json
{
  "error": {
    "code": "invalid_key",
    "message": "Invalid or revoked API key",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#invalid_key"
  }
}
```

429: Over the account request budget or the per-minute cap of this route. Wait for the `Retry-After` header, then retry.

```json
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#rate_limit_exceeded"
  }
}
```

503: Temporary platform condition; retry shortly.

```json
{
  "error": {
    "code": "auth_unavailable",
    "message": "Authentication service temporarily unavailable",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#auth_unavailable"
  }
}
```

### Error codes

[`auth_unavailable`](https://www.scarleta.ai/docs/errors#auth_unavailable), [`db_unavailable`](https://www.scarleta.ai/docs/errors#db_unavailable), [`invalid_auth_format`](https://www.scarleta.ai/docs/errors#invalid_auth_format), [`invalid_key`](https://www.scarleta.ai/docs/errors#invalid_key), [`invalid_key_format`](https://www.scarleta.ai/docs/errors#invalid_key_format), [`missing_api_key`](https://www.scarleta.ai/docs/errors#missing_api_key), [`missing_auth`](https://www.scarleta.ai/docs/errors#missing_auth), [`rate_limit_exceeded`](https://www.scarleta.ai/docs/errors#rate_limit_exceeded), [`rate_limit_unavailable`](https://www.scarleta.ai/docs/errors#rate_limit_unavailable), [`unauthorized`](https://www.scarleta.ai/docs/errors#unauthorized)

### Example

```bash
curl -X POST "https://api.scarleta.ai/v1/audio/trash/empty" \
  -H "Authorization: Bearer $SCARLETA_API_KEY"
```

## POST /v1/audio/trash/restore

Operation id: `restore_from_trash`

**Restore files from the trash**

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.

Access: API key required; free and paid accounts. Cost: no token cost.

### Request body

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

### Response fields (inside `data`)

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

### Responses

200: One result per id sent, in the order sent. This response has no `meta`.

```json
{
  "data": {
    "results": [
      {
        "audio_id": "audio_3f9c1a7d2b60",
        "restored": true
      }
    ]
  }
}
```

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.

```json
{
  "error": {
    "code": "missing_audio_ids",
    "message": "audio_ids must be a non-empty array",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#missing_audio_ids"
  }
}
```

401: Missing, malformed, unknown or revoked API key.

```json
{
  "error": {
    "code": "invalid_key",
    "message": "Invalid or revoked API key",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#invalid_key"
  }
}
```

429: Over the account request budget or the per-minute cap of this route. Wait for the `Retry-After` header, then retry.

```json
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#rate_limit_exceeded"
  }
}
```

503: Temporary platform condition; retry shortly.

```json
{
  "error": {
    "code": "auth_unavailable",
    "message": "Authentication service temporarily unavailable",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#auth_unavailable"
  }
}
```

### Error codes

[`auth_unavailable`](https://www.scarleta.ai/docs/errors#auth_unavailable), [`db_unavailable`](https://www.scarleta.ai/docs/errors#db_unavailable), [`invalid_auth_format`](https://www.scarleta.ai/docs/errors#invalid_auth_format), [`invalid_json`](https://www.scarleta.ai/docs/errors#invalid_json), [`invalid_key`](https://www.scarleta.ai/docs/errors#invalid_key), [`invalid_key_format`](https://www.scarleta.ai/docs/errors#invalid_key_format), [`missing_api_key`](https://www.scarleta.ai/docs/errors#missing_api_key), [`missing_audio_ids`](https://www.scarleta.ai/docs/errors#missing_audio_ids), [`missing_auth`](https://www.scarleta.ai/docs/errors#missing_auth), [`rate_limit_exceeded`](https://www.scarleta.ai/docs/errors#rate_limit_exceeded), [`rate_limit_unavailable`](https://www.scarleta.ai/docs/errors#rate_limit_unavailable), [`too_many_ids`](https://www.scarleta.ai/docs/errors#too_many_ids), [`unauthorized`](https://www.scarleta.ai/docs/errors#unauthorized)

### Example

```bash
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"
    ]
  }'
```