Admin API and control plane

The admin plane listens on 127.0.0.1:9099 by default and serves health probes, Prometheus metrics, and the configuration API. What you can do through it depends on how the gateway was booted.

Inspecting a running gateway

orca-gateway admin config get
orca-gateway admin destinations list
orca-gateway admin routes list
orca-gateway admin plugins list

Every admin subcommand takes --gateway-url (default http://localhost:9099, or the ORCA_GATEWAY_ADMIN_URL environment variable) and --actor, which is sent as an X-Orca-Actor header on writes and recorded with the change. --actor defaults to $USER.

Validating against a running gateway

orca-gateway admin config validate --file ./config.yaml

This runs structural validation plus live checks such as whether referenced TLS, token, credential, and vault files exist and are readable. It does not authenticate every credential against its provider.

Writing configuration

With a Postgres control plane, resources can be changed individually:

orca-gateway admin destinations put openai-primary --file ./openai.yaml
orca-gateway admin routes put chat --file ./chat-route.yaml
orca-gateway admin rate-limits put prod --file ./prod-limits.yaml --position 0
orca-gateway admin vaults put openai_key --file ./vault.yaml
orca-gateway admin destinations delete stale-provider

Plugin writes additionally name the family slot they belong to:

orca-gateway admin plugins put pii --family guardrails --file ./pii.yaml

Valid families are guardrails, audit_sinks, usage_sinks, trace_exporters, signers, authorizers, rate_limiter, and cache.

To load a whole config at once - which is the usual first step when migrating a file-based deployment onto the control plane:

orca-gateway admin import-yaml ./config.yaml

This reads the file and issues a write for every resource it contains, then reports a summary.

How revisions work

The control plane stores configuration as revisions in a config_revisions table, with a partial unique index guaranteeing exactly one active revision at any time. Each write inserts a new row and promotes it.

Rolling back means promoting an earlier revision, in a single transaction:

BEGIN;
UPDATE config_revisions SET active = FALSE WHERE active;
UPDATE config_revisions SET active = TRUE WHERE id = <previous_id>;
COMMIT;

HTTP endpoints

If you would rather call the API directly than use the CLI, see the HTTP API reference. Resource writes use PUT and DELETE; POST is reserved for config/validate.