Workflows
Send the Workflow Architect a message
Send the Workflow Architect the next message on a workflow’s draft and start its turn, acting for a Personal key’s owner.
POST
Send the Architect a message
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/sendArchitectMessage
The API twin of the Architect drawer’s composer. It saves your message on the draft’s Architect conversation (opening one when the draft has none) and starts the next turn.
The API never queues a message. While a turn is running, queued or stopping, the route answers 409 before any write and before a turn is spent; wait for turn.state to be "idle" in listArchitectMessages and send again with a new Idempotency-Key: the refusal is recorded under the key it was sent with, so repeating that key answers 409 idempotency_result_unavailable.
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 at the workflow’s home org unit.
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
Responses
202 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

