> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gloo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Procedures

> Read and administer the procedure catalog (references, callers, bindings, delete, deprecate, rename) and the sandbox endpoints a running procedure calls back through.

## 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](https://docs.gloo.com/forge/reference/http-api/procedures/list.md) — page procedure families by `procedureId`
* `GET /api/v3/procedures/{procedureId}?version=` — [getProcedure](https://docs.gloo.com/forge/reference/http-api/procedures/get.md) — one version's detail (default: the highest visible active version)
* `GET /api/v3/procedures/{procedureId}/versions` — [listProcedureVersions](https://docs.gloo.com/forge/reference/http-api/procedures/listVersions.md) — every visible version, highest first
* `GET /api/v3/procedures/{procedureId}/source?version=` — [getProcedureSource](https://docs.gloo.com/forge/reference/http-api/procedures/getSource.md) — one version's bundled source (separate, sensitive permission; see below)
* `GET /api/v3/procedures/{procedureId}/consumers` — [listProcedureConsumers](https://docs.gloo.com/forge/reference/http-api/procedures/listConsumers.md) — the published workflow versions that pin the family (see [Procedure consumers](#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](#procedure-administration) and [Procedure lifecycle](#procedure-lifecycle)). Re-judging one is [Re-judge procedure](https://docs.gloo.com/forge/reference/http-api/judges/rejudgeProcedure.md) 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](https://docs.gloo.com/forge/reference/http-api/procedures/listReferences.md) — the workflows referencing the family, before you delete or deprecate it (`procedures:manage`)
* `GET /api/v3/procedures/{procedureId}/version-callers?version=` — [listProcedureVersionCallers](https://docs.gloo.com/forge/reference/http-api/procedures/listVersionCallers.md) — the published workflows pinning one version (`procedures:write`)
* `GET /api/v3/procedures/{procedureId}/similar-procedures?version=` — [findSimilarProcedures](https://docs.gloo.com/forge/reference/http-api/procedures/findSimilar.md) — other procedures with the same signature (`procedures:read`)
* `GET /api/v3/procedures/{procedureId}/connection-binding?version=` — [getProcedureConnectionBinding](https://docs.gloo.com/forge/reference/http-api/procedures/getConnectionBinding.md) — whether each connection binding resolves a Credential (`procedures:manage`)
* `POST /api/v3/procedures/delete-versions` — [deleteProcedures](https://docs.gloo.com/forge/reference/http-api/procedures/delete.md) — hard-delete up to 200 versions, each decided on its own (`procedures:manage`)
* `POST /api/v3/procedures/{procedureId}/deprecate` — [deprecateProcedure](https://docs.gloo.com/forge/reference/http-api/procedures/deprecate.md) — deprecate an active version (`procedures:manage`)
* `POST /api/v3/procedures/{procedureId}/rename` — [renameProcedure](https://docs.gloo.com/forge/reference/http-api/procedures/rename.md) — change a family's display name (`procedures:manage`)
* `POST /api/v3/procedures/{procedureId}/set-connections` — [setProcedureConnections](https://docs.gloo.com/forge/reference/http-api/procedures/setConnections.md) — 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](https://docs.gloo.com/forge/reference/http-api/procedures/getLatestValidationRun.md) — the version's latest validation run (`procedures:write`)
* `POST /api/v3/procedure-validation-runs/{validationRunId}/cancel` — [cancelProcedureValidationRun](https://docs.gloo.com/forge/reference/http-api/procedures/cancelValidationRun.md) — cancel a running run (`procedures:write` at its procedure's home)
* `POST /api/v3/procedures/{procedureId}/clone` — [cloneProcedure](https://docs.gloo.com/forge/reference/http-api/procedures/clone.md) — 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](https://docs.gloo.com/forge/reference/http-api/procedures/dismissScriptPromotion.md) — dismiss a script-promotion proposal (`workflows:write` at the platform scope)
* `POST /api/v3/procedures/{procedureId}/promote` — [promoteProcedure](https://docs.gloo.com/forge/reference/http-api/procedures/promote.md) — provisional to approved (`procedures:approve`)
* `POST /api/v3/procedures/{procedureId}/request-review` — [requestProcedureReview](https://docs.gloo.com/forge/reference/http-api/procedures/requestReview.md) — open a repository pull request for review (`procedures:approve`; an effect outside Forge)
* `POST /api/v3/procedures/{procedureId}/resolve-review-hold` — [resolveProcedureReviewHold](https://docs.gloo.com/forge/reference/http-api/procedures/resolveReviewHold.md) — 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](https://docs.gloo.com/forge/reference/http-api/procedures/startBuilder.md) — a new workspace draft homed at a unit you name, and its first turn
* `POST /api/v3/procedures/{procedureId}/open-in-builder` — [openProcedureInBuilder](https://docs.gloo.com/forge/reference/http-api/procedures/openInBuilder.md) — resume the in-flight draft, or draft the next version with an orienting turn
* `POST /api/v3/procedures/{procedureId}/builder-messages` — [sendProcedureBuilderMessage](https://docs.gloo.com/forge/reference/http-api/procedures/sendBuilderMessage.md) — your next message and its turn
* `POST /api/v3/procedures/{procedureId}/retry-builder-turn` — [retryProcedureBuilderTurn](https://docs.gloo.com/forge/reference/http-api/procedures/retryBuilderTurn.md) — run the failed turn again
* `POST /api/v3/procedures/{procedureId}/reset-builder` — [resetProcedureBuilder](https://docs.gloo.com/forge/reference/http-api/procedures/resetBuilder.md) — archive the conversation
* `POST /api/v3/procedures/{procedureId}/stop-builder-turn` — [stopProcedureBuilderTurn](https://docs.gloo.com/forge/reference/http-api/procedures/stopBuilderTurn.md) — ask the running turn to stop
* `GET /api/v3/procedures/{procedureId}/builder-messages?version=` — [listProcedureBuilderMessages](https://docs.gloo.com/forge/reference/http-api/procedures/listBuilderMessages.md) — the conversation and the turn's state to poll
* `POST /api/v3/procedure-script-promotions/{proposalId}/accept` — [acceptScriptPromotion](https://docs.gloo.com/forge/reference/http-api/procedures/acceptScriptPromotion.md) — 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

| Path | Method | Purpose |
| - | - | - |
| `POST /api/v1/proceduresApi/invokeCapability` | POST | Invoke a Convex-side capability provider from inside the sandbox. |
| `POST /api/v1/proceduresApi/putFile` | POST | Persist file bytes produced inside the sandbox via the unified files/bindings model. |
| `POST /api/v1/proceduresApi/getFile` | POST | Read a file the dispatch has access to, either as content bytes or metadata. |

## 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](https://docs.gloo.com/forge/reference/errors.md#procedure-sandbox-api-errors)).

`invokeCapability` body:

```json theme={null}
{
  "capabilityDomain": "linear",
  "operation": "createIssue",
  "args": { "title": "...", "teamId": "..." }
}
```

`putFile` and `getFile` mirror the agent-tool surfaces documented in [Files and Bindings](https://docs.gloo.com/forge/architecture/files-and-bindings.md) — 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.

> [!NOTE]
>
> 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](https://docs.gloo.com/forge/architecture/files-and-bindings.md) — agent-side surface; identical schemas
* [Authoring a Procedure](https://docs.gloo.com/forge/build/author-a-procedure.md)
* Procedure SDKs (Node + Python) — shipping in the next docs cut


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.