API reference

Imports and duplicates

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

Jump to an operation
POST/v1/audio/duplicates/check

Check files for duplicates

Free and paid accounts
  • API key required
  • Free and paid accounts
  • No token cost

Tells you which of your files you already have, before you upload them. Send up to 1000 items, each with the SHA-256 of a file's bytes; the answer lists the items whose hash matches a file in your library (originals only, not renders). An item with no match is simply absent from matches. Hashes you sent at upload time are checked against the real bytes later, so a match is reliable but a brand-new upload may not match yet. Capped at 60 requests per minute per account across the upload session routes and the duplicate check; this route does not use up the hourly account request budget. Available to free and paid accounts.

Cost. Free of charge.

curl -X POST "https://api.scarleta.ai/v1/audio/duplicates/check" \
  -H "Authorization: Bearer $SCARLETA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "ref": "morning-session.wav",
        "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
        "size_bytes": 1920044
      }
    ]
  }'

Request body

NameTypeRequiredDescription
itemsbodyarray<object>RequiredFiles to check, 1 to 1000 items.
items[].refbodystringRequiredYour own label for the file (a path or an id). Echoed back on a match. Allowed: at least 1 character.
items[].sha256bodystringRequiredSHA-256 of the file bytes as 64 lowercase hexadecimal characters.
items[].size_bytesbodynumberRequiredSize of the file in bytes. Allowed: at least 0.
Response fields
FieldTypeDescription
matchesarray<object>
matches[].refstringThe `ref` of the matching item you sent.
matches[].audio_idstringLibrary identifier of the file you already have.
matches[].file_idstring | nullStorage identifier of that file, when known.
matches[].namestring | nullDisplay name of that file.
matches[].uploaded_atstringWhen that file was uploaded, as an ISO 8601 timestamp.
matches[].track_group_idstring | nullIdentifier of the track the file is a version of, if any.
Errors
StatusCodeDescription
400invalid_items`items` is empty or too long, or an item has no `ref`, a malformed `sha256` or a negative size.
401invalid_keyMissing, malformed, unknown or revoked API key.
429rate_limit_exceededOver the account request budget. Wait for the `Retry-After` header, then retry.
503duplicates_unavailableThe check is temporarily unavailable. Retry shortly.
Example responses
{
  "data": {
    "matches": [
      {
        "ref": "morning-session.wav",
        "audio_id": "audio_bbb14949dc19",
        "file_id": "3f2b8c1e-5d4a-4e6f-9a7b-1c2d3e4f5a6b",
        "name": "morning-session.wav",
        "uploaded_at": "2026-10-20T11:53:45.938Z",
        "track_group_id": null
      }
    ]
  }
}
  • 200 The matching items. The body is `{ data }` without `meta`.
  • 400 `items` is empty or too long, or an item has no `ref`, a malformed `sha256` or a negative size.
  • 401 Missing, malformed, unknown or revoked API key.
  • 429 Over the account request budget. Wait for the `Retry-After` header, then retry.
  • 503 The check is temporarily unavailable. 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: auth_unavailable, invalid_auth_format, invalid_json, invalid_key_format, invalid_sha256, missing_api_key, missing_auth, rate_limit_unavailable, unauthorized.

GET/v1/audio/imports

List imports

Free and paid accounts
  • API key required
  • Free and paid accounts
  • No token cost

Returns your imports, newest first, at most 100; there is no paging, so older imports are not returned. Add active=1 to list only the ones still in progress (queued or running). Counts against the hourly account request budget. Available to free and paid accounts.

Cost. Free of charge.

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

Parameters

