Skip to main content
This is a procedure-sandbox session endpoint, not a Forge Platform API v3 operation. The Procedure SDK calls this /api/v1/proceduresApi/* protocol with the invocation’s session token.
POST /api/v1/proceduresApi/invokeCapability The sandbox-facing entry point for capability calls. The procedure names a capability domain and an operation; Forge resolves the active provider, runs the operation server-side, and returns the result. A session reaches only admitted operations: Files go through the getFile and putFile routes. Every other domain and operation, including secrets_store, inference and source_control, returns 403 CAPABILITY_DENIED: a procedure never reads a secret or a platform credential through this route.

Authentication

Bearer session token in Authorization. The token is minted at dispatch time and encodes which capabilities the procedure may call. A token without permission for the requested capabilityDomain, or a call to an operation that is not admitted, returns 403 CAPABILITY_DENIED.

Request body

string
required
One of the registered capability domains. See Capability Inventory.
string
required
An admitted operation for the domain (e.g. fetch on network). See the table above.
object
default:"{}"
Operation arguments — passed through to the provider.

Responses

object
The provider’s return value for the requested operation. Shape depends on the capability + operation.
string
The resolved provider key (e.g. forge for the built-in network provider). Lets callers correlate failures with the active provider.
Body malformed or missing a required field. Validate the JSON against the request schema before retrying.
Missing or invalid bearer token. Procedure sandboxes receive the session token in their environment; if it’s missing the dispatch was misconfigured.
The token is valid but lacks permission for the requested capability, or the operation is not admitted for procedure sessions (the message names the domain and operation). The token’s capability set is fixed at dispatch — re-dispatch the procedure with a permitting binding. An operation outside the admitted list cannot be granted per procedure. The body’s decisionId names the Trust Fabric decision that recorded the refusal.
Capability domain or operation is not registered. Check the Capability Inventory for the live domain list.
Provider raised an unhandled exception. Details are in the response message; correlate with the audit row via runId / stepId.

Typed Judgements

The typed_judgments domain exposes evaluateChoices: it evaluates a bounded set of supplied choices and returns typed selections and probabilities. TypeSafe Jev is its external provider; this operation does not generate a textual answer or replace a chat model. Before calling it, configure the TypeSafe typed-judgments Connection with a raw API key Credential at the intended company org-unit scope. Enable the TypeSafe provider, make it the active provider for this domain, and bind that same provider to the org unit. A missing, disabled, or divergent binding refuses the call. The published Procedure must declare the Connection and external delivery, require procedures:use, and receive an explicit typed_judgments capability allowlist at dispatch. Forge checks the signed grant against the persisted Procedure version, execution subject and complete Connection scope before reading the provider secret. Do not put the vendor key, a provider URL, or a company scope in the operation arguments. Each request contains a serialized state string and at most 16 questions. Each question has a unique ID, instructions and 2–255 options with unique IDs and descriptions. Consumers must handle provider failures, ties and insufficient confidence explicitly. Forge makes no automatic transport retry for this provider.

Usage attribution and audit evidence

Reported provider usage is attributed to the actual Procedure ID and version. Procedure events may have no agentId; Forge does not invent an agent for them. These events contribute to global, provider and workflow usage totals, while agent breakdowns and agent budgets include only events attributed to an agent. Existing agent events remain readable without the new optional attribution fields. If the provider omits usage, it stays unreported. If usage recording fails after a provider response, the call reports that failure and records response audit evidence without retrying the provider. Audit evidence contains request, candidate and response digests plus question/version and provider/model identifiers, rather than raw ticket state or credentials.