Skip to main content
POST
Start a procedure with the Procedure Builder
Creates a new workspace procedure draft, as Console’s “New procedure” does, and starts the Procedure Builder’s first turn. The draft is version 1.0.0 of a new family with a placeholder name the Builder replaces as the conversation proceeds. The answer is 201 with the draft’s procedureId and version and turn: { state: "running" }.

Where the draft lives

The draft is homed at owningOrgUnitId, where the key’s owner must hold procedures:write (403 naming it otherwise). A Personal key must name one (400 bad_request otherwise).

Who may start a turn

Only a Personal key starts a Procedure Builder turn. The turn acts for the key’s owner and never with more than the key’s scopes carry: its tools and Trust Fabric gates see the owner’s grants narrowed to the key’s scopes, and so does every continuation the platform schedules for it (an output-limit retry, the follow-up after an off-turn validation, the resume after a held tool call is approved). An External App or a platform key answers 403 with personRequired: true. Each started turn spends one of the credential’s Procedure Builder turns: 60 an hour with a burst of 10. Past that the answer is 429 rate_limited with a Retry-After header in seconds, and nothing is written; a refused call spends none. The turn runs in the background. Poll listBuilderMessages no faster than every 2 seconds until turn.state is "idle", then read the new builder items. Validation runs off the turn; read it with getLatestValidationRun.

Idempotency

With an Idempotency-Key, a same-key repeat within 24 hours returns the recorded answer, without starting another turn, only while you still hold procedures:write at the draft’s home; otherwise 409 idempotency_result_unavailable.

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 starting another turn.

Required string length: 1 - 255

Body

application/json
owningOrgUnitId
string

The org unit the new draft is homed at, where the key's owner holds procedures:write. Required for a Personal key.

Minimum string length: 1

Response

Success

data
object
required

The version the Builder conversation works on and its turn. A started turn is running; reopening an in-flight draft starts none and reports the turn as it stands.

meta
object
required