Create a recipe from a task
Run any agent task with record_recipe: true. When the job finishes it carries a recipe_draft_id. Save it as a recipe and give it a name.
curl https://browsa.io/v1/tasks -H "X-API-Key: $BROWSA_API_KEY" \
-d '{"task": "Search walmart.com for coffee maker, return title and price of each result",
"llm": "browsa", "record_recipe": true,
"output_schema": {"type": "object", "properties": {"items": {"type": "array"}}, "required": ["items"]}}'
# when the job is completed
curl https://browsa.io/v1/recipes -H "X-API-Key: $BROWSA_API_KEY" \
-d '{"from_job_id": "JOB_ID", "name": "walmart-search"}'Browsa turns the run into steps. Calls the page made to the site's own JSON endpoints become network steps; clicks, typing and reads become DOM steps with several locators each. Browsa proposes the parameters (here the search term). Check them with GET /v1/recipes/{id}, and pass params or output on create to set them yourself.
Or upload one
A recipe is plain JSON. Write it by hand or edit a recorded one, then POST /v1/recipes with {"recipe": {...}}. It is checked against the recipe schema (recipe-v1) before it is saved.
{
"name": "quotes",
"version": 1,
"params": { "type": "object", "properties": { "page": { "type": "integer", "default": 1 } } },
"output": { "type": "object", "properties": { "items": { "type": "array", "minItems": 1 } }, "required": ["items"] },
"exit": { "network": "default" },
"steps": [
{ "id": "s1", "kind": "navigate", "url": "https://quotes.toscrape.com/page/{{page}}/" },
{ "id": "s2", "kind": "fetch", "in_page": true, "method": "GET", "mutation": false, "save_as": "quotes",
"url": "https://quotes.toscrape.com/api/quotes?page={{page}}" },
{ "id": "s3", "kind": "extract", "from": "saved", "source": "quotes", "schema_ref": "output",
"how": { "jsonpath": "$.quotes[*]" } },
{ "id": "s4", "kind": "extract", "from": "page", "schema_ref": "output",
"how": { "css": "div.quote", "fields": { "text": "span.text", "author": "small.author" } } }
],
"fallbacks": { "s2": ["s4"] }
}- Step kinds.
navigate,click,type,select,press,scroll,wait,fetch,extract,assert. - Placeholders.
{{param}},{{json:param}}for a JSON value,{{discover:key}}for a value read from the page at run time. - Fallbacks. The steps that run instead when a step fails. Here the DOM read replaces the network call.
- Writes. A fetch that changes something must say
mutation: true. It is sent only when your recipe says so.
Run it with new inputs
curl https://browsa.io/v1/recipes/RECIPE_ID/run -H "X-API-Key: $BROWSA_API_KEY" \
-d '{"params": {"query": "air fryer"}, "wait": 60}'With wait the call returns the finished run. Without it you get a run id at once; read it with GET /v1/recipe-runs/{run_id} or pass webhook_url. A run returns status, output, the layer each step used, whether a repair ran, duration_ms and credits. You can also pass proxy and profile_id, as on a task, and schedule a recipe with recipe_id and params.
Each step tries three layers in order:
- Network, inside the page. The site's own JSON call, sent from a live Phantom page with its cookies and fingerprint.
- DOM. If the call fails or its answer does not fit, the fallback steps run. Captchas are solved in the session, as in tasks.
- One-step repair. If a DOM step fails, the agent gets that one goal on the current page, with a small step budget. Its action becomes the new step.
- Check. The output must match your
outputschema and assertions, or the run fails.
Versions, promote, rollback
A repair never changes the live version on the spot. It saves a draft version. The draft becomes live only after a full run with it passes and its output validates.
repair_mode: "auto"- Default. A draft that passes its check run is promoted.
repair_mode: "review"- Drafts wait for you:
POST /v1/recipes/{id}/versions/{v}/promote. - List versions
GET /v1/recipes/{id}/versions- Roll back
POST /v1/recipes/{id}/rollbackmakes the previous version live again.- Webhooks
recipe.repaired,recipe.promoted,recipe.failed
Failures
A failed run is typed and free. If a browser had started, its time is refunded as with tasks.
| Code | What happened | What to do |
|---|---|---|
blocked | A bot wall was not passed | Try another exit (proxy). See the per-site numbers |
needs_login | The site asked to sign in | Sign in again on the profile, then rerun |
site_changed | A step broke and the repair did not fix it | Record the task again; the live version is unchanged |
invalid_output | The data did not match the output schema | Check the schema, or record again |
params_invalid | The inputs did not match the params schema | Fix the request |
timeout | The run took longer than its budget | Rerun, or raise wait |
Pricing
A replay costs the same credits as the task it was recorded from. Failed replays are free. What you gain is time: seconds instead of a minute, and the same steps and output on every run.