Published endpoints
The HTTP surface of a flow published as a virtual endpoint. This page is for whoever calls the endpoint: your own services, a partner, or a client.
Endpoints are served under https://api.orderly-hub.com/v. They do not use the /api/v1 prefix, and the organization comes from the URL, so no X-Organization-Id header is needed. To manage endpoints and keys, use the Flows API.
Invoke an endpoint
/v/{orgSlug}/{endpointSlug}Each endpoint accepts exactly one method (POST, GET, PUT, or DELETE), set when it was created; any other method returns 405. The request becomes the flow's trigger.payload:
POST,PUT,DELETE: the body, which must be JSON. An empty body is treated as{}.GET: the query string, as an object. Values are converted to the types the endpoint's request schema declares, so?limit=20arrives as the number20.
If the endpoint has a request schema, a request that does not match it is rejected with 422 before any flow runs.
curl -X POST https://api.orderly-hub.com/v/acme/create-order \
-H "Authorization: Bearer $ORDERLY_ENDPOINT_KEY" \
-H "Idempotency-Key: po-88412" \
-H "Content-Type: application/json" \
-d '{
"externalId": "PO-88412",
"customer": { "email": "buyer@example.com" },
"lineItems": [{ "sku": "WIDGET-A", "name": "Widget A", "quantity": 2, "price": 19.99 }],
"totals": { "total": 39.98 }
}'
{
"order_id": "8c1f…",
"external_id": "PO-88412",
"status": "pending"
}
The body of a successful response is exactly what the flow's Respond step returned, with the status it set. It is not wrapped in data.
curl "https://api.orderly-hub.com/v/acme/order-status?external_id=PO-88412" \
-H "Authorization: Bearer $ORDERLY_ENDPOINT_KEY"
Authentication
Send a bearer token in the Authorization header. Which kinds an endpoint accepts depends on its auth mode:
| Auth mode | Accepts |
|---|---|
either (default) | An endpoint key or an organization API key |
endpoint_key | Only endpoint keys |
org_api_key | Only organization API keys |
- Endpoint keys (
fe_...) are issued per endpoint from the dashboard or the Flows API. They can only invoke the endpoint they belong to and poll its requests; they cannot call any other Orderly API. A key tied to a client works only for that client's endpoint. - Organization API keys (
oh_...) must carry theflows:runscope.
Missing, unknown, revoked, or expired credentials, a key of a kind the endpoint does not accept, an endpoint key for a different endpoint, and an API key without flows:run all return 401. If your organization's plan does not include Flows, every request returns 402 with PLAN_REQUIRED.
Responses
What comes back depends on the endpoint's response mode.
| Mode | Outcome | Response |
|---|---|---|
sync | The flow reached a Respond step | The step's status (2xx) and body |
sync | The flow succeeded without a Respond step | 200 with request_id, run_id, and "status": "succeeded" |
sync | The flow failed or was cancelled | 502 with FLOW_RUN_FAILED |
sync | The flow's response broke the response schema | 502 with RESPONSE_CONTRACT_VIOLATION |
sync | The sync timeout (up to 25 seconds) passed first | 202 with a status URL |
async | Always, right away | 202 with a status URL |
A 202 response carries the request and run IDs and where to check on them, also sent as the Location header:
{
"request_id": "3b9e2c1a-…",
"run_id": "7d0a…",
"status_url": "/v/acme/_requests/3b9e2c1a-…"
}
Poll a request
/v/{orgSlug}/_requests/{requestId}Use the same credentials as the original request. An endpoint key can only read requests made with that key; any other request ID returns 404.
curl https://api.orderly-hub.com/v/acme/_requests/$REQUEST_ID \
-H "Authorization: Bearer $ORDERLY_ENDPOINT_KEY"
{
"data": {
"request_id": "3b9e2c1a-…",
"status": "responded",
"http_status": 200,
"run_id": "7d0a…",
"response": { "order_id": "8c1f…", "external_id": "PO-88412", "status": "pending" }
}
}
Poll until status is responded, failed, or timed_out. response is included only once the status is responded; http_status is the status the caller would have received.
| Status | Meaning |
|---|---|
queued | Accepted; the run is starting |
running | The run is in progress |
responded | Finished, with a response |
failed | The run failed, could not start, or broke the response contract |
timed_out | The request did not settle in time |
rejected | Refused before a run started |
Callbacks
If the endpoint has a callback URL, Orderly POSTs the final result there for every request whose result was not returned inline: all async requests, and sync requests that answered 202 because they timed out.
{
"request_id": "3b9e2c1a-…",
"status": "responded",
"http_status": 200,
"run_id": "7d0a…",
"response": { "order_id": "8c1f…", "external_id": "PO-88412", "status": "pending" }
}
Each callback is signed with the endpoint's callback secret, which was shown once when the callback URL was first set:
X-Orderly-Signature: t=1760450000000,v1=5f2c…
t is the send time in milliseconds and v1 is the hex HMAC-SHA256 of {t}.{raw body} with the callback secret. Verify it before trusting the payload:
import crypto from 'node:crypto'
function verifyOrderlyCallback(rawBody, header, secret) {
const match = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(header ?? '')
if (!match) return false
const expected = crypto
.createHmac('sha256', secret)
.update(`${match[1]}.${rawBody}`)
.digest('hex')
return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(match[2]))
}
Respond with a 2xx quickly. Failed deliveries are retried up to 3 times. Callback URLs must use HTTPS and resolve to a public address.
Idempotency
Every request is recorded, and repeats of the same request return the stored outcome instead of running the flow again. Deduplication is scoped to one endpoint and one credential: two different keys never collide.
| You send | A repeat is recognized | For |
|---|---|---|
An Idempotency-Key header, any method | By the same key value | As long as the request is kept: 90 days |
No header, POST, PUT, or DELETE | By the same method, path, and exact body | 24 hours |
No header, GET | Never; every GET starts a new run |
What a repeat returns depends on how the original request ended:
- Responded: the original status and body, exactly.
- Still running, or timed out:
202with the same request ID and status URL. - Failed because the response broke the contract: the original
502error. - Failed because the flow run failed, or the run could not start: nothing is replayed. The repeat is processed as a new request and starts a new run, so a retry can succeed once the cause is fixed.
- Rejected (body too large or not matching the request schema): never stored under the key, so you can correct the request and send it again with the same key.
Concurrent duplicates are safe: if two identical requests arrive together, only one run starts and the other receives its outcome or a 202.
A key you choose, such as your own order or message ID, makes retries after a network error safe for 90 days and lets you resend the same body on purpose without it being treated as a repeat.
Rate limits and size
| Limit | Value |
|---|---|
| Requests per IP address, across all endpoints | 1,200 per minute |
| Requests per credential, per endpoint | The endpoint's rate limit (600 per minute unless changed) |
| Requests per organization | Set by your plan |
| Request body | 1 MB by default; your plan may allow more |
Limits use a sliding one-minute window. Requests over a limit get 429; requests with a body over the size limit get 413.
Errors
Errors use the standard envelope. When Orderly recorded the request, details includes its request_id (and run_id once a run started), which you can look up in the endpoint's request log.
{
"error": {
"code": "CONTRACT_VIOLATION",
"message": "Request does not match the endpoint contract",
"details": {
"code": "CONTRACT_VIOLATION",
"request_id": "3b9e2c1a-…",
"problems": ["/lineItems must NOT have fewer than 1 items"]
}
}
}
| Status | error.code | When |
|---|---|---|
400 | BAD_REQUEST | The body is not valid JSON |
401 | UNAUTHORIZED | Credentials are missing or not accepted by this endpoint |
402 | PLAN_REQUIRED | Your plan does not include Flows |
402 | RUN_LIMIT | Your plan's monthly run limit is reached |
404 | NOT_FOUND | No active endpoint at this URL, or no such request |
405 | UNKNOWN_ERROR | Wrong method; the message names the accepted one |
409 | ENDPOINT_UNAVAILABLE | The flow behind the endpoint is paused, archived, or not published |
413 | PAYLOAD_TOO_LARGE | The body is over the size limit |
422 | CONTRACT_VIOLATION | The request does not match the request schema; see details.problems |
422 | FLOW_INPUTS_MISMATCH | The payload does not match the flow's own inputs schema; see details.problems |
429 | RATE_LIMITED | Too many requests |
502 | FLOW_RUN_FAILED | The flow run failed or was cancelled (sync mode) |
502 | RESPONSE_CONTRACT_VIOLATION | The flow's response does not match the response schema |
502 | RUNTIME_UNAVAILABLE | The run could not be started; retry later |
500 | INTERNAL_ERROR or INTERNAL | Something went wrong on Orderly's side |
OpenAPI
Your organization's active endpoints are described by a generated OpenAPI 3.1 document, available from Flows → Endpoints → OpenAPI in the dashboard or from GET /api/v1/flows/endpoints/openapi. Use it to generate a client for the endpoints you call.