API reference

Documents

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

Jump to an operation

GET/v1/documents

List documents

Free and paid accounts

API key required
Free and paid accounts
No token cost

Returns the latest version of each of your documents, newest first, with the full content. meta.count is the number of documents returned.

Cost. Free of charge.

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

Parameters

Name	Type	Required	Description
limitquery	integer	Optional	Documents to return, from 1 to 100. Defaults to 50. A value outside the range, or one that is not a whole number, is refused with `invalid_limit`.

Response fields

Field	Type	Description
[].id	string	Identifier of the document. Every version of one document has the same id.
[].created_at	string	ISO 8601 timestamp of this version.
[].title	string	The document title.
[].content	string \| null	The document content; null when the version has none.
[].kind	"text" \| "code" \| "sheet" \| "image" \| "chart"	What the content is: `text`, `code`, `sheet`, `image` or `chart`.

Errors

Status	Code	Description
400	invalid_limit	`limit` is not a whole number in the allowed range.
401	invalid_key	Missing, malformed, unknown or revoked API key.
429	rate_limit_exceeded	Over the account request budget for the hour. Wait for the `Retry-After` header, then retry.
503	auth_unavailable	Temporary platform condition; retry shortly.

Example responses

{
  "data": [
    {
      "id": "5c2f8a14-9d3b-4e07-a1c6-0b7d4e9f2a38",
      "created_at": "2026-10-21T03:41:56.630Z",
      "title": "Mix notes",
      "content": "Kick is masking the bass below 80 Hz.",
      "kind": "text"
    }
  ],
  "meta": {
    "request_id": "4d18043e-5317-4d76-9c7f-b01c34db04b4",
    "count": 1
  }
}

200 Success
400 `limit` is not a whole number in the allowed range.
401 Missing, malformed, unknown or revoked API key.
429 Over the account request budget for the hour. 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, list_failed, missing_api_key, missing_auth, rate_limit_unavailable, unauthorized.

POST/v1/documents

Create a document or save a new version

Free and paid accounts

API key required
Free and paid accounts
No token cost

Without id, creates a new document and returns its first version with 201. With the id of one of your documents, appends a new version to it (the history is kept) and returns that version, also with 201. A body that is not valid JSON is answered like a body with no title: 400 missing_title. A chart whose content is an invented, flat heatmap is refused with 400 degenerate_heatmap; fix the content to save it.

Cost. Free of charge.

curl -X POST "https://api.scarleta.ai/v1/documents" \
  -H "Authorization: Bearer $SCARLETA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Mix notes",
    "content": "Kick is masking the bass below 80 Hz.",
    "kind": "text"
  }'

Request body

Name	Type	Required	Description
idbody	string	Optional	Id of an existing document to add a version to. Leave it out to create a new document. Must be a UUID.
titlebody	string	Required	The title, at most 200 characters after leading and trailing spaces are removed. Required, and not blank. Allowed: 1 to 200 characters.
contentbody	string \| null	Optional	The content, at most 1048576 characters. Leave it out or send null for none.
kindbody	"text" \| "code" \| "sheet" \| "image" \| "chart"	Optional	What the content is. Defaults to `text`.

Response fields

Field	Type	Description
id	string	Identifier of the document. Every version of one document has the same id.
created_at	string	ISO 8601 timestamp of this version.
title	string	The document title.
content	string \| null	The document content; null when the version has none.
kind	"text" \| "code" \| "sheet" \| "image" \| "chart"	What the content is: `text`, `code`, `sheet`, `image` or `chart`.

Errors

Status	Code	Description
400	missing_title	The title is missing or blank, or the body is not valid JSON (`missing_title`); the title is too long (`title_too_long`); `id` is not a UUID (`invalid_id`); `kind` is not one of the five kinds (`invalid_kind`); or a chart is a degenerate heatmap (`degenerate_heatmap`).
401	invalid_key	Missing, malformed, unknown or revoked API key.
404	not_found	`id` names a document that is not yours or does not exist.
413	content_too_large	The content is over the size limit.
429	rate_limit_exceeded	Over the account request budget for the hour. Wait for the `Retry-After` header, then retry.
503	auth_unavailable	Temporary platform condition; retry shortly.

Example responses

{
  "data": {
    "id": "5c2f8a14-9d3b-4e07-a1c6-0b7d4e9f2a38",
    "created_at": "2026-10-21T03:41:56.630Z",
    "title": "Mix notes",
    "content": "Kick is masking the bass below 80 Hz.",
    "kind": "text"
  },
  "meta": {
    "request_id": "req_0b7a3c2e-6f1d-4d9a-8e55-3a4b5c6d7e8f"
  }
}

201 The version just saved.
400 The title is missing or blank, or the body is not valid JSON (`missing_title`); the title is too long (`title_too_long`); `id` is not a UUID (`invalid_id`); `kind` is not one of the five kinds (`invalid_kind`); or a chart is a degenerate heatmap (`degenerate_heatmap`).
401 Missing, malformed, unknown or revoked API key.
404 `id` names a document that is not yours or does not exist.
413 The content is over the size limit.
429 Over the account request budget for the hour. Wait for the `Retry-After` header, then retry.
503 Temporary platform condition; retry shortly.

Try it

