Skip to main content
Use this section after choosing an interface. For exact HTTP request and response fields, the generated operation pages and OpenAPI documents are authoritative.

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 v3 is a resource-oriented mapping onto the same operations served under /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 with meta.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

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.requestId without logging credentials or sensitive bodies.
  • Follow cursors and bounded-result metadata.
  • Test 401, 403, 409, 429, provider failure, and timeout behavior.