# Saved views: Scarleta API reference

Page: https://www.scarleta.ai/docs/reference/saved-views
Base URL: https://api.scarleta.ai. Authentication: `Authorization: Bearer $SCARLETA_API_KEY`.
Operations: 8.

## GET /v1/audio/views

Operation id: `list_views`

**List saved views**

Returns all your saved views, newest first. `data` is the list itself. A stored definition that can no longer be read is returned as the default definition instead of failing the list. 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.

### Response fields (inside `data`)

| Field | Type | Description |
| --- | --- | --- |
| `[].id` | string | Identifier of the view. |
| `[].name` | string |   |
| `[].origin` | "user" \| "chat" | `user` for views you saved, `chat` for views the assistant built in a conversation until you keep them. |
| `[].source_conversation_id` | string \| null | For a `chat` view, the conversation it was built in. |
| `[].source_tool_call_id` | string \| null | For a `chat` view, the step of that conversation that built it. |
| `[].definition` | object | The definition in the current (version 2) form, as stored. |
| `[].dropped` | array<string> | Parts of an older stored definition that the current form no longer supports and that were left out. |
| `[].config` | object | The same definition in the older (version 1) form, kept for existing clients. |
| `[].created_at` | string |   |
| `[].updated_at` | string |   |
| `[].last_opened_at` | string \| null | When the view was last read with the get route. |

### Responses

200: Your views. The body is `{ data }` where `data` is an array, without `meta`.

```json
{
  "data": [
    {
      "id": "8a1c3e5f-7b9d-4f20-a4c6-e8f0123456ab",
      "name": "Fast tracks",
      "origin": "user",
      "source_conversation_id": null,
      "source_tool_call_id": null,
      "definition": {
        "version": 2,
        "filters": {},
        "sort": [],
        "columns": []
      },
      "dropped": [],
      "config": {},
      "created_at": "2026-10-20T11:53:45.938Z",
      "updated_at": "2026-10-20T11:53:45.938Z",
      "last_opened_at": 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. 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_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/views" \
  -H "Authorization: Bearer $SCARLETA_API_KEY"
```

## POST /v1/audio/views

Operation id: `create_view`

**Create a saved view**

Saves a named view of your library. Send `definition` (the current form) or `config` (the older form), not both; with neither, the view covers the whole library. The response is the stored view with `201`. 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 |
| --- | --- | --- |
| `name` | string | The view name, 1 to 200 characters after trimming. |
| `definition` | object | The view definition: `{"version":2,"filters":{...},"sort":[...],"group":...,"columns":[...]}`. Every part is optional; `{"version":2}` is the whole library. The same definition is accepted by the library read route (`q`). |
| `config` | object | The older (version 1) form of the definition. Send this or `definition`, not both. |

### Response fields (inside `data`)

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | Identifier of the view. |
| `name` | string |   |
| `origin` | "user" \| "chat" | `user` for views you saved, `chat` for views the assistant built in a conversation until you keep them. |
| `source_conversation_id` | string \| null | For a `chat` view, the conversation it was built in. |
| `source_tool_call_id` | string \| null | For a `chat` view, the step of that conversation that built it. |
| `definition` | object | The definition in the current (version 2) form, as stored. |
| `dropped` | array<string> | Parts of an older stored definition that the current form no longer supports and that were left out. |
| `config` | object | The same definition in the older (version 1) form, kept for existing clients. |
| `created_at` | string |   |
| `updated_at` | string |   |
| `last_opened_at` | string \| null | When the view was last read with the get route. |

### Responses

201: The view was saved. The body is `{ data }` without `meta`.

```json
{
  "data": {
    "id": "8a1c3e5f-7b9d-4f20-a4c6-e8f0123456ab",
    "name": "Fast tracks",
    "origin": "user",
    "source_conversation_id": null,
    "source_tool_call_id": null,
    "definition": {
      "version": 2,
      "filters": {},
      "sort": [],
      "columns": []
    },
    "dropped": [],
    "config": {},
    "created_at": "2026-10-20T11:53:45.938Z",
    "updated_at": "2026-10-20T11:53:45.938Z",
    "last_opened_at": null
  }
}
```

400: The body is invalid JSON, a name is missing (`missing_name`) or too long (`name_too_long`), or the definition is not valid (`invalid_config`, `invalid_filter`, `invalid_sort`, `invalid_group`, `invalid_columns`; `error.details.field` names the part).

