Procedures
Send a message to the Procedure Builder
Sends the person’s message on the version’s Builder conversation and starts the next turn. Requires permission procedures:write, through a Personal key.
POST
Send a message to the Procedure Builder
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
Sends the person’s message on a version’s Builder conversation and starts the next turn. The answer is202 with turn: { state: "running" }. A published version reopens its next draft, as Console does, and the answer’s version is the draft the turn runs on. fileIds attach files the key’s owner uploaded (POST /api/v2/files), at most 10; text is at most 32,000 characters.
A message while a turn is running, queued or stopping is 409 conflict; it is never queued. 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 version that is not a workspace procedure is 409 conflict, and one that can no longer be improved is 409 invalid_state. A fileId the key’s owner did not upload (or that does not exist) is 404 resource_missing (File not found), and nothing is sent.
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 answers403 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 anIdempotency-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
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
Path Parameters
Body
application/json

