Recipes

28 operations on 14 paths.

/api/recipes

GETList recipes

Sign-in Session cookie or Bearer tokenMCP tool list_recipes

A workflow is reached by its owner and, while it is filed in a project, by that project's owner and people; its steps, layout and runs follow it. Results name the workflow's owner and SQL home and are read in that home within the caller's own reach: a reference the caller cannot reach is missing to them, named as written, and recorded lineage, output links and captured layer identities out of their reach are left out. Content changes are open to the owner, the project's owner and its editors; the SQL and dataset parameters anyone but the owner saves into a step must name only datasets within their own reach in the workflow's home, the workflow's declared outputs aside, else the save is refused with sql_error naming the reference as written and nothing changes. Deletion stays the owner's. Anyone who reaches a workflow may duplicate it into their own space: the copy keeps the workflow's SQL home and is filed in its project only when the duplicator may file there (its owner or an editor). Administrators reach nothing more. Unreached or missing workflows, steps, captured layers and project references return not_found before reading private contents or changing resources; a reached workflow whose change the caller may not make returns forbidden and changes nothing. A step's declared output name is taken when a dataset of that name is in the workflow's SQL home or in the declaring person's own space, and duplicate-name allocation considers the duplicator's own datasets and workflows and the datasets of the SQL home the copy keeps, both preserving the existing same-workflow conflict rules. Accepted changes recheck account activity and referenced-resource access at commit. Every recipe the caller reaches (their own, and every one filed in a project they own or belong to), each with its steps and their current conditions, what each step reads now, and a summary of the whole (its status and counts). A recipe is a workspace object like a dataset — not owned by a map, and outliving the layer that prompted it. origin narrows the answer to the workflows page's own (workflow) or the builder's one-step recipes (builder); unfiltered, both answer.

Parameters

• originQuery

  Which surface made the recipes wanted. Omitted, every recipe.

  string

  One of workflow, builder

• projectQuery

  Narrow to one project's members by project id: any project the caller reaches, its own or one shared with it, whoever owns what is filed there; "none" narrows to the caller's own items filed in no project at all (one still filed in a project the caller no longer reaches is not none). Omitted, everything the caller reaches answers. An unknown or unreached project is not found, never an empty list.

  string

Responses

• 200

  Success.

  application/json

  RecipeList

• 401403404503default

  Error with a machine-readable code and human message.

  application/json

  Error

• 405

  method_not_allowed: the method is unsupported for this path.

  application/json

  Error

  • AllowHeader

    Exactly the documented methods for this path.

    stringalways GET, HEAD, OPTIONS, POST

POSTCreate a recipe

Sign-in Session cookie or Bearer tokenMCP tool create_recipe

Created resources belong to the authenticated account. Submitted owner identities cannot assign or transfer ownership. A workflow is reached by its owner and, while it is filed in a project, by that project's owner and people; its steps, layout and runs follow it. Results name the workflow's owner and SQL home and are read in that home within the caller's own reach: a reference the caller cannot reach is missing to them, named as written, and recorded lineage, output links and captured layer identities out of their reach are left out. Content changes are open to the owner, the project's owner and its editors; the SQL and dataset parameters anyone but the owner saves into a step must name only datasets within their own reach in the workflow's home, the workflow's declared outputs aside, else the save is refused with sql_error naming the reference as written and nothing changes. Deletion stays the owner's. Anyone who reaches a workflow may duplicate it into their own space: the copy keeps the workflow's SQL home and is filed in its project only when the duplicator may file there (its owner or an editor). Administrators reach nothing more. Unreached or missing workflows, steps, captured layers and project references return not_found before reading private contents or changing resources; a reached workflow whose change the caller may not make returns forbidden and changes nothing. A step's declared output name is taken when a dataset of that name is in the workflow's SQL home or in the declaring person's own space, and duplicate-name allocation considers the duplicator's own datasets and workflows and the datasets of the SQL home the copy keeps, both preserving the existing same-workflow conflict rules. Accepted changes recheck account activity and referenced-resource access at commit. Request body bound. At most 16,777,216 wire bytes; a larger body is refused with request_body_too_large before JSON parsing. Ordinary maximum-shape layout documents fit; escape-inflated keys and unbounded note ids can exceed the outer byte bound and are refused by design. A named, ordered list of steps. Dependencies may point only backwards, which is what keeps it authorable as a list and checkable without cycle detection at run time. The name is trimmed, must not be empty, and is at most 120 characters; two recipes may share one. origin says which surface is creating it — workflow (the default) or builder, the one-step Tools' invisible recipes — and never changes afterwards. Only workflows can be project members.

Request body

At most 16,777,216 bytes (16 MiB); a larger body is refused with request_body_too_large.

application/json

object

• namestringrequiredmax length 120

• originstring

  One of workflow, builder

• projectIdstringor null

  The project the new workflow joins; omitted or null, it starts unfiled. An unknown project refuses and creates nothing. Builder-origin recipes are refused project membership. It must be a project the caller owns or edits, whose owner is active: one the caller only views refuses with forbidden, and one they cannot reach refuses as an unknown one.

Responses

• 201

  Created.

  application/json

  RecipeEnvelope

• 401403404413503default

  Error with a machine-readable code and human message.

  application/json

  Error

• 405

  method_not_allowed: the method is unsupported for this path.

  application/json

  Error

  • AllowHeader

    Exactly the documented methods for this path.

    stringalways GET, HEAD, OPTIONS, POST

• HEADRead response headers

  Sign-in Session cookie or Bearer tokenAnswers 200, 401, 403, 404, 405, 503, defaultAllow GET, HEAD, OPTIONS, POST

  Automatic HEAD uses GET with no response body.

Also on this path: OPTIONS under System.

/api/recipes/{id}

GETRead a recipe

Sign-in Session cookie or Bearer tokenMCP tool get_recipe

A workflow is reached by its owner and, while it is filed in a project, by that project's owner and people; its steps, layout and runs follow it. Results name the workflow's owner and SQL home and are read in that home within the caller's own reach: a reference the caller cannot reach is missing to them, named as written, and recorded lineage, output links and captured layer identities out of their reach are left out. Content changes are open to the owner, the project's owner and its editors; the SQL and dataset parameters anyone but the owner saves into a step must name only datasets within their own reach in the workflow's home, the workflow's declared outputs aside, else the save is refused with sql_error naming the reference as written and nothing changes. Deletion stays the owner's. Anyone who reaches a workflow may duplicate it into their own space: the copy keeps the workflow's SQL home and is filed in its project only when the duplicator may file there (its owner or an editor). Administrators reach nothing more. Unreached or missing workflows, steps, captured layers and project references return not_found before reading private contents or changing resources; a reached workflow whose change the caller may not make returns forbidden and changes nothing. A step's declared output name is taken when a dataset of that name is in the workflow's SQL home or in the declaring person's own space, and duplicate-name allocation considers the duplicator's own datasets and workflows and the datasets of the SQL home the copy keeps, both preserving the existing same-workflow conflict rules. Accepted changes recheck account activity and referenced-resource access at commit. The recipe and every step in order, each with all the conditions true of it — broken, output missing, stale, never run, current — its stale causes with the input each came from, and its latest attempt as an ordinary run. The condition and the attempt are read together: fresh output with a failed latest attempt is a real and common combination.

Parameters

• idPathrequired

  Recipe id.

  string

Responses

• 200

  Success.

  application/json

  RecipeEnvelope

• 401403404503default

  Error with a machine-readable code and human message.

  application/json

  Error

• 405

  method_not_allowed: the method is unsupported for this path.

  application/json

  Error

  • AllowHeader

    Exactly the documented methods for this path.

    stringalways DELETE, GET, HEAD, OPTIONS, PATCH

PATCHRename a recipe

