Skip to main content

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.

Open Endpoints

Publish an endpoint​

  1. Create a flow with the Endpoint trigger. See Build a flow.
  2. Build it. The trigger payload is the request: the JSON body for POST, PUT, and DELETE, or the query string for GET. End the flow with a Respond step that sets the status (any 2xx) and body. A Respond step ends the run, so put it last.
  3. Create the endpoint. On the Endpoints tab, click Create endpoint and fill in the fields below. Each flow can have one endpoint.
  4. Publish the flow. An endpoint flow cannot be published until its endpoint exists, and the endpoint answers with the flow's published version.
FieldWhat it does
SlugThe last part of the URL. Lowercase letters, digits, and hyphens, starting with a letter. Fixed once created
MethodPOST, GET, PUT, or DELETE. Requests with any other method get 405
Contractcustom, or a standard contract that fixes the method and schemas (below). Fixed once created
FlowThe endpoint-triggered flow to run
Response modeSync 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 URLOptional HTTPS URL that receives the result of requests that did not get it inline
AuthOrg 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.

ContractMethodPurpose
customYour choiceWhatever your schemas and Respond step define
orders.createPOSTCreate an order from an Orderly-shaped body
orders.getGETFetch one order by external_id
shipments.getGETFetch one shipment by external_id or tracking_number
shipments.listGETList shipments, paged
inventory.listGETList inventory levels, paged
invoices.listGETList 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 200 with the request ID, run ID, and succeeded.
  • If the flow fails, the caller gets 502.
  • If the timeout passes first, the caller gets 202 with 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.

  1. Enter a Label, an optional Expires date, and, if you manage clients, an optional Client to tie the key to.
  2. 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.

StatusMeaning
rejectedRefused before the flow ran: the body was too large or did not match the contract
queuedAccepted and about to start a run
runningThe run is in progress
respondedThe flow returned its response
timed_outThe request did not settle in time
failedThe 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​