Skip to main content

Flows

Flow automation definitions, runs, exception triage, virtual endpoints, and partner templates.

All endpoints require a bearer token (oh_... API key or user JWT) and are served under https://api.orderly-hub.com. Use the Try it consoles to run a request against the Preview (test) server.

For the concepts behind these endpoints, see Build a flow and The reference language. Callers of a published endpoint use the Published endpoints reference instead.

Scopes and plan​

ScopeGrants
flows:readList and read flows, versions, runs, exceptions, endpoints, keys, requests, usage, and the step catalog
flows:writeCreate and edit flows, save and publish drafts, dry-run, rotate secrets, and manage endpoints and keys
flows:runStart, cancel, replay, retry, and signal runs
flows:triageRetry, ignore, escalate, correct, and assign exceptions
embed:manageRequired in addition to flows:* for templates, installs, upgrades, the clients summary, and for creating a flow bound to a client

Signed-in users need the matching permissions (flows.read, flows.write, and so on). API keys also need the Flows capability on your plan; without it every call returns 402.

Errors use the standard envelope. Validation failures on drafts, publishes, and installs list every problem in error.details.problems:

{
"error": {
"code": "FLOW_DEFINITION_INVALID",
"message": "Definition invalid",
"details": {
"code": "FLOW_DEFINITION_INVALID",
"problems": ["step \"notify\" references steps.fetch_order which runs later"]
}
}
}

Manage flows​

MethodPathScopeDescription
GET/api/v1/flows/catalogflows:readStep catalog: every step type with its description, config schema, and output schema
GET/api/v1/flowsflows:readList flows. Filters: status, trigger_type, end_user_id
POST/api/v1/flowsflows:writeCreate a flow with an empty draft
GET/api/v1/flows/{id}flows:readGet a flow
PATCH/api/v1/flows/{id}flows:writeUpdate name, description, trigger configuration, params, or client_runnable
POST/api/v1/flows/{id}/pauseflows:writeStop triggers from starting runs
POST/api/v1/flows/{id}/resumeflows:writeResume a paused flow
POST/api/v1/flows/{id}/archiveflows:writeArchive the flow permanently
POST/api/v1/flows/{id}/signing-secret/rotateflows:writeReplace the secret that signs the flow's http.request calls
POST/api/v1/flows/{id}/webhook-secret/rotateflows:writeReplace the secret that verifies the webhook intake. Webhook flows only
POST/api/v1/flows/{id}/intake-token/rotateflows:writeReplace the token in the intake URL. The previous URL stops working at once. Webhook flows only
GET/api/v1/flows/usageflows:readRuns and billable steps this billing period against your plan allowance, and max_loop_items, the most items one For each loop may run on your plan
GET/api/v1/flows/statsflows:readActive flows, runs and failures in the last 24 hours, open exceptions, waiting runs

The flow object​

FieldTypeDescription
idstringFlow ID
namestringDisplay name
slugstringURL-safe identifier, unique in the organization
descriptionstringOptional description
statusactive | paused | archivedWhether triggers start runs
trigger_typewebhook | schedule | bridge_event | exchange_document | endpoint | manualWhat starts a run
trigger_configobjectTrigger settings (below)
intake_tokenstringWebhook flows: the token in the intake URL. Returned only to callers that hold flows:write; null for read-only callers and for other trigger types
current_version_idstringThe published version that new runs use, or null before the first publish
end_user_idstringThe client the flow runs for, or null
template_idstringThe template the flow was installed from, or null
template_versionintegerThe template version the flow's draft came from
paramsobjectInstall parameters, readable as {{ params.* }}
client_runnablebooleanWhether the client may start runs from the embed
created_at, updated_atstringTimestamps
Triggertrigger_config
webhookverify_hmac (boolean, default false)
schedulecron (five fields), timezone (default UTC)
bridge_eventbridge_id, events (one or more of order_created, order_updated, shipment_created)
exchange_documentpartner_id, doc_types (list, empty for all)
endpointNone
manualNone
GET/api/v1/flows

List flows

https://api-test.orderly-hub.com/api/v1/flows

Create a flow​

POST/api/v1/flowsflows:write

Creates the flow with an empty draft, version 1. Subject to your plan's active flow limit (402 when reached).