Sign-in Session cookie or Bearer tokenMCP tool update_recipe

A workflow is reached by its owner and, while it is filed in a project, by that project's owner and people; its steps, layout and runs follow it. Results name the workflow's owner and SQL home and are read in that home within the caller's own reach: a reference the caller cannot reach is missing to them, named as written, and recorded lineage, output links and captured layer identities out of their reach are left out. Content changes are open to the owner, the project's owner and its editors; the SQL and dataset parameters anyone but the owner saves into a step must name only datasets within their own reach in the workflow's home, the workflow's declared outputs aside, else the save is refused with sql_error naming the reference as written and nothing changes. Deletion stays the owner's. Anyone who reaches a workflow may duplicate it into their own space: the copy keeps the workflow's SQL home and is filed in its project only when the duplicator may file there (its owner or an editor). Administrators reach nothing more. Unreached or missing workflows, steps, captured layers and project references return not_found before reading private contents or changing resources; a reached workflow whose change the caller may not make returns forbidden and changes nothing. A step's declared output name is taken when a dataset of that name is in the workflow's SQL home or in the declaring person's own space, and duplicate-name allocation considers the duplicator's own datasets and workflows and the datasets of the SQL home the copy keeps, both preserving the existing same-workflow conflict rules. Accepted changes recheck account activity and referenced-resource access at commit. Request body bound. At most 16,777,216 wire bytes; a larger body is refused with request_body_too_large before JSON parsing. Ordinary maximum-shape layout documents fit; escape-inflated keys and unbounded note ids can exceed the outer byte bound and are refused by design. The same name rule as creation: trimmed, not empty, at most 120 characters, shared names allowed. Renaming moves the recipe's last-edited time, as adding, editing, reordering or removing a step does; running it does not.

Parameters

• X-Edit-RevisionHeaderrequired

  Read the document first and send its editRevision. Missing or malformed: 400 invalid_request. Stale: 409 stale_revision, with no changes. Chain accepted results; reload explicitly after refusal.

  stringpattern ^[0-9a-f]{32}$

  Opaque durable revision paired with this document state. Camera and derived writes do not change it.

• idPathrequired

  Recipe id.

  string

Request body

At most 16,777,216 bytes (16 MiB); a larger body is refused with request_body_too_large.

application/json

object

• namestringrequired

Responses

• 200

  Success.

  application/json

  RecipeEnvelope

• 400401403404409413503default

  Error with a machine-readable code and human message.

  application/json

  Error

• 405

  method_not_allowed: the method is unsupported for this path.

  application/json

  Error

  • AllowHeader

    Exactly the documented methods for this path.

    stringalways DELETE, GET, HEAD, OPTIONS, PATCH

DELETEDelete a recipe

Sign-in Session cookie or Bearer tokenMCP tool delete_recipe

A workflow is reached by its owner and, while it is filed in a project, by that project's owner and people; its steps, layout and runs follow it. Results name the workflow's owner and SQL home and are read in that home within the caller's own reach: a reference the caller cannot reach is missing to them, named as written, and recorded lineage, output links and captured layer identities out of their reach are left out. Content changes are open to the owner, the project's owner and its editors; the SQL and dataset parameters anyone but the owner saves into a step must name only datasets within their own reach in the workflow's home, the workflow's declared outputs aside, else the save is refused with sql_error naming the reference as written and nothing changes. Deletion stays the owner's. Anyone who reaches a workflow may duplicate it into their own space: the copy keeps the workflow's SQL home and is filed in its project only when the duplicator may file there (its owner or an editor). Administrators reach nothing more. Unreached or missing workflows, steps, captured layers and project references return not_found before reading private contents or changing resources; a reached workflow whose change the caller may not make returns forbidden and changes nothing. A step's declared output name is taken when a dataset of that name is in the workflow's SQL home or in the declaring person's own space, and duplicate-name allocation considers the duplicator's own datasets and workflows and the datasets of the SQL home the copy keeps, both preserving the existing same-workflow conflict rules. Accepted changes recheck account activity and referenced-resource access at commit. Deletes the workflow, its steps, lineage and run records. The datasets its steps produced remain in the workspace. A recipe records how they were made; it does not own them.

Parameters

• X-Edit-RevisionHeaderrequired

  Read the document first and send its editRevision. Missing or malformed: 400 invalid_request. Stale: 409 stale_revision, with no changes. Chain accepted results; reload explicitly after refusal.

  stringpattern ^[0-9a-f]{32}$

  Opaque durable revision paired with this document state. Camera and derived writes do not change it.

• idPathrequired

  Recipe id.

  string

Responses

• 200

  Success.

  application/json

  RecipeDeleted

• 400401403404409503default

  Error with a machine-readable code and human message.

  application/json

  Error

• 405

  method_not_allowed: the method is unsupported for this path.

  application/json

  Error

  • AllowHeader

    Exactly the documented methods for this path.

    stringalways DELETE, GET, HEAD, OPTIONS, PATCH

• HEADRead response headers

  Sign-in Session cookie or Bearer tokenAnswers 200, 401, 403, 404, 405, 503, defaultAllow DELETE, GET, HEAD, OPTIONS, PATCH

  Automatic HEAD uses GET with no response body.

Also on this path: OPTIONS under System.

/api/recipes/{id}/duplicate

POSTDuplicate a recipe

Sign-in Session cookie or Bearer tokenMCP tool duplicate_recipe

Created resources belong to the authenticated account. Submitted owner identities cannot assign or transfer ownership. A workflow is reached by its owner and, while it is filed in a project, by that project's owner and people; its steps, layout and runs follow it. Results name the workflow's owner and SQL home and are read in that home within the caller's own reach: a reference the caller cannot reach is missing to them, named as written, and recorded lineage, output links and captured layer identities out of their reach are left out. Content changes are open to the owner, the project's owner and its editors; the SQL and dataset parameters anyone but the owner saves into a step must name only datasets within their own reach in the workflow's home, the workflow's declared outputs aside, else the save is refused with sql_error naming the reference as written and nothing changes. Deletion stays the owner's. Anyone who reaches a workflow may duplicate it into their own space: the copy keeps the workflow's SQL home and is filed in its project only when the duplicator may file there (its owner or an editor). Administrators reach nothing more. Unreached or missing workflows, steps, captured layers and project references return not_found before reading private contents or changing resources; a reached workflow whose change the caller may not make returns forbidden and changes nothing. A step's declared output name is taken when a dataset of that name is in the workflow's SQL home or in the declaring person's own space, and duplicate-name allocation considers the duplicator's own datasets and workflows and the datasets of the SQL home the copy keeps, both preserving the existing same-workflow conflict rules. Accepted changes recheck account activity and referenced-resource access at commit. A copy named "<name> copy", a workflow, that has never run: the same steps in the same order under fresh ids, each from its active definition (a pending edit is not carried) with its layer provenance; every output renamed to a free name; every read of an original output redirected to the copy's, in named inputs and in SQL table references alike, with literals and comments untouched. The original and its datasets are unchanged. Refused (409) if the recipe changes while the copy is prepared, and (422) if a step's SQL cannot be rewritten to read the copy's outputs.

Parameters

• idPathrequired

  Recipe id.

  string

Responses

• 201

  Created.

  application/json

  RecipeEnvelope

• 401403404503default

  Error with a machine-readable code and human message.

  application/json

  Error

• 405

  method_not_allowed: the method is unsupported for this path.

  application/json

  Error

  • AllowHeader

    Exactly the documented methods for this path.

    stringalways OPTIONS, POST

Also on this path: OPTIONS under System.

/api/recipes/{id}/dependencies

GETThe datasets a workflow reads and writes

Sign-in Session cookie or Bearer tokenMCP tool get_workflow_dependencies

