HTTP API
Tenant-scoped routes require the four CPET headers (X-Customer, X-Product, X-Env, X-Tenant). The management routes require a Bearer token; the dynamic trigger paths are gated by the job’s own access rule (and, for Teams, an HMAC signature) instead.
Trigger endpoints
Section titled “Trigger endpoints”Registered dynamically from each job’s webhook / teams triggers.
| Method | Path | Auth | Behavior |
|---|---|---|---|
| POST | (job-defined) | job access rule | Webhook trigger. Body → payload. 200 {"runid":"01K…","message":"job execution started successfully"} |
| POST | (job-defined) | HMAC | Teams trigger. Authorization: HMAC <sig>. 200 with a Teams message body; 401 on signature mismatch |
Scheduled, git-poll, and database triggers fire internally — there is no “run now” endpoint for them.
Management
Section titled “Management”| Method | Path | Purpose |
|---|---|---|
| GET | /jobs | The loaded, active job definitions for the tenant → {"jobs": {<name>: <definition>}} |
| GET | /runs?id=<ulid> | One run by id |
| GET | /runs?filter=<expr>&page=&pagesize= | Query runs (default page 1, pagesize 10, ordered newest-first) |
| GET | /jobdefinitions | List stored definitions (v2 query options) |
| POST | /jobdefinitions | Create — body {"definition": "<job YAML text>"} |
| POST | /jobdefinitions/search | Structured search |
| GET | /jobdefinitions/:id | Read one |
| PATCH / PUT | /jobdefinitions/:id | Update |
| DELETE | /jobdefinitions/:id | Delete |
A run record carries status (created → completed / failed), the trigger name, triggertype, the context payload, and logs. Logs include the script’s captured output and, under result, its return value. Output over ~16 KB is offloaded to object storage and surfaced as a link.
Fleet and queue
Section titled “Fleet and queue”| Method | Path | Purpose |
|---|---|---|
| GET | /agents | Agents serving this tenant — id, version, status, type, health, tags, capabilities |
| GET | /workflow/queue | Pending/dispatched work items for this tenant |
| DELETE | /workflow/queue/:id | Cancel one queued item (403 cross-tenant, 404 unknown) |
Health
Section titled “Health”GET /health and GET /ready — unauthenticated, no CPET headers.
Error codes
Section titled “Error codes”| Code | Meaning |
|---|---|
jobs-json-request-parse-failed | Request body was not valid JSON |
jobs-request-required-field-not-found | A required field was missing |
jobs-query-parsing-failed | The /runs filter could not be parsed |
jobs-ctx-tenant-not-found | CPET headers didn’t resolve to a tenant |
jobs-global-config-is-nil | The service booted without required global config |