Skip to main content
POST
Open a procedure in the Procedure Builder
Opens a workspace procedure for improvement, as Console’s “Improve” does. When the procedure has an in-flight draft, the conversation resumes on it and no turn starts: turn reports where it stands. Otherwise its next version is drafted from the latest active one (manifest, code and tests copied), homed where that version lives, with an orienting first turn that changes nothing: the Builder summarizes the procedure and waits for your message. The published version never changes. 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. A procedure with no active version is 409 invalid_state, and one that is not a workspace procedure (clone it first) is 409 conflict. The answer names the draft’s version.

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

Path Parameters

procedureId
string
required

The workspace procedure to improve.

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