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

# HTTP API reference

> How the HTTP API reference is organized, what each operation page tells you, and which family holds the operations you need.

The HTTP API reference lists every operation you can call on Forge. Operations are grouped into
families, most families into domains, and each operation has its own page generated from the
OpenAPI document. Every path in this reference is under `/api/v3` on `https://api.forge.gloo.com`.

Before your first call, read [Conventions](https://docs.gloo.com/forge/reference/conventions.md) for the request and
response envelope, and [Authentication and permissions](https://docs.gloo.com/forge/reference/permissions) for the
credential you send.

## Reading an operation page

Each operation page shows the method and path, the request parameters and body, and every
response. Most descriptions end by naming the permission the call requires ("Requires permission
`runs:read`.") or by saying it requires none. A permission is decided where the record lives, so
holding it somewhere else can still answer `403` or `404`. A write that takes
an `Idempotency-Key` lists it with its parameters; see [Idempotency](https://docs.gloo.com/forge/reference/idempotency.md)
for when a retry is safe.

The OpenAPI document also records facts about each operation that its page does not show:

* **Which permissions it checks** (`x-forge-permissions`): the permission keys the call
  requires. An empty list means it requires none.
* **Which credentials it accepts** (`x-forge-actor-kinds`): an External App, a platform API key,
  a Personal key, or a subset of them. [Credential kinds](https://docs.gloo.com/forge/reference/credential-kinds.md) lists
  each operation's set by its `/api/v2` route and operation id.
* **Which rate-limit bucket it spends from** (`x-forge-rate-limit`): `read`, `write`, or
  `expensive`. [Rate limiting](https://docs.gloo.com/forge/reference/conventions.md#rate-limiting) lists the expensive
  operations and each bucket's size.

## Families

> [card] [Identity and access](https://docs.gloo.com/forge/reference/http-api/families/identity-and-access)
>
> The calling credential, Personal keys, External Apps and job roles.

> [card] [Workforce](https://docs.gloo.com/forge/reference/http-api/families/workforce)
>
> Org units, positions, pods, people, workers and the customer directory.

> [card] [Agents](https://docs.gloo.com/forge/reference/http-api/families/agents)
>
> Agents and their skills, tools, models and memory, plus chat sessions.

> [card] [Workflows and runs](https://docs.gloo.com/forge/reference/http-api/families/workflows-and-runs)
>
> Author and dispatch workflows, follow and control runs, read outcomes and files.

> [card] [Planning](https://docs.gloo.com/forge/reference/http-api/families/planning)
>
> Objectives and key results, roadmaps, workstreams, milestones and projects.

> [card] [Knowledge](https://docs.gloo.com/forge/reference/http-api/knowledge)
>
> Search, ask and add knowledge; curate cases; connect external sources.

> [card] [Governance](https://docs.gloo.com/forge/reference/http-api/families/governance)
>
> Approvals and human tasks, policies, grants, denial explanations and audit exports.

> [card] [Quality](https://docs.gloo.com/forge/reference/http-api/families/quality)
>
> Machine judges, rubrics and verdicts, and evaluation sets and runs.

> [card] [Integrations](https://docs.gloo.com/forge/reference/http-api/families/integrations)
>
> Credentials, connections, environments, vendors, sandboxes, webhooks and email.

> [card] [Cost and operations](https://docs.gloo.com/forge/reference/http-api/families/cost-and-operations)
>
> Budgets, spending limits, token prices, the attention board and health.

## Finding an operation

| You know | Start here |
| - | - |
| The area of Forge | Open its family above, then the domain. |
| The operation's name or path | Search the docs for it. |
| The operation id | Find it in the [OpenAPI v3 document](https://docs.gloo.com/forge/reference/openapi-v3.json) (`operationId`), which gives its path. |
| Only what you want to do, from an AI host | Ask the Forge MCP server's `forge_search_operations` tool. See [MCP server](https://docs.gloo.com/forge/reference/mcp-server.md). |
| You want the whole contract | Download the [OpenAPI v3 document](https://docs.gloo.com/forge/reference/openapi-v3.json). |

The `/api/v2` paths serve the same operations; [API versions](https://docs.gloo.com/forge/reference/conventions.md#api-versions)
explains how the two map. Use `/api/v3` in new integrations.


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