Run a flow

Call one of your endpoint flows. Each endpoint flow answers one method at one path, both set in the flow's entry: a flow with "method": "POST" and "path": "create-order" answers POST /flows/create-order, and nothing else.

The token needs the run permission on the flow, or run-with-identity when the request carries an identity. The flow runs in one transaction: if it fails, nothing it wrote is kept.

ANY https://api.jsonpad.io/flows/{path}

Example

1234567

curl https://api.jsonpad.io/flows/create-order \
  -H "Content-Type: application/json" \
  -H "x-api-token: <YOUR TOKEN>" \
  -d '{ "productId": "7e3d5360-6348-4fcb-98c9-e79bc871e70a", "quantity": 2 }'

curl "https://api.jsonpad.io/flows/orders/summary?status=open" \
  -H "x-api-token: <YOUR TOKEN>"

Parameters

required
pathstringhttps://api.jsonpad.io/flows/orders/summaryThe flow's path, which can have more than one segment. It has to match exactly: paths don't have parameters, so pass values in the input instead. A trailing slash is ignored.

Query parameters

A GET or DELETE flow takes its input from the query string, as an object: ?status=open&page=2 gives the flow { "status": "open", "page": "2" }. Values are always strings, and a repeated parameter gives an array of them, so an input schema for these flows should expect strings. Other methods ignore the query string.

Request headers

required
x-api-tokenstringYour API token. It decides which of your flows the path is looked up among, so two accounts can each have a flow at the same path.
optional
x-identity-tokenstringAn identity token. The flow sees the identity as identity, so its require nodes can decide what that identity may do. See the context.
optional
x-identity-groupstringThe identity's group, if it belongs to one.

Request body

For a POST, PUT or PATCH flow, the body is the flow's input, as it is. It can be any JSON value; without a body the input is an empty object.

If the flow's entry has an input schema, input that doesn't match it is refused with FLOW_INPUT_INVALID before the flow runs, and nothing is read or written.

Response body

Whatever the flow's respond node chose: its status and its body. A flow that finishes without reaching a respond node responds 204 No Content.

201 Created

{orderId: "e84bf0d7-5f5a-4410-b7f6-a5e6c7cfa479"
total: 39.98
}

Response headers

x-flow-runstringThe run's id, to find it in the flow's run log. Failed runs have one too.

Any headers the respond node set are sent as well, and can be read from a browser. The response also carries the rate limit and quota headers described in limits and quotas.

Errors

A flow that fails responds with a FLOW_FAILED error, with the status the flow failed with: here, a require node's 409. details.code says why, and details.node where. See why a run fails.

409 Conflict

{name: "FLOW_FAILED"
code: 23008
message: "not enough stock"
details: {code: "REQUIRE_FAILED"
node: "in_stock"
}
}

The request can also be refused before the flow runs:

REQUESTED_ENTITY_NOT_FOUND404 Not FoundNone of your flows answers this method and path, or the flow is deactivated.
TOKEN_NOT_AUTHORIZED403 ForbiddenThe token doesn't have run on this flow (or run-with-identity, with an identity).
FLOW_INPUT_INVALID400 Bad RequestThe input doesn't match the flow's input schema.
FLOW_LOCKED403 ForbiddenYou have more flows than your plan allows, and this is one of the newest.

All the error codes are listed on the errors page.

Public flows

A flow with "public": true in its entry can also be called without a token, by its id, with the flow's method:

ANY https://api.jsonpad.io/flows/public/{flowId}

Everything else is the same, except that no identity is sent, so the flow's require nodes are all that decides who may do what. A token doesn't need run to call a public flow at its path, either. Each run counts against your allowance, and one address can call a public flow at most 30 times a minute.

With the JavaScript SDK, call jsonpad.runPublicFlow(flowId, input).

2026-09-29