Skip to Content
APIOpenAPI

OpenAPI

The gateway exposes a filtered OpenAPI document.

Endpoint

GET /openapi.json
Authorization: Bearer {api_key}

Source

OpenAPI is generated by the agent from capability.yaml. When the agent connects, gateway sends a meta request and caches the returned OpenAPI spec in memory.

{
  "id": "01J5ABCDEG...",
  "capability": "meta"
}

The agent responds with:

{
  "id": "01J5ABCDEG...",
  "result": {
    "data": {
      "openapi": "3.0.0"
    }
  }
}

Filtering

/openapi.json is filtered by API key authorization.

If an API key can call only get_customer, paths for other capabilities are removed from the returned spec. If a capability has policy.expose_in_openapi: false, it is not exposed through OpenAPI or MCP tools/list.

Gateway Metadata

Gateway adds:

  • servers using GATEWAY_PUBLIC_URL, or a fallback derived from GATEWAY_ADDR
  • components.securitySchemes.bearerAuth for Authorization: Bearer {api_key}
  • components.securitySchemes.apiKeyAuth for X-API-Key: {api_key}
  • top-level security requiring either auth scheme

The same completed document is used for /openapi.json and for the optional openapi_snapshot stdout event.

Sensitive Data

OpenAPI metadata must not include:

  • SQL text
  • DB host, user, password, or DSN
  • agent private key
  • runtime params
  • agent error detail

The spec is a public contract for allowed capability calls, not a mirror of capability.yaml.

MCPHealthz