A workflow is reached by its owner and, while it is filed in a project, by that project's owner and people; its steps, layout and runs follow it. Results name the workflow's owner and SQL home and are read in that home within the caller's own reach: a reference the caller cannot reach is missing to them, named as written, and recorded lineage, output links and captured layer identities out of their reach are left out. Content changes are open to the owner, the project's owner and its editors; the SQL and dataset parameters anyone but the owner saves into a step must name only datasets within their own reach in the workflow's home, the workflow's declared outputs aside, else the save is refused with sql_error naming the reference as written and nothing changes. Deletion stays the owner's. Anyone who reaches a workflow may duplicate it into their own space: the copy keeps the workflow's SQL home and is filed in its project only when the duplicator may file there (its owner or an editor). Administrators reach nothing more. Unreached or missing workflows, steps, captured layers and project references return not_found before reading private contents or changing resources; a reached workflow whose change the caller may not make returns forbidden and changes nothing. A step's declared output name is taken when a dataset of that name is in the workflow's SQL home or in the declaring person's own space, and duplicate-name allocation considers the duplicator's own datasets and workflows and the datasets of the SQL home the copy keeps, both preserving the existing same-workflow conflict rules. Accepted changes recheck account activity and referenced-resource access at commit. Each step's references resolve to dataset identities in the workflow's SQL home within the caller's reach, the workflow's own outputs as the caller would run them, and each one is listed with its owner and the name the caller would type: a dataset the caller cannot reach is left out rather than named, and a same-named dataset of the caller's own never stands in for the home's. Memberships name the projects the caller reaches, and on the caller's own datasets every project they are in, one the caller no longer reaches included; producers only workflows the caller reaches, each marked with whether the caller owns it. The filing checklist's subject for a workflow: every registered dataset the workflow's current node definitions read (a pending edit over the active one) and every runner's recorded output of the workflow that the caller reaches, exactly once — a dataset both read and written appears once — with the same facts as a map's dependencies: source, row count, project memberships, the producing workflow, geometry column and sampled geometry type. A node whose definition cannot be analyzed fails the whole read with dependencies_unresolved; unlike the recipe read, which tolerates an unreadable node, this read never answers partially.

Parameters

• idPathrequired

  Recipe id.

  string

Responses

• 200

  Success.

  application/json

  WorkflowDependencies

• 401403404503default

  Error with a machine-readable code and human message.

  application/json

  Error

• 405

  method_not_allowed: the method is unsupported for this path.

  application/json

  Error

  • AllowHeader

    Exactly the documented methods for this path.

    stringalways GET, HEAD, OPTIONS

• HEADRead response headers

  Sign-in Session cookie or Bearer tokenAnswers 200, 401, 403, 404, 405, 503, defaultAllow GET, HEAD, OPTIONS

  Automatic HEAD uses GET with no response body.

Also on this path: OPTIONS under System.

/api/recipes/{id}/layout

GETRead a recipe's canvas layout

Sign-in Session cookie or Bearer tokenMCP tool get_recipe_layout

A workflow is reached by its owner and, while it is filed in a project, by that project's owner and people; its steps, layout and runs follow it. Results name the workflow's owner and SQL home and are read in that home within the caller's own reach: a reference the caller cannot reach is missing to them, named as written, and recorded lineage, output links and captured layer identities out of their reach are left out. Content changes are open to the owner, the project's owner and its editors; the SQL and dataset parameters anyone but the owner saves into a step must name only datasets within their own reach in the workflow's home, the workflow's declared outputs aside, else the save is refused with sql_error naming the reference as written and nothing changes. Deletion stays the owner's. Anyone who reaches a workflow may duplicate it into their own space: the copy keeps the workflow's SQL home and is filed in its project only when the duplicator may file there (its owner or an editor). Administrators reach nothing more. Unreached or missing workflows, steps, captured layers and project references return not_found before reading private contents or changing resources; a reached workflow whose change the caller may not make returns forbidden and changes nothing. A step's declared output name is taken when a dataset of that name is in the workflow's SQL home or in the declaring person's own space, and duplicate-name allocation considers the duplicator's own datasets and workflows and the datasets of the SQL home the copy keeps, both preserving the existing same-workflow conflict rules. Accepted changes recheck account activity and referenced-resource access at commit. The layout document: where each step and each source sits on the canvas, and the notes written around them. Stored beside the recipe, never inside it: nothing here changes what a run does or what a step reads. A recipe never arranged reads as the empty document with no write time. A read never names a step the recipe no longer has.

Parameters

• idPathrequired

  Recipe id.

  string

Responses

• 200

  Success.

  application/json

  RecipeLayoutEnvelope

• 401403404503default

  Error with a machine-readable code and human message.

  application/json

  Error

• 405

  method_not_allowed: the method is unsupported for this path.

  application/json

  Error

  • AllowHeader

    Exactly the documented methods for this path.

    stringalways GET, HEAD, OPTIONS, PUT

PUTReplace a recipe's canvas layout

Sign-in Session cookie or Bearer tokenMCP tool set_recipe_layout

A workflow is reached by its owner and, while it is filed in a project, by that project's owner and people; its steps, layout and runs follow it. Results name the workflow's owner and SQL home and are read in that home within the caller's own reach: a reference the caller cannot reach is missing to them, named as written, and recorded lineage, output links and captured layer identities out of their reach are left out. Content changes are open to the owner, the project's owner and its editors; the SQL and dataset parameters anyone but the owner saves into a step must name only datasets within their own reach in the workflow's home, the workflow's declared outputs aside, else the save is refused with sql_error naming the reference as written and nothing changes. Deletion stays the owner's. Anyone who reaches a workflow may duplicate it into their own space: the copy keeps the workflow's SQL home and is filed in its project only when the duplicator may file there (its owner or an editor). Administrators reach nothing more. Unreached or missing workflows, steps, captured layers and project references return not_found before reading private contents or changing resources; a reached workflow whose change the caller may not make returns forbidden and changes nothing. A step's declared output name is taken when a dataset of that name is in the workflow's SQL home or in the declaring person's own space, and duplicate-name allocation considers the duplicator's own datasets and workflows and the datasets of the SQL home the copy keeps, both preserving the existing same-workflow conflict rules. Accepted changes recheck account activity and referenced-resource access at commit. Request body bound. At most 16,777,216 wire bytes; a larger body is refused with request_body_too_large before JSON parsing. Ordinary maximum-shape layout documents fit; escape-inflated keys and unbounded note ids can exceed the outer byte bound and are refused by design. Replaces the whole document and answers with it as stored; there is no partial update, and {} is the empty document. A position for a step id the recipe does not have is dropped, not refused. Anything else wrong (a position that is not two finite numbers, more than 1,000 step positions, more than 1,000 source positions, a step or source key past 1,000 characters, a note missing a field, a colour outside the six, text past 4,000 characters, a non-positive size, a blank or duplicated note id, more than 100 notes) is refused whole (400) naming the first fault, and nothing is stored. A write that changes the document moves the recipe's last-edited time; one that stores what was already stored does not. Last write wins.

Parameters

• X-Edit-RevisionHeaderrequired

  Read the document first and send its editRevision. Missing or malformed: 400 invalid_request. Stale: 409 stale_revision, with no changes. Chain accepted results; reload explicitly after refusal.

  stringpattern ^[0-9a-f]{32}$

  Opaque durable revision paired with this document state. Camera and derived writes do not change it.

• idPathrequired

  Recipe id.

  string

Request body

At most 16,777,216 bytes (16 MiB); a larger body is refused with request_body_too_large.

application/json

RecipeLayoutInput

Responses

• 200

  Success.

  application/json

  RecipeLayoutEnvelope

• 400401403404409413503default

  Error with a machine-readable code and human message.

  application/json

  Error

