# Notes: Scarleta API reference

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

## GET /v1/audio/{audioId}/notes

Operation id: `list_version_notes`

**List the notes of a file**

Returns the notes you wrote on one file, newest first. A file that is not yours, or does not exist, simply has no notes: the answer is an empty list. On success this route answers `{ data, meta }`, and `meta.request_id` is not the id used in error bodies; errors use the standard error body.

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

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `audioId` | path | string | yes | The `audio_id` or file id of one of your files. |

### Response fields (inside `data`)

| Field | Type | Description |
| --- | --- | --- |
| `[].id` | string | Identifier of the note. |
| `[].audio_id` | string | The version the note belongs to. |
| `[].body` | string |   |
| `[].created_at` | string | ISO 8601 time. |
| `[].updated_at` | string | ISO 8601 time. |

### Responses

200: The notes, newest first.

```json
{
  "data": [
    {
      "id": "7d2c9e1a-4b3f-4c68-9a5d-1e0f8b7c6a52",
      "audio_id": "audio_3f9c1a7d2b60",
      "body": "Vocals too loud in the second chorus",
      "created_at": "2026-10-21T06:13:09.068Z",
      "updated_at": "2026-10-21T06:13:09.068Z"
    }
  ],
  "meta": {
    "request_id": "1f6c2a9e-3b47-4d58-9a10-6e2d8c4b7f03",
    "count": 1
  }
}
```

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), [`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
AUDIOID="YOUR_AUDIOID"
curl "https://api.scarleta.ai/v1/audio/$AUDIOID/notes" \
  -H "Authorization: Bearer $SCARLETA_API_KEY"
```

## POST /v1/audio/{audioId}/notes

Operation id: `create_version_note`

**Add a note to a file**

Adds a text note to one of your files. The text is trimmed, must not be empty, and is at most 10000 characters. A file that is not yours, or does not exist, is 404 `not_found`. On success this route answers `{ data, meta }`, and `meta.request_id` is not the id used in error bodies; errors use the standard error body.

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

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `audioId` | path | string | yes | The `audio_id` or file id of one of your files. |

### Request body

| Field | Type | Description |
| --- | --- | --- |
| `body` | string | The note text, 1 to 10000 characters after trimming. |

### Response fields (inside `data`)

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | Identifier of the note. |
| `audio_id` | string | The version the note belongs to. |
| `body` | string |   |
| `created_at` | string | ISO 8601 time. |
| `updated_at` | string | ISO 8601 time. |

### Responses

201: The note was created.

```json
{
  "data": {
    "id": "7d2c9e1a-4b3f-4c68-9a5d-1e0f8b7c6a52",
    "audio_id": "audio_3f9c1a7d2b60",
    "body": "Vocals too loud in the second chorus",
    "created_at": "2026-10-21T06:13:09.068Z",
    "updated_at": "2026-10-21T06:13:09.068Z"
  },
  "meta": {
    "request_id": "1f6c2a9e-3b47-4d58-9a10-6e2d8c4b7f03"
  }
}
```

400: The body is not valid JSON, `body` is missing or blank (`missing_body`), or it is longer than the limit (`body_too_long`).

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

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: The file does not exist in your library.

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

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), [`body_too_long`](https://www.scarleta.ai/docs/errors#body_too_long), [`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), [`missing_body`](https://www.scarleta.ai/docs/errors#missing_body), [`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
AUDIOID="YOUR_AUDIOID"
curl -X POST "https://api.scarleta.ai/v1/audio/$AUDIOID/notes" \
  -H "Authorization: Bearer $SCARLETA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Vocals too loud in the second chorus"
  }'
```

## DELETE /v1/audio/{audioId}/notes/{noteId}

Operation id: `delete_version_note`

**Delete a note**

Deletes one of your notes. Deleting a note twice, or a note that is not yours, is 404 `not_found`. On success this route answers `{ data, meta }`, and `meta.request_id` is not the id used in error bodies; errors use the standard error body.

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

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `audioId` | path | string | yes | The `audio_id` or file id of one of your files. |
| `noteId` | path | string | yes | The `id` of the note. |

### Response fields (inside `data`)

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | The deleted note. |
| `status` | "deleted" |   |

### Responses

200: The note is deleted.

```json
{
  "data": {
    "id": "7d2c9e1a-4b3f-4c68-9a5d-1e0f8b7c6a52",
    "status": "deleted"
  },
  "meta": {
    "request_id": "1f6c2a9e-3b47-4d58-9a10-6e2d8c4b7f03"
  }
}
```

400: `noteId` is not a UUID.

```json
{
  "error": {
    "code": "invalid_id",
    "message": "noteId must be a valid UUID",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#invalid_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: The note does not exist, is already deleted, or is not yours.

```json
{
  "error": {
    "code": "not_found",
    "message": "Note 7d2c9e1a-4b3f-4c68-9a5d-1e0f8b7c6a52 not found",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#not_found"
  }
}
```

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), [`invalid_auth_format`](https://www.scarleta.ai/docs/errors#invalid_auth_format), [`invalid_id`](https://www.scarleta.ai/docs/errors#invalid_id), [`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), [`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
AUDIOID="YOUR_AUDIOID"
NOTEID="YOUR_NOTEID"
curl -X DELETE "https://api.scarleta.ai/v1/audio/$AUDIOID/notes/$NOTEID" \
  -H "Authorization: Bearer $SCARLETA_API_KEY"
```