GET/v1/audio/tags

List tags

Free and paid accounts

API key required
Free and paid accounts
No token cost

Returns every tag in your library with the number of files that carry it: the tags you added (user_tags, with their color) and the ones Scarleta suggested (auto_tags). Files in the trash are not counted. Counts against the hourly account request budget. Available to free and paid accounts.

Cost. Free of charge.

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

Response fields

Field	Type	Description
user_tags	array<object>	Tags you put on files, most used first.
user_tags[].name	string
user_tags[].count	integer	Files that carry the tag. Allowed: -9007199254740991 to 9007199254740991.
user_tags[].color	string \| null	The color set for the tag, or null.
user_tags[].similar_to	array<string>	Other tags that differ only by letter case or surrounding spaces.
auto_tags	array<object>	Tags Scarleta suggested from analysis of your files, most used first.
auto_tags[].name	string
auto_tags[].count	integer	Allowed: -9007199254740991 to 9007199254740991.

Errors

Status	Code	Description
401	invalid_key	Missing, malformed, unknown or revoked API key.
429	rate_limit_exceeded	Over the account request budget. Wait for the `Retry-After` header, then retry.
503	db_unavailable	The tags could not be read. Retry shortly.

Example responses

{
  "data": {
    "user_tags": [
      {
        "name": "morning",
        "count": 12,
        "color": "blue",
        "similar_to": []
      }
    ],
    "auto_tags": [
      {
        "name": "speech",
        "count": 40
      }
    ]
  },
  "meta": {
    "request_id": "req_0b7a3c2e-6f1d-4d9a-8e55-3a4b5c6d7e8f"
  }
}

200 Your tags.
401 Missing, malformed, unknown or revoked API key.
429 Over the account request budget. Wait for the `Retry-After` header, then retry.
503 The tags 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/tags

Add or remove tags on files

Free and paid accounts

API key required
Free and paid accounts
No token cost

Adds the tags in add to, and removes the tags in remove from, every file in audio_ids, in one call. At most 50 tags per list, each at most 64 characters. A tag a file already has is not added twice, and a tag it does not have is ignored when removing. The response counts your files the call was applied to, including files that already had every tag to add and none of the tags to remove. Ids that are not your files are skipped without an error. If both lists are empty, or hold only empty strings, nothing is changed and updated is 0. Counts against the hourly account request budget. Available to free and paid accounts.

Cost. Free of charge.

curl -X POST "https://api.scarleta.ai/v1/audio/tags" \
  -H "Authorization: Bearer $SCARLETA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "audio_ids": [
      "audio_bbb14949dc19"
    ],
    "add": [
      "morning",
      "demo"
    ],
    "remove": [
      "draft"
    ]
  }'

Request body

Name	Type	Required	Description
audio_idsbody	array<string>	Required	Your files: library identifiers (`audio_id`) or storage identifiers (`file_id`). At least one. Allowed: at least 1 item.
addbody	array<string>	Optional	Tags to add, at most 50 of at most 64 characters each. Empty strings are ignored.
removebody	array<string>	Optional	Tags to remove, at most 50 of at most 64 characters each. Empty strings are ignored.

Response fields

Field	Type	Description
updated	integer	Your files the call was applied to, whether or not their tags actually changed. Allowed: -9007199254740991 to 9007199254740991.

Errors

Status	Code	Description
400	tag_too_long	The body is empty or invalid JSON, `audio_ids` is missing or empty, a tag is too long, or a list has too many tags (`too_many_tags`).
401	invalid_key	Missing, malformed, unknown or revoked API key.
429	rate_limit_exceeded	Over the account request budget. Wait for the `Retry-After` header, then retry.
503	db_unavailable	The tags could not be saved. Retry shortly.

Example responses

{
  "data": {
    "updated": 2
  }
}

200 The number of your files the call was applied to. The body is `{ data }` without `meta`.
400 The body is empty or invalid JSON, `audio_ids` is missing or empty, a tag is too long, or a list has too many tags (`too_many_tags`).
401 Missing, malformed, unknown or revoked API key.
429 Over the account request budget. Wait for the `Retry-After` header, then retry.
503 The tags could not be saved. 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_tag, missing_api_key, missing_audio_ids, missing_auth, rate_limit_unavailable, too_many_audio_ids, too_many_tags, unauthorized.

POST/v1/audio/tags/adopt

Turn a suggested tag into your own

Free and paid accounts

API key required
Free and paid accounts
No token cost