NameTypeRequiredDescription
activequery"1"OptionalSet to `1` to list only imports that are still in progress.
Response fields
FieldTypeDescription
importsarray<object>
imports[].import_idstringIdentifier of the import.
imports[].provider"link" | "google_drive" | "dropbox"Where the file comes from: `link`, `google_drive` or `dropbox`.
imports[].source_labelstringFor `link`, the host and path of the link without any query string; for `google_drive` and `dropbox`, the file name.
imports[].status"queued" | "running" | "completed" | "failed" | "rejected"`queued` and `running` are in progress; the other three are final.
imports[].audio_idstring | nullLibrary identifier of the imported file once `completed`.
imports[].bytesnumber | nullSize of the imported file in bytes once `completed`.
imports[].tagsarray<string>
imports[].error_codestring | nullWhy the import failed or was rejected, when it did.
imports[].error_messagestring | null
imports[].created_atstringISO 8601 timestamp.
imports[].updated_atstringISO 8601 timestamp.
Errors
StatusCodeDescription
401invalid_keyMissing, malformed, unknown or revoked API key.
429rate_limit_exceededOver the account request budget. Wait for the `Retry-After` header, then retry.
503db_unavailableThe list could not be read. Retry shortly.
Example responses
{
  "data": {
    "imports": [
      {
        "import_id": "2b4d6f80-1a3c-4e5f-8071-92a3b4c5d6e7",
        "provider": "link",
        "source_label": "example.com/audio/morning-session.wav",
        "status": "completed",
        "audio_id": "audio_bbb14949dc19",
        "bytes": 1920044,
        "tags": [
          "morning"
        ],
        "error_code": null,
        "error_message": null,
        "created_at": "2026-10-20T11:53:45.938Z",
        "updated_at": "2026-10-20T11:53:45.938Z"
      }
    ]
  }
}
  • 200 Your imports. The body is `{ data }` without `meta`.
  • 401 Missing, malformed, unknown or revoked API key.
  • 429 Over the account request budget. Wait for the `Retry-After` header, then retry.
  • 503 The list could not be read. 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: auth_unavailable, invalid_auth_format, invalid_key_format, missing_api_key, missing_auth, rate_limit_unavailable, unauthorized.

POST/v1/audio/imports

Import files from a link, Google Drive or Dropbox

Free and paid accounts
  • API key required
  • Free and paid accounts
  • No token cost

Asks Scarleta to fetch an audio file from a public link and add it to your library, so you do not have to download and re-upload it. The call returns 202 at once with the import in state queued; read the import (or list the active ones) until its status is final. A completed import carries the new file's audio_id. The link must be a public http or https address that serves audio; links to private or internal addresses are refused with 400 invalid_url, and a rejected request is still recorded in your import list with status rejected. provider: "link" takes url. provider: "google_drive" takes files (a list of { id, name }, at most 50 distinct files) and access_token (a short-lived Google OAuth token with the drive.file scope; it is not written to our database or logs and is used only to download the picked files; the import job holds it for as long as that job runs; it stops working after about an hour). provider: "dropbox" takes files (a list of { link, name, bytes }, at most 50 distinct files), where each link is a direct link on dl.dropboxusercontent.com. Google Drive and Dropbox create one import per distinct file, so the call can return several imports; a file whose import could not be started is returned as a failed import with its own id; Google-native documents (Docs, Sheets) cannot be imported. Any other provider returns 400 unsupported_provider. If the import service cannot start the job, the call still returns 202 with the import already failed (error_code: "import_unavailable"). Counts against the hourly account request budget. Available to free and paid accounts.

Cost. Free of charge; the imported file counts toward your storage.

curl -X POST "https://api.scarleta.ai/v1/audio/imports" \
  -H "Authorization: Bearer $SCARLETA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "link",
    "url": "https://example.com/audio/morning-session.wav",
    "tags": [
      "morning"
    ]
  }'

Request body

