API reference

Saved views

8 operations. Base URL https://api.scarleta.ai. Select an operation to see its parameters, samples and errors.

Jump to an operation

GET/v1/audio/views

List saved views

Free and paid accounts

API key required
Free and paid accounts
No token cost

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.

Cost. Free of charge.

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

Response fields

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.

Errors

Status	Code	Description
401	invalid_key	Missing, malformed, unknown or revoked API key.
429	rate_limit_exceeded	Over the account request budget. Wait for the `Retry-After` header, then retry.

Example responses

{
  "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
    }
  ]
}

200 Your views. The body is `{ data }` where `data` is an array, without `meta`.
401 Missing, malformed, unknown or revoked API key.
429 Over the account request budget. Wait for the `Retry-After` header, then retry.

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: auth_unavailable, invalid_auth_format, invalid_key_format, missing_api_key, missing_auth, rate_limit_unavailable, unauthorized.

POST/v1/audio/views

Create a saved view

Free and paid accounts

API key required
Free and paid accounts
No token cost

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.

Cost. Free of charge.

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

Request body

Name	Type	Required	Description
namebody	string	Required	The view name, 1 to 200 characters after trimming.
definitionbody	object	Optional	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`).
configbody	object	Optional	The older (version 1) form of the definition. Send this or `definition`, not both.

Response fields

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.

Errors

Status	Code	Description
400	invalid_config	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).
401	invalid_key	Missing, malformed, unknown or revoked API key.
429	rate_limit_exceeded	Over the account request budget. Wait for the `Retry-After` header, then retry.
503	db_unavailable	The view could not be saved. Retry shortly.

Example responses

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

201 The view was saved. The body is `{ data }` without `meta`.
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).
401 Missing, malformed, unknown or revoked API key.
429 Over the account request budget. Wait for the `Retry-After` header, then retry.
503 The view could not be saved. Retry shortly.

Try it

Other error codes this operation can return: auth_unavailable, invalid_auth_format, invalid_columns, invalid_filter, invalid_group, invalid_json, invalid_key_format, invalid_name, invalid_sort, missing_api_key, missing_auth, missing_name, name_too_long, rate_limit_unavailable, unauthorized.

GET/v1/audio/views/{viewId}

Get a saved view

Free and paid accounts

API key required
Free and paid accounts
No token cost

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.

Cost. Free of charge.

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

Parameters

Name	Type	Required	Description
viewIdpath	string	Required	The `id` of one of your saved views.

Response fields

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.

Errors

Status	Code	Description
401	invalid_key	Missing, malformed, unknown or revoked API key.
404	view_not_found	No view with this id in your account.
429	rate_limit_exceeded	Over the account request budget. Wait for the `Retry-After` header, then retry.
503	db_unavailable	The view could not be read. Retry shortly.

Example responses

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

200 The view.
401 Missing, malformed, unknown or revoked API key.
404 No view with this id in your account.
429 Over the account request budget. Wait for the `Retry-After` header, then retry.
503 The view could not be read. Retry shortly.

Try it

Other error codes this operation can return: auth_unavailable, invalid_auth_format, invalid_key_format, missing_api_key, missing_auth, rate_limit_unavailable, unauthorized.

PUT/v1/audio/views/{viewId}

Update a saved view

Free and paid accounts

API key required
Free and paid accounts
No token cost

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.

Cost. Free of charge.

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

Parameters

Name	Type	Required	Description
viewIdpath	string	Required	The `id` of one of your saved views.

Request body

Name	Type	Required	Description
namebody	string	Optional	The view name, 1 to 200 characters after trimming.
definitionbody	object	Optional	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`).
configbody	object	Optional	The older (version 1) form of the definition. Send this or `definition`, not both.

Response fields

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.

Errors

Status	Code	Description
400	nothing_to_update	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.
401	invalid_key	Missing, malformed, unknown or revoked API key.
404	not_found	No view with this id in your account.
429	rate_limit_exceeded	Over the account request budget. Wait for the `Retry-After` header, then retry.
503	db_unavailable	The view could not be saved. Retry shortly.

Example responses

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

200 The updated view. The body is `{ data }` without `meta`.
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.
401 Missing, malformed, unknown or revoked API key.
404 No view with this id in your account.
429 Over the account request budget. Wait for the `Retry-After` header, then retry.
503 The view could not be saved. Retry shortly.

Try it

Other error codes this operation can return: auth_unavailable, invalid_auth_format, invalid_columns, invalid_config, invalid_filter, invalid_group, invalid_json, invalid_key_format, invalid_name, invalid_sort, invalid_view_id, missing_api_key, missing_auth, missing_view_id, name_too_long, rate_limit_unavailable, unauthorized.

DELETE/v1/audio/views/{viewId}

Delete a saved view

Free and paid accounts

