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

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 brief: what the workflow should do. 1 to 32,000 characters.
string
A factory to build the workflow in; the workflow is homed with it. A factory the owner cannot read answers 404.
string
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.
string[]
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

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

Body

application/json
initialText
string
required

The brief: what the workflow should do.

Required string length: 1 - 32000
factoryId
string

A factory to build the workflow in; the workflow is homed with it.

Minimum string length: 1
jitMode
enum<string>

on lets the Architect build missing primitives; every Builder it starts acts for the key's owner under the key's scopes.

Available options:
off,
on
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

Start a Workflow Architect conversation

data
object
required
meta
object
required