NameTypeRequiredDescription
providerbody"link" | "google_drive" | "dropbox"RequiredThe source type.
urlbodystringOptionalPublic address of the audio file. Required for `link`.
filesbodyarray<object>OptionalThe picked files, at most 50 distinct ones (repeats are ignored). Required for `google_drive` and `dropbox`.
files[].idbodystringOptionalGoogle Drive file id. Required for `google_drive`.
files[].linkbodystringOptionalDropbox direct link on `dl.dropboxusercontent.com`. Required for `dropbox`.
files[].namebodystringOptionalFile name shown in the import list.
files[].bytesbodynumberOptionalFile size reported by Dropbox. Informational only.
access_tokenbodystringOptionalGoogle OAuth access token (`drive.file` scope). Required for `google_drive`. Not written to our database or logs; used only to download the picked files. Allowed: at most 4096 characters.
tagsbodyarray<string>OptionalTags to put on the imported file, at most 50 of at most 64 characters each.
Response fields
FieldTypeDescription
importsarray<object>One entry per import created: one for a link, one per distinct picked file for Google Drive and Dropbox.
imports[].import_idstringIdentifier of the import.
imports[].provider"link" | "google_drive" | "dropbox"Where the file comes from: `link`, `google_drive` or `dropbox`.
imports[].source_labelstringFor `link`, the host and path of the link without any query string; for `google_drive` and `dropbox`, the file name.
imports[].status"queued" | "running" | "completed" | "failed" | "rejected"`queued` and `running` are in progress; the other three are final.
imports[].audio_idstring | nullLibrary identifier of the imported file once `completed`.
imports[].bytesnumber | nullSize of the imported file in bytes once `completed`.
imports[].tagsarray<string>
imports[].error_codestring | nullWhy the import failed or was rejected, when it did.
imports[].error_messagestring | null
imports[].created_atstringISO 8601 timestamp.
imports[].updated_atstringISO 8601 timestamp.
Errors
StatusCodeDescription
400invalid_urlThe provider is not supported, the link is empty, malformed, or points to a private or unsafe address, the picked files or the Google Drive token are missing or invalid, or `tags` is invalid.
401invalid_keyMissing, malformed, unknown or revoked API key.
429rate_limit_exceededOver the account request budget. Wait for the `Retry-After` header, then retry.
503db_unavailableThe import could not be recorded. Retry shortly.
Example responses
{
  "data": {
    "imports": [
      {
        "import_id": "2b4d6f80-1a3c-4e5f-8071-92a3b4c5d6e7",
        "provider": "link",
        "source_label": "example.com/audio/morning-session.wav",
        "status": "queued",
        "audio_id": null,
        "bytes": null,
        "tags": [
          "morning"
        ],
        "error_code": null,
        "error_message": null,
        "created_at": "2026-10-20T11:53:45.938Z",
        "updated_at": "2026-10-20T11:53:45.938Z"
      }
    ]
  }
}
  • 202 The import is queued. The body is `{ data }` without `meta`.
  • 400 The provider is not supported, the link is empty, malformed, or points to a private or unsafe address, the picked files or the Google Drive token are missing or invalid, or `tags` is invalid.
  • 401 Missing, malformed, unknown or revoked API key.
  • 429 Over the account request budget. Wait for the `Retry-After` header, then retry.
  • 503 The import could not be recorded. 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: access_token_required, auth_unavailable, invalid_auth_format, invalid_files, invalid_json, invalid_key_format, invalid_tags, missing_api_key, missing_auth, rate_limit_unavailable, tag_too_long, too_many_files, too_many_tags, unauthorized, unsupported_provider.

GET/v1/audio/imports/{importId}

Get an import

Free and paid accounts
  • API key required
  • Free and paid accounts
  • No token cost

Returns one import. Poll it after creating the import until status is completed, failed or rejected. Only imports created by your own account can be read; any other id returns 404. Counts against the hourly account request budget. Available to free and paid accounts.

Cost. Free of charge.

IMPORTID="YOUR_IMPORTID"
curl "https://api.scarleta.ai/v1/audio/imports/$IMPORTID" \
  -H "Authorization: Bearer $SCARLETA_API_KEY"

Parameters

NameTypeRequiredDescription
importIdpathstringRequiredThe `import_id` returned when the import was created.
Response fields
FieldTypeDescription
import_idstringIdentifier of the import.
provider"link" | "google_drive" | "dropbox"Where the file comes from: `link`, `google_drive` or `dropbox`.
source_labelstringFor `link`, the host and path of the link without any query string; for `google_drive` and `dropbox`, the file name.
status"queued" | "running" | "completed" | "failed" | "rejected"`queued` and `running` are in progress; the other three are final.
audio_idstring | nullLibrary identifier of the imported file once `completed`.
bytesnumber | nullSize of the imported file in bytes once `completed`.
tagsarray<string>
error_codestring | nullWhy the import failed or was rejected, when it did.
error_messagestring | null
created_atstringISO 8601 timestamp.
updated_atstringISO 8601 timestamp.
Errors
StatusCodeDescription
401invalid_keyMissing, malformed, unknown or revoked API key.
404import_not_foundNo import with this id in your account.
429rate_limit_exceededOver the account request budget. Wait for the `Retry-After` header, then retry.
503db_unavailableThe import could not be read. Retry shortly.
Example responses
{
  "data": {
    "import_id": "2b4d6f80-1a3c-4e5f-8071-92a3b4c5d6e7",
    "provider": "link",
    "source_label": "example.com/audio/morning-session.wav",
    "status": "completed",
    "audio_id": "audio_bbb14949dc19",
    "bytes": 1920044,
    "tags": [
      "morning"
    ],
    "error_code": null,
    "error_message": null,
    "created_at": "2026-10-20T11:53:45.938Z",
    "updated_at": "2026-10-20T11:53:45.938Z"
  }
}
  • 200 The import. The body is `{ data }` without `meta`.
  • 401 Missing, malformed, unknown or revoked API key.
  • 404 No import with this id in your account.
  • 429 Over the account request budget. Wait for the `Retry-After` header, then retry.
  • 503 The import could not be read. 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: auth_unavailable, invalid_auth_format, invalid_key_format, missing_api_key, missing_auth, rate_limit_unavailable, unauthorized.