API key required
Free and paid accounts
No token cost

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.

Cost. Free of charge.

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

Parameters

Name	Type	Required	Description
viewIdpath	string	Required	The `id` of one of your saved views.

Response fields

Field	Type	Description
id	string	The deleted view.
deleted	true

Errors

Status	Code	Description
400	invalid_view_id	The id is not a UUID.
401	invalid_key	Missing, malformed, unknown or revoked API key.
404	not_found	No view with this id in your account (or it is already deleted).
429	rate_limit_exceeded	Over the account request budget. Wait for the `Retry-After` header, then retry.
503	db_unavailable	The view could not be deleted. Retry shortly.

Example responses

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

200 The view is deleted. The body is `{ data }` without `meta`.
400 The id is not a UUID.
401 Missing, malformed, unknown or revoked API key.
404 No view with this id in your account (or it is already deleted).
429 Over the account request budget. Wait for the `Retry-After` header, then retry.
503 The view could not be deleted. Retry shortly.

Try it

Other error codes this operation can return: auth_unavailable, invalid_auth_format, invalid_key_format, missing_api_key, missing_auth, missing_view_id, rate_limit_unavailable, unauthorized.

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

Keep a view under a name

Free and paid accounts

API key required
Free and paid accounts
No token cost

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.

Cost. Free of charge.

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

Parameters

Name	Type	Required	Description
viewIdpath	string	Required	The `id` of one of your saved views.

Request body

Name	Type	Required	Description
namebody	string	Required	The view name, 1 to 200 characters after trimming.

Response fields

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.

Errors

Status	Code	Description
400	missing_name	The body is invalid JSON, or the name is missing (`missing_name`) or too long (`name_too_long`). `error.details.field` names it.
401	invalid_key	Missing, malformed, unknown or revoked API key.
404	view_not_found	No view with this id in your account.
429	rate_limit_exceeded	Over the account request budget. Wait for the `Retry-After` header, then retry.
503	db_unavailable	The view could not be saved. Retry shortly.

Example responses

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

200 The kept view.
400 The body is invalid JSON, or the name is missing (`missing_name`) or too long (`name_too_long`). `error.details.field` names it.
401 Missing, malformed, unknown or revoked API key.
404 No view with this id in your account.
429 Over the account request budget. Wait for the `Retry-After` header, then retry.
503 The view could not be saved. Retry shortly.

Try it

Other error codes this operation can return: auth_unavailable, invalid_auth_format, invalid_json, invalid_key_format, missing_api_key, missing_auth, name_too_long, rate_limit_unavailable, unauthorized.

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

Summarize a saved view

Free and paid accounts

API key required
Free and paid accounts
No token cost

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.

Cost. Free of charge.

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

Parameters

Name	Type	Required	Description
viewIdpath	string	Required	The `id` of one of your saved views.

Response fields

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.

Errors

Status	Code	Description
401	invalid_key	Missing, malformed, unknown or revoked API key.
404	view_not_found	No view with this id in your account.
429	rate_limit_exceeded	Over the account request budget. Wait for the `Retry-After` header, then retry.
503	db_unavailable	The summary could not be computed. Retry shortly.

Example responses

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

200 The summary.
401 Missing, malformed, unknown or revoked API key.
404 No view with this id in your account.
429 Over the account request budget. Wait for the `Retry-After` header, then retry.
503 The summary could not be computed. Retry shortly.

Try it

Other error codes this operation can return: auth_unavailable, invalid_auth_format, invalid_key_format, missing_api_key, missing_auth, rate_limit_unavailable, unauthorized.

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

Find the view a conversation step built

Free and paid accounts

API key required
Free and paid accounts
No token cost

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.

Cost. Free of charge.

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

Parameters

Name	Type	Required	Description
toolCallIdpath	string	Required	Identifier of the conversation step. Allowed: at least 1 character.
conversation_idquery	string	Required	The conversation the step belongs to. Allowed: at least 1 character.

Response fields

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.

Errors

Status	Code	Description
400	missing_conversation_id	The `conversation_id` query parameter is missing or blank.
401	invalid_key	Missing, malformed, unknown or revoked API key.
404	view_not_found	No view of yours was built by this step.
429	rate_limit_exceeded	Over the account request budget. Wait for the `Retry-After` header, then retry.
503	db_unavailable	The view could not be read. Retry shortly.

Example responses

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

200 The view.
400 The `conversation_id` query parameter is missing or blank.
401 Missing, malformed, unknown or revoked API key.
404 No view of yours was built by this step.
429 Over the account request budget. Wait for the `Retry-After` header, then retry.
503 The view could not be read. Retry shortly.

Try it

Other error codes this operation can return: auth_unavailable, invalid_auth_format, invalid_key_format, missing_api_key, missing_auth, rate_limit_unavailable, unauthorized.