API reference

File conversations

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

Jump to an operation

GET/v1/audio/{fileId}/conversations

List the conversations about a file

Free and paid accounts

API key required
Free and paid accounts
No token cost

Returns your conversations that were started on one file, newest activity first, so a file page can show the discussions about it. A conversation counts when it was created with the file's audio_url, under any of the addresses the same file has been known by. Deleted conversations are left out. Page with cursor: while meta.has_more is true, pass meta.cursor as cursor in the next request. A file with no conversations, a file that does not exist and a file that is not yours all answer an empty list. On success this route answers { data, meta }, and meta carries counts but no request_id. meta here also has cursor and has_more. If the database is briefly unavailable the list is empty rather than an error.

Cost. Free of charge.

FILEID="YOUR_FILEID"
curl "https://api.scarleta.ai/v1/audio/$FILEID/conversations" \
  -H "Authorization: Bearer $SCARLETA_API_KEY"

Parameters

Name	Type	Required	Description
fileIdpath	string	Required	The `audio_id` of one of your files. A trailing media extension such as `.wav` is ignored.
cursorquery	string	Optional	The `meta.cursor` of the previous page.

Response fields

Field	Type	Description
[].conversation_id	string	Identifier of the conversation.
[].title	string \| null	Title of the conversation, or null.
[].updated_at	number \| null	When the conversation last changed, in milliseconds since the Unix epoch.

Errors

Status	Code	Description
401	invalid_key	Missing, malformed, unknown or revoked API key.
429	rate_limit_exceeded	Over the account request budget or the per-minute cap of this route. Wait for the `Retry-After` header, then retry.
503	auth_unavailable	Temporary platform condition; retry shortly.

Example responses

{
  "data": [
    {
      "conversation_id": "c3a9f1d2-7b46-4e80-9d15-2f6a8b0c4e71",
      "title": "Mix notes",
      "updated_at": 1791333870854
    }
  ],
  "meta": {
    "count": 1,
    "cursor": null,
    "has_more": false
  }
}

200 A page of conversations, newest first.
401 Missing, malformed, unknown or revoked API key.
429 Over the account request budget or the per-minute cap of this route. Wait for the `Retry-After` header, then retry.
503 Temporary platform condition; retry shortly.

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