Skip to main content
POST
Retry the Procedure Builder's failed turn
Runs the turn that just failed again on the version’s Builder conversation, writing no message: your message is already in the conversation. The answer is 202 with turn: { state: "running" }. With nothing to retry the answer is 409 conflict naming why: no conversation reached the Builder (send the message again), the conversation has no message to answer, it is not bound to a procedure, or a turn is running. You need procedures:write at the version’s home (a version with no home: the platform scope); a version out of reach is the same 404 resource_missing as a missing one.

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 version’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

Path Parameters

procedureId
string
required

The procedure family's id (its slug).

Minimum string length: 1

Body

application/json
version
string
required

The semver version.

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