Skip to main content

API Overview

OrcFlows exposes a JSON REST API served by cmd/api (default http://localhost:3001). This section documents the raw HTTP API; for narrative/conceptual documentation of what each resource does, see Core Concepts.

Base URL​

All authenticated routes are under /api/v1. A handful of routes live outside that prefix because they're public (webhooks, public workflow runs, file downloads) — see Public & Webhook Routes.

http://localhost:3001/api/v1/...

Authentication​

Most routes require a JWT bearer token, obtained from POST /api/v1/auth/register or POST /api/v1/auth/login:

Authorization: Bearer <jwt>

The JWT encodes tenant_id, user_id, and role. All data access is scoped to the token's tenant — see Multi-Tenancy & Data Model.

Three other ways to authenticate exist for specific use cases:

MechanismUsed forHeader
JWT bearer tokenThe web app and any first-party integrationAuthorization: Bearer <jwt>
Workflow API keyCalling a single workflow's public endpointAuthorization: Bearer <workflow_api_key>
Platform API keyPOST /api/v1/api-keys — a long-lived key tied to a user, for scripts/CIAuthorization: Bearer <api_key>
Webhook URL secrecy/webhooks/{workflowId} and similar — no header, the 128-bit workflow UUID in the path is the secretn/a

Response envelope​

Successful responses return the resource directly, or for list endpoints:

{ "data": [ /* ... */ ], "limit": 50, "offset": 0 }

Errors return:

{ "error": "human-readable message" }

with an appropriate 4xx/5xx status code.

Pagination​

List endpoints accept ?limit= and ?offset= query parameters (default limit 50).

Roles & permissions​

Endpoints that mutate sensitive resources (deleting workflows, managing secrets, team members, billing, SSO config) require a minimum role — admin or owner. A 403 is returned if the caller's role is insufficient.

CORS​

The API allows all origins (Access-Control-Allow-Origin: *) with GET, POST, PUT, DELETE, OPTIONS and Authorization, Content-Type, X-Request-ID headers — suitable for calling from a browser-based frontend hosted anywhere.

Health & metrics​

EndpointAuthDescription
GET /healthnoneLiveness check, returns {"status":"ok"}.
GET /api/v1/metricsJWTBasic usage metrics for the current tenant.
GET /api/v1/system/workersadmin/ownerTemporal worker pool status.

Sections​