Adds a tag Scarleta suggested (auto_tags in the tag list) to every file it was suggested for, as one of your own tags, optionally under another name (as). Files that already have the tag are not changed. A suggested tag that does not exist changes nothing and returns updated: 0. Counts against the hourly account request budget. Available to free and paid accounts.

Cost. Free of charge.

curl -X POST "https://api.scarleta.ai/v1/audio/tags/adopt" \
  -H "Authorization: Bearer $SCARLETA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "auto_tag": "speech",
    "as": "talk"
  }'

Request body

Name	Type	Required	Description
auto_tagbody	string	Required	The suggested tag, 1 to 64 characters.
asbody	string	Optional	The name to give it, 1 to 64 characters. Defaults to the suggested name.

Response fields

Field	Type	Description
updated	integer	Files whose tags changed. Allowed: -9007199254740991 to 9007199254740991.

Errors

Status	Code	Description
400	invalid_tag	The body is invalid JSON, or a name is empty or too long (`tag_too_long`).
401	invalid_key	Missing, malformed, unknown or revoked API key.
429	rate_limit_exceeded	Over the account request budget. Wait for the `Retry-After` header, then retry.
503	db_unavailable	The tag could not be adopted. Retry shortly.

Example responses

{
  "data": {
    "updated": 8
  },
  "meta": {
    "request_id": "req_0b7a3c2e-6f1d-4d9a-8e55-3a4b5c6d7e8f"
  }
}

200 The number of files that gained the tag.
400 The body is invalid JSON, or a name is empty or too long (`tag_too_long`).
401 Missing, malformed, unknown or revoked API key.
429 Over the account request budget. Wait for the `Retry-After` header, then retry.
503 The tag could not be adopted. 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, missing_api_key, missing_auth, rate_limit_unavailable, tag_too_long, unauthorized.

PUT/v1/audio/tags/color

Set a tag color

Free and paid accounts

API key required
Free and paid accounts
No token cost

Sets the color of a tag, or clears it with color: null. The color is kept for the tag name even when no file carries it at the moment. Allowed colors: red, orange, amber, green, teal, blue, purple, pink, gray. Counts against the hourly account request budget. Available to free and paid accounts.

Cost. Free of charge.

curl -X PUT "https://api.scarleta.ai/v1/audio/tags/color" \
  -H "Authorization: Bearer $SCARLETA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "morning",
    "color": "blue"
  }'

Request body

Name	Type	Required	Description
namebody	string	Required	The tag, 1 to 64 characters.
colorbody	"red" \| "orange" \| "amber" \| "green" \| "teal" \| "blue" \| "purple" \| "pink" \| "gray" \| null	Required	A color, or `null` to clear it.

Response fields

Field	Type	Description
name	string
color	string \| null

Errors

Status	Code	Description
400	invalid_color	The body is invalid JSON, the name is empty or too long, or the color is not an allowed one.
401	invalid_key	Missing, malformed, unknown or revoked API key.
429	rate_limit_exceeded	Over the account request budget. Wait for the `Retry-After` header, then retry.
503	db_unavailable	The color could not be saved. Retry shortly.

Example responses

{
  "data": {
    "name": "morning",
    "color": "blue"
  },
  "meta": {
    "request_id": "req_0b7a3c2e-6f1d-4d9a-8e55-3a4b5c6d7e8f"
  }
}

200 The tag and its color after the change.
400 The body is invalid JSON, the name is empty or too long, or the color is not an allowed one.
401 Missing, malformed, unknown or revoked API key.
429 Over the account request budget. Wait for the `Retry-After` header, then retry.
503 The color could not be saved. 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_tag, missing_api_key, missing_auth, rate_limit_unavailable, tag_too_long, unauthorized.

POST/v1/audio/tags/merge

Merge tags into one

Free and paid accounts

API key required
Free and paid accounts
No token cost

Replaces up to 20 tags with a single tag, on every file that carries any of them. If the target tag already has a color it keeps it; otherwise it takes the color of the first source that had one. The source tags disappear. Counts against the hourly account request budget. Available to free and paid accounts.

Cost. Free of charge.

curl -X POST "https://api.scarleta.ai/v1/audio/tags/merge" \
  -H "Authorization: Bearer $SCARLETA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": [
      "demo",
      "draft"
    ],
    "into": "morning"
  }'

Request body

Name	Type	Required	Description
frombody	array<string>	Required	Tags to merge, 1 to 20.
intobody	string	Required	The tag to keep, 1 to 64 characters.

Response fields

Field	Type	Description
updated	integer	Files whose tags changed. Allowed: -9007199254740991 to 9007199254740991.

Errors

