# File actions: Scarleta API reference

Page: https://www.scarleta.ai/docs/reference/file-actions
Base URL: https://api.scarleta.ai. Authentication: `Authorization: Bearer $SCARLETA_API_KEY`.
Operations: 5.

## POST /v1/audio/archive

Operation id: `archive_files`

**Archive or unarchive files**

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.

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

### Request body

| Field | Type | Description |
| --- | --- | --- |
| `audio_ids` | array<string> | The files: library identifiers (`audio_id`) or storage identifiers (`file_id`) of your files, 1 to 100. |
| `archived` | boolean | `true` (the default) to archive, `false` to bring the files back. |

### Response fields (inside `data`)

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

### Responses

200: The call was applied. The body is `{ data }` without `meta`.

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

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

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

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. 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: The change could not be saved. Retry shortly.

```json
{
  "error": {
    "code": "db_unavailable",
    "message": "Database not available",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#db_unavailable"
  }
}
```

### Error codes

[`auth_unavailable`](https://www.scarleta.ai/docs/errors#auth_unavailable), [`db_unavailable`](https://www.scarleta.ai/docs/errors#db_unavailable), [`invalid_archived`](https://www.scarleta.ai/docs/errors#invalid_archived), [`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/archive" \
  -H "Authorization: Bearer $SCARLETA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "audio_ids": [
      "audio_bbb14949dc19"
    ],
    "archived": true
  }'
```

## POST /v1/audio/best

Operation id: `mark_best_version`

**Mark a file as the best version**

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.

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

### Request body

| Field | Type | Description |
| --- | --- | --- |
| `audio_id` | string | Library identifier (`audio_id`) of the file. Allowed: at least 1 character. |

### Response fields (inside `data`)

| Field | Type | Description |
| --- | --- | --- |
| `audio_id` | string |   |
| `is_best` | true |   |

### Responses

200: The file is now the best version. The body is `{ data }` without `meta`.

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

400: The body is invalid JSON or has no `audio_id`.

```json
{
  "error": {
    "code": "missing_audio_id",
    "message": "audio_id is required",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#missing_audio_id"
  }
}
```

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

404: No current file of yours has this id.

```json
{
  "error": {
    "code": "not_found",
    "message": "Audio not found or not owned",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#not_found"
  }
}
```

429: Over the account request budget. 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: The mark could not be saved. Retry shortly.

```json
{
  "error": {
    "code": "db_unavailable",
    "message": "Database not available",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#db_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_id`](https://www.scarleta.ai/docs/errors#missing_audio_id), [`missing_auth`](https://www.scarleta.ai/docs/errors#missing_auth), [`not_found`](https://www.scarleta.ai/docs/errors#not_found), [`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/best" \
  -H "Authorization: Bearer $SCARLETA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "audio_id": "audio_bbb14949dc19"
  }'
```

## POST /v1/audio/bulk-delete

Operation id: `bulk_delete_files`

**Delete several files**

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.

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

### Request body

| Field | Type | Description |
| --- | --- | --- |
| `audio_ids` | array<string> | The files to delete: library identifiers (`audio_id`) or storage identifiers (`file_id`) of your files, 1 to 100. |

### Response fields (inside `data`)

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

### Responses

200: One result per id. The body is `{ data }` without `meta`.

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

400: The body is invalid JSON, `audio_ids` is missing or empty, or it names more files than the limit (`too_many_ids`).

```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. 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"
  }
}
```

### Error codes

[`auth_unavailable`](https://www.scarleta.ai/docs/errors#auth_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/bulk-delete" \
  -H "Authorization: Bearer $SCARLETA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "audio_ids": [
      "audio_bbb14949dc19"
    ]
  }'
```

## POST /v1/audio/rename

Operation id: `rename_file`

**Rename a file**

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.

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

### Request body

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

### Response fields (inside `data`)

| Field | Type | Description |
| --- | --- | --- |
| `audio_id` | string |   |
| `name` | string |   |

### Responses

200: The file was renamed. The body is `{ data }` without `meta`.

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

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

```json
{
  "error": {
    "code": "missing_name",
    "message": "name is required and must be non-empty",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#missing_name"
  }
}
```

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

404: No file of yours has this id.

```json
{
  "error": {
    "code": "not_found",
    "message": "Audio not found or not owned",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#not_found"
  }
}
```

429: Over the account request budget. 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: The name could not be saved. Retry shortly.

```json
{
  "error": {
    "code": "db_unavailable",
    "message": "Database not available",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#db_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), [`invalid_name`](https://www.scarleta.ai/docs/errors#invalid_name), [`missing_api_key`](https://www.scarleta.ai/docs/errors#missing_api_key), [`missing_audio_id`](https://www.scarleta.ai/docs/errors#missing_audio_id), [`missing_auth`](https://www.scarleta.ai/docs/errors#missing_auth), [`missing_name`](https://www.scarleta.ai/docs/errors#missing_name), [`name_too_long`](https://www.scarleta.ai/docs/errors#name_too_long), [`not_found`](https://www.scarleta.ai/docs/errors#not_found), [`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/rename" \
  -H "Authorization: Bearer $SCARLETA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "audio_id": "audio_bbb14949dc19",
    "name": "Morning session v2"
  }'
```

## POST /v1/audio/star

Operation id: `star_files`

**Star or unstar files**

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.

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

### Request body

| Field | Type | Description |
| --- | --- | --- |
| `audio_ids` | array<string> | The files: library identifiers (`audio_id`) or storage identifiers (`file_id`) of your files, 1 to 5000. |
| `starred` | boolean | `true` to star, `false` to remove the star. |

### Response fields (inside `data`)

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

### Responses

200: The number of files changed.

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

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

```json
{
  "error": {
    "code": "invalid_starred",
    "message": "starred must be true or false",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#invalid_starred"
  }
}
```

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. 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: The star could not be saved. Retry shortly.

```json
{
  "error": {
    "code": "db_unavailable",
    "message": "Database not available",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#db_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), [`invalid_starred`](https://www.scarleta.ai/docs/errors#invalid_starred), [`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_audio_ids`](https://www.scarleta.ai/docs/errors#too_many_audio_ids), [`unauthorized`](https://www.scarleta.ai/docs/errors#unauthorized)

### Example

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