v1

latestOpenAPI 3.1.0MIT2026-08-0481194343.8 KB
workflows

Create a workflow

Scope: workflows:write. Free (definition only). Creates a versioned workflow from a DSL definition.

post/v1/workflows

Headers

Idempotency-Keystring

Optional client-supplied key (≤128 chars, [A-Za-z0-9_-:]) for safe retries. Keys are global within one concrete API-key credential plus live/test mode; never reuse one on another endpoint. 'Same request' = a SHA-256 of an explicit operation discriminator plus the canonical (sorted-key) JSON body (session_id is folded in for /sessions/{id}/predict). LLM-capable operations also bind the non-secret effective provider, role models, and one-way provider-key fingerprint; plaintext provider keys never enter the hash or replay record. Replays the response for 24 h when operation, body, and effective execution identity match (X-Coasty-Idempotent-Replay: true and X-Credits-Charged: 0). Action screenshot pixels are response-only and deliberately omitted from replay storage; a replay retains frame_id but returns screenshot=null and observation_available=false. Inference replays also set body usage.credits_charged=0 and usage.billed=false; machine-snapshot bodies retain the original gross charge for auditability. A retry while the original is still running waits up to ~25 s then returns the result, otherwise 409 IDEMPOTENCY_IN_FLIGHT (retry with the SAME key). Returns 422 IDEMPOTENCY_KEY_REUSED if any bound input differs. Rotating the API key starts a new replay namespace. Collect a lost result via GET /v1/idempotency/{key} using the original credential.

Request body

namestring required
slugstring required

Stable handle.

inputs_schemaWorkflowInputsSchema

Typed input declarations. The server also enforces the configured serialized byte ceiling.

descriptionstring nullable
metadataobject nullable

Response

The created workflow.

idstring required
object'workflow' required
namestring required
slugstring required
versioninteger required
dsl_versionstring
inputs_schemaWorkflowInputsSchema

Typed input declarations. The server also enforces the configured serialized byte ceiling.

descriptionstring nullable
status'active' | 'archived'
metadataobject nullable
created_atstring nullable
updated_atstring nullable
request_idstring nullable