API reference

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

Jump to an operation

GET/v1/audio/{audioId}/shares

List the share links of a file

Free and paid accounts

API key required
Free and paid accounts
No token cost

Returns every link you created for one file, newest first, including revoked and expired ones (check active). A file that is not yours simply has none. 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/shares" \
  -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 share.
[].token	string	The secret part of the link. Anyone with the link can open the file, so treat it like a password.
[].public_url	string	Path of the public page: `/share/<token>` on www.scarleta.ai.
[].audio_id	string
[].allow_download	boolean	True when visitors may download the file.
[].include_analyses	boolean	True when visitors also see the analysis results.
[].expires_at	number \| null	When the link stops working, in milliseconds since the Unix epoch; null for a link that never expires.
[].revoked_at	number \| null	When you revoked the link, in milliseconds since the Unix epoch, or null.
[].created_at	number	Milliseconds since the Unix epoch.
[].active	boolean	False once the link is revoked or has expired.

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",
      "token": "example-share-token",
      "public_url": "/share/example-share-token",
      "audio_id": "audio_3f9c1a7d2b60",
      "allow_download": false,
      "include_analyses": false,
      "expires_at": null,
      "revoked_at": null,
      "created_at": 1791333870854,
      "active": true
    }
  ],
  "meta": {
    "request_id": "1f6c2a9e-3b47-4d58-9a10-6e2d8c4b7f03",
    "count": 1,
    "active_count": 1
  }
}

200 The links, 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}/shares

Create a public share link for a file

Free and paid accounts

API key required
Free and paid accounts
No token cost

Creates a link that lets anyone open one of your files without an account. The defaults are the most private: no download and no analysis results. Send expires_in_seconds for a link that stops working, otherwise it never expires. The body is optional; an empty body uses the defaults. expires_in_seconds must be positive and at most 315360000. 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/shares" \
  -H "Authorization: Bearer $SCARLETA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "expires_in_seconds": 3600,
    "allow_download": false,
    "include_analyses": false
  }'

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
expires_in_secondsbody	number	Optional	Seconds until the link stops working, above 0 and at most 315360000. Omit for a link that never expires.
allow_downloadbody	boolean	Optional	True lets visitors download the file. Defaults to false.
include_analysesbody	boolean	Optional	True shows visitors the analysis results. Defaults to false.

Response fields

Field	Type	Description
id	string	Identifier of the share.
token	string	The secret part of the link. Anyone with the link can open the file, so treat it like a password.
public_url	string	Path of the public page: `/share/<token>` on www.scarleta.ai.
audio_id	string
allow_download	boolean	True when visitors may download the file.
include_analyses	boolean	True when visitors also see the analysis results.
expires_at	number \| null	When the link stops working, in milliseconds since the Unix epoch; null for a link that never expires.
revoked_at	number \| null	When you revoked the link, in milliseconds since the Unix epoch, or null.
created_at	number	Milliseconds since the Unix epoch.
active	boolean	False once the link is revoked or has expired.

Errors

Status	Code	Description
400	invalid_expiry	The body is not valid JSON (`invalid_json`), or `expires_in_seconds` is not a positive number within the limit (`invalid_expiry`).
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",
    "token": "example-share-token",
    "public_url": "/share/example-share-token",
    "audio_id": "audio_3f9c1a7d2b60",
    "allow_download": false,
    "include_analyses": false,
    "expires_at": null,
    "revoked_at": null,
    "created_at": 1791333870854,
    "active": true
  },
  "meta": {
    "request_id": "1f6c2a9e-3b47-4d58-9a10-6e2d8c4b7f03"
  }
}

201 The link was created.
400 The body is not valid JSON (`invalid_json`), or `expires_in_seconds` is not a positive number within the limit (`invalid_expiry`).
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

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

DELETE/v1/audio/{audioId}/shares/{shareId}

Revoke a share link

Free and paid accounts

API key required
Free and paid accounts
No token cost

Stops a link from working. The answer is the link with revoked_at set and active false. Revoking a link twice, a link that is not yours, or an id that is not a UUID 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"
SHAREID="YOUR_SHAREID"
curl -X DELETE "https://api.scarleta.ai/v1/audio/$AUDIOID/shares/$SHAREID" \
  -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.
shareIdpath	string	Required	The `id` of the share.

Response fields

Field	Type	Description
id	string	Identifier of the share.
token	string	The secret part of the link. Anyone with the link can open the file, so treat it like a password.
public_url	string	Path of the public page: `/share/<token>` on www.scarleta.ai.
audio_id	string
allow_download	boolean	True when visitors may download the file.
include_analyses	boolean	True when visitors also see the analysis results.
expires_at	number \| null	When the link stops working, in milliseconds since the Unix epoch; null for a link that never expires.
revoked_at	number \| null	When you revoked the link, in milliseconds since the Unix epoch, or null.
created_at	number	Milliseconds since the Unix epoch.
active	boolean	False once the link is revoked or has expired.

Errors

Status	Code	Description
401	invalid_key	Missing, malformed, unknown or revoked API key.
404	not_found	The link does not exist, is already revoked, 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",
    "token": "example-share-token",
    "public_url": "/share/example-share-token",
    "audio_id": "audio_3f9c1a7d2b60",
    "allow_download": false,
    "include_analyses": false,
    "expires_at": null,
    "revoked_at": 1791333930854,
    "created_at": 1791333870854,
    "active": false
  },
  "meta": {
    "request_id": "1f6c2a9e-3b47-4d58-9a10-6e2d8c4b7f03"
  }
}

200 The link is revoked.
401 Missing, malformed, unknown or revoked API key.
404 The link does not exist, is already revoked, 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

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