Invoke Skill Workstream Draft

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

Draft a new workstream conversationally — describe what you want and Archie produces a structured, reviewable workstream definition with typed steps, dependencies, and validation. Produces unified drafts targeting either inline or containerized execution mode. The canonical drafting entry; the legacy `playbook.creator` slug is retained only for API back-compat.

Request bodyapplication/json

Field	Type	Description
`description`required	`string`	Natural-language description of the workstream to draft.
`topic_id`	`string \| null`	Topic to anchor the draft to — permakey (preferred) or UUID.
`prior_draft_id`	`string (uuid) \| null`	Optional prior draft to iterate on instead of creating a new one.
`target_execution_mode`	`"inline" \| "containerized"`	Which execution mode the draft should target. Defaults to 'inline' for fast, declarative-step workflows; 'containerized' for longer-running agentic work that runs on a Fly.io machine (Studio-authored variants typically use this). The legacy labels 'container' and 'external' are accepted as input aliases and normalised to 'containerized'. `inlinecontainerized`
`idempotency_key`	`string \| null`	Caller-supplied stable token. Replaying within 24h returns the previously-created draft id rather than generating a duplicate.

Responses

200Skill executed successfully

Field Type Description

skillrequired string —

outputrequired

object

Pointer to the draft + summary of what got generated.

show nested

Field	Type	Description
`stub_fields`	`string[]`	—
`warnings`	`string[]`	—
`draft_id`	`string (uuid) \| null`	Newly-created draft id.
`name`	`string`	Working name the LLM gave the draft.
`step_count`	`integer`	Number of steps the LLM generated.
`target_execution_mode`	`"inline" \| "containerized"`	Execution mode the draft was generated for. `inlinecontainerized`
`validation_warning_count`	`integer`	Number of validation warnings on the draft. Non-zero is fine for drafts; commit will reject if any blocking warnings remain.
`error`	`string \| null`	—
`error_envelope`	`any \| null`	Canonical structured error. Populated on draft generation failure.

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.draft/invoke \
  -X POST \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{
       "description": "string",
       "topic_id": null,
       "prior_draft_id": null,
       "target_execution_mode": "inline",
       "idempotency_key": null
     }'