PubFi publishes an interactive reference and a machine-readable Runtime OpenAPI:

​
Runtime Authority

The Runtime OpenAPI is generated from the currently installed Registry v2 snapshot. It merges account, purchase, health, and MCP routes with current ready gateway operations. It does not use a static provider schema as a fallback. The document identifies its Registry authority with:
  • x-pubfi-registry;
  • x-pubfi-registry-generation; and
  • x-pubfi-registry-manifest.
Each generated Registry operation can also describe the exact route, provider, upstream, matcher, readiness, request policy, response policy, billing, meter, and maximum raw units. For an operation whose x-pubfi-billing.mode is quantro_priced, Runtime OpenAPI also copies the method price into these top-level extensions: Runtime OpenAPI omits these four top-level price extensions for free_health and pricing_unavailable operations. Use x-pubfi-billing to read the billing mode. If no valid snapshot is programmed, the document reports that the Registry is unavailable. It does not advertise old gateway operations in that state.

​
Catalog And OpenAPI Roles

Use these surfaces together: The operation-pricing inventory uses Cache-Control: no-store and returns 503 instead of silently omitting a plan that cannot form the complete approved projection. A Discovery page is source-selection context. It is not Registry execution authority.

​
Response Contract

A successful gateway request returns the provider’s exact bounded response bytes for the selected operation. It is not wrapped in a PubFi success envelope. Every success includes:
  • Content-Type;
  • x-pubfi-request-id.
An API-key lane success also includes x-pubfi-registry-generation. A settled x402 lane success instead includes PAYMENT-RESPONSE and Cache-Control: private, no-store. The body and media type depend on the provider response. PubFi reduces a valid Content-Type to its parameter-free media type and uses application/octet-stream when the value is missing or malformed. Inspect Runtime OpenAPI for request construction and handle the advertised provider response shapes in your client. A bounded provider HTTP 2xx, 4xx, or 5xx response keeps its provider status and exact body. These provider responses are not PubFi error envelopes. Transport failure, redirects, oversized data, and unsupported final status classes remain PubFi gateway failures.

​
Authentication And Payment Boundary

OpenAPI visibility does not make every route anonymous. Do not combine an API-key carrier with PAYMENT-SIGNATURE. X-PubFi-Api-Key is not accepted, but its presence still selects the credential lane and conflicts with payment. Purchase route visibility also does not prove that a current purchase offer exists. GET /v1/auth/context is private and no-store. Its response contains exactly principal_id, billing_account_id, and nullable actor_subject_id. Missing, invalid, OAuth, or environment-mismatched credentials return 401; the route does not use OAuth fallback.

​
Use These Docs

Use Registry Gateway Examples for request selection, success headers, and failure classes. Use Payment And Execution Modes for the boundary between API-key allowance, registered purchases, Credits, and accountless x402. The dashboard calls automatic Credit purchases Auto Top-Up. The API keeps the credit-auto-reload route name. Auto Top-Up is off until an Owner or Admin explicitly enables a complete policy with a current offer, an active payment method, exact accepted terms, and a finite UTC monthly limit. A temporary Auto Top-Up read conflict does not establish that the account’s other dashboard data or manual Credit purchase is unavailable.