API overview
Everything the editor does is an HTTP API — scoped tokens, a machine-checked contract, and conventions built for both scripts and AI agents.
Everything the editor does is an HTTP API on your workspace's own URL:
https://<your-workspace-url>/api/…The reference pages in this section are generated from the platform's OpenAPI 3.1 contract, which is machine-checked against the router: a route that exists but is undocumented, or documented but not served, fails GoRunner's own build — so what you read here is what the server does.
The five-minute integration
TOKEN="grt_…" # Settings → Workspace → API tokens
BASE="https://<your-workspace-url>"
# Create a workflow
curl -s -X POST "$BASE/api/workflows" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"name": "From the API"}'
# Validate a definition BEFORE writing it (free, judges everything the publish gate judges)
curl -s -X POST "$BASE/api/workflows/validate" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d @definition.json
# Trigger a run and wait up to 20s for the result in one call
curl -s -X POST "$BASE/api/workflows/$ID/run?environment=production&wait=20" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"orderId": 42}'Conventions
| Convention | Detail |
|---|---|
| Auth | Authorization: Bearer grt_… — scoped tokens. No CSRF for token calls. |
| Envelope | Success: {"data": …} (lists: {"data": [...], "total": n} — empty lists are [], never null). Failure: {"error": {"code", "message"}}. |
| Environments | POST /workflows/{id}/run?environment=test|production. Production executes the published snapshot; test executes the draft. The parameter is required by convention for agents — never run production by omission. |
| Synchronous runs | ?wait=N (0–30s) on the run endpoint answers with the finished run instead of a 202. |
| Validate before write | POST /workflows/validate runs the exact publish-gate validator and returns diagnostics that name the fault and the admissible set — built so a program (or a model) can self-correct. |
| Optimistic concurrency | Workflow updates accept expectedRev; a stale revision is a 409, never a silent clobber. |
| Idempotency | Opt-in Idempotency-Key on the writes where a duplicate costs something real. |
| Rate limits | Per-credential buckets with X-RateLimit-* headers and Retry-After, plus a per-address flood ceiling. |
| Live runs | GET /api/runs/{id}/stream is SSE — step events as they happen. |
| Pagination | ?page= and ?limit= on list endpoints; the response carries total. |
How this reference is organized
Every endpoint is its own page, listed in the sidebar with its method — grouped by resource in the order an integration meets them: Workflows, Lifecycle (validate, publish, run, versions, variables), Runs, Pieces, Connections, Folders, Templates. Endpoints within a group follow the contract's own order, not the alphabet. Editor Internals sits last: the operations GoRunner's own builder uses moment to moment, documented because every served route is documented (the contract is machine-checked against the router, both directions), but rarely called by an integration.
The API is consumed by scripts, CI — and increasingly by AI agents (it also backs the MCP server). The conventions above reflect that: unknown paths answer inside the JSON error envelope, error codes have one stable spelling, refusals name legal alternatives, and a definition that validates is a definition that publishes, because both doors run the same function.