Scarleta LogoScarleta
Docs menu

API reference

Recipe catalog

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

Jump to an operation
GET/v1/recipe/{recipe_id}

Get a recipe

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

Returns one recipe with its steps. You can read catalog recipes and your own account's recipes. Step feature names are the neutral capability names.

Cost. Free of charge.

RECIPE_ID="YOUR_RECIPE_ID"
curl "https://api.scarleta.ai/v1/recipe/$RECIPE_ID" \
  -H "Authorization: Bearer $SCARLETA_API_KEY"

Parameters

NameTypeRequiredDescription
recipe_idpathstringRequiredThe recipe id, for example `rec_4821_mix_check`. Ids are case-insensitive and are read in lower case. Allowed: at least 1 character.
Response fields
FieldTypeDescription
successtrueAlways true.
recipeobject
recipe.recipe_idstringIdentifier of the recipe.
recipe.recipe_namestring | nullThe recipe name.
recipe.user_intentstring | nullWhat the recipe was made to do, in the words it was created with.
recipe.ai_descriptionstring | nullA short description of what the recipe does; null when none was set.
recipe.domainstring | nullThe subject area of the recipe; null when none was set.
recipe.scopestringWho can see the recipe: `universal` (the public catalog), `org-private` (your team) or `user-custom` (you).
recipe.catalog_statusstring | null`draft`, `published` or null for a recipe that was saved without a status.
recipe.author_idstring | nullIdentifier of the author, for catalog recipes; null otherwise.
recipe.author_kindstring | nullWhat kind of author made it, for catalog recipes; null otherwise.
recipe.forked_fromstring | nullThe recipe this one was forked from, or null.
recipe.is_templatebooleanTrue for a catalog template recipe.
recipe.usage_countintegerHow many times the recipe has been run. Allowed: -9007199254740991 to 9007199254740991.
recipe.stepsarray<object>The ordered steps. Each has a `step` number, a `tool` name and its `parameters`, and may list `features` and `depends_on`.
recipe.budgetanyThe recipe's budget settings, or null.
recipe.executionanyThe recipe's execution settings, or null.
recipe.is_ownerbooleanTrue when your account can delete this recipe.
Errors
StatusCodeDescription
401invalid_keyMissing, malformed, unknown or revoked API key.
404not_foundNo recipe with this id is visible to you: it does not exist, or it is a private recipe of another account. Both are answered the same way.
429rate_limit_exceededOver the account request budget for the hour. Wait for the `Retry-After` header, then retry.
503auth_unavailableTemporary platform condition; retry shortly.
Example responses
{
  "data": {
    "success": true,
    "recipe": {
      "recipe_id": "rec_1005_cat_spectral",
      "recipe_name": "Analyze the spectral characteristics of an audio recording",
      "user_intent": "analyze the spectral content of this audio",
      "ai_description": "Analyze brightness, spectral centroid, rolloff and energy for mixing and sound-design decisions.",
      "domain": "audio analysis",
      "scope": "universal",
      "catalog_status": "published",
      "author_id": "example-author",
      "author_kind": "scarleta",
      "forked_from": null,
      "is_template": true,
      "usage_count": 8,
      "steps": [
        {
          "step": 1,
          "tool": "spectral_analysis",
          "features": [
            "spectral.centroid",
            "spectral.rolloff"
          ],
          "parameters": {
            "analysis_level": "basic"
          }
        }
      ],
      "budget": null,
      "execution": null,
      "is_owner": false
    }
  },
  "meta": {
    "request_id": "req_0b7a3c2e-6f1d-4d9a-8e55-3a4b5c6d7e8f"
  }
}
  • 200 Success
  • 401 Missing, malformed, unknown or revoked API key.
  • 404 No recipe with this id is visible to you: it does not exist, or it is a private recipe of another account. Both are answered 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

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.

GET/v1/recipe/{recipe_id}/comments

List the comments on a recipe

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

Returns the discussion on a recipe you can see, oldest first. Page with limit and offset; has_more is true when another page exists.

Cost. Free of charge.

RECIPE_ID="YOUR_RECIPE_ID"
curl "https://api.scarleta.ai/v1/recipe/$RECIPE_ID/comments" \
  -H "Authorization: Bearer $SCARLETA_API_KEY"

Parameters

NameTypeRequiredDescription
recipe_idpathstringRequiredThe recipe id, for example `rec_4821_mix_check`. Ids are case-insensitive and are read in lower case. Allowed: at least 1 character.
limitqueryintegerOptionalComments to return. Defaults to 100; a value above 200 is clamped to 200, a value below 1 is read as 1, and a value that is not a number falls back to the default.
offsetqueryintegerOptionalComments to skip. Defaults to 0; a negative or non-numeric value is read as 0. Allowed: 0 to 9007199254740991.
Response fields
FieldTypeDescription
successtrueAlways true.
commentsarray<object>
comments[].comment_idstringIdentifier of the comment.
comments[].recipe_idstringThe recipe the comment belongs to.
comments[].author_labelstringA stable display name for the author, such as `Member 11e594`. It cannot be turned back into an account id.
comments[].bodystringThe comment text.
comments[].created_atintegerWhen the comment was posted, in milliseconds since the Unix epoch. Allowed: -9007199254740991 to 9007199254740991.
countintegerComments in `comments`. Allowed: -9007199254740991 to 9007199254740991.
has_morebooleanTrue when more comments exist after this page.
Errors
StatusCodeDescription
401invalid_keyMissing, malformed, unknown or revoked API key.
404not_foundNo recipe with this id is visible to you: it does not exist, or it is a private recipe of another account. Both are answered the same way.
429rate_limit_exceededOver the account request budget for the hour. Wait for the `Retry-After` header, then retry.
503auth_unavailableTemporary platform condition; retry shortly.
Example responses
{
  "data": {
    "success": true,
    "comments": [
      {
        "comment_id": "cmt_0b2d9f4e-6a31-4c58-9e07-3d1a5b7c9e02",
        "recipe_id": "rec_4821_mix_check",
        "author_label": "Member 11e594",
        "body": "The tempo step works well on this track.",
        "created_at": 1792554097272
      }
    ],
    "count": 1,
    "has_more": false
  },
  "meta": {
    "request_id": "req_0b7a3c2e-6f1d-4d9a-8e55-3a4b5c6d7e8f"
  }
}
  • 200 Success
  • 401 Missing, malformed, unknown or revoked API key.
  • 404 No recipe with this id is visible to you: it does not exist, or it is a private recipe of another account. Both are answered 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

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/recipe/{recipe_id}/comments

Post a comment on a recipe

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

Adds a comment to a recipe you can see and returns it with 201. The comment is shown under a display name derived from your account, never the account id. There is no route to edit or delete a comment; comments on a recipe are removed when the recipe is deleted. A body that is not valid JSON is answered like an empty comment: 400 invalid_request.

Cost. Free of charge.

RECIPE_ID="YOUR_RECIPE_ID"
curl -X POST "https://api.scarleta.ai/v1/recipe/$RECIPE_ID/comments" \
  -H "Authorization: Bearer $SCARLETA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "The tempo step works well on this track."
  }'

Parameters

NameTypeRequiredDescription
recipe_idpathstringRequiredThe recipe id, for example `rec_4821_mix_check`. Ids are case-insensitive and are read in lower case. Allowed: at least 1 character.

Request body

NameTypeRequiredDescription
bodybodystringRequiredThe comment text, at most 4000 characters after leading and trailing spaces are removed. Required, and not blank. Allowed: 1 to 4000 characters.
Response fields
FieldTypeDescription
successtrueAlways true.
commentobject
comment.comment_idstringIdentifier of the comment.
comment.recipe_idstringThe recipe the comment belongs to.
comment.author_labelstringA stable display name for the author, such as `Member 11e594`. It cannot be turned back into an account id.
comment.bodystringThe comment text.
comment.created_atintegerWhen the comment was posted, in milliseconds since the Unix epoch. Allowed: -9007199254740991 to 9007199254740991.
Errors
StatusCodeDescription
400invalid_requestThe comment is missing or blank, is over the length limit, or the body is not valid JSON.
401invalid_keyMissing, malformed, unknown or revoked API key.
404not_foundNo recipe with this id is visible to you: it does not exist, or it is a private recipe of another account. Both are answered the same way.
429rate_limit_exceededOver the account request budget for the hour. Wait for the `Retry-After` header, then retry.
503auth_unavailableTemporary platform condition; retry shortly.
Example responses
{
  "data": {
    "success": true,
    "comment": {
      "comment_id": "cmt_0b2d9f4e-6a31-4c58-9e07-3d1a5b7c9e02",
      "recipe_id": "rec_4821_mix_check",
      "author_label": "Member 11e594",
      "body": "The tempo step works well on this track.",
      "created_at": 1792554097272
    }
  },
  "meta": {
    "request_id": "req_0b7a3c2e-6f1d-4d9a-8e55-3a4b5c6d7e8f"
  }
}
  • 201 The comment just posted.
  • 400 The comment is missing or blank, is over the length limit, or the body is not valid JSON.
  • 401 Missing, malformed, unknown or revoked API key.
  • 404 No recipe with this id is visible to you: it does not exist, or it is a private recipe of another account. Both are answered 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

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.

GET/v1/recipe/author/{author_id}

Get an author's published recipes

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

Returns the public profile of a catalog author: the kind of author, their total number of published catalog recipes, and up to 100 of those recipes, newest first. Page past the first 100 with offset. Drafts and private recipes are never listed. The author_id of a catalog recipe is on GET /v1/recipe/{recipe_id}.

Cost. Free of charge.

AUTHOR_ID="YOUR_AUTHOR_ID"
curl "https://api.scarleta.ai/v1/recipe/author/$AUTHOR_ID" \
  -H "Authorization: Bearer $SCARLETA_API_KEY"

