Skip to main content

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​

POST/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=20 arrives as the number 20.

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 modeAccepts
either (default)An endpoint key or an organization API key
endpoint_keyOnly endpoint keys
org_api_keyOnly 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 the flows:run scope.

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.

ModeOutcomeResponse
syncThe flow reached a Respond stepThe step's status (2xx) and body
syncThe flow succeeded without a Respond step200 with request_id, run_id, and "status": "succeeded"
syncThe flow failed or was cancelled502 with FLOW_RUN_FAILED
syncThe flow's response broke the response schema502 with RESPONSE_CONTRACT_VIOLATION
syncThe sync timeout (up to 25 seconds) passed first202 with a status URL
asyncAlways, right away202 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​

GET/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.

StatusMeaning
queuedAccepted; the run is starting
runningThe run is in progress
respondedFinished, with a response
failedThe run failed, could not start, or broke the response contract
timed_outThe request did not settle in time
rejectedRefused 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 sendA repeat is recognizedFor
An Idempotency-Key header, any methodBy the same key valueAs long as the request is kept: 90 days
No header, POST, PUT, or DELETEBy the same method, path, and exact body24 hours
No header, GETNever; 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: 202 with the same request ID and status URL.
  • Failed because the response broke the contract: the original 502 error.
  • 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.

Always send an Idempotency-Key for writes

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​

LimitValue
Requests per IP address, across all endpoints1,200 per minute
Requests per credential, per endpointThe endpoint's rate limit (600 per minute unless changed)
Requests per organizationSet by your plan
Request body1 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"]
}
}
}
Statuserror.codeWhen
400BAD_REQUESTThe body is not valid JSON
401UNAUTHORIZEDCredentials are missing or not accepted by this endpoint
402PLAN_REQUIREDYour plan does not include Flows
402RUN_LIMITYour plan's monthly run limit is reached
404NOT_FOUNDNo active endpoint at this URL, or no such request
405UNKNOWN_ERRORWrong method; the message names the accepted one
409ENDPOINT_UNAVAILABLEThe flow behind the endpoint is paused, archived, or not published
413PAYLOAD_TOO_LARGEThe body is over the size limit
422CONTRACT_VIOLATIONThe request does not match the request schema; see details.problems
422FLOW_INPUTS_MISMATCHThe payload does not match the flow's own inputs schema; see details.problems
429RATE_LIMITEDToo many requests
502FLOW_RUN_FAILEDThe flow run failed or was cancelled (sync mode)
502RESPONSE_CONTRACT_VIOLATIONThe flow's response does not match the response schema
502RUNTIME_UNAVAILABLEThe run could not be started; retry later
500INTERNAL_ERROR or INTERNALSomething 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.