Workflows
Start a Workflow Architect conversation
Create a workflow from a brief and start the Workflow Architect’s first turn, acting for a Personal key’s owner.
POST
Start a Workflow Architect conversation
The reference panel describes the current v3 operation. The notes below describe its v2 compatibility API. Follow the v3 request schema for current calls: v3 can move identifiers from the body or query into the URL. Keep the v2 method, path, and payload together when using the compatibility API.
v2 compatibility notes
POST /api/v2/workflows/startArchitectConversation
The API twin of the Console’s AI-assisted start. It creates a workflow and its draft, opens the draft’s Architect conversation with your brief as the first message, and starts the first turn. The workflow is homed the way create homes one: with the factory you name, else at the key owner’s home.
Authentication
Personal key only: the turn acts for the key’s owner, and never with more than the key’s scopes carry, so the Architect’s tools, procedures and Trust Fabric gates see the owner’s grants narrowed to the key’s scopes. An External App or a platform API key is refused with403 and personRequired: true. Requires permission workflows:write, and workflows:write and workflows:read held where the workflow is homed.
Each start or send spends one of the credential’s Architect turns: 60 an hour, with a burst of 10. Past that the route answers 429 rate_limited with a Retry-After header in seconds; a retry with the same Idempotency-Key runs normally once the delay passes.
Headers
Optional. A same-key retry within 24 hours returns the recorded answer without running again, only while the caller may still write the draft of the workflow that answer names, at that workflow’s home; otherwise
409 idempotency_result_unavailable. A replay never starts a second turn. The same key with a different body is 422. See Idempotency.Body
A factory to build the workflow in; the workflow is homed with it. A factory the owner cannot read answers 404.
on lets the Architect build missing primitives from the first turn; off (the default) does not. Every Builder the conversation starts, including each item of a batch a person confirms through their own Personal key, acts for that person under the key’s scopes.Up to 10 files to attach, each uploaded by the key’s owner with
POST /api/v2/files or in the Console.Responses
201 with data.workflowId, data.draftId and data.turn: {"state": "running"}.
The turn runs in the background. Poll listArchitectMessages no faster than every 2 seconds until turn.state is "idle" (a turn ends within 9 minutes), then read the new architect items. If the Architect proposes a plan or a synthesis batch, getArchitectPlan and getSynthesisConfirmation show it, and a person decides it through its human task.
Errors
Example
Authorizations
A Personal key (fmcp_…), bound to the person who created it, or an interactive MCP sign-in that resolves to one. Pass as Authorization: Bearer <key>. It acts for that person, under their role grants narrowed by its scopes; an operation that acts for a person admits only this kind.
Headers
Body
application/json

