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 inAuthorization. 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
Responses
The provider’s return value for the requested operation. Shape depends on the capability + operation.
The resolved provider key (e.g.
forge for the built-in network provider). Lets callers correlate failures with the active provider.400 — INVALID_INPUT
400 — INVALID_INPUT
Body malformed or missing a required field. Validate the JSON against the request schema before retrying.
401 — AUTH_FAILED
401 — AUTH_FAILED
Missing or invalid bearer token. Procedure sandboxes receive the session token in their environment; if it’s missing the dispatch was misconfigured.
403 — CAPABILITY_DENIED
403 — CAPABILITY_DENIED
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.404 — NOT_FOUND
404 — NOT_FOUND
Capability domain or operation is not registered. Check the Capability Inventory for the live domain list.
500 — INTERNAL_ERROR
500 — INTERNAL_ERROR
Provider raised an unhandled exception. Details are in the response
message; correlate with the audit row via runId / stepId.Typed Judgements
Thetyped_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 noagentId; 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.
Related
- Procedures domain index
- Capability architecture