Request body​

FieldTypeDescription
namestringRequired. 1 to 120 characters
slugstringOptional. Lowercase letters, digits, and hyphens, starting with a letter
descriptionstringOptional. Up to 2,000 characters
trigger_typestringRequired. One of the trigger types above
trigger_configobjectTrigger settings
end_user_idstringOptional client ID. Requires embed:manage
client_runnablebooleanOptional. Requires embed:manage

Responses​

201 Flow created. The response adds draft_version_id and, returned only here, http_signing_secret (the hex key that signs this flow's http.request calls). Webhook flows created with verify_hmac also get webhook_secret.

curl -X POST https://api.orderly-hub.com/api/v1/flows \
-H "Authorization: Bearer $ORDERLY_API_KEY" \
-H "X-Organization-Id: $ORG_ID" \
-H "Content-Type: application/json" \
-d '{
"name": "Ship paid orders",
"trigger_type": "webhook",
"trigger_config": { "verify_hmac": true }
}'
{
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Ship paid orders",
"slug": "ship-paid-orders",
"status": "active",
"trigger_type": "webhook",
"trigger_config": { "verify_hmac": true },
"intake_token": "…",
"current_version_id": null,
"draft_version_id": "6f1c…",
"http_signing_secret": "9b2e…",
"webhook_secret": "41d7…"
}
}

Store both secrets now. They are never returned again; rotate them to get new ones.

POST/api/v1/flows

Create a flow

https://api-test.orderly-hub.com/api/v1/flows

Update a flow​

PATCH/api/v1/flows/{id}flows:write

Accepts name, description, trigger_config, params (up to 16 KB), and client_runnable. Turning verify_hmac on for a webhook flow mints its webhook secret, returned once as data.webhook_secret.

Webhook intake​

Webhook flows receive events at their intake URL. It needs no API key; the token in the URL identifies the flow, so treat it like a password.

POST/api/webhooks/flows/{intake_token}

The body must be JSON and becomes trigger.payload. When verify_hmac is on, send X-Orderly-Signature: t=<timestamp>,v1=<signature>, where <timestamp> is in milliseconds and <signature> is the hex HMAC-SHA256 of <timestamp>.<body> with the webhook secret; signatures more than five minutes old are refused with 401. An Idempotency-Key header (or, without one, the body itself) deduplicates deliveries.

202 Run started: { "data": { "run_id": "…", "duplicate": false } }. 200 Duplicate delivery; the existing run ID is returned with "duplicate": true.

Rotate the intake token​

POST/api/v1/flows/{id}/intake-token/rotateflows:write

Replaces the token in the flow's intake URL. Rotate when the intake URL may have been seen by someone who should not have it: a former member, a read-only member before intake tokens were hidden from read-only callers, a shared screenshot, or a log. The previous URL stops working at once (404), so give every sender the new URL straight away; deliveries to the old URL in the meantime are not accepted. The webhook secret and the HTTP signing secret are not changed.

200 { "data": { "intake_token": "…", "intake_url": "https://api.orderly-hub.com/api/webhooks/flows/…" } }. The new token is also readable on the flow by callers that hold flows:write. 409 The flow is not webhook-triggered. Refused during staff impersonation.

Drafts, versions, and publishing​

MethodPathScopeDescription
PUT/api/v1/flows/{id}/draftflows:writeReplace the draft definition
POST/api/v1/flows/{id}/publishflows:writeValidate the draft and publish it as the current version
POST/api/v1/flows/{id}/testflows:writeDry-run a definition against a sample payload
GET/api/v1/flows/{id}/versionsflows:readList draft, published, and archived versions
GET/api/v1/flows/{id}/versions/{versionId}flows:readGet one version with its definition

The definition​

FieldTypeDescription
schema_version1Required
inputsobjectOptional JSON Schema; new runs whose payload does not match are refused
stepsarrayThe steps, in order
uiobjectDesigner layout. Ignored when running

Each step:

FieldTypeDescription
keystringUnique step key: a lowercase letter, then lowercase letters, digits, or underscores, up to 64 characters
typestringA step type from the catalog, such as orderly.order.get or http.request
configobjectThe step's settings, which may hold references
on_errorobject{ "mode": "fail" }, { "mode": "skip" }, { "mode": "retry", "max_attempts": 1-10, "backoff": "5s" }, or { "mode": "handler", "steps": [...], "then": "continue" | "fail", "retry"?: {...} } (see Handle step errors). Money steps (orderly.label.purchase, orderly.pickup.schedule, orderly.label.void) and For each loops that hold one cannot skip or use a handler
whenobjectOptional guard: conditions and match_mode (all or any)

A branch step's config.branches is a list of lanes, each with a key, optional conditions and match_mode, and its own steps. Definitions are limited to 512 KB.

Save the draft​

PUT/api/v1/flows/{id}/draftflows:write

The request body is the definition itself. The draft is saved even when it has problems, and the response lists them so you can keep iterating: { "data": { "version_id": "…", "version": 2, "problems": [] } }. Archived flows return 409; definitions over 512 KB return 422.

Publish​

POST/api/v1/flows/{id}/publishflows:write

Validates the draft and makes it the current version; the previous published version is archived. Returns { "data": { "version_id": "…", "version": 2 } }. Returns 404 when there is no draft, 409 for an archived flow, and 422 with details.problems when the draft is invalid, for example when a step references a later step, a money step skips on error, an endpoint flow has no endpoint yet, a client's flow uses another client's bridge, a lookup() or in_set() names a table or set that does not exist, or an http.request credential secret is not set on the flow. Runs already in progress keep the version they started with.

curl -X PUT https://api.orderly-hub.com/api/v1/flows/$FLOW_ID/draft \
-H "Authorization: Bearer $ORDERLY_API_KEY" \
-H "X-Organization-Id: $ORG_ID" \
-H "Content-Type: application/json" \
-d '{
"schema_version": 1,
"steps": [
{
"key": "fetch_order",
"type": "orderly.order.get",
"config": { "external_id": "{{ trigger.payload.order_id }}" }
},
{
"key": "notify",
"type": "http.request",
"config": {
"url": "https://ops.example.com/orders",
"body": { "order": "{{ steps.fetch_order.output.order_number }}" }
},
"on_error": { "mode": "retry", "max_attempts": 3, "backoff": "30s" }
}
]
}'

curl -X POST https://api.orderly-hub.com/api/v1/flows/$FLOW_ID/publish \
-H "Authorization: Bearer $ORDERLY_API_KEY" \
-H "X-Organization-Id: $ORG_ID"

Dry-run a definition​

POST/api/v1/flows/{id}/testflows:write
FieldTypeDescription
definitionobjectOptional. The definition to test; the saved draft when omitted
payloadobjectThe sample trigger payload

Returns { "data": { "steps": [...] } } with one entry per step: its key, type, status (executed, resolved, skipped, or error), and its resolved input, output, chosen lane, or problems. Steps that write data or call outside systems are only resolved, never run. Returns 404 when no definition is given and there is no draft, and 422 when the definition is invalid.

Lookup tables and flow secrets​

MethodPathScopeDescription
GET, POST/api/v1/flows/lookup-tablesflows:read, flows:writeList or create lookup tables
GET, PATCH, DELETE/api/v1/flows/lookup-tables/{tableId}flows:read, flows:writeRead, rename, or delete a table
GET, PUT/api/v1/flows/lookup-tables/{tableId}/rowsflows:read, flows:writeList rows, or add and update up to 1,000
POST/api/v1/flows/lookup-tables/{tableId}/rows/deleteflows:writeDelete up to 1,000 rows by key
POST/api/v1/flows/lookup-tables/{tableId}/importflows:writeImport a CSV file (mode merge or replace)
GET/api/v1/flows/lookup-tables/{tableId}/exportflows:readDownload a table as CSV
GET/api/v1/flows/{id}/secretsflows:readList the flow's secret names
PUT, DELETE/api/v1/flows/{id}/secrets/{name}flows:writeSet or delete a secret that http.request auth refers to

Runs​