```json
{
  "error": {
    "code": "invalid_config",
    "message": "Send definition or config, not both",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#invalid_config"
  }
}
```

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 view 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_columns`](https://www.scarleta.ai/docs/errors#invalid_columns), [`invalid_config`](https://www.scarleta.ai/docs/errors#invalid_config), [`invalid_filter`](https://www.scarleta.ai/docs/errors#invalid_filter), [`invalid_group`](https://www.scarleta.ai/docs/errors#invalid_group), [`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), [`invalid_sort`](https://www.scarleta.ai/docs/errors#invalid_sort), [`missing_api_key`](https://www.scarleta.ai/docs/errors#missing_api_key), [`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), [`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/views" \
  -H "Authorization: Bearer $SCARLETA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Fast tracks",
    "definition": {
      "version": 2
    }
  }'
```

## GET /v1/audio/views/{viewId}

Operation id: `get_view`

**Get a saved view**

Returns one view and records that it was opened (`last_opened_at` in the response is the new time). Only your own views can be read; any other id returns 404 `view_not_found`. 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.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `viewId` | path | string | yes | The `id` of one of your saved views. |

### Response fields (inside `data`)

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | Identifier of the view. |
| `name` | string |   |
| `origin` | "user" \| "chat" | `user` for views you saved, `chat` for views the assistant built in a conversation until you keep them. |
| `source_conversation_id` | string \| null | For a `chat` view, the conversation it was built in. |
| `source_tool_call_id` | string \| null | For a `chat` view, the step of that conversation that built it. |
| `definition` | object | The definition in the current (version 2) form, as stored. |
| `dropped` | array<string> | Parts of an older stored definition that the current form no longer supports and that were left out. |
| `config` | object | The same definition in the older (version 1) form, kept for existing clients. |
| `created_at` | string |   |
| `updated_at` | string |   |
| `last_opened_at` | string \| null | When the view was last read with the get route. |

### Responses

200: The view.

```json
{
  "data": {
    "id": "8a1c3e5f-7b9d-4f20-a4c6-e8f0123456ab",
    "name": "Fast tracks",
    "origin": "user",
    "source_conversation_id": null,
    "source_tool_call_id": null,
    "definition": {
      "version": 2,
      "filters": {},
      "sort": [],
      "columns": []
    },
    "dropped": [],
    "config": {},
    "created_at": "2026-10-20T11:53:45.938Z",
    "updated_at": "2026-10-20T11:53:45.938Z",
    "last_opened_at": "2026-10-20T11:53:45.938Z"
  },
  "meta": {
    "request_id": "req_0b7a3c2e-6f1d-4d9a-8e55-3a4b5c6d7e8f"
  }
}
```

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 view with this id in your account.

```json
{
  "error": {
    "code": "view_not_found",
    "message": "View not found",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#view_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 view could not be read. 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_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), [`view_not_found`](https://www.scarleta.ai/docs/errors#view_not_found)

### Example

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

## PUT /v1/audio/views/{viewId}

Operation id: `update_view`

**Update a saved view**

Changes the name and/or the definition of one of your views. Send at least one of `name`, `definition`, `config` (`definition` and `config` not together); a request that changes nothing returns 400 `nothing_to_update`. Parts you leave out stay as they are. 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.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `viewId` | path | string | yes | The `id` of one of your saved views. |

### Request body

| Field | Type | Description |
| --- | --- | --- |
| `name` | string | The view name, 1 to 200 characters after trimming. |
| `definition` | object | The view definition: `{"version":2,"filters":{...},"sort":[...],"group":...,"columns":[...]}`. Every part is optional; `{"version":2}` is the whole library. The same definition is accepted by the library read route (`q`). |
| `config` | object | The older (version 1) form of the definition. Send this or `definition`, not both. |

### Response fields (inside `data`)

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | Identifier of the view. |
| `name` | string |   |
| `origin` | "user" \| "chat" | `user` for views you saved, `chat` for views the assistant built in a conversation until you keep them. |
| `source_conversation_id` | string \| null | For a `chat` view, the conversation it was built in. |
| `source_tool_call_id` | string \| null | For a `chat` view, the step of that conversation that built it. |
| `definition` | object | The definition in the current (version 2) form, as stored. |
| `dropped` | array<string> | Parts of an older stored definition that the current form no longer supports and that were left out. |
| `config` | object | The same definition in the older (version 1) form, kept for existing clients. |
| `created_at` | string |   |
| `updated_at` | string |   |
| `last_opened_at` | string \| null | When the view was last read with the get route. |

### Responses

200: The updated view. The body is `{ data }` without `meta`.

```json
{
  "data": {
    "id": "8a1c3e5f-7b9d-4f20-a4c6-e8f0123456ab",
    "name": "Fast tracks",
    "origin": "user",
    "source_conversation_id": null,
    "source_tool_call_id": null,
    "definition": {
      "version": 2,
      "filters": {},
      "sort": [],
      "columns": []
    },
    "dropped": [],
    "config": {},
    "created_at": "2026-10-20T11:53:45.938Z",
    "updated_at": "2026-10-20T11:53:45.938Z",
    "last_opened_at": null
  }
}
```

400: The id is not a UUID (`invalid_view_id`), the body is invalid JSON, nothing is being changed, the name is blank (`missing_name`) or too long, or the definition is not valid.

```json
{
  "error": {
    "code": "nothing_to_update",
    "message": "No fields to update",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#nothing_to_update"
  }
}
```

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 view with this id in your account.

```json
{
  "error": {
    "code": "not_found",
    "message": "View 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 view 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_columns`](https://www.scarleta.ai/docs/errors#invalid_columns), [`invalid_config`](https://www.scarleta.ai/docs/errors#invalid_config), [`invalid_filter`](https://www.scarleta.ai/docs/errors#invalid_filter), [`invalid_group`](https://www.scarleta.ai/docs/errors#invalid_group), [`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), [`invalid_sort`](https://www.scarleta.ai/docs/errors#invalid_sort), [`invalid_view_id`](https://www.scarleta.ai/docs/errors#invalid_view_id), [`missing_api_key`](https://www.scarleta.ai/docs/errors#missing_api_key), [`missing_auth`](https://www.scarleta.ai/docs/errors#missing_auth), [`missing_view_id`](https://www.scarleta.ai/docs/errors#missing_view_id), [`name_too_long`](https://www.scarleta.ai/docs/errors#name_too_long), [`not_found`](https://www.scarleta.ai/docs/errors#not_found), [`nothing_to_update`](https://www.scarleta.ai/docs/errors#nothing_to_update), [`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
VIEWID="YOUR_VIEWID"
curl -X PUT "https://api.scarleta.ai/v1/audio/views/$VIEWID" \
  -H "Authorization: Bearer $SCARLETA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Fast tracks v2",
    "definition": {
      "version": 2
    }
  }'
```

## DELETE /v1/audio/views/{viewId}

Operation id: `delete_view`

**Delete a saved view**

Deletes one of your saved views for good (views are not kept in a trash). Your files are not affected. 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.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `viewId` | path | string | yes | The `id` of one of your saved views. |

### Response fields (inside `data`)

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | The deleted view. |
| `deleted` | true |   |

### Responses

200: The view is deleted. The body is `{ data }` without `meta`.

```json
{
  "data": {
    "id": "8a1c3e5f-7b9d-4f20-a4c6-e8f0123456ab",
    "deleted": true
  }
}
```

400: The id is not a UUID.

```json
{
  "error": {
    "code": "invalid_view_id",
    "message": "viewId must be a valid UUID",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#invalid_view_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 view with this id in your account (or it is already deleted).

```json
{
  "error": {
    "code": "not_found",
    "message": "View 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 view could not be deleted. 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_key`](https://www.scarleta.ai/docs/errors#invalid_key), [`invalid_key_format`](https://www.scarleta.ai/docs/errors#invalid_key_format), [`invalid_view_id`](https://www.scarleta.ai/docs/errors#invalid_view_id), [`missing_api_key`](https://www.scarleta.ai/docs/errors#missing_api_key), [`missing_auth`](https://www.scarleta.ai/docs/errors#missing_auth), [`missing_view_id`](https://www.scarleta.ai/docs/errors#missing_view_id), [`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
VIEWID="YOUR_VIEWID"
curl -X DELETE "https://api.scarleta.ai/v1/audio/views/$VIEWID" \
  -H "Authorization: Bearer $SCARLETA_API_KEY"
```

## POST /v1/audio/views/{viewId}/save

Operation id: `save_view`

**Keep a view under a name**

Keeps a view the assistant built in a conversation: its `origin` becomes `user` and it gets the name you send. On a view you already saved this just renames it. 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.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `viewId` | path | string | yes | The `id` of one of your saved views. |

### Request body

| Field | Type | Description |
| --- | --- | --- |
| `name` | string | The view name, 1 to 200 characters after trimming. |

### Response fields (inside `data`)

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | Identifier of the view. |
| `name` | string |   |
| `origin` | "user" \| "chat" | `user` for views you saved, `chat` for views the assistant built in a conversation until you keep them. |
| `source_conversation_id` | string \| null | For a `chat` view, the conversation it was built in. |
| `source_tool_call_id` | string \| null | For a `chat` view, the step of that conversation that built it. |
| `definition` | object | The definition in the current (version 2) form, as stored. |
| `dropped` | array<string> | Parts of an older stored definition that the current form no longer supports and that were left out. |
| `config` | object | The same definition in the older (version 1) form, kept for existing clients. |
| `created_at` | string |   |
| `updated_at` | string |   |
| `last_opened_at` | string \| null | When the view was last read with the get route. |

### Responses

200: The kept view.

```json
{
  "data": {
    "id": "8a1c3e5f-7b9d-4f20-a4c6-e8f0123456ab",
    "name": "Fast tracks",
    "origin": "user",
    "source_conversation_id": null,
    "source_tool_call_id": null,
    "definition": {
      "version": 2,
      "filters": {},
      "sort": [],
      "columns": []
    },
    "dropped": [],
    "config": {},
    "created_at": "2026-10-20T11:53:45.938Z",
    "updated_at": "2026-10-20T11:53:45.938Z",
    "last_opened_at": null
  },
  "meta": {
    "request_id": "req_0b7a3c2e-6f1d-4d9a-8e55-3a4b5c6d7e8f"
  }
}
```

400: The body is invalid JSON, or the name is missing (`missing_name`) or too long (`name_too_long`). `error.details.field` names it.

```json
{
  "error": {
    "code": "missing_name",
    "message": "name is required",
    "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 view with this id in your account.

```json
{
  "error": {
    "code": "view_not_found",
    "message": "View not found",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#view_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 view 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_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), [`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), [`view_not_found`](https://www.scarleta.ai/docs/errors#view_not_found)

### Example

```bash
VIEWID="YOUR_VIEWID"
curl -X POST "https://api.scarleta.ai/v1/audio/views/$VIEWID/save" \
  -H "Authorization: Bearer $SCARLETA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Fast tracks"
  }'
```

## GET /v1/audio/views/{viewId}/summary

Operation id: `get_view_summary`

**Summarize a saved view**

Counts what a view matches and describes it: the number of tracks and files, how many files have each searchable value (`coverage`), a profile of the matched files (tempo and loudness range, most common keys and tags) and the first five matches. Reading does not spend tokens. 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.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `viewId` | path | string | yes | The `id` of one of your saved views. |

### Response fields (inside `data`)

| Field | Type | Description |
| --- | --- | --- |
| `view_id` | string \| null |   |
| `name` | string \| null |   |
| `track_count` | integer | Tracks the view matches. Allowed: -9007199254740991 to 9007199254740991. |
| `file_count` | integer | Files the view matches. Allowed: -9007199254740991 to 9007199254740991. |
| `coverage` | object |   |
| `coverage.total_library_size` | integer | Files in the scope of the view before its filters. Allowed: -9007199254740991 to 9007199254740991. |
| `coverage.indexed` | object | Per searchable value, the number of files that have it. |
| `profile` | object |   |
| `profile.bpm` | object \| null |   |
| `profile.bpm.min` | number |   |
| `profile.bpm.max` | number |   |
| `profile.top_keys` | array<object> | The most common keys; `pct` is the whole-number share of matched files that have a key. |
| `profile.top_keys[].key` | string |   |
| `profile.top_keys[].pct` | number |   |
| `profile.loudness` | object \| null |   |
| `profile.loudness.min` | number |   |
| `profile.loudness.max` | number |   |
| `profile.top_tags` | array<object> |   |
| `profile.top_tags[].tag` | string |   |
| `profile.top_tags[].count` | integer | Allowed: -9007199254740991 to 9007199254740991. |
| `top` | array<object> | The first five matches. |
| `top[].audio_id` | string |   |
| `top[].name` | string |   |
| `top[].facts` | object | The values the view sorts or filters by, for this file. |

### Responses

200: The summary.

```json
{
  "data": {
    "view_id": "8a1c3e5f-7b9d-4f20-a4c6-e8f0123456ab",
    "name": "Fast tracks",
    "track_count": 12,
    "file_count": 15,
    "coverage": {
      "total_library_size": 42,
      "indexed": {
        "bpm": 17,
        "key_label": 9
      }
    },
    "profile": {
      "bpm": {
        "min": 90,
        "max": 174
      },
      "top_keys": [
        {
          "key": "A minor",
          "pct": 40
        }
      ],
      "loudness": {
        "min": -18,
        "max": -6
      },
      "top_tags": [
        {
          "tag": "morning",
          "count": 5
        }
      ]
    },
    "top": [
      {
        "audio_id": "audio_bbb14949dc19",
        "name": "morning-session.wav",
        "facts": {
          "bpm": 128
        }
      }
    ]
  },
  "meta": {
    "request_id": "req_0b7a3c2e-6f1d-4d9a-8e55-3a4b5c6d7e8f"
  }
}
```

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 view with this id in your account.

```json
{
  "error": {
    "code": "view_not_found",
    "message": "View not found",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#view_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 summary could not be computed. 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_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), [`view_not_found`](https://www.scarleta.ai/docs/errors#view_not_found)

### Example

```bash
VIEWID="YOUR_VIEWID"
curl "https://api.scarleta.ai/v1/audio/views/$VIEWID/summary" \
  -H "Authorization: Bearer $SCARLETA_API_KEY"
```

## GET /v1/audio/views/by-tool-call/{toolCallId}

Operation id: `get_view_by_tool_call`

**Find the view a conversation step built**

Returns the view the assistant built in a given step of a conversation, so a client can show it again. Both `toolCallId` (the step) and the `conversation_id` query parameter are needed. A step that built no view of yours returns 404 `view_not_found`. 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.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `toolCallId` | path | string | yes | Identifier of the conversation step. Allowed: at least 1 character. |
| `conversation_id` | query | string | yes | The conversation the step belongs to. Allowed: at least 1 character. |

### Response fields (inside `data`)

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | Identifier of the view. |
| `name` | string |   |
| `origin` | "user" \| "chat" | `user` for views you saved, `chat` for views the assistant built in a conversation until you keep them. |
| `source_conversation_id` | string \| null | For a `chat` view, the conversation it was built in. |
| `source_tool_call_id` | string \| null | For a `chat` view, the step of that conversation that built it. |
| `definition` | object | The definition in the current (version 2) form, as stored. |
| `dropped` | array<string> | Parts of an older stored definition that the current form no longer supports and that were left out. |
| `config` | object | The same definition in the older (version 1) form, kept for existing clients. |
| `created_at` | string |   |
| `updated_at` | string |   |
| `last_opened_at` | string \| null | When the view was last read with the get route. |

### Responses

200: The view.

```json
{
  "data": {
    "id": "8a1c3e5f-7b9d-4f20-a4c6-e8f0123456ab",
    "name": "Fast tracks",
    "origin": "chat",
    "source_conversation_id": "c0e1d2f3-0000-4000-8000-000000000000",
    "source_tool_call_id": "call_1",
    "definition": {
      "version": 2,
      "filters": {},
      "sort": [],
      "columns": []
    },
    "dropped": [],
    "config": {},
    "created_at": "2026-10-20T11:53:45.938Z",
    "updated_at": "2026-10-20T11:53:45.938Z",
    "last_opened_at": null
  },
  "meta": {
    "request_id": "req_0b7a3c2e-6f1d-4d9a-8e55-3a4b5c6d7e8f"
  }
}
```

400: The `conversation_id` query parameter is missing or blank.

```json
{
  "error": {
    "code": "missing_conversation_id",
    "message": "conversation_id is required",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#missing_conversation_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 view of yours was built by this step.

```json
{
  "error": {
    "code": "view_not_found",
    "message": "View not found",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#view_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 view could not be read. 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_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_conversation_id`](https://www.scarleta.ai/docs/errors#missing_conversation_id), [`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), [`view_not_found`](https://www.scarleta.ai/docs/errors#view_not_found)

### Example

```bash
TOOLCALLID="YOUR_TOOLCALLID"
curl "https://api.scarleta.ai/v1/audio/views/by-tool-call/$TOOLCALLID" \
  -H "Authorization: Bearer $SCARLETA_API_KEY"
```