Skip to content
pistra

Add a provider with a catalog overlay

Use a catalog overlay to add or correct a provider without a binary release. An overlay can declare endpoints, dialects, model gates, and capability claims that the binary already supports.

Add a custom providers: entry for an endpoint only your deployment uses. Use an overlay for a public provider or a compatibility claim you need to track. See add a custom provider.

Add a provider

Section titled “Add a provider”

Write the overlay into the config and use the provider as a preset:

catalog_overlays:
  - name: acme
    providers:
      - op: add
        name: acme
        schema: {name: OpenAI}
        base_url: https://api.acme.example
        key_env: ACME_API_KEY
        docs: https://docs.acme.example/api
        channels:
          - id: chat
            dialect: openai
            tier: native
            docs: https://docs.acme.example/api


providers:
  - preset: acme
    api_key: ${ACME_API_KEY}
    models: ["gpt-*"]

The gateway rebuilds overlays on every reload. A failed overlay leaves the last valid configuration in place.

name identifies the overlay in provenance and validation errors.

Or from a directory

Section titled “Or from a directory”

catalog_overlay_paths reads the same documents as JSON files:

catalog_overlay_paths: ["overlays/*.json"]

Use paths for bulk import from a directory your deployment tool manages. They are node-scoped because the path belongs to one machine. Paths apply first, then inline catalog_overlays apply over them.

Three rules that will stop you first

Section titled “Three rules that will stop you first”

Follow these validation rules:

  • base_url must be absolute https. It is a published provider endpoint, not a local override. To point at something local, override base_url in the providers: entry instead of in the overlay.
  • A native channel must not declare caps. Native means the provider’s own dialect, which by definition preserves everything. Listing capabilities there would imply the list is exhaustive.
  • A native channel must not declare verified_at/verified_by. There is no capability claim to have verified.

Declare capability claims on provider_compat channels:

- op: add
  id: openai-compat
  dialect: openai
  tier: provider_compat
  caps: [tools, structured_output]
  docs: https://docs.acme.example/openai-compat
  verified_at: "2026-08-16"
  verified_by: doc

Correct a claim on a provider that ships with the binary

Section titled “Correct a claim on a provider that ships with the binary”

patch changes base_url, key_env, docs and channels only. Use replace for any other field. The gateway does not deep-merge schemas or mutations because merged claims would have no source.

catalog_overlays:
  - name: org-anthropic
    providers:
      - op: patch
        name: anthropic
        channels:
          - op: replace
            id: openai-compat
            dialect: openai
            tier: provider_compat
            caps: [tools]
            docs: https://platform.claude.com/docs/en/api/openai-sdk
            verified_at: "2026-08-16"
            verified_by: live

Channel replacement replaces the whole channel. Caps and model gates are explicit sets and are never merged.

replace swaps a provider definition. remove deletes one. A later config build fails if it still references the removed provider.

See which claim was acted on

Section titled “See which claim was acted on”

Run this command:

Terminal window
$ curl -s localhost:8485/admin/v1/catalog/report

The report lists every routable channel, what it preserves and loses, which overlay the claim came from, the page it was read off, and when it was last established. Individual routing decisions carry the same provenance as the span attribute pistra.channel_origin.

Section titled “Related”