MethodPathScopeDescription
POST/api/v1/flows/{id}/runflows:runStart a run of the published version
GET/api/v1/flows/runsflows:readList runs across all flows, newest first. Filters: status, flow_id, end_user_id, limit (1 to 200, default 50)
GET/api/v1/flows/{id}/runsflows:readList one flow's runs. Filters: status, end_user_id, limit
GET/api/v1/flows/runs/{runId}flows:readGet a run with its steps, events, and exception
GET/api/v1/flows/runs/{runId}/loops/{stepKey}/iterationsflows:readOne page of a For each loop's items. offset (default 0) and limit (1 to 100, default 50)
GET/api/v1/flows/runs/{runId}/loops/{stepKey}/iterations/{index}flows:readOne item of a For each loop: its value and every attempt of the steps that ran for it
POST/api/v1/flows/runs/{runId}/cancelflows:runCancel a queued, running, waiting, or failed run
POST/api/v1/flows/runs/{runId}/replayflows:runStart a new run from the original trigger payload
POST/api/v1/flows/runs/{runId}/retryflows:runResume a failed run from its failing step
POST/api/v1/flows/runs/{runId}/signalflows:runDeliver an event to a waiting run

The run object​

FieldTypeDescription
idstringRun ID
flow_idstringThe flow
flow_version_idstringThe version the run executes
statusqueued | running | waiting | succeeded | failed | cancelledRun status
trigger_sourcestringA trigger type, or replay
trigger_refstringWhat triggered it, such as the endpoint request ID or the replayed run ID
end_user_idstringThe client, for client flows
inputobjectpayload and meta, as the steps saw them in trigger
outputobjectFor endpoint runs, the status and body of the Respond step
errorstringWhy the run failed
steps_executed, billable_stepsintegerStep counters used for metering
started_at, finished_at, created_atstringTimestamps

