Relay docs

Workflows API

Run stored workflows from your own app. Every call except webhooks and resume URLs needs a gateway key with the workflows.run scope (an empty scope list allows everything). A key sees workflows in its own workspace plus global ones, and only those with API callable switched on.

#List workflows

GET /v1/workflows — the workflows this key may run, each with its trigger's input_schema.

#Start a run

POST /v1/workflows/{idOrName}/runs

{ "input": { "question": "Why was I charged twice?" }, "priority": 0 }

Returns 202 with { id, status }. Add ?wait=true to block until the run finishes (up to Gateway:Workflows:MaxSyncWaitSeconds, default 60): 200 with output when it completes, 502 when it fails, 202 if it's still going. Send an Idempotency-Key header to make retries safe — a repeat returns the original run.

#Read, cancel, watch

  • GET /v1/workflows/runs/{id} — status, counters, usage, output, error.
  • POST /v1/workflows/runs/{id}/cancel — cooperative: the engine stops at the next step boundary.
  • GET /v1/workflows/runs/{id}/events — server-sent events: step when a node starts or settles, run on each status change, done at the end with the final run.

#Approvals

POST /v1/workflows/runs/{id}/approve and /reject, body { "comment": "…", "decided_by": "ana@contoso.com" }. Only a run waiting on an Approval node accepts a decision, and only the first decision counts (409 afterwards).

#As a chat model

POST /v1/workflows/{idOrName}/chat/completions accepts an OpenAI chat request. trigger.input is { message, messages } — the last user message and the whole conversation. The reply is the output's text, answer, reply, content or message field, the output itself if it's a string, or its JSON. stream: true returns one chunk plus [DONE].

from openai import OpenAI
client = OpenAI(base_url="https://relay.example.com/v1/workflows/support-triage", api_key="app_live_…")
print(client.chat.completions.create(model="workflow", messages=[{"role": "user", "content": "hi"}]).choices[0].message.content)

#Webhooks (no key)

GET|POST|PUT|PATCH|DELETE /v1/workflows/hooks/{token} — the webhook trigger's URL. Bodies are capped (Gateway:Workflows:Webhook:MaxBodyBytes, 1 MB), calls are rate-limited per token (:RatePerMinute, 60), and each call is audited. The response depends on the trigger's Respond setting: 202 with the run id, the run's output, or whatever a Respond to webhook node sets.

#Resume URLs (no key)

POST /v1/workflows/resume/{token} — the {{ run.resumeUrl }} of a run waiting on a Wait node in webhook mode. The body becomes the Wait node's payload. Single use: once the run resumes, the URL returns 404.