Recipes

Permanently deletes a recipe saved by your account or team, together with its comments. This cannot be undone. A catalog recipe, another account's recipe, or one already deleted answers 404 not_found.

Shows which top-level fields of a fork differ from the recipe it was forked from, and how many steps each has. The recipe in the path must be a fork you can see, and its source must still be visible to you.

Copies a recipe you can see (a catalog recipe or one of yours) into a new draft that belongs to you, and returns it with 201. The copy keeps a pointer to the source in forked_from; use GET /v1/recipe/{recipe_id}/compare to see how a fork has drifted. Without recipe_name the copy is named after the source with " (fork)" added. The response also carries internal bookkeeping fields; do not rely on them.

Moves one of your recipes back to a draft. Only the status changes. You can unpublish recipes saved by your account or team; a catalog recipe or another account's recipe answers 404 not_found.

Records that you approved or rejected a saved recipe. It changes nothing on the recipe itself and does not run it; it leaves a record that your own tools can use. With approved: true you may list modifications (fields you changed); their names are echoed in modifications_applied. With approved: false you may give a rejection_reason. modifications may be at most 102400 bytes once serialized.

Declines a recipe that the assistant proposed in one of your conversations; a recipe that was never proposed in the conversation answers 404 recipe_not_found. The decline is saved durably in the conversation, and a run of that recipe that is still queued or in progress is stopped. Cancel is silent: it sends no reply and costs nothing. Calling it again for the same conversation and recipe answers 200 too and records nothing new. reason is optional. Leading and trailing spaces are removed, a reason that is only spaces counts as none, and only the first 500 characters of the rest are kept.

Starts a recipe on one audio file and answers 200 at once with a job_id; read progress with GET /v1/recipe/jobs/{job_id} or receive a recipe_completed webhook. Name the recipe with recipe_id (a saved recipe of yours or a catalog recipe) or send the whole recipe in recipe, never both. The cost is estimated before anything starts (a rough run time is shown in estimated_seconds, summed from typical timings of each step's tool; a tool with no measured timing counts as 45 seconds); an account whose balance cannot cover it gets 402 insufficient_balance with the estimate, the balance and the shortfall. audio_url must be a public http or https URL or a file in your own library; audio longer than 60 minutes is refused with 400 audio_too_long. Send conversation_id of one of your conversations to tie the run to it; repeating the same run for that conversation returns the existing job with idempotent: true, and a recipe you set aside with POST /v1/recipe/cancel answers status: declined with no job. Refusals use the standard error body; insufficient_balance (402) carries estimated_cost, balance, shortfall and audio_duration in error.details, and audio_too_long (400) carries audio_duration and max_duration. The top-level field budget is refused; set budgets in the recipe.

Describes in words what you want to find out and returns a recipe the planner built for it. Nothing is saved or run: review the recipe, change it if you like, then save it with POST /v1/recipe/save and run it. The recipe_id in the answer is only a suggestion and is not unique, so save the recipe under your own rec_ id. The call needs a token balance of at least 1 and does not debit tokens. It calls the planner, so it takes several seconds and can answer 503 planner_unavailable when the planner times out (the same status as auth_unavailable; read the code); retry later.

Returns the state of a run started with POST /v1/recipe/execute. Poll it until status is COMPLETED, FAILED, CANCELLED or TIMEOUT; results is filled in only once the run has ended. Only recipe runs (ids that start with recipe_) are read here; use GET /v1/analyze/{job_id} for analyses. completed_steps and num_steps count the steps that finished and the steps in the recipe (num_steps is 0 until the run has ended). When you gave a webhook_url, webhook_delivery_status shows how the recipe_completed delivery went: in_progress, delivered, failed, or unconfirmed; it is null when there is no webhook or the run has not ended. It describes only that per-request webhook_url: addresses registered with POST /v1/webhooks are retried the same way, but their outcome is not shown in this field.

Saves a recipe to your account and returns it. A recipe saved with recipe_id of an existing recipe of yours replaces it; one saved under another account's id answers 404 not_found. Without catalog_status or with published, the recipe must pass validation and recipe.recipe_id is required. With catalog_status: draft validation is skipped so you can save work in progress, and a recipe with no recipe_id gets one made for you. catalog_status can only be draft or published, and cannot be set on a template recipe (403 forbidden). The response also carries internal bookkeeping fields; do not rely on them.

Checks a recipe without saving or running it. A valid recipe answers { valid: true, steps_count }. An invalid one answers 400 invalid_request and the message lists every problem, one per line. Run it before saving or running a recipe you built by hand. The recipe may be at most 102400 bytes once serialized.