Procedure catalog
Three v2 reads let an integration browse the procedures it may use: page procedure families, read one version, and list a family’s versions. All three requireprocedures:read and return only what the caller may read.
Visibility
A procedure version is visible only when the caller holdsprocedures:read at the version’s home org unit (a version with no home: at the platform scope). Procedures are homed at the deployment root, so keys and External Apps with platform-scope or root grants see the whole catalog, and a credential whose grants are scoped only to org units below the root sees none of it — the same catalog a Console person scoped to a unit sees. A family’s versions are filtered first and the head is chosen among the visible ones. A missing procedure and one you may not read are the same 404 resource_missing. These three reads never return source code or bundled files; source has its own read below. After a rename, every procedure route answers to the earlier procedureId and the new one; the reference, caller and consumer lists include the workflows that pinned the family under either name.
Resource shape
Procedure(list): one family, described by its highest-semver active visible version —procedureId,version,name,description,status,runtime,sourceType,capabilities,deterministic,idempotent,inputs,outputs,operationContract?(operationId,version),maturity,exposedAs.ProcedureDetail(get): one version’s contract,lifecycleHistory(without who acted),usage(totalDispatches,versionDispatches,lastDispatchedAt, folded over the visible versions),retirement.blockers,familyReferencedByCurrentWorkflow, andimmutable: true— a minted version never changes.ProcedureVersion(listVersions):version,status,synthesisTier,isLatestActive,updatedAt,versionDispatches,lastDispatchedAt.
retirement.blockers lists why the version cannot be hard-deleted safely, in this order: builtin, active, approved, non_provisional_tier, recorded_usage; an empty list means none apply. familyReferencedByCurrentWorkflow is true when a live draft or active published version of some workflow uses any version of the family, false when none does, and null when the bounded check could not decide. It never names the workflows.
Operations
GET /api/v3/procedures— listProcedures — page procedure families byprocedureIdGET /api/v3/procedures/{procedureId}?version=— getProcedure — one version’s detail (default: the highest visible active version)GET /api/v3/procedures/{procedureId}/versions— listProcedureVersions — every visible version, highest firstGET /api/v3/procedures/{procedureId}/source?version=— getProcedureSource — one version’s bundled source (separate, sensitive permission; see below)GET /api/v3/procedures/{procedureId}/consumers— listProcedureConsumers — the published workflow versions that pin the family (see Procedure consumers)
limit (default 50, at most 100; a larger value is 400 too_big) and cursor page the list. The optional search, source, runtime, vendor and agentTool filters are the Console catalog’s; they apply to each family’s head before paging. meta.nextCursor is an opaque family cursor: a family added or retired during a walk never repeats or skips a family already returned. Follow it while meta.hasMore is true. A cursor the server did not issue is 400 bad_request.
Changes from earlier releases
- The list cursor was a numeric offset; it is now an opaque family cursor, and a numeric cursor is
400. Restart a walk withoutcursor. - The list returns one item per family rather than one per active version, and drops
snapshotBuildStatus,snapshotBuildError,snapshotBuiltAtandoperationContract.binding. getreturns theProcedureDetailallowlist: row ids, creator, synthesis request, lifecycle actors, sandbox, image digest, repository and draft state and connection bindings are no longer returned, andusage.totalReferencesis replaced byfamilyReferencedByCurrentWorkflow.- A credential whose grants are scoped only to org units below the deployment root no longer sees root-homed procedures.
Procedure source
GET /api/v3/procedures/{procedureId}/source returns one version’s bundled files exactly as stored, with UTF-8 byte counts, as ProcedureSource (procedureId, version, entrypoint, files[] of path, content, bytes). It is not covered by procedures:read: the credential’s scopes must reach procedures:write, and its grants must hold procedures:write at the version’s home org unit — the permission that lets a person author procedures. The built-in apps never receive it. The version is chosen among the versions whose source you may read, as get chooses among visible versions. Source is not scanned for secrets. More than 900 KiB of source is 413 payload_too_large.
Authoring a procedure with the Procedure Builder is not yet an HTTP route or MCP tool; administration and the lifecycle are (see Procedure administration and Procedure lifecycle). Re-judging one is Re-judge procedure in the judges family. A machine sees a version’s lifecycle state through GET /api/v3/procedures/{procedureId}.
The Forge MCP server’s find job lists two of the catalog reads, forge_list_procedures and forge_get_procedure. It reaches versions, source and consumers in its workflows tool group through forge_call_operation with operationId listProcedureVersions, getProcedureSource and listProcedureConsumers.
Procedure consumers
GET /api/v3/procedures/{procedureId}/consumers answers “what runs this procedure” before you change it. Each PrimitiveConsumer row is one node of a published workflow version: workflowId, workflowVersionId, workflowVersion, versionStatus (active or superseded), the node’s logicalNodeId, and pinnedVersion, the exact version the node runs (null for a node published before pinning). Published workflow versions keep their pins: a new procedure version never changes what they run.
- The family must have a version you may read (
procedures:readat its home), otherwise404 resource_missing. - The credential’s scopes must also include
workflows:read; otherwise the answer is403 permission_deniednaming it, before anything is read. Each row’s workflow must be readable at its home (workflows:readthere), otherwise the row is left out; a row whose home cannot be decided is left out and the page reportsmeta.partial: true. - Drafts are never listed.
version=keeps only nodes pinned to exactly that version. - Paged with
limit(1–50, default 50) and an opaquecursor; followmeta.nextCursorwhilemeta.hasMoreistrue. A page can be short or empty before the last one.
Procedure administration
Console’s operator actions on a procedure, decided at each version’s home org unit (a version with no home: the platform scope). A version out of reach is the same404 resource_missing as a missing one.
GET /api/v3/procedures/{procedureId}/references— listProcedureReferences — the workflows referencing the family, before you delete or deprecate it (procedures:manage)GET /api/v3/procedures/{procedureId}/version-callers?version=— listProcedureVersionCallers — the published workflows pinning one version (procedures:write)GET /api/v3/procedures/{procedureId}/similar-procedures?version=— findSimilarProcedures — other procedures with the same signature (procedures:read)GET /api/v3/procedures/{procedureId}/connection-binding?version=— getProcedureConnectionBinding — whether each connection binding resolves a Credential (procedures:manage)POST /api/v3/procedures/delete-versions— deleteProcedures — hard-delete up to 200 versions, each decided on its own (procedures:manage)POST /api/v3/procedures/{procedureId}/deprecate— deprecateProcedure — deprecate an active version (procedures:manage)POST /api/v3/procedures/{procedureId}/rename— renameProcedure — change a family’s display name (procedures:manage)POST /api/v3/procedures/{procedureId}/set-connections— setProcedureConnections — replace a version’s connection bindings (procedures:manage)
workflows:read at the workflow’s home). Writes take an optional Idempotency-Key; a repeat returns the recorded result only while you still manage every version it names. A Personal key acts as its owner, narrowed by its scopes; an External App or platform API key acts as itself, and audits name it and who granted it. Over MCP, the find job lists forge_find_similar_procedures; the rest are reached through forge_call_operation with operationId listProcedureReferences, listProcedureVersionCallers, getProcedureConnectionBinding, deleteProcedures, deprecateProcedure, renameProcedure and setProcedureConnections.
Procedure lifecycle
Validation, cloning, promotion, repository review and review holds, as Console runs them, each decided where its record lives:GET /api/v3/procedures/{procedureId}/latest-validation-run?version=— getProcedureLatestValidationRun — the version’s latest validation run (procedures:write)POST /api/v3/procedure-validation-runs/{validationRunId}/cancel— cancelProcedureValidationRun — cancel a running run (procedures:writeat its procedure’s home)POST /api/v3/procedures/{procedureId}/clone— cloneProcedure — a workspace copy of a built-in or marketplace procedure, homed at a unit you name or an External App’s own (procedures:writethere)POST /api/v3/procedure-script-promotions/{proposalId}/dismiss— dismissScriptPromotion — dismiss a script-promotion proposal (workflows:writeat the platform scope)POST /api/v3/procedures/{procedureId}/promote— promoteProcedure — provisional to approved (procedures:approve)POST /api/v3/procedures/{procedureId}/request-review— requestProcedureReview — open a repository pull request for review (procedures:approve; an effect outside Forge)POST /api/v3/procedures/{procedureId}/resolve-review-hold— resolveProcedureReviewHold — approve or send back a held Builder draft (approvals:approve)
procedures:approve and approvals:approve are approve permissions: a Personal key carries them only when its owner opts in, an External App only by an explicit grant, and a Forge agent never. Over MCP, these are reached through forge_call_operation with operationId getProcedureLatestValidationRun, cancelProcedureValidationRun, cloneProcedure, dismissScriptPromotion, promoteProcedure, requestProcedureReview and resolveProcedureReviewHold.
Authoring with the Procedure Builder
The Procedure Builder conversation, as Console runs it, decided at the version’s home (procedures:write):
POST /api/v3/procedures/start-builder— startProcedureBuilder — a new workspace draft homed at a unit you name, and its first turnPOST /api/v3/procedures/{procedureId}/open-in-builder— openProcedureInBuilder — resume the in-flight draft, or draft the next version with an orienting turnPOST /api/v3/procedures/{procedureId}/builder-messages— sendProcedureBuilderMessage — your next message and its turnPOST /api/v3/procedures/{procedureId}/retry-builder-turn— retryProcedureBuilderTurn — run the failed turn againPOST /api/v3/procedures/{procedureId}/reset-builder— resetProcedureBuilder — archive the conversationPOST /api/v3/procedures/{procedureId}/stop-builder-turn— stopProcedureBuilderTurn — ask the running turn to stopGET /api/v3/procedures/{procedureId}/builder-messages?version=— listProcedureBuilderMessages — the conversation and the turn’s state to pollPOST /api/v3/procedure-script-promotions/{proposalId}/accept— acceptScriptPromotion — synthesize a skill script’s procedure (workflows:writeat the platform scope)
procedureId and version; use those. An earlier name keeps working, and so does a version the draft was corrected past.
Only a Personal key starts a turn: it acts for the key’s owner, never with more than the key’s scopes carry, and spends one of the key’s Procedure Builder turns (60 an hour, burst 10; 429 rate_limited past that). A message while a turn is running is refused, not queued. Reset, stop and the transcript serve every credential kind. Over MCP, these are reached through forge_call_operation with operationId startProcedureBuilder, openProcedureInBuilder, sendProcedureBuilderMessage, retryProcedureBuilderTurn, resetProcedureBuilder, stopProcedureBuilderTurn, listProcedureBuilderMessages and acceptScriptPromotion.
Authoring and source over the API
procedures:write is the procedure author permission, and it is also what reads source: people who may author a procedure may read it. There is no source-only permission. The scope name procedures:read:source is retired; credentials that carried it were rewritten to procedures:write and may do everything that key allows, including each authoring route as it ships. Grant procedures:write only to credentials that may author. procedures:manage (retire, delete, rename, rebind) and procedures:approve (promote) are separate keys.
Sandbox shims
Procedures execute inside isolated Vercel Sandbox VMs. They reach the platform — to call a Convex-side capability provider or to persist / read a file — through three HTTP shims under/api/v1/proceduresApi/*. The shims are deliberately separate from the v2 management surface because procedure sandboxes authenticate via a per-dispatch session token, not an External App credential.
The shape and contract are stable; the platform’s internal actions hold all the business logic. The HTTP shims are thin transport layers that:
- Parse
Authorization: Bearer <session-token>. - Validate the JSON body.
- Delegate to the corresponding internalAction.
- Map structured error codes (
AUTH_FAILED→ 401,CAPABILITY_DENIED→ 403,NOT_FOUND→ 404,INVALID_INPUT→ 400,SCHEMA_MISMATCH→ 502) to HTTP statuses.
2026-05-18-procedures-and-llm-routing.md.
Authentication
All three endpoints requireAuthorization: Bearer <session-token>. The session token is minted at procedure dispatch time by the orchestrator and embedded in the sandbox’s environment — procedures never construct it themselves. The token encodes the run, step, dispatch, and the set of capabilities + bindings the procedure is permitted to use.
Operations
Wire shape
All three endpoints return JSON. Success responses use a{ data, ... } envelope; failures use { error, message }, with code, docUrl and meta.requestId beside them. A body field the route refuses adds details, one { path, message, code } entry for that field (Procedure sandbox API errors).
invokeCapability body:
putFile and getFile mirror the agent-tool surfaces documented in Files and Bindings — same discriminated source × bind (for putFile) and mode: "text" | "sandbox" | "meta" (for getFile). The HTTP wire shape is the JSON serialization of the same input schemas.
The sandbox shims are not in the v2 OpenAPI spec — they target sandbox procedures, not operators or integrators. They are not surfaced through the TypeScript SDK or MCP Server. The Procedure SDKs (
@tangogroup/procedure-sdk-node and procedure-sdk-python) wrap these endpoints idiomatically; procedure authors should reach for the SDK rather than calling the shims directly.Related
- Files and Bindings — agent-side surface; identical schemas
- Authoring a Procedure
- Procedure SDKs (Node + Python) — shipping in the next docs cut

