Invoke Skill Workstream Advance

post/api/v1/skills/workstream.advance/invoke

Advance a paused or awaiting-approval workstream run — approve a task, skip a step, pause, or resume. This is the supervisory surface; for starting a new run use workstream_run, for cancelling use workstream_cancel.

Request bodyapplication/json

Field	Type	Description
`cycle_id`required	`string (uuid)`	The cycle to advance.
`action`required	`"approve_task" \| "skip_step" \| "pause" \| "resume"`	What to do: - `approve_task`: mark the task in `task_id` approved; the run moves on. - `skip_step`: skip the current step. - `pause`: halt the run in-place. - `resume`: continue a previously paused run. `approve_taskskip_steppauseresume`
`task_id`	`string (uuid) \| null`	Required for `approve_task`. The task being approved.
`reason`	`string \| null`	Audit trail. Recommended for skip_step.
`idempotency_key`	`string \| null`	Caller-supplied stable token. Replaying within 24h returns the same outcome rather than re-applying the action.

Responses

200Skill executed successfully

Field Type Description

skillrequired string —

outputrequired

object

Cycle state after the action lands.

show nested

Field	Type	Description
`stub_fields`	`string[]`	—
`warnings`	`string[]`	—
`cycle_id`	`string (uuid) \| null`	The cycle the action was applied to.
`run_id`	`string (uuid) \| null`	—
`status`	`"running" \| "paused" \| "awaiting_approval" \| "completed" \| "cancelled" \| "failed"`	Lifecycle state after the action. `runningpausedawaiting_approvalcompletedcancelledfailed`
`current_step`	`string`	Slug of the currently-executing step.
`next_step`	`string \| null`	Slug of the next step (None on terminal states).
`error`	`string \| null`	—
`error_envelope`	`any \| null`	Canonical structured error. Populated when the action could not be applied.

correlation_idrequired string —

401Authentication required

Field Type Description

errorrequired

object

—

show nested

Field	Type	Description
`type`required	`string`	—
`code`required	`string`	—
`message`required	`string`	—
`param`	`string`	—
`retry_after_seconds`	`integer`	—

403Insufficient permissions

Field Type Description

errorrequired

object

—

show nested

Field	Type	Description
`type`required	`string`	—
`code`required	`string`	—
`message`required	`string`	—
`param`	`string`	—
`retry_after_seconds`	`integer`	—

404Skill not found

Field Type Description

errorrequired

object

—

show nested

Field	Type	Description
`type`required	`string`	—
`code`required	`string`	—
`message`required	`string`	—
`param`	`string`	—
`retry_after_seconds`	`integer`	—

429Rate limit exceeded

Field Type Description

errorrequired

object

—

show nested

Field	Type	Description
`type`required	`string`	—
`code`required	`string`	—
`message`required	`string`	—
`param`	`string`	—
`retry_after_seconds`	`integer`	—

5XXInternal server error

Field Type Description

errorrequired

object

—

show nested

Field	Type	Description
`type`required	`string`	—
`code`required	`string`	—
`message`required	`string`	—
`param`	`string`	—
`retry_after_seconds`	`integer`	—

curl https://api.dev.arch.ie/api/v1/skills/workstream.advance/invoke \
  -X POST \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{
       "cycle_id": "00000000-0000-0000-0000-000000000000",
       "action": "approve_task",
       "task_id": null,
       "reason": null,
       "idempotency_key": null
     }'