> ## 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.

# Invoke a capability

> Proxy a Convex-side capability provider call from inside a running Procedure sandbox. Authenticated by per-dispatch session token.

> [!NOTE]
>
> 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:

| Domain | Operations |
| - | - |
| `network` | `fetch` |
| `project_management` | `listProjects`, `getProject`, `listTasks`, `getTask`, `createTask`, `updateTask`, `createProject` |
| `typed_judgments` | `evaluateChoices` (see [Typed Judgements](#typed-judgements)) |
| `knowledge` | `list`, `get`, `search` (with explicit governance admission) |

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

**capabilityDomain** `string` *required*

One of the registered capability domains. See Capability Inventory.

**operation** `string` *required*

An admitted operation for the domain (e.g. `fetch` on `network`). See the table above.

**args** `object` (default: \{})

Operation arguments — passed through to the provider.

```bash curl theme={null}
curl -X POST https://forge.example.com/api/v1/proceduresApi/invokeCapability \
  -H "Authorization: Bearer $FORGE_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "capabilityDomain": "network",
    "operation": "fetch",
    "args": { "url": "https://api.example.com/status", "method": "GET" }
  }'
```

```python Python theme={null}
import os, requests

resp = requests.post(
    f"{os.environ['FORGE_BASE_URL']}/api/v1/proceduresApi/invokeCapability",
    headers={"Authorization": f"Bearer {os.environ['FORGE_SESSION_TOKEN']}"},
    json={
        "capabilityDomain": "network",
        "operation": "fetch",
        "args": {"url": "https://api.example.com/status", "method": "GET"},
    },
)
resp.raise_for_status()
print(resp.json())
```

```typescript TypeScript theme={null}
const resp = await fetch(`${process.env.FORGE_BASE_URL}/api/v1/proceduresApi/invokeCapability`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.FORGE_SESSION_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    capabilityDomain: "network",
    operation: "fetch",
    args: { url: "https://api.example.com/status", method: "GET" },
  }),
});
if (!resp.ok) throw new Error(await resp.text());
const { data, providerId } = await resp.json();
```

```json Body theme={null}
{
  "capabilityDomain": "network",
  "operation": "fetch",
  "args": { "url": "https://api.example.com/status", "method": "GET" }
}
```

## Responses

**data** `object`

The provider's return value for the requested operation. Shape depends on the capability + operation.

**providerId** `string`

The resolved provider key (e.g. `forge` for the built-in network provider). Lets callers correlate failures with the active provider.

> [accordion] 400 — INVALID\_INPUT
>
> Body malformed or missing a required field. Validate the JSON against the request schema before retrying.

> [accordion] 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.

> [accordion] 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.

> [accordion] 404 — NOT\_FOUND
>
> Capability domain or operation is not registered. Check the Capability Inventory for the live domain list.

> [accordion] 500 — INTERNAL\_ERROR
>
> Provider raised an unhandled exception. Details are in the response `message`; correlate with the audit row via `runId` / `stepId`.

```json 200 theme={null}
{
  "data": { "status": 200, "statusText": "OK", "headers": {}, "body": { "ok": true } },
  "providerId": "forge"
}
```

## 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.

## Related

* [Procedures domain index](https://docs.gloo.com/forge/reference/http-api/procedures)
* Capability architecture


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