Status	Code	Description
400	invalid_tag	The body is invalid JSON, `from` is not 1 to the allowed number of names, or a name is empty or too long (`tag_too_long`).
401	invalid_key	Missing, malformed, unknown or revoked API key.
429	rate_limit_exceeded	Over the account request budget. Wait for the `Retry-After` header, then retry.
503	db_unavailable	The tags could not be merged. Retry shortly.

Example responses

{
  "data": {
    "updated": 5
  },
  "meta": {
    "request_id": "req_0b7a3c2e-6f1d-4d9a-8e55-3a4b5c6d7e8f"
  }
}

200 The number of files changed.
400 The body is invalid JSON, `from` is not 1 to the allowed number of names, or a name is empty or too long (`tag_too_long`).
401 Missing, malformed, unknown or revoked API key.
429 Over the account request budget. Wait for the `Retry-After` header, then retry.
503 The tags could not be merged. 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, missing_api_key, missing_auth, rate_limit_unavailable, tag_too_long, unauthorized.

POST/v1/audio/tags/rename

Rename a tag

Free and paid accounts

API key required
Free and paid accounts
No token cost

Renames a tag on every file that carries it. If a file already has the new name the two merge. The tag's color moves to the new name. Renaming a tag nothing carries changes nothing and returns updated: 0. Counts against the hourly account request budget. Available to free and paid accounts.

Cost. Free of charge.

curl -X POST "https://api.scarleta.ai/v1/audio/tags/rename" \
  -H "Authorization: Bearer $SCARLETA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "demo",
    "to": "draft-demo"
  }'

Request body

Name	Type	Required	Description
frombody	string	Required	The tag to rename, 1 to 64 characters.
tobody	string	Required	The new name, 1 to 64 characters.

Response fields

Field	Type	Description
updated	integer	Files whose tags changed. Allowed: -9007199254740991 to 9007199254740991.

Errors

Status	Code	Description
400	invalid_tag	The body is invalid JSON, or a name is empty, or too long (`tag_too_long`). `error.details.field` names it.
401	invalid_key	Missing, malformed, unknown or revoked API key.
429	rate_limit_exceeded	Over the account request budget. Wait for the `Retry-After` header, then retry.
503	db_unavailable	The tag could not be renamed. Retry shortly.

Example responses

{
  "data": {
    "updated": 3
  },
  "meta": {
    "request_id": "req_0b7a3c2e-6f1d-4d9a-8e55-3a4b5c6d7e8f"
  }
}

200 The number of files changed.
400 The body is invalid JSON, or a name is empty, or too long (`tag_too_long`). `error.details.field` names it.
401 Missing, malformed, unknown or revoked API key.
429 Over the account request budget. Wait for the `Retry-After` header, then retry.
503 The tag could not be renamed. 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, missing_api_key, missing_auth, rate_limit_unavailable, tag_too_long, unauthorized.

POST/v1/audio/tags/selection-state

Count tags across a selection of files

Free and paid accounts

API key required
Free and paid accounts
No token cost

For the files you name, returns each tag they carry with how many of those files carry it, so a tag that is on all of them can be told from one that is on some. Files that are not yours, and files in the trash, are left out. Counts against the hourly account request budget. Available to free and paid accounts.

Cost. Free of charge.

curl -X POST "https://api.scarleta.ai/v1/audio/tags/selection-state" \
  -H "Authorization: Bearer $SCARLETA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "audio_ids": [
      "audio_bbb14949dc19"
    ]
  }'

Request body

Name	Type	Required	Description
audio_idsbody	array<string>	Required	The selection: library identifiers (`audio_id`) or storage identifiers (`file_id`) of your files, 1 to 5000.

Errors

Status	Code	Description
400	missing_audio_ids	The `audio_ids` list is missing, empty, or not a list of strings.
401	invalid_key	Missing, malformed, unknown or revoked API key.
429	rate_limit_exceeded	Over the account request budget. Wait for the `Retry-After` header, then retry.
503	db_unavailable	The tags could not be read. Retry shortly.

Example responses

{
  "data": {
    "morning": 2,
    "demo": 1
  },
  "meta": {
    "request_id": "req_0b7a3c2e-6f1d-4d9a-8e55-3a4b5c6d7e8f"
  }
}

200 Tag counts for the selection. An empty object when no tag applies.
400 The `audio_ids` list is missing, empty, or not a list of strings.
401 Missing, malformed, unknown or revoked API key.
429 Over the account request budget. Wait for the `Retry-After` header, then retry.
503 The tags 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_json, invalid_key_format, missing_api_key, missing_auth, rate_limit_unavailable, too_many_audio_ids, unauthorized.