GET/v1/audio/{audioId}/notes

List the notes of a file

Free and paid accounts

API key required
Free and paid accounts
No token cost

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.

Cost. Free of charge.

AUDIOID="YOUR_AUDIOID"
curl "https://api.scarleta.ai/v1/audio/$AUDIOID/notes" \
  -H "Authorization: Bearer $SCARLETA_API_KEY"

Parameters

Name	Type	Required	Description
audioIdpath	string	Required	The `audio_id` or file id of one of your files.

Response fields

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.

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

200 The notes, 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.

POST/v1/audio/{audioId}/notes

Add a note to a file

Free and paid accounts

API key required
Free and paid accounts
No token cost

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.

Cost. Free of charge.

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

Parameters

Name	Type	Required	Description
audioIdpath	string	Required	The `audio_id` or file id of one of your files.

Request body

Name	Type	Required	Description
bodybody	string	Required	The note text, 1 to 10000 characters after trimming.

Response fields

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.

Errors

Status	Code	Description
400	missing_body	The body is not valid JSON, `body` is missing or blank (`missing_body`), or it is longer than the limit (`body_too_long`).
401	invalid_key	Missing, malformed, unknown or revoked API key.
404	not_found	The file does not exist in your library.
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": {
    "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"
  }
}

201 The note was created.
400 The body is not valid JSON, `body` is missing or blank (`missing_body`), or it is longer than the limit (`body_too_long`).
401 Missing, malformed, unknown or revoked API key.
404 The file does not exist in your library.
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: body_too_long, invalid_auth_format, invalid_key_format, missing_api_key, missing_auth, rate_limit_unavailable, unauthorized.

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

Delete a note

Free and paid accounts

API key required
Free and paid accounts
No token cost

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.

Cost. Free of charge.

AUDIOID="YOUR_AUDIOID"
NOTEID="YOUR_NOTEID"
curl -X DELETE "https://api.scarleta.ai/v1/audio/$AUDIOID/notes/$NOTEID" \
  -H "Authorization: Bearer $SCARLETA_API_KEY"

Parameters

Name	Type	Required	Description
audioIdpath	string	Required	The `audio_id` or file id of one of your files.
noteIdpath	string	Required	The `id` of the note.

Response fields

Field	Type	Description
id	string	The deleted note.
status	"deleted"

Errors

Status	Code	Description
400	invalid_id	`noteId` is not a UUID.
401	invalid_key	Missing, malformed, unknown or revoked API key.
404	not_found	The note does not exist, is already deleted, or is not yours.
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": {
    "id": "7d2c9e1a-4b3f-4c68-9a5d-1e0f8b7c6a52",
    "status": "deleted"
  },
  "meta": {
    "request_id": "1f6c2a9e-3b47-4d58-9a10-6e2d8c4b7f03"
  }
}

200 The note is deleted.
400 `noteId` is not a UUID.
401 Missing, malformed, unknown or revoked API key.
404 The note does not exist, is already deleted, or is not yours.
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.