Other error codes this operation can return: create_failed, degenerate_heatmap, invalid_auth_format, invalid_id, invalid_key_format, invalid_kind, missing_api_key, missing_auth, rate_limit_unavailable, title_too_long, unauthorized.

GET/v1/documents/{id}

Get a document

Free and paid accounts

API key required
Free and paid accounts
No token cost

Returns the latest version of one document. With versions=true, returns every version instead, oldest first, and meta.count is the number of versions.

Cost. Free of charge.

ID="YOUR_ID"
curl "https://api.scarleta.ai/v1/documents/$ID" \
  -H "Authorization: Bearer $SCARLETA_API_KEY"

Parameters

Name	Type	Required	Description
idpath	string	Required	The document id, for example `5c2f8a14-9d3b-4e07-a1c6-0b7d4e9f2a38`. Allowed: at least 1 character.
versionsquery	string	Optional	Send `true` to get every version of the document, oldest first. Any other value returns only the latest version.

Response fields

Field	Type	Description
id	string	Identifier of the document. Every version of one document has the same id.
created_at	string	ISO 8601 timestamp of this version.
title	string	The document title.
content	string \| null	The document content; null when the version has none.
kind	"text" \| "code" \| "sheet" \| "image" \| "chart"	What the content is: `text`, `code`, `sheet`, `image` or `chart`.
[].id	string	Identifier of the document. Every version of one document has the same id.
[].created_at	string	ISO 8601 timestamp of this version.
[].title	string	The document title.
[].content	string \| null	The document content; null when the version has none.
[].kind	"text" \| "code" \| "sheet" \| "image" \| "chart"	What the content is: `text`, `code`, `sheet`, `image` or `chart`.

Errors

Status	Code	Description
400	invalid_id	The id in the path is not a UUID.
401	invalid_key	Missing, malformed, unknown or revoked API key.
404	not_found	No document with this id exists in your account (a document of another account is reported the same way).
429	rate_limit_exceeded	Over the account request budget for the hour. Wait for the `Retry-After` header, then retry.
503	auth_unavailable	Temporary platform condition; retry shortly.

Example responses

{
  "data": {
    "id": "5c2f8a14-9d3b-4e07-a1c6-0b7d4e9f2a38",
    "created_at": "2026-10-21T03:41:56.630Z",
    "title": "Mix notes",
    "content": "Kick is masking the bass below 80 Hz.",
    "kind": "text"
  },
  "meta": {
    "request_id": "req_0b7a3c2e-6f1d-4d9a-8e55-3a4b5c6d7e8f"
  }
}

200 The latest version as an object, or with `versions=true` an array of versions (see the response fields: `data` is an object or an array).
400 The id in the path is not a UUID.
401 Missing, malformed, unknown or revoked API key.
404 No document with this id exists in your account (a document of another account is reported the same way).
429 Over the account request budget for the hour. Wait for the `Retry-After` header, then retry.
503 Temporary platform condition; retry shortly.

Try it

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

DELETE/v1/documents/{id}

Delete the versions of a document saved after a time

Free and paid accounts

API key required
Free and paid accounts
No token cost

Removes every version of the document saved after the time in after, which restores the document to the version that was current at that time. This cannot be undone. after is required so a call can never wipe a whole history by accident; send after=0 to remove every version, which deletes the document. The call answers 200 with removed: 0 when nothing is newer, when the document is already gone, or when it is not yours.

Cost. Free of charge.

ID="YOUR_ID"
curl -X DELETE "https://api.scarleta.ai/v1/documents/$ID" \
  -H "Authorization: Bearer $SCARLETA_API_KEY"

Parameters

Name	Type	Required	Description
idpath	string	Required	The document id, for example `5c2f8a14-9d3b-4e07-a1c6-0b7d4e9f2a38`. Allowed: at least 1 character.
afterquery	number	Required	A time in milliseconds since the Unix epoch. Versions saved after it are removed; the version saved at exactly this time stays. Use `Date.parse(created_at)` of the version you want to keep. Send a whole number of milliseconds (digits only): a blank, fractional, signed or exponent value is refused with `invalid_after`.

Response fields

Field	Type	Description
id	string	The document id.
removed	integer	Versions removed. Allowed: -9007199254740991 to 9007199254740991.

Errors

Status	Code	Description
400	missing_after	`after` is missing (`missing_after`) or is not a whole number of milliseconds (`invalid_after`), or the id is not a UUID (`invalid_id`).
401	invalid_key	Missing, malformed, unknown or revoked API key.
429	rate_limit_exceeded	Over the account request budget for the hour. Wait for the `Retry-After` header, then retry.
503	auth_unavailable	Temporary platform condition; retry shortly.

Example responses

{
  "data": {
    "id": "5c2f8a14-9d3b-4e07-a1c6-0b7d4e9f2a38",
    "removed": 1
  },
  "meta": {
    "request_id": "req_0b7a3c2e-6f1d-4d9a-8e55-3a4b5c6d7e8f"
  }
}

200 Success
400 `after` is missing (`missing_after`) or is not a whole number of milliseconds (`invalid_after`), or the id is not a UUID (`invalid_id`).
401 Missing, malformed, unknown or revoked API key.
429 Over the account request budget for the hour. Wait for the `Retry-After` header, then retry.
503 Temporary platform condition; retry shortly.

Try it

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