This page lists the current public runtime endpoint families. It does not list internal webhook, operator, repair, or control-plane routes.

​
Environment Roots

Use one row for a complete test. Do not mix a staging key or session with a Production root. See the Staging guide for the complete test flow.

​
API Host

The corresponding Staging API root is https://api-stg.pubfi.ai. Fetch that environment’s /v1/capabilities and /openapi.json before you select a route.

​
Public Service And Registry Routes

GET /v1/capabilities is the catalog endpoint. It includes the exact Registry generation, manifest, compact capability summaries, and current ready or blocked state. Follow each opaque next_cursor for the complete generation. Use Runtime OpenAPI for ready operation request and response schemas. GET /v1/operation-pricing-inventory exposes canonical operation keys, route revisions and closures, request bounds, and merchant_priced classification for every approved typed plan. It contains no selected price and has no route-selection or execution authority. The compatibility response is quantro.operation-pricing-inventory.v2. When x402 V2 intake is on, the route returns quantro.operation-pricing-inventory.v3 with x402_contract_version: "quantro.x402.v2"; that value participates in the v3 entry-set hash. Clients must inspect schema_version. The route returns 503 if the complete projection cannot be formed; it does not return a partial inventory. The Runtime OpenAPI includes only current ready Registry operations. If the API has no valid programmed snapshot, it marks the Registry as unavailable and does not use a static provider fallback. The status reads use Cache-Control: no-store and the states operational, degraded, major_outage, or unknown. Missing, stale, or incoherent evidence is unknown; it is not treated as healthy. Status is public-safe evidence about current PubFi components, Gateway probe coverage, providers, and active operations. It does not replace the Registry catalog as route authority or prove that a purchase offer or x402 challenge is available. Status counts logical API operations separately from source operations and Registry route variants. One logical API operation can have more than one source operation or route variant. In Gateway summaries, active_operations counts logical API operations and active_route_variants counts route variants. operation_coverage reports api_operations, source_operations, and route_variants, separates offered from not_offered, and classifies monitoring as continuous, manual, not_applicable, or unreviewed. Provider summaries use the same logical API grouping. The Gateway response includes provider summaries and sentinel observations. Provider summaries separate reachability_status from operation_family_status and expose nullable health_status. Their evidence_status is current, missing_or_stale, stale, or unverified. Missing or stale observations do not prove healthy service. A known failure remains visible when other observations are missing. Daily request metrics can remain present after the latest health observation becomes stale; they are not proof of current health. The Gateway response can include incidents in suspect, open, recovering, or resolved state. Incident ownership and stage keep a provider failure separate from a PubFi Registry, credential, or gateway failure. Provider and operation detail endpoints are no longer part of the public Status API; use /v1/status/gateway for provider summaries. Gateway summaries expose operation_pricing_status separately from provider and PubFi proxy evidence. A known pricing outage is major_outage because paid execution is blocked, but it does not replace independent provider or proxy signals. Missing pricing evidence remains unknown. Read health_history.window_days, segment_duration_seconds, and each segment’s started_at and ended_at from the selected environment’s response. Do not assume a fixed history window or segment length: these can differ between deployed versions. Active history fields report active_expected_targets, active_passed_targets, active_failed_targets, active_unknown_targets, and active_check_percentage. Keep active-target coverage separate from passive request metrics when those metrics are present. Request totals do not prove current health. These counts are operational evidence, not uptime percentages or route authority.

​
Gateway Route

The installed Registry matcher defines the complete path and method. There is no fixed provider-and-network URL convention. Clients must copy an exact current operation from /v1/capabilities or /openapi.json. Only GET and POST can execute. HEAD returns 405 Method Not Allowed. The gateway has two separate caller lanes: Do not send Authorization or X-PubFi-Api-Key with PAYMENT-SIGNATURE. The legacy header is not accepted, but its presence still selects the credential lane. Relayed upstream health operations follow normal pricing and authentication. PubFi’s own service health endpoints remain public and free. A quantro_priced operation uses the method-specific positive credit_cost for API-key execution and the independent x402 terms from the same immutable price version. An eligible exact GET or POST operation can also advertise an account-level free variant. The capability catalog exposes its effective free_rate_limit, and Runtime OpenAPI exposes x-pubfi-free-variant with the :free suffix and the same policy. Append :free to the final path segment, keep the provider query intended for the operation, keep the body required by its body policy, and send the normal Authorization: Bearer <PubFi API key> header. This variant charges zero Credits and does not use x402. A retryable limit rejection returns 429, gateway.free_rate_limited, and Retry-After. A cumulative limit returns 429 with gateway.free_limit_reached and no Retry-After. Do not append the suffix unless the current catalog or OpenAPI operation advertises it. Direct-HTTP response delivery is automatic on the normal authenticated paid or :free route. The catalog and Runtime OpenAPI do not publish a stream-policy field or a caller-selected :stream suffix. The runtime applies the platform response ceiling, deadlines, and heavy-transfer concurrency limits without changing the selected gateway path.

​
Account And Purchase Routes