GET /api/v1/flows/runs/{runId} adds steps (each attempt of each step with its status, input, output, error, and duration_ms), events (the run's timeline), exception (or null), and loops (one summary per For each step). The steps that run once per item inside a For each loop, and their events, are left out of steps and events; page them with the iterations endpoints.

Start a run​

POST/api/v1/flows/{id}/runflows:run
FieldTypeDescription
payloadobjectThe trigger payload. Defaults to {}
metaobjectExtra values for trigger.meta. Defaults to {}

Send an Idempotency-Key header to make retries safe: a repeat with the same key returns 200 with the existing run instead of starting another. Returns 202 with the queued run. The flow must be active and published (409 otherwise), the payload must match the definition's inputs schema (422), and your plan's monthly run limit applies (402).

curl -X POST https://api.orderly-hub.com/api/v1/flows/$FLOW_ID/run \
-H "Authorization: Bearer $ORDERLY_API_KEY" \
-H "X-Organization-Id: $ORG_ID" \
-H "Idempotency-Key: order-1001" \
-H "Content-Type: application/json" \
-d '{ "payload": { "order_id": "1001" } }'
{
"data": {
"id": "7d0a…",
"flow_id": "550e8400-e29b-41d4-a716-446655440000",
"status": "queued",
"trigger_source": "manual",
"input": { "payload": { "order_id": "1001" }, "meta": { "source": "manual" } }
}
}
GET/api/v1/flows/runs

List runs across all flows

https://api-test.orderly-hub.com/api/v1/flows/runs

Cancel, replay, retry​

  • Cancel stops the run and marks it cancelled; steps that already finished are not undone. Cancelling a failed run closes it for good, so it can no longer be retried. A succeeded or cancelled run returns 409.
  • Replay returns 202 with a new run that uses the original trigger payload against the flow's currently published version, with trigger_source replay and meta.replay_of set. The flow must be active.
  • Retry resumes a failed run from the step that failed, without running earlier steps again. Returns 409 when the run is not failed. It is the same action as retrying the run's exception.

Signal a waiting run​

POST/api/v1/flows/runs/{runId}/signalflows:run
FieldTypeDescription
eventstringRequired. 1 to 200 characters; must match the waiting step's event
payloadanyOptional. Becomes the wait.event step's output

Returns { "data": { "delivered": true } } when the run resumed, or false when it was not waiting on that event. See Waits and signals.

Exceptions​

MethodPathScopeDescription
GET/api/v1/flows/exceptionsflows:readList exceptions. Filters: resolution (open, retried, corrected, ignored, escalated), priority (high, normal, low), flow_id, end_user_id, limit
POST/api/v1/flows/exceptions/{id}/retryflows:triageResume the run from its failing step
POST/api/v1/flows/exceptions/{id}/ignoreflows:triageMark ignored. Body: optional note
POST/api/v1/flows/exceptions/{id}/escalateflows:triageMark escalated. Body: optional note
POST/api/v1/flows/exceptions/{id}/correctflows:triageMark corrected after a manual fix. Body: optional note
POST/api/v1/flows/exceptions/{id}/assignflows:triageAssign to a user with user_id, or clear with null

Every failed run has one exception, carrying run_id, flow_id, step_key, priority (high when the failing step moves money), resolution, last_error, and assigned_to. Retrying an exception whose run is no longer failed returns 409. Notes are up to 2,000 characters.

curl -X POST https://api.orderly-hub.com/api/v1/flows/exceptions/$EXCEPTION_ID/ignore \
-H "Authorization: Bearer $ORDERLY_API_KEY" \
-H "X-Organization-Id: $ORG_ID" \
-H "Content-Type: application/json" \
-d '{ "note": "Duplicate order, cancelled in Shopify." }'
GET/api/v1/flows/exceptions

List flow exceptions

https://api-test.orderly-hub.com/api/v1/flows/exceptions

Virtual endpoints​

MethodPathScopeDescription
GET/api/v1/flows/endpointsflows:readList endpoints
POST/api/v1/flows/endpointsflows:writeCreate an endpoint for an endpoint-triggered flow
GET/api/v1/flows/endpoints/{id}flows:readGet an endpoint
PATCH/api/v1/flows/endpoints/{id}flows:writeUpdate method and schemas (custom contracts), response mode, timeout, callback, auth mode, or rate limit
POST/api/v1/flows/endpoints/{id}/activateflows:writeStart accepting requests
POST/api/v1/flows/endpoints/{id}/deactivateflows:writeStop accepting requests
GET/api/v1/flows/endpoints/{id}/keysflows:readList the endpoint's keys (hashes are never returned)
POST/api/v1/flows/endpoints/{id}/keysflows:writeIssue an fe_ key for the endpoint
DELETE/api/v1/flows/endpoints/keys/{keyId}flows:writeRevoke a key immediately
GET/api/v1/flows/endpoints/{id}/requestsflows:readThe request log, newest first. Filters: status, limit (up to 200)
GET/api/v1/flows/endpoints/requests/{requestId}flows:readOne request with its run's status and error
POST/api/v1/flows/endpoints/{id}/testflows:writeValidate a sample payload and dry-run the flow
GET/api/v1/flows/endpoints/openapiflows:readOpenAPI 3.1 document for your active endpoints

Create an endpoint​

POST/api/v1/flows/endpointsflows:write
FieldTypeDescription
flow_idstringRequired. A flow with the endpoint trigger and no endpoint yet
slugstringRequired. Lowercase letters, digits, and hyphens, starting with a letter, up to 64 characters
contractstringcustom (default), orders.create, orders.get, shipments.get, shipments.list, inventory.list, or invoices.list
methodstringPOST (default), GET, PUT, or DELETE. Standard contracts set their own
request_schemaobjectCustom contracts only. Defaults to the flow definition's inputs
response_schemaobjectCustom contracts only
response_modestringsync (default) or async
sync_timeout_msinteger1,000 to 25,000. Default 25,000
callback_urlstringOptional HTTPS URL for results that were not returned inline
auth_modestringeither (default), org_api_key, or endpoint_key
rate_limit_per_minuteinteger1 to 100,000 per caller. Default 600

Returns 201 with the endpoint. When callback_url is set, data.callback_secret_plaintext is returned once; it is never returned again. Returns 409 when the flow is not endpoint-triggered, already has an endpoint, or the slug is taken, and 402 when your plan's endpoint limit is reached. The slug and contract cannot be changed later.

Issue a key​

POST/api/v1/flows/endpoints/{id}/keysflows:write
FieldTypeDescription
consumer_labelstringRequired. 1 to 120 characters, such as the caller's name
end_user_idstringOptional. Ties the key to a client; it must match the flow's client
expires_atstringOptional ISO 8601 expiry

Returns 201 with data.key (the fe_ key, shown once) and data.row (the stored key without its secret).

curl -X POST https://api.orderly-hub.com/api/v1/flows/endpoints \
-H "Authorization: Bearer $ORDERLY_API_KEY" \
-H "X-Organization-Id: $ORG_ID" \
-H "Content-Type: application/json" \
-d '{
"flow_id": "'"$FLOW_ID"'",
"slug": "create-order",
"contract": "orders.create",
"response_mode": "sync",
"auth_mode": "endpoint_key"
}'

