HTTP API
- Production origin:
https://api.forge.gloo.com - Primary paths:
/api/v3/... - Authentication:
Authorization: Bearer <credential> - Success:
{ data, meta } - Application error:
{ error, meta }
/api/v2. Each
generated operation page renders the v3 method and path while retaining the operation identity that
ties it to the source contract. Use v3 in new examples; use the operation page to confirm
validators, permission, credential kinds, idempotency, and responses.
Start with Conventions, Errors, and
Idempotency.
Authentication and authorization
External Apps mint short-lived tokens at/oauth/token. Personal keys act as their owner only on
operations that accept that credential kind. Roles and scoped grants establish authority; token
scopes only narrow it. Runtime policy and resource reach can still refuse an otherwise valid actor.
Read Credentials and access,
Permissions, and Credential kinds.
Pagination and bounded results
List operations return paging metadata. Continue withmeta.nextCursor while meta.hasMore is
true. Treat partial, truncated, or an omitted large field as an explicit incomplete result;
follow the documented continuation rather than assuming the first response is complete.
Contract sources
- OpenAPI v3 JSON for resource-oriented paths.
- OpenAPI v2 JSON for operation identities used by generated pages and MCP operation discovery.
- HTTP API reference for every operation, grouped by family.
- Outcomes for workflow completion evidence.
MCP
MCP provides common task tools, searchable operation discovery, resources, and prompts for AI hosts. It is not an exhaustive named-tool mirror of the HTTP API. Read MCP server or connect a host.Client choices
Read Choose an interface,
Node procedure SDK,
and Python procedure SDK.
Integration checklist
- Use a distinct actor and minimal roles/scopes.
- Persist stable idempotency keys for logical write intents.
- Handle non-JSON gateway failures and unknown write outcomes.
- Log
meta.requestIdwithout logging credentials or sensitive bodies. - Follow cursors and bounded-result metadata.
- Test
401,403,409,429, provider failure, and timeout behavior.