The auth-context response contains exactly principal_id, billing_account_id, and nullable actor_subject_id. It accepts only a valid PubFi API key, rejects query parameters, and does not fall back to OAuth. It creates no account or billing state. Use its billing_account_id in the same-account read paths below. Auth-context, purchase, and Auto Top-Up responses are private and use Cache-Control: private, no-store. The presence of these routes does not prove that a purchase offer is currently available. The dashboard uses Auto Top-Up for the customer feature; credit-auto-reload is the stable API route name. The focused account reads are also private and no-store. credit-balance returns only billingAccountId, meterKey: "request_count", a canonical whole-number creditBalance string, and generatedAt from the authoritative Credit source. free-quotas returns the account and observation time plus compact per-provider bucket scope, primary and optional quota windows, concurrency, and an optional cumulative total. Its public counters are JavaScript-safe integers. Neither response exposes internal bucket keys, permit settings, payment state, or x402 state. API-key creation accepts only { "name": "..." }. The runtime assigns development, staging, or production from its trusted environment and rejects a caller-supplied environment field. Key summaries still report the assigned environment.

​
MCP Host

The corresponding Staging MCP root is https://mcp-stg.pubfi.ai. Current endpoint families:
  • POST / for authenticated MCP JSON-RPC;
  • POST /x402 for accountless x402 MCP JSON-RPC;
  • GET /healthz;
  • GET /readyz;
  • GET /version;
  • GET /.well-known/mcp.json;
  • GET /.well-known/openai-apps-challenge; and
  • GET /.well-known/oauth-protected-resource;
  • GET /.well-known/oauth-authorization-server for PubFi-owned OAuth metadata; and
  • /oauth/register, /oauth/authorize, /oauth/token, and /oauth/revoke for the advertised OAuth protocol flow.
The handshake, ping, tools/list, resource listing, and prompt listing methods are public. On the root endpoint, pubfi.route.execute and pubfi.substrate.runtime_upgrade.verify accept a PubFi API key or OAuth access token for the endpoint environment. Invalid credentials do not fall back, and payment metadata is rejected. On the /x402 endpoint, pubfi.route.execute accepts the official x402 metadata flow for an eligible route and rejects every Bearer credential. /x402 exposes only the three general Registry tools; it does not expose the runtime-upgrade verifier. tools/list is endpoint-specific. The root declares noauth for capability reads and oauth2 with no scopes for both execution tools. Route execution contains free-health, account-free, and account-paid outcomes. /x402 declares noauth for every tool and limits route results to free-health, x402 settlement, payment-required, and x402 error outcomes. Missing or invalid OAuth execution credentials return HTTP 401 with protected-resource discovery and an MCP _meta["mcp/www_authenticate"] linking challenge. An invalid pf_sk_v1_ API key keeps the separate API-key 401 response. The MCP output schemas retain free-health outcomes for compatibility. Clients must not infer free execution from an upstream operation name or path. Read the current method-specific billing metadata before execution. For an advertised free variant, pubfi.route.execute uses the same API-key admission and the same exact path with :free appended to its final segment. A successful result reports execution_status: registry_free_route_executed and credits_charged: 0. Anonymous and x402 MCP calls cannot use the suffix.

​
Web Host

The corresponding Staging web root is https://stg.pubfi.ai. Current public endpoint families include:
  • /, /about, /contact, /developers, /partners, /products, /pricing, /status, /blog, /blog/{slug}, and /products/{slug};
  • /discovery, its /discovery/sources directory and pagination, and its source, category, chain, comparison, topic, and Markdown routes;
  • /login, /oauth/consent, /privacy-policy, and /terms-of-service;
  • /index.md, /about.md, /contact.md, /developers.md, /products.md, /pricing.md, and /auth.md;
  • /agents.md, /llms.txt, /developers/llms.txt, and /llms-full.txt;
  • /blog/{slug}.md for canonical article Markdown companions;
  • /openapi.json, /api-reference, and /api as 307 redirects to the request environment’s API;
  • /sitemap.xml and /robots.txt;
  • /discovery/agent-capabilities.json;
  • /.well-known/api-catalog for the environment-matched RFC 9727 API Linkset;
  • /.well-known/ai-catalog.json and /.well-known/ard.json, which return the same catalog body;
  • /.well-known/mcp.json;
  • /.well-known/mcp/server-card.json; and
  • /.well-known/mcp-registry-auth, which is optional and can return 404.
Legacy /docs routes redirect to https://docs.pubfi.ai. External GET and HEAD requests to /, /about, /contact, /developers, /products, and /pricing can select the shared Markdown representation with Accept: text/markdown. HTML remains the default. These responses set Vary: Accept; negotiated Markdown is private and no-store. A request that accepts neither HTML nor Markdown returns 406. Unknown public paths return an HTML or Markdown 404 according to the same preference, while Next.js internal navigation and private application paths retain normal handling.

​
Public-Safe Rule

Public docs can name endpoint families, public schemas, and placeholder requests. They must not publish API keys, signed payment material, account or purchase identifiers, usage rows, billing records, checkout URLs, provider credentials, or private runtime readbacks.