curl -X POST https://api.orderly-hub.com/api/v1/flows/endpoints/$ENDPOINT_ID/keys \
-H "Authorization: Bearer $ORDERLY_API_KEY" \
-H "X-Organization-Id: $ORG_ID" \
-H "Content-Type: application/json" \
-d '{ "consumer_label": "Acme ERP" }'

Test an endpoint​

POST/api/v1/flows/endpoints/{id}/testflows:write

Send { "payload": … }. The payload is checked against the request schema (400 with CONTRACT_VIOLATION and details.problems when it does not match), then the flow's draft, or its published version when there is no draft, is dry-run. Returns { "data": { "problems": [...], "dry_run": { "steps": [...] }, "response": … } }, where problems lists any response schema violations of the Respond body. No run is created.

Templates and clients​

All of these need embed:manage in addition to the flows:* scope shown.

MethodPathScopeDescription
GET/api/v1/flows/templatesflows:readList templates. Filter: status (draft, published, archived)
POST/api/v1/flows/templatesflows:writeCreate a draft template
GET/api/v1/flows/templates/{id}flows:readGet a template
PUT/api/v1/flows/templates/{id}/draftflows:writeUpdate name, description, trigger configuration, definition, or params schema
POST/api/v1/flows/templates/{id}/publishflows:writeValidate and publish; increments the template version
POST/api/v1/flows/templates/{id}/archiveflows:writeArchive; installed flows keep running
POST/api/v1/flows/templates/{id}/installflows:writeCreate a flow from a published template, optionally for a client
POST/api/v1/flows/{id}/upgrade-templateflows:writeReplace an installed flow's draft with the template's current definition
GET/api/v1/flows/clients/summaryflows:readOne row per client: active and total flows, runs this period, open exceptions

Creating and updating a template returns { "template": …, "problems": [...] }: structural problems are reported without blocking the save. Publishing returns 422 with TEMPLATE_INVALID when the definition or trigger configuration is invalid, and 409 for an archived template.

Install a template​

POST/api/v1/flows/templates/{id}/installflows:writeembed:manage
FieldTypeDescription
end_user_idstringThe client to install for, or omit for your own organization
namestringFlow name. Defaults to the template's name
slugstringFlow slug. Generated when omitted
paramsobjectValues validated against the template's params schema. Up to 16 KB
trigger_configobjectOverrides the template's trigger configuration, such as the client's own bridge_id
client_runnablebooleanLets the client start runs from the embed. Default false

Returns 201 with { "flow": …, "version_id": "…", "problems": [...] }. The new flow holds the template's definition as its draft; publish it to start running. Returns 409 when the template is not published, 422 with TEMPLATE_PARAMS_INVALID when params do not match the schema, and 402 when a plan limit on flows or client flows is reached.

curl -X POST https://api.orderly-hub.com/api/v1/flows/templates/$TEMPLATE_ID/install \
-H "Authorization: Bearer $ORDERLY_API_KEY" \
-H "X-Organization-Id: $ORG_ID" \
-H "Content-Type: application/json" \
-d '{
"end_user_id": "'"$CLIENT_ID"'",
"params": { "carrier": "fedex" },
"trigger_config": {
"bridge_id": "'"$CLIENT_BRIDGE_ID"'",
"events": ["order_created"]
}
}'

Upgrade an installed flow​

POST/api/v1/flows/{id}/upgrade-templateflows:writeembed:manage

Replaces the flow's draft with the template's current definition and records the new template_version. The published version keeps running until you publish the flow again. Returns { "version_id": "…", "template_version": 3, "problems": [...] }, 409 when the flow was not installed from a template or the template is not published, and 422 when the flow's params no longer satisfy the template's schema.