• 405

  method_not_allowed: the method is unsupported for this path.

  application/json

  Error

  • AllowHeader

    Exactly the documented methods for this path.

    stringalways GET, HEAD, OPTIONS, PUT

• HEADRead response headers

  Sign-in Session cookie or Bearer tokenAnswers 200, 401, 403, 404, 405, 503, defaultAllow GET, HEAD, OPTIONS, PUT

  Automatic HEAD uses GET with no response body.

Also on this path: OPTIONS under System.

/api/recipes/{id}/steps

POSTAdd a step

Sign-in Session cookie or Bearer tokenMCP tool add_recipe_step

A workflow is reached by its owner and, while it is filed in a project, by that project's owner and people; its steps, layout and runs follow it. Results name the workflow's owner and SQL home and are read in that home within the caller's own reach: a reference the caller cannot reach is missing to them, named as written, and recorded lineage, output links and captured layer identities out of their reach are left out. Content changes are open to the owner, the project's owner and its editors; the SQL and dataset parameters anyone but the owner saves into a step must name only datasets within their own reach in the workflow's home, the workflow's declared outputs aside, else the save is refused with sql_error naming the reference as written and nothing changes. Deletion stays the owner's. Anyone who reaches a workflow may duplicate it into their own space: the copy keeps the workflow's SQL home and is filed in its project only when the duplicator may file there (its owner or an editor). Administrators reach nothing more. Unreached or missing workflows, steps, captured layers and project references return not_found before reading private contents or changing resources; a reached workflow whose change the caller may not make returns forbidden and changes nothing. A step's declared output name is taken when a dataset of that name is in the workflow's SQL home or in the declaring person's own space, and duplicate-name allocation considers the duplicator's own datasets and workflows and the datasets of the SQL home the copy keeps, both preserving the existing same-workflow conflict rules. Accepted changes recheck account activity and referenced-resource access at commit. Request body bound. At most 16,777,216 wire bytes; a larger body is refused with request_body_too_large before JSON parsing. Ordinary maximum-shape layout documents fit; escape-inflated keys and unbounded note ids can exceed the outer byte bound and are refused by design. Appends a step naming an operation from the catalog, its parameters, and the dataset it will produce. The output's name: stored in the registry's form; a blank or letterless name is refused in its own words; a name a registered table carries, or another step of this recipe declares or holds, is refused (name_taken) naming the holder. Another recipe's unrun declaration is no reservation. A step may be added unnamed; the run refuses a nameless one. SQL the parser cannot read is accepted with no present reads; the dry run and the run refuse it and say why. Give fromLayerId to author it from a layer: the step takes that layer's SQL refined by its filters, captured now and never re-read, so the step stays reproducible when the filters later change. Where the layer is drawn as hex bins, grid cells or origin–destination lines, the step consumes the rows behind those cells rather than the cells themselves, and the answer says so in origin.substitutionNote. Any layer the caller reaches can be captured, its SQL carried from its map's home into this workflow's context; one the caller does not reach answers as a missing one. Give writtenIn when the parameters were written elsewhere (a node copied from another workflow, the caller's console, a map): their dataset inputs and SQL are carried into this workflow's context, where this step's own output already takes its name. Each dataset reference keeps the dataset it meant where it was written: a plain name of a dataset the destination's SQL home does not own, or whose name an output there takes, becomes <sql name>.<dataset>; an already qualified name stays as written; a workflow's own output becomes the dataset the caller's latest successful run of it made. Only those references change; the rest of the text is kept as written, and nothing where it came from is touched. A reference that cannot be carried (a dataset outside the caller's reach, an output the caller has not produced, a computed table name that would have to change) refuses the request with sql_error naming it, and nothing is written. A step that would read its own output, or a later step's, is refused here rather than at run time.

Parameters

• X-Edit-RevisionHeaderrequired

  Read the document first and send its editRevision. Missing or malformed: 400 invalid_request. Stale: 409 stale_revision, with no changes. Chain accepted results; reload explicitly after refusal.

  stringpattern ^[0-9a-f]{32}$

  Opaque durable revision paired with this document state. Camera and derived writes do not change it.

• idPathrequired

  Recipe id.

  string

Request body

At most 16,777,216 bytes (16 MiB); a larger body is refused with request_body_too_large.

application/json

object

• operationstringrequired

  An operation id from the catalog.

• parametersobject

  The operation's own parameters, as the catalog describes them — including non-scalar ones, which are kept as sent.

• fromLayerIdstring

  Author from this layer: its filtered SQL is captured into the step's sql parameter, carried from the layer's map into this workflow.

• writtenInWrittenIn

  Where parameters were written, when not in this workflow; they are carried into it.

Responses

• 201

  Created.

  application/json

  RecipeStepEnvelope

• 400401403404409413503default

  Error with a machine-readable code and human message.

  application/json

  Error

• 405

  method_not_allowed: the method is unsupported for this path.

  application/json

  Error

  • AllowHeader

    Exactly the documented methods for this path.

    stringalways OPTIONS, POST

Also on this path: OPTIONS under System.

/api/recipes/{id}/steps/{stepId}

GETRead a step

Sign-in Session cookie or Bearer tokenMCP tool get_recipe_step

A workflow is reached by its owner and, while it is filed in a project, by that project's owner and people; its steps, layout and runs follow it. Results name the workflow's owner and SQL home and are read in that home within the caller's own reach: a reference the caller cannot reach is missing to them, named as written, and recorded lineage, output links and captured layer identities out of their reach are left out. Content changes are open to the owner, the project's owner and its editors; the SQL and dataset parameters anyone but the owner saves into a step must name only datasets within their own reach in the workflow's home, the workflow's declared outputs aside, else the save is refused with sql_error naming the reference as written and nothing changes. Deletion stays the owner's. Anyone who reaches a workflow may duplicate it into their own space: the copy keeps the workflow's SQL home and is filed in its project only when the duplicator may file there (its owner or an editor). Administrators reach nothing more. Unreached or missing workflows, steps, captured layers and project references return not_found before reading private contents or changing resources; a reached workflow whose change the caller may not make returns forbidden and changes nothing. A step's declared output name is taken when a dataset of that name is in the workflow's SQL home or in the declaring person's own space, and duplicate-name allocation considers the duplicator's own datasets and workflows and the datasets of the SQL home the copy keeps, both preserving the existing same-workflow conflict rules. Accepted changes recheck account activity and referenced-resource access at commit. One step's definition, condition, stale causes, recorded inputs and latest attempt.

Parameters

• idPathrequired

  Recipe id.

  string

• stepIdPathrequired

  Step id.

  string

Responses

• 200

  Success.

  application/json

  RecipeStepEnvelope

• 401403404503default

  Error with a machine-readable code and human message.

  application/json

  Error

• 405

  method_not_allowed: the method is unsupported for this path.

  application/json

  Error

  • AllowHeader

    Exactly the documented methods for this path.

    stringalways DELETE, GET, HEAD, OPTIONS, PATCH

PATCHEdit a step

Sign-in Session cookie or Bearer tokenMCP tool update_recipe_step

A workflow is reached by its owner and, while it is filed in a project, by that project's owner and people; its steps, layout and runs follow it. Results name the workflow's owner and SQL home and are read in that home within the caller's own reach: a reference the caller cannot reach is missing to them, named as written, and recorded lineage, output links and captured layer identities out of their reach are left out. Content changes are open to the owner, the project's owner and its editors; the SQL and dataset parameters anyone but the owner saves into a step must name only datasets within their own reach in the workflow's home, the workflow's declared outputs aside, else the save is refused with sql_error naming the reference as written and nothing changes. Deletion stays the owner's. Anyone who reaches a workflow may duplicate it into their own space: the copy keeps the workflow's SQL home and is filed in its project only when the duplicator may file there (its owner or an editor). Administrators reach nothing more. Unreached or missing workflows, steps, captured layers and project references return not_found before reading private contents or changing resources; a reached workflow whose change the caller may not make returns forbidden and changes nothing. A step's declared output name is taken when a dataset of that name is in the workflow's SQL home or in the declaring person's own space, and duplicate-name allocation considers the duplicator's own datasets and workflows and the datasets of the SQL home the copy keeps, both preserving the existing same-workflow conflict rules. Accepted changes recheck account activity and referenced-resource access at commit. Request body bound. At most 16,777,216 wire bytes; a larger body is refused with request_body_too_large before JSON parsing. Ordinary maximum-shape layout documents fit; escape-inflated keys and unbounded note ids can exceed the outer byte bound and are refused by design. A change to a step that has already produced something is a proposal. The step keeps meaning what its output was produced from until a run of the proposal succeeds; applied says which of the two happened — active for a step that had produced nothing, proposed otherwise. An edit that puts the active definition back clears the pending one and answers active. Reading a later step's output orders the recipe rather than refusing: the reader and everything depending on it move after the producer, other steps keep their places, the whole order is checked, and the edit and the order land together or not at all; a self-read is refused. A produced output's name is frozen; before the first run the name rule of adding applies. SQL the parser cannot read is accepted with no present reads. Refused (409) if the recipe changed while the edit was checked.

Parameters

• X-Edit-RevisionHeaderrequired

  Read the document first and send its editRevision. Missing or malformed: 400 invalid_request. Stale: 409 stale_revision, with no changes. Chain accepted results; reload explicitly after refusal.

  stringpattern ^[0-9a-f]{32}$

  Opaque durable revision paired with this document state. Camera and derived writes do not change it.

• idPathrequired

  Recipe id.

  string

• stepIdPathrequired

  Step id.

  string

Request body

At most 16,777,216 bytes (16 MiB); a larger body is refused with request_body_too_large.

application/json

object

• parametersobject

• fromLayerIdstring

  Re-author from this layer, any the caller reaches: its filtered SQL is captured and carried from its map into this workflow.

• writtenInWrittenIn

  Where parameters were written, when not in this workflow; they are carried into it as an add's are.

Responses

• 200

  Success.

  application/json

  RecipeStepEdited

• 400401403404409413503default

  Error with a machine-readable code and human message.

  application/json

  Error

• 405

  method_not_allowed: the method is unsupported for this path.

  application/json

  Error

  • AllowHeader

    Exactly the documented methods for this path.

    stringalways DELETE, GET, HEAD, OPTIONS, PATCH

DELETERemove a step

Sign-in Session cookie or Bearer tokenMCP tool remove_recipe_step

A workflow is reached by its owner and, while it is filed in a project, by that project's owner and people; its steps, layout and runs follow it. Results name the workflow's owner and SQL home and are read in that home within the caller's own reach: a reference the caller cannot reach is missing to them, named as written, and recorded lineage, output links and captured layer identities out of their reach are left out. Content changes are open to the owner, the project's owner and its editors; the SQL and dataset parameters anyone but the owner saves into a step must name only datasets within their own reach in the workflow's home, the workflow's declared outputs aside, else the save is refused with sql_error naming the reference as written and nothing changes. Deletion stays the owner's. Anyone who reaches a workflow may duplicate it into their own space: the copy keeps the workflow's SQL home and is filed in its project only when the duplicator may file there (its owner or an editor). Administrators reach nothing more. Unreached or missing workflows, steps, captured layers and project references return not_found before reading private contents or changing resources; a reached workflow whose change the caller may not make returns forbidden and changes nothing. A step's declared output name is taken when a dataset of that name is in the workflow's SQL home or in the declaring person's own space, and duplicate-name allocation considers the duplicator's own datasets and workflows and the datasets of the SQL home the copy keeps, both preserving the existing same-workflow conflict rules. Accepted changes recheck account activity and referenced-resource access at commit. The step detaches: the dataset it produced and its run history both survive, and a step that reads that dataset goes on reading it as an ordinary workspace table. The answer says what is true: whether that dataset exists, was deleted since, or never was, and which steps read its name.

Parameters

• X-Edit-RevisionHeaderrequired

  Read the document first and send its editRevision. Missing or malformed: 400 invalid_request. Stale: 409 stale_revision, with no changes. Chain accepted results; reload explicitly after refusal.

  stringpattern ^[0-9a-f]{32}$

  Opaque durable revision paired with this document state. Camera and derived writes do not change it.

• idPathrequired

  Recipe id.

  string

• stepIdPathrequired

  Step id.

  string

Responses

• 200

  Success.

  application/json

  RecipeStepRemoved

• 400401403404409503default

  Error with a machine-readable code and human message.

  application/json

  Error

• 405

  method_not_allowed: the method is unsupported for this path.

  application/json

  Error

  • AllowHeader

    Exactly the documented methods for this path.

    stringalways DELETE, GET, HEAD, OPTIONS, PATCH

• HEADRead response headers

  Sign-in Session cookie or Bearer tokenAnswers 200, 401, 403, 404, 405, 503, defaultAllow DELETE, GET, HEAD, OPTIONS, PATCH

  Automatic HEAD uses GET with no response body.

Also on this path: OPTIONS under System.

/api/recipes/{id}/steps/{stepId}/proposal

DELETEDiscard a step's pending edit

Sign-in Session cookie or Bearer tokenMCP tool discard_recipe_step_edit

A workflow is reached by its owner and, while it is filed in a project, by that project's owner and people; its steps, layout and runs follow it. Results name the workflow's owner and SQL home and are read in that home within the caller's own reach: a reference the caller cannot reach is missing to them, named as written, and recorded lineage, output links and captured layer identities out of their reach are left out. Content changes are open to the owner, the project's owner and its editors; the SQL and dataset parameters anyone but the owner saves into a step must name only datasets within their own reach in the workflow's home, the workflow's declared outputs aside, else the save is refused with sql_error naming the reference as written and nothing changes. Deletion stays the owner's. Anyone who reaches a workflow may duplicate it into their own space: the copy keeps the workflow's SQL home and is filed in its project only when the duplicator may file there (its owner or an editor). Administrators reach nothing more. Unreached or missing workflows, steps, captured layers and project references return not_found before reading private contents or changing resources; a reached workflow whose change the caller may not make returns forbidden and changes nothing. A step's declared output name is taken when a dataset of that name is in the workflow's SQL home or in the declaring person's own space, and duplicate-name allocation considers the duplicator's own datasets and workflows and the datasets of the SQL home the copy keeps, both preserving the existing same-workflow conflict rules. Accepted changes recheck account activity and referenced-resource access at commit. Puts the step back to its active definition — what its output was produced from — and changes nothing else. A step holding no pending edit is unchanged, and discarded says so.

Parameters

• X-Edit-RevisionHeaderrequired

  Read the document first and send its editRevision. Missing or malformed: 400 invalid_request. Stale: 409 stale_revision, with no changes. Chain accepted results; reload explicitly after refusal.

  stringpattern ^[0-9a-f]{32}$

  Opaque durable revision paired with this document state. Camera and derived writes do not change it.

• idPathrequired

  Recipe id.

  string

• stepIdPathrequired

  Step id.

  string

Responses

• 200

  Success.

  application/json

  RecipeStepDiscarded

• 400401403404409503default

  Error with a machine-readable code and human message.

  application/json

  Error

• 405

  method_not_allowed: the method is unsupported for this path.

  application/json

  Error

  • AllowHeader

    Exactly the documented methods for this path.

    stringalways DELETE, OPTIONS

Also on this path: OPTIONS under System.

/api/recipes/{id}/steps/{stepId}/move

POSTReorder a step

Sign-in Session cookie or Bearer tokenMCP tool move_recipe_step

A workflow is reached by its owner and, while it is filed in a project, by that project's owner and people; its steps, layout and runs follow it. Results name the workflow's owner and SQL home and are read in that home within the caller's own reach: a reference the caller cannot reach is missing to them, named as written, and recorded lineage, output links and captured layer identities out of their reach are left out. Content changes are open to the owner, the project's owner and its editors; the SQL and dataset parameters anyone but the owner saves into a step must name only datasets within their own reach in the workflow's home, the workflow's declared outputs aside, else the save is refused with sql_error naming the reference as written and nothing changes. Deletion stays the owner's. Anyone who reaches a workflow may duplicate it into their own space: the copy keeps the workflow's SQL home and is filed in its project only when the duplicator may file there (its owner or an editor). Administrators reach nothing more. Unreached or missing workflows, steps, captured layers and project references return not_found before reading private contents or changing resources; a reached workflow whose change the caller may not make returns forbidden and changes nothing. A step's declared output name is taken when a dataset of that name is in the workflow's SQL home or in the declaring person's own space, and duplicate-name allocation considers the duplicator's own datasets and workflows and the datasets of the SQL home the copy keeps, both preserving the existing same-workflow conflict rules. Accepted changes recheck account activity and referenced-resource access at commit. Request body bound. At most 16,777,216 wire bytes; a larger body is refused with request_body_too_large before JSON parsing. Ordinary maximum-shape layout documents fit; escape-inflated keys and unbounded note ids can exceed the outer byte bound and are refused by design. Moves the step to a position, rewriting the ordinals densely. The whole proposed ordering is checked, not just the step that moved: dragging a producer downwards breaks its consumers rather than itself, and a reorder that would leave the recipe invalid is refused with nothing changed.

Parameters

• X-Edit-RevisionHeaderrequired

  Read the document first and send its editRevision. Missing or malformed: 400 invalid_request. Stale: 409 stale_revision, with no changes. Chain accepted results; reload explicitly after refusal.

  stringpattern ^[0-9a-f]{32}$

  Opaque durable revision paired with this document state. Camera and derived writes do not change it.

• idPathrequired

  Recipe id.

  string

• stepIdPathrequired

  Step id.

  string

Request body

At most 16,777,216 bytes (16 MiB); a larger body is refused with request_body_too_large.

application/json

object

• ordinalintegerrequired

  Zero-based position to move it to.

Responses

• 200

  Success.

  application/json

  RecipeEnvelope

• 400401403404409413503default

  Error with a machine-readable code and human message.

  application/json

  Error

• 405

  method_not_allowed: the method is unsupported for this path.

  application/json

  Error

  • AllowHeader

    Exactly the documented methods for this path.

    stringalways OPTIONS, POST

Also on this path: OPTIONS under System.

/api/recipes/{id}/steps/{stepId}/run

POSTRun one step

Sign-in Session cookie or Bearer tokenMCP tool run_recipe_step

Created resources belong to the authenticated account. Submitted owner identities cannot assign or transfer ownership. Workflow runs, member attempts and retained outputs follow their workflow: everyone who reaches it reads its runs, with output links out of the caller's reach left out. Planning and starting a run are open to whoever may change the workflow's content (its owner, the project's owner and its editors); a viewer is refused with forbidden before anything is planned. A run is its runner's: it reads in the workflow's SQL home within the runner's reach, its outputs are created as the runner's own datasets, never replacing anyone else's, and are filed into the workflow's project as it stands when each output commits, when the runner may file there; a rerun replaces only the same runner's earlier output of that step, and a dataset of the runner's already holding the name is refused with name_taken. A run is cancelled by its initiator or the workflow's owner; an initiator who no longer reaches the workflow still cancels their own run by its identifier, answered 204 without the run. Administrators reach nothing more. Every referenced step and run must belong to the addressed workflow; unreached, missing and mixed-parent references return not_found before planning or execution. Account activity is checked after planning, at worker entry and at publication. At each output's commit the runner's permission and reach to every input are checked again: an input another account owns that the runner no longer reaches refuses that output with sql_error naming it as written, even though the step already read it; a runner who may no longer run the workflow (no longer its editor, or no longer reaching it after it was unfiled, moved, dissolved out of its project or transferred) completes the steps already admitted privately, into their own datasets, unfiled, leaving the workflow's recorded outputs, proposals and definitions unchanged, and no further step is admitted; the run records each outcome. A workflow moved or transferred while running files each output into its project as it stands at commit. Deactivation prevents further admission and publication, drains admitted work and retains already committed outputs and terminal attempts. Results remain owned after step or output deletion and independent job-history pruning. Restart marks unfinished runs interrupted without executing them again. Answers 202 with one of the recipe's runs: a run of kind single with this one member, listed among the recipe's runs and read and cancelled through them; poll /api/recipes/{id}/runs/{runId} for its outcome. This runs the step and nothing else — carrying its dependents is the recipe-run endpoint's job. A re-run replaces the same runner's earlier output of the step in place, keeping the dataset's id and name, so every layer built on it keeps pointing at fresh data with no re-wiring; another runner's output is never touched. A failed re-run leaves the previous output intact and queryable. What a caller may rely on. The recipe's one-run-at-a-time rule applies: while a run is in flight this answers 409 run_in_flight naming it. Ordinarily, a step the API cannot admit alone is refused before anything exists: no run, no attempt. Narrow exception: if the run was already listable and cancellation was accepted before that refusal, the cancelled run remains with the refusal member and no attempt. The run stays with the recipe after the step is removed.

Parameters

• X-Edit-RevisionHeaderrequired

  Read the document first and send its editRevision. Missing or malformed: 400 invalid_request. Stale: 409 stale_revision, with no changes. Chain accepted results; reload explicitly after refusal.

  stringpattern ^[0-9a-f]{32}$

  Opaque durable revision paired with this document state. Camera and derived writes do not change it.

• idPathrequired

  Recipe id.

  string

• stepIdPathrequired

  Step id.

  string

Responses

• 202

  Accepted; poll the recipe run for its outcome.

  application/json

  RecipeRunStarted

• 400401403404503default

  Error with a machine-readable code and human message.

  application/json

  Error

• 405

  method_not_allowed: the method is unsupported for this path.

  application/json

  Error

  • AllowHeader

    Exactly the documented methods for this path.

    stringalways OPTIONS, POST

• 409

  The revision is stale (stale_revision), or a run is already in flight (run_in_flight, naming it); nothing started.

Also on this path: OPTIONS under System.

/api/recipes/{id}/runs

GETList a recipe's runs

Sign-in Session cookie or Bearer tokenMCP tool list_recipe_runs

Workflow runs, member attempts and retained outputs follow their workflow: everyone who reaches it reads its runs, with output links out of the caller's reach left out. Planning and starting a run are open to whoever may change the workflow's content (its owner, the project's owner and its editors); a viewer is refused with forbidden before anything is planned. A run is its runner's: it reads in the workflow's SQL home within the runner's reach, its outputs are created as the runner's own datasets, never replacing anyone else's, and are filed into the workflow's project as it stands when each output commits, when the runner may file there; a rerun replaces only the same runner's earlier output of that step, and a dataset of the runner's already holding the name is refused with name_taken. A run is cancelled by its initiator or the workflow's owner; an initiator who no longer reaches the workflow still cancels their own run by its identifier, answered 204 without the run. Administrators reach nothing more. Every referenced step and run must belong to the addressed workflow; unreached, missing and mixed-parent references return not_found before planning or execution. Account activity is checked after planning, at worker entry and at publication. At each output's commit the runner's permission and reach to every input are checked again: an input another account owns that the runner no longer reaches refuses that output with sql_error naming it as written, even though the step already read it; a runner who may no longer run the workflow (no longer its editor, or no longer reaching it after it was unfiled, moved, dissolved out of its project or transferred) completes the steps already admitted privately, into their own datasets, unfiled, leaving the workflow's recorded outputs, proposals and definitions unchanged, and no further step is admitted; the run records each outcome. A workflow moved or transferred while running files each output into its project as it stands at commit. Deactivation prevents further admission and publication, drains admitted work and retains already committed outputs and terminal attempts. Results remain owned after step or output deletion and independent job-history pruning. Restart marks unfinished runs interrupted without executing them again. Every cascade this recipe has had, newest first, each durable and readable long after it finished.

Parameters

• idPathrequired

  Recipe id.

  string

Responses

• 200

  Success.

  application/json

  RecipeRunList

• 401403404503default

  Error with a machine-readable code and human message.

  application/json

  Error

• 405

  method_not_allowed: the method is unsupported for this path.

  application/json

  Error

  • AllowHeader

    Exactly the documented methods for this path.

    stringalways GET, HEAD, OPTIONS, POST

POSTRun a recipe, or a step and its dependents

Sign-in Session cookie or Bearer tokenMCP tool run_recipe

Created resources belong to the authenticated account. Submitted owner identities cannot assign or transfer ownership. Workflow runs, member attempts and retained outputs follow their workflow: everyone who reaches it reads its runs, with output links out of the caller's reach left out. Planning and starting a run are open to whoever may change the workflow's content (its owner, the project's owner and its editors); a viewer is refused with forbidden before anything is planned. A run is its runner's: it reads in the workflow's SQL home within the runner's reach, its outputs are created as the runner's own datasets, never replacing anyone else's, and are filed into the workflow's project as it stands when each output commits, when the runner may file there; a rerun replaces only the same runner's earlier output of that step, and a dataset of the runner's already holding the name is refused with name_taken. A run is cancelled by its initiator or the workflow's owner; an initiator who no longer reaches the workflow still cancels their own run by its identifier, answered 204 without the run. Administrators reach nothing more. Every referenced step and run must belong to the addressed workflow; unreached, missing and mixed-parent references return not_found before planning or execution. Account activity is checked after planning, at worker entry and at publication. At each output's commit the runner's permission and reach to every input are checked again: an input another account owns that the runner no longer reaches refuses that output with sql_error naming it as written, even though the step already read it; a runner who may no longer run the workflow (no longer its editor, or no longer reaching it after it was unfiled, moved, dissolved out of its project or transferred) completes the steps already admitted privately, into their own datasets, unfiled, leaving the workflow's recorded outputs, proposals and definitions unchanged, and no further step is admitted; the run records each outcome. A workflow moved or transferred while running files each output into its project as it stands at commit. Deactivation prevents further admission and publication, drains admitted work and retains already committed outputs and terminal attempts. Results remain owned after step or output deletion and independent job-history pruning. Restart marks unfinished runs interrupted without executing them again. Request body bound. At most 16,777,216 wire bytes; a larger body is refused with request_body_too_large before JSON parsing. Ordinary maximum-shape layout documents fit; escape-inflated keys and unbounded note ids can exceed the outer byte bound and are refused by design. Omit fromStepId to run the whole recipe from the beginning; give one to re-run that step and everything that reads it, in dependency order. A step starts only once every step it reads has succeeded, and one whose dependency failed is not attempted — reported not_run, minting no run at all, with the failure that stopped it named. Steps that do not depend on the failure still run. Ask first with plan: true. It answers what the request would carry and the editRevision paired with that definition, without starting anything. Starting requires that revision in X-Edit-Revision, including when planning awaits asynchronous work. A changed basis refuses with stale_revision before any run or output exists. wide is true for a run of the whole recipe and for a re-run that carries dependents, and false for the same request aimed at a step nothing reads. That is what the when_wide confirmation on this operation means — confirm the wide cases, not the leaf. A recipe run is not an operation run: it answers 202 with its own resource, which has its own outcome and contains the members' ordinary runs. What a caller may rely on. A recipe runs one run at a time: a start while one is in flight — this operation's or a single step's — answers 409 run_in_flight naming the run, and two starts that race yield one run and one refusal. A start that names members — the step ids a confirmation listed, in order — starts exactly when the plan at start is that set in that order, and answers 409 plan_changed otherwise, nothing started. This membership check accompanies the start revision check. Each member is read when admitted. Each attempted member's record carries its attempt — state, error, times, output — kept with the run after the step's own history is pruned; a member never attempted has none; every member keeps its step's operation and name after the step is removed.

Parameters

• X-Edit-RevisionHeader

  Read the document first and send its editRevision. Missing or malformed: 400 invalid_request. Stale: 409 stale_revision, with no changes. Chain accepted results; reload explicitly after refusal. Required to start; plan: true is a read and requires none.

  stringpattern ^[0-9a-f]{32}$

  Opaque durable revision paired with this document state. Camera and derived writes do not change it.

• idPathrequired

  Recipe id.

  string

Request body (optional)

At most 16,777,216 bytes (16 MiB); a larger body is refused with request_body_too_large.

application/json

object

• fromStepIdstring

  Re-run this step and its dependents. Omitted, the whole recipe runs.

• planboolean

  Report what would be carried, and whether that is wide, without starting anything.

• membersarray of string

  The step ids a confirmation listed, in order. Given, the run starts only when the plan at start is exactly that set in that order; otherwise 409 plan_changed.

Responses

• 200

  What this would carry; nothing started.

  application/json

  RecipeRunPlan

• 202

  Accepted; poll the recipe run for its outcome.

  application/json

  RecipeRunStarted

• 400401403404413503default

  Error with a machine-readable code and human message.

  application/json

  Error

• 405

  method_not_allowed: the method is unsupported for this path.

  application/json

  Error

  • AllowHeader

    Exactly the documented methods for this path.

    stringalways GET, HEAD, OPTIONS, POST

• 409

  The revision is stale (stale_revision), a run is already in flight (run_in_flight, naming it), or the plan no longer matches the confirmed members (plan_changed); nothing started.

• HEADRead response headers

  Sign-in Session cookie or Bearer tokenAnswers 200, 401, 403, 404, 405, 503, defaultAllow GET, HEAD, OPTIONS, POST

  Automatic HEAD uses GET with no response body.

Also on this path: OPTIONS under System.

/api/recipes/{id}/runs/{runId}

GETRead a recipe run

Sign-in Session cookie or Bearer tokenMCP tool get_recipe_run

Workflow runs, member attempts and retained outputs follow their workflow: everyone who reaches it reads its runs, with output links out of the caller's reach left out. Planning and starting a run are open to whoever may change the workflow's content (its owner, the project's owner and its editors); a viewer is refused with forbidden before anything is planned. A run is its runner's: it reads in the workflow's SQL home within the runner's reach, its outputs are created as the runner's own datasets, never replacing anyone else's, and are filed into the workflow's project as it stands when each output commits, when the runner may file there; a rerun replaces only the same runner's earlier output of that step, and a dataset of the runner's already holding the name is refused with name_taken. A run is cancelled by its initiator or the workflow's owner; an initiator who no longer reaches the workflow still cancels their own run by its identifier, answered 204 without the run. Administrators reach nothing more. Every referenced step and run must belong to the addressed workflow; unreached, missing and mixed-parent references return not_found before planning or execution. Account activity is checked after planning, at worker entry and at publication. At each output's commit the runner's permission and reach to every input are checked again: an input another account owns that the runner no longer reaches refuses that output with sql_error naming it as written, even though the step already read it; a runner who may no longer run the workflow (no longer its editor, or no longer reaching it after it was unfiled, moved, dissolved out of its project or transferred) completes the steps already admitted privately, into their own datasets, unfiled, leaving the workflow's recorded outputs, proposals and definitions unchanged, and no further step is admitted; the run records each outcome. A workflow moved or transferred while running files each output into its project as it stands at commit. Deactivation prevents further admission and publication, drains admitted work and retains already committed outputs and terminal attempts. Results remain owned after step or output deletion and independent job-history pruning. Restart marks unfinished runs interrupted without executing them again. Its own outcome — completed, partly completed, failed, cancelled or interrupted — every member with what became of it, and every dataset it produced. A member reported not_run carries no run id, because nothing was minted for it.

Parameters

• idPathrequired

  Recipe id.

  string

• runIdPathrequired

  Recipe run id.

  string

Responses

• 200

  Success.

  application/json

  RecipeRunEnvelope

• 401403404503default

  Error with a machine-readable code and human message.

  application/json

  Error

• 405

  method_not_allowed: the method is unsupported for this path.

  application/json

  Error

  • AllowHeader

    Exactly the documented methods for this path.

    stringalways GET, HEAD, OPTIONS

• HEADRead response headers

  Sign-in Session cookie or Bearer tokenAnswers 200, 401, 403, 404, 405, 503, defaultAllow GET, HEAD, OPTIONS

  Automatic HEAD uses GET with no response body.

Also on this path: OPTIONS under System.

/api/recipes/{id}/runs/{runId}/cancel

POSTCancel a recipe run

Sign-in Session cookie or Bearer tokenMCP tool cancel_recipe_run

Standalone run records and subject histories are private to their initiating account, including for administrators. Standalone jobs retain their initiating owner before any output exists, after failure and after output deletion; contained jobs follow their workflow, read by everyone who reaches it and cancelled by their initiator or the workflow's owner. Unreached and missing run identities return not_found before cancellation or private content reads. Subject grouping, history pruning and output-name conflicts are account-local. Workers recheck account activity before preparation and at publication; an inactive owner's unfinished job fails with authentication_required and keeps no new output, and an input another account owns that is no longer within the runner's reach when the output commits refuses it with sql_error naming the input as written. Workflow runs, member attempts and retained outputs follow their workflow: everyone who reaches it reads its runs, with output links out of the caller's reach left out. Planning and starting a run are open to whoever may change the workflow's content (its owner, the project's owner and its editors); a viewer is refused with forbidden before anything is planned. A run is its runner's: it reads in the workflow's SQL home within the runner's reach, its outputs are created as the runner's own datasets, never replacing anyone else's, and are filed into the workflow's project as it stands when each output commits, when the runner may file there; a rerun replaces only the same runner's earlier output of that step, and a dataset of the runner's already holding the name is refused with name_taken. A run is cancelled by its initiator or the workflow's owner; an initiator who no longer reaches the workflow still cancels their own run by its identifier, answered 204 without the run. Administrators reach nothing more. Every referenced step and run must belong to the addressed workflow; unreached, missing and mixed-parent references return not_found before planning or execution. Account activity is checked after planning, at worker entry and at publication. At each output's commit the runner's permission and reach to every input are checked again: an input another account owns that the runner no longer reaches refuses that output with sql_error naming it as written, even though the step already read it; a runner who may no longer run the workflow (no longer its editor, or no longer reaching it after it was unfiled, moved, dissolved out of its project or transferred) completes the steps already admitted privately, into their own datasets, unfiled, leaving the workflow's recorded outputs, proposals and definitions unchanged, and no further step is admitted; the run records each outcome. A workflow moved or transferred while running files each output into its project as it stands at commit. Deactivation prevents further admission and publication, drains admitted work and retains already committed outputs and terminal attempts. Results remain owned after step or output deletion and independent job-history pruning. Restart marks unfinished runs interrupted without executing them again. One thing to stop, whatever it was in the middle of: what has not started never starts. Every member found running when cancellation is accepted is cancelled before any member settlement is awaited; only a member already terminal at acceptance stays finished, and its output stands. Running members are interrupted in the engine, not only in the record. The run's own outcome is then cancelled, written once the last in-flight member has settled. Cancelling one that has already finished is not an error.

Parameters

• idPathrequired

  Recipe id.

  string

• runIdPathrequired

  Recipe run id.

  string

Responses

• 200

  Success.

  application/json

  RecipeRunEnvelope

• 204

  Cancelled for its initiator, who no longer reaches the workflow: the run is not shown.

• 401403404503default

  Error with a machine-readable code and human message.

  application/json

  Error

• 405

  method_not_allowed: the method is unsupported for this path.

  application/json

  Error

  • AllowHeader

    Exactly the documented methods for this path.

    stringalways OPTIONS, POST

Also on this path: OPTIONS under System.

/api/recipes/{id}/transfer

POSTTransfer a workflow to someone who reaches it

Sign-in Session cookie or Bearer tokenMCP tool transfer_workflow

At most 16,777,216 wire bytes; a larger body is refused with request_body_too_large before JSON parsing. A workflow is reached by its owner and, while it is filed in a project, by that project's owner and people; its steps, layout and runs follow it. Results name the workflow's owner and SQL home and are read in that home within the caller's own reach: a reference the caller cannot reach is missing to them, named as written, and recorded lineage, output links and captured layer identities out of their reach are left out. Content changes are open to the owner, the project's owner and its editors; the SQL and dataset parameters anyone but the owner saves into a step must name only datasets within their own reach in the workflow's home, the workflow's declared outputs aside, else the save is refused with sql_error naming the reference as written and nothing changes. Deletion stays the owner's. Anyone who reaches a workflow may duplicate it into their own space: the copy keeps the workflow's SQL home and is filed in its project only when the duplicator may file there (its owner or an editor). Administrators reach nothing more. Unreached or missing workflows, steps, captured layers and project references return not_found before reading private contents or changing resources; a reached workflow whose change the caller may not make returns forbidden and changes nothing. A step's declared output name is taken when a dataset of that name is in the workflow's SQL home or in the declaring person's own space, and duplicate-name allocation considers the duplicator's own datasets and workflows and the datasets of the SQL home the copy keeps, both preserving the existing same-workflow conflict rules. Accepted changes recheck account activity and referenced-resource access at commit. Transfer is the only change of ownership any operation makes, and it is always the current owner's own act. The new owner is named by their SQL name and must be an active account. The owner's authority, the recipient, the ownership change and everything that moves with it commit together, or nothing changes. Datasets and connections have no transfer. Makes another active person who already reaches the workflow its owner: the owner of the project it is filed in, or one of that project's people. An unfiled workflow is refused with invalid_request: file the workflow in a project first. The workflow keeps its SQL home, so its SQL means what it meant, and it keeps its steps, layout and run history, while every run's outputs stay with the person who ran it. Anyone else who reaches it is refused with forbidden. A recipient who is deactivated, not yet redeemed, unknown, the owner, or does not reach it is refused with invalid_request, and nothing changes. Answers the workflow's identity and its new owner.

Parameters

• X-Edit-RevisionHeaderrequired

  Read the document first and send its editRevision. Missing or malformed: 400 invalid_request. Stale: 409 stale_revision, with no changes. Chain accepted results; reload explicitly after refusal.

  stringpattern ^[0-9a-f]{32}$

  Opaque durable revision paired with this document state. Camera and derived writes do not change it.

• idPathrequired

  Workflow id.

  string

Request body

At most 16,777,216 bytes (16 MiB); a larger body is refused with request_body_too_large.

application/json

object

• tostringrequiredmin length 1

  The new owner's SQL name.

Responses

• 200

  Success.

  application/json

  DocumentTransfer

• 400401403404409413503default

  Error with a machine-readable code and human message.

  application/json

  Error

• 405

  method_not_allowed: the method is unsupported for this path.

  application/json

  Error

  • AllowHeader

    Exactly the documented methods for this path.

    stringalways OPTIONS, POST

Also on this path: OPTIONS under System.