Skip to main content
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 with 403 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

string
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

string
required
The workflow ID.
string
required
The message. 1 to 32,000 characters.
string[]
Up to 10 files to attach, each uploaded by the key’s owner.

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

Authorization
string
header
required

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

Idempotency-Key
string

Optional logical intent key. A same-key retry within 24 hours returns the recorded result without writing again.

Required string length: 1 - 255

Path Parameters

workflowId
string
required

The workflow id.

Minimum string length: 1

Body

application/json
text
string
required

The message to the Architect.

Required string length: 1 - 32000
fileIds
string[]

Files this credential's owner uploaded (POST /api/v2/files) to attach to the message.

Maximum array length: 10
Minimum string length: 1

Response

Send the Architect a message

data
object
required
meta
object
required