Skip to Content
APIOpenAPI

OpenAPI

GET /openapi.json returns an OpenAPI 3.1 document for the capabilities the API key may call. Use it to generate clients, to explore the API in Swagger UI, or to review exactly what a key exposes.

curl -s -H "Authorization: Bearer $ONPREST_API_KEY" https://gateway.example.com/openapi.json

What it contains

The agent generates the document from capability.yaml and the gateway caches it when the agent connects. For each capability it describes the request body (JSON, plus multipart when the capability takes files), the success envelope with the declared output schema, and the error envelope. A capability with delivery.rest: direct is described as returning a binary file.

The gateway adds:

  • servers, from GATEWAY_PUBLIC_URL (or derived from GATEWAY_ADDR)
  • the bearerAuth and apiKeyAuth security schemes
  • x-onprest-annotations and x-onprest-examples on operations that set annotations or examples

The document is a public contract, not a copy of the configuration: SQL, source settings, credentials, and paths never appear in it.

Filtering

Each API key sees only the capabilities it may call. A capability with policy.expose_in_openapi: false is left out of OpenAPI and the MCP tool list for every key, but a key that is allowed to call it still can.

Until the agent is connected and its contract is loaded, /openapi.json returns AGENT_OFFLINE. Capability calls return the same, or DEPENDENCY_UNAVAILABLE when the contract was refused because ONPREST_PUBLIC_BASE_URL is missing; see File reference origin.

MCPHealthz