Parameters

NameTypeRequiredDescription
author_idpathstringRequiredThe author id, for example `example-author`. Allowed: at least 1 character.
offsetqueryintegerOptionalRecipes to skip, newest first, to reach the ones after the first 100. Defaults to 0; a negative or non-numeric value is read as 0. A page past the end returns an empty `recipes` list with the real `total`. Allowed: 0 to 9007199254740991.
Response fields
FieldTypeDescription
successtrueAlways true.
authorobject
author.author_idstringThe author id you asked for.
author.author_kindstring | nullWhat kind of author this is.
author.recipesarray<object>Their newest published catalog recipes (at most 100).
author.recipes[].recipe_idstringIdentifier of the recipe.
author.recipes[].recipe_namestring | nullThe recipe name.
author.recipes[].ai_descriptionstring | nullA short description of what the recipe does; null for a recipe that has none.
author.recipes[].domainstring | nullThe subject area of the recipe, for example `transcription`; null when none was set.
author.totalintegerHow many published catalog recipes the author has in all, which can be more than the 100 listed. Allowed: -9007199254740991 to 9007199254740991.
Errors
StatusCodeDescription
401invalid_keyMissing, malformed, unknown or revoked API key.
404not_foundNo author with this id has a published catalog recipe.
429rate_limit_exceededOver the account request budget for the hour. Wait for the `Retry-After` header, then retry.
503auth_unavailableTemporary platform condition; retry shortly.
Example responses
{
  "data": {
    "success": true,
    "author": {
      "author_id": "example-author",
      "author_kind": "scarleta",
      "recipes": [
        {
          "recipe_id": "rec_1005_cat_spectral",
          "recipe_name": "Analyze the spectral characteristics of an audio recording",
          "ai_description": "Analyze brightness, spectral centroid, rolloff and energy for mixing and sound-design decisions.",
          "domain": "audio analysis"
        }
      ],
      "total": 1
    }
  },
  "meta": {
    "request_id": "req_0b7a3c2e-6f1d-4d9a-8e55-3a4b5c6d7e8f"
  }
}
  • 200 Success
  • 401 Missing, malformed, unknown or revoked API key.
  • 404 No author with this id has a published catalog recipe.
  • 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, missing_api_key, missing_auth, rate_limit_unavailable, unauthorized.

GET/v1/recipe/browse

Browse recipes

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

Returns recipes you can see, newest first within a tab. scope=universal (the default) lists the public catalog; scope=own lists recipes saved by your account; scope=draft lists your unpublished recipes. Any other scope value is read as universal, and your own tabs never show another account's recipes. This is a summary list: use GET /v1/recipe/{recipe_id} for the steps. is_owner is true for recipes your account can delete. When the catalog is switched off for an environment the answer is an empty list, not an error.

Cost. Free of charge.

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

Parameters

NameTypeRequiredDescription
scopequery"universal" | "own" | "draft"OptionalWhich list to return. Defaults to `universal`. `tab` is accepted as another name for this parameter.
limitqueryintegerOptionalRecipes to return. Defaults to 50; a value above 100 is clamped to 100, and a value that is not a positive number falls back to the default. Allowed: 1 to 100.
offsetqueryintegerOptionalRecipes to skip, for paging. Defaults to 0; a value that is not a positive number is read as 0. Allowed: 0 to 9007199254740991.
Response fields
FieldTypeDescription
successtrueAlways true.
recipesarray<object>
recipes[].recipe_idstringIdentifier of the recipe.
recipes[].recipe_namestring | nullThe recipe name.
recipes[].ai_descriptionstring | nullA short description of what the recipe does; null for a recipe that has none.
recipes[].domainstring | nullThe subject area of the recipe, for example `transcription`; null when none was set.
recipes[].is_ownerbooleanTrue when your account can delete this recipe.
countintegerRecipes in `recipes`. Allowed: -9007199254740991 to 9007199254740991.
Errors
StatusCodeDescription
401invalid_keyMissing, malformed, unknown or revoked API key.
429rate_limit_exceededOver the account request budget for the hour. Wait for the `Retry-After` header, then retry.
503auth_unavailableTemporary platform condition; retry shortly.
Example responses
{
  "data": {
    "success": true,
    "recipes": [
      {
        "recipe_id": "rec_1005_cat_spectral",
        "recipe_name": "Analyze the spectral characteristics of an audio recording",
        "ai_description": "Analyze brightness, spectral centroid, rolloff and energy for mixing and sound-design decisions.",
        "domain": "audio analysis",
        "is_owner": false
      }
    ],
    "count": 1
  },
  "meta": {
    "request_id": "req_0b7a3c2e-6f1d-4d9a-8e55-3a4b5c6d7e8f"
  }
}
  • 200 The recipes of the chosen tab.
  • 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, missing_api_key, missing_auth, rate_limit_unavailable, unauthorized.