Recipes API

A recipe is a saved, composable pipeline: an ordered list of capability steps plus an execution policy, saved once and invoked by a stable recipe_id. Design your pipeline once, then run it by ID.

Recipe IDs follow the format rec_NNNN_name , a four-digit number and a short slug. Save-time validation enforces this up front, so a recipe that saves is a recipe that runs.

Browse & discover

GET /v1/recipe/browse returns three lanes. You create and save your own recipes, and you discover a growing public library that we curate. Cross-account isolation is enforced: you only ever see the public Discover library plus your own recipes and drafts, never another account's private recipes.

Discover

A growing public library of recipes we curate. Curation is in progress: the catalog is real and live, and still filling out.

My Recipes

The recipes you have created and saved, ready to invoke by ID.

Drafts

Your in-progress recipes, saved before they're finalized.

Run a recipe

Available · API-key authenticated

Run a saved recipe over audio, then poll for the result or receive a recipe_completed webhook. To process many files at once with GA-validated reliability, use the batch API.

POST/v1/recipe/execute

Run a saved recipe over one or more audio files. Poll the returned job, or receive a recipe_completed webhook.

curl -X POST https://api.scarleta.ai/v1/recipe/execute \
  -H "Authorization: Bearer $SCARLETA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recipe_id": "rec_0007_stem_split",
    "audio_urls": ["https://example.com/song.wav"],
    "webhook_url": "https://your-app.com/hooks/scarleta"
  }'

Parameters

Name	Type	Required	Description
recipe_id	string	Required	The saved recipe to run (format rec_NNNN_name).
audio_urls	string[]	Required	Audio to run the recipe over.
webhook_url	string	Optional	Where we POST the recipe_completed event when the run finishes.

Response

Field	Type	Description
job_id	string	Poll with GET /v1/recipe/jobs/:job_id.
status	string	IN_QUEUE on submit.
recipe_id	string	The recipe that was run.

Example response

{
  "job_id": "rjob_4a2f",
  "status": "IN_QUEUE",
  "recipe_id": "rec_0007_stem_split"
}

Poll a recipe job

GET/v1/recipe/jobs/{job_id}

The async status surface for single-recipe runs. Fetch progress and, once complete, the result.

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

Response

Field	Type	Description
status	string	IN_QUEUE, or terminal completed / failed / cancelled.
result	object	Per-step output once completed.

Cancel a recipe run

POST/v1/recipe/cancel

Cancel an in-progress single-recipe run.

curl -X POST https://api.scarleta.ai/v1/recipe/cancel \
  -H "Authorization: Bearer $SCARLETA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "job_id": "rjob_4a2f" }'

Authoring a recipe

Build a recipe from a prompt or from explicit steps, validate it, save it, approve it for use, and delete it when you no longer need it.

POST/v1/recipe/generate

Generate a recipe draft from a plain-language description of the pipeline you want.

curl -X POST https://api.scarleta.ai/v1/recipe/generate \
  -H "Authorization: Bearer $SCARLETA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "prompt": "Remove vocals, then trim to the chorus." }'

POST/v1/recipe/validate

Validate a set of steps before saving: catches malformed pipelines up front.

curl -X POST https://api.scarleta.ai/v1/recipe/validate \
  -H "Authorization: Bearer $SCARLETA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "steps": [ { "capability": "remove_audio_element" }, { "capability": "crop_audio" } ] }'

POST/v1/recipe/save

Save a recipe. Save-time validation enforces the recipe_id format, so a saved recipe is a usable one.

curl -X POST https://api.scarleta.ai/v1/recipe/save \
  -H "Authorization: Bearer $SCARLETA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "karaoke_maker", "steps": [ … ] }'

POST/v1/recipe/approve

Approve a saved recipe for execution.

curl -X POST https://api.scarleta.ai/v1/recipe/approve \
  -H "Authorization: Bearer $SCARLETA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "recipe_id": "rec_0007_stem_split" }'

DELETE/v1/recipe/{recipe_id}

Delete a recipe. Past runs, batches and their results are kept, but the recipe can no longer be run, batched or retried. Any member of the team that owns the recipe (or one of that team's API keys) can delete it; a personal (no-team) recipe can only be deleted by its author. For any other recipe (another team's, another account's or a catalog recipe) the API returns 404 and changes nothing, and a second delete also returns 404.

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

Response

Field	Type	Description
recipe_id	string	The recipe that was deleted.
deleted	boolean	Always true on success.

Next steps

Batch API MCP server