Invoke Skill Workstream Run

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

Start a workstream run against the supplied client / period / runtime variables. Returns a run_id you can poll with workstream_status, events_url for live SSE progress, and detail_url to open the run in Workstream Studio. The query_id in the output is the join key for Slack→Studio deep-links.

Request bodyapplication/json

Field	Type	Description
`workstream_id`required	`string`	UUID, slug, or 7-char permakey. The adapter resolves it.
`client_id`	`string (uuid) \| null`	Client to run against. Optional for client-agnostic workstreams.
`period`	`string \| null`	Period label (e.g., 'FY26-Q1', '2026-04').
`runtime_vars`	`object`	Runtime overrides for the workstream's declared inputs. Keys are input names from `WorkstreamDescribeOutput.inputs_required`; values are JSON-typed (string, number, boolean, array, object, null). show nested Empty object.
`idempotency_key`	`string \| null`	Caller-supplied stable token (≤200 chars). When the same key is replayed within 24h the API returns the original cycle id rather than starting a duplicate run. Strongly recommended for any automated retry loop.

Responses

200Skill executed successfully

Field Type Description

skillrequired string —

outputrequired

object

Pointer to the new cycle + URLs the caller can use to monitor / open it. The canonical noun is ``cycle`` (Workstream → Blueprint → Cycle → Task). The legacy ``run_id`` field is kept populated alongside ``cycle_id`` for backwards compat with SDK consumers; new code should read ``cycle_id`` and treat ``run_id`` as deprecated.

show nested

Field	Type	Description
`stub_fields`	`string[]`	—
`warnings`	`string[]`	—
`cycle_id`	`string (uuid) \| null`	The cycle id of the launched workstream cycle.
`run_id`	`string (uuid) \| null`	—
`status`	`"pending" \| "running" \| "awaiting_approval"`	— `pendingrunningawaiting_approval`
`execution_mode`	`"inline" \| "containerized"`	— `inlinecontainerized`
`query_id`	`string \| null`	—
`events_url`	`string`	—
`detail_url`	`string`	—
`error`	`string \| null`	—
`error_envelope`	`any \| null`	Canonical structured error. Set when the cycle failed to start (workstream not found, validation, FGA denied, rate limited, etc.). The legacy `error` string is populated alongside it for back-compat.

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.run/invoke \
  -X POST \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{
       "workstream_id": "string",
       "client_id": null,
       "period": null,
       "runtime_vars": {},
       "idempotency_key": null
     }'