Skip to main content

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 require procedures:read and return only what the caller may read.

Visibility

A procedure version is visible only when the caller holds procedures: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, and immutable: 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 by procedureId
  • GET /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 first
  • GET /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 without cursor.
  • The list returns one item per family rather than one per active version, and drops snapshotBuildStatus, snapshotBuildError, snapshotBuiltAt and operationContract.binding.
  • get returns the ProcedureDetail allowlist: row ids, creator, synthesis request, lifecycle actors, sandbox, image digest, repository and draft state and connection bindings are no longer returned, and usage.totalReferences is replaced by familyReferencedByCurrentWorkflow.
  • 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:read at its home), otherwise 404 resource_missing.
  • The credential’s scopes must also include workflows:read; otherwise the answer is 403 permission_denied naming it, before anything is read. Each row’s workflow must be readable at its home (workflows:read there), otherwise the row is left out; a row whose home cannot be decided is left out and the page reports meta.partial: true.
  • Drafts are never listed. version= keeps only nodes pinned to exactly that version.
  • Paged with limit (1–50, default 50) and an opaque cursor; follow meta.nextCursor while meta.hasMore is true. A page can be short or empty before the last one.
Reinstating a deprecated procedure version stays in the Console.

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 same 404 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)
Workflow lists inside these answers keep only workflows you may read (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:write at 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:write there)
  • POST /api/v3/procedure-script-promotions/{proposalId}/dismiss — dismissScriptPromotion — dismiss a script-promotion proposal (workflows:write at 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 turn
  • POST /api/v3/procedures/{procedureId}/open-in-builder — openProcedureInBuilder — resume the in-flight draft, or draft the next version with an orienting turn
  • POST /api/v3/procedures/{procedureId}/builder-messages — sendProcedureBuilderMessage — your next message and its turn
  • POST /api/v3/procedures/{procedureId}/retry-builder-turn — retryProcedureBuilderTurn — run the failed turn again
  • POST /api/v3/procedures/{procedureId}/reset-builder — resetProcedureBuilder — archive the conversation
  • POST /api/v3/procedures/{procedureId}/stop-builder-turn — stopProcedureBuilderTurn — ask the running turn to stop
  • GET /api/v3/procedures/{procedureId}/builder-messages?version= — listProcedureBuilderMessages — the conversation and the turn’s state to poll
  • POST /api/v3/procedure-script-promotions/{proposalId}/accept — acceptScriptPromotion — synthesize a skill script’s procedure (workflows:write at the platform scope)
A draft’s name and version can change while it is built: the Builder names a new draft, and a version floor correction can raise a draft’s version. Each answer names the draft’s current 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:
  1. Parse Authorization: Bearer <session-token>.
  2. Validate the JSON body.
  3. Delegate to the corresponding internalAction.
  4. Map structured error codes (AUTH_FAILED → 401, CAPABILITY_DENIED → 403, NOT_FOUND → 404, INVALID_INPUT → 400, SCHEMA_MISMATCH → 502) to HTTP statuses.
Spec: 2026-05-18-procedures-and-llm-routing.md.

Authentication

All three endpoints require Authorization: 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.