Virtual endpoints
A virtual endpoint publishes a flow as a stable HTTP API. Your systems, your partners, or your clients call one URL, the flow runs, and its Respond step becomes the HTTP response. You get a real API surface, with contracts, keys, rate limits, idempotency, and a request log, without deploying a service.
Every endpoint lives at:
https://api.orderly-hub.com/v/{org}/{endpoint}
where {org} is your organization's slug and {endpoint} is the endpoint's
slug, for example https://api.orderly-hub.com/v/acme/create-order.
Publish an endpoint
- Create a flow with the Endpoint trigger. See Build a flow.
- Build it. The trigger payload is the request: the JSON body for
POST,PUT, andDELETE, or the query string forGET. End the flow with a Respond step that sets thestatus(any 2xx) andbody. A Respond step ends the run, so put it last. - Create the endpoint. On the Endpoints tab, click Create endpoint and fill in the fields below. Each flow can have one endpoint.
- Publish the flow. An endpoint flow cannot be published until its endpoint exists, and the endpoint answers with the flow's published version.
| Field | What it does |
|---|---|
| Slug | The last part of the URL. Lowercase letters, digits, and hyphens, starting with a letter. Fixed once created |
| Method | POST, GET, PUT, or DELETE. Requests with any other method get 405 |
| Contract | custom, or a standard contract that fixes the method and schemas (below). Fixed once created |
| Flow | The endpoint-triggered flow to run |
| Response mode | Sync waits for the flow's response; Async answers 202 right away |
| Sync timeout (ms) | How long a sync request waits, from 1,000 to 25,000 (the default) |
| Callback URL | Optional HTTPS URL that receives the result of requests that did not get it inline |
| Auth | Org API key or endpoint key (the default), Org API key only, or Endpoint key only |
| Rate limit (per minute) | Requests each caller may make per minute, from 1 to 100,000 (default 600) |
| Request schema (JSON) and Response schema (JSON) | Custom contracts only: JSON Schemas for the request and the response |
Contracts
A contract describes what the endpoint accepts and returns. Requests that do not
match the request schema are rejected with 422 before the flow runs, and a
response that does not match the response schema is replaced with a 502, so
callers can rely on the shape.
| Contract | Method | Purpose |
|---|---|---|
custom | Your choice | Whatever your schemas and Respond step define |
orders.create | POST | Create an order from an Orderly-shaped body |
orders.get | GET | Fetch one order by external_id |
shipments.get | GET | Fetch one shipment by external_id or tracking_number |
shipments.list | GET | List shipments, paged |
inventory.list | GET | List inventory levels, paged |
invoices.list | GET | List invoices, paged |
For a custom contract with no request schema, Orderly uses the flow
definition's inputs schema when it has one. You can change a custom
endpoint's method and schemas later; standard contracts keep theirs.
Response modes and callbacks
With Sync, the request waits up to the sync timeout for the flow:
- If the flow responds, the caller gets the Respond step's status and body.
- If the flow finishes without a Respond step, the caller gets
200with the request ID, run ID, andsucceeded. - If the flow fails, the caller gets
502. - If the timeout passes first, the caller gets
202with a status URL to poll.
With Async, every request gets 202 with a status URL immediately.
When you set a Callback URL, Orderly POSTs the final result there for any
request whose result was not returned inline: every async request, and sync
requests that timed out. Callbacks are signed. When you create the endpoint
with a callback URL, Orderly shows Save your callback secret once; use it to
verify the X-Orderly-Signature header. The endpoint
reference has the payload and signature
format.
Keys
Click an endpoint to open its detail panel. The Keys tab issues endpoint
keys (fe_...): credentials that can only invoke this endpoint, nothing else.
Give each consumer its own key so you can see and revoke them independently.
- Enter a Label, an optional Expires date, and, if you manage clients, an optional Client to tie the key to.
- Click Create key. Orderly shows Save your endpoint key once. Copy it, then click I have saved it. The key cannot be shown again.
The table lists each key's label, prefix, creation time, and when it was last used. Revoke cuts a key off immediately; callers using it are rejected from the next request.
Depending on the endpoint's Auth setting, callers can also use an
organization API key (oh_...) that carries the flows:run scope.
The request log
The Requests tab lists the endpoint's requests, newest first, with their status, latency, caller, and time. Orderly keeps request records for 90 days.
| Status | Meaning |
|---|---|
rejected | Refused before the flow ran: the body was too large or did not match the contract |
queued | Accepted and about to start a run |
running | The run is in progress |
responded | The flow returned its response |
timed_out | The request did not settle in time |
failed | The run failed or never started, or its response broke the contract |
Test an endpoint
The Test tab checks an endpoint without calling it. Paste a Sample payload and click Run dry test. Orderly validates the payload against the request schema, dry-runs the flow's draft (or its published version when there is no draft), and validates the Respond body against the response schema. You see each step's result, any contract problems, and the response the endpoint would send. No run is created and nothing is written.
Turn an endpoint off and on
The Active switch in the endpoints list stops or restarts traffic. An
inactive endpoint answers 404, exactly like one that does not exist. Use
Edit to change its settings, and the copy button next to its path to copy
the full URL.
Share the API with OpenAPI
Click OpenAPI on the Endpoints tab to download
orderly-endpoints-openapi.json, an OpenAPI 3.1 document describing every
active endpoint in your organization, with their methods, schemas, and
authentication. Hand it to the team or partner calling you, or load it into an
API client to generate code.
Next steps
- Published endpoint reference: authentication, idempotency, polling, callbacks, and errors for callers.
- Endpoints management API: create endpoints and keys programmatically.