Authoring over the API

From the Team tier, a coding agent can create, validate and publish workflows through the REST API with its agent token. Without a token the API refuses every request.

Workflows are normally authored in the visual designer. From the Team tier and up, a coding agent can author them too — through the REST API on port 3001 — which is what "AI workflow authoring" on the pricing page means: the agent designs and publishes a workflow, then runs it.

Authentication

Every /api/* request needs a credential in an Authorization: Bearer header. There are two kinds:

Credential	Who holds it	Can use the API?
A session token	A person signed in to the web interface	Yes, on every tier
An agent token (`wsk_…`)	A coding agent or CI job	Only when the license grants agent API access — Team and up

No credential → 401 UNAUTHORIZED. The API does not work without a key.
An agent token on a Starter or Pro license → 403 FORBIDDEN. On those tiers an agent may use the MCP tool surface only.
An agent token on a Team or Enterprise license → the request proceeds under that token's profile.

The token is the same one the agent uses for MCP — see connect your coding agent. The tier decides what it can reach, not the token.

The authoring lifecycle

Every response uses one envelope: { "success": true, "data": … } or { "success": false, "error": { "code", "message" } }.

POST /api/workflows — create a draft. The server generates the id, sets version: 1 and status: "draft". Send a workflow document without id, version, status or timestamps.
PUT /api/workflows/:id — update steps and transitions. Draft saves are lenient: incomplete step configs are accepted, so work in progress can be saved.
POST /api/workflows/:id/validate — returns { valid, errors[] }. Run it before publishing and fix every error; the validation rules are what it checks.
POST /api/workflows/:id/publish — validates strictly, bumps version, sets status: "published". Only a published workflow can be started with ccw_start or referenced by a sub_workflow or execute_task_list step, so publish children before parents.

Other endpoints: GET /api/workflows (list; ?search=, ?status=, ?tags=a,b), GET /api/workflows/:id, DELETE /api/workflows/:id, and folder management under /api/workflows/folders. Instruction files and skills have their own routes at /api/instruction-files and /api/skills.

Example

curl -X POST http://127.0.0.1:3001/api/workflows \
  -H "Authorization: Bearer wsk_…" \
  -H "Content-Type: application/json" \
  -d @workflow.json

Then validate and publish with the returned id:

curl -X POST http://127.0.0.1:3001/api/workflows/wf_abc123/validate -H "Authorization: Bearer wsk_…"
curl -X POST http://127.0.0.1:3001/api/workflows/wf_abc123/publish  -H "Authorization: Bearer wsk_…"

What an agent authoring a workflow should know

The design guidelines apply in full, and two of them matter most to an author that is itself a model: specify the output contract in every prompt, and set allowSummaryFallback: false on every decision. The MCP server on port 3002 is execution only — an agent cannot author there, whatever its tier.