/
/Busbar Admin API
ChangesDocsSign in
  • Docs
  • History
  • Schema
  • get/api/v1/admin/admin-authAdmin-plane auth config (the admin surface guard)
  • put/api/v1/admin/admin-authReplace the admin_auth chain at runtime, dry-run guarded (the calling credentials must hold full scope under the NEW chain, else 409). Live until the next reload/restart
  • get/api/v1/admin/auditAdmin audit log: every mutation with its outcome (newest first). Page: ?limit=, ?cursor=; returns {items, next_cursor}
  • get/api/v1/admin/authIngress auth chain + upstream-credential mode
  • post/api/v1/admin/auth/cache/flushFlush the credential cache: one module's partition (`{module}`) or everything (empty body). Instant revocation of the cached-allow window
  • get/api/v1/admin/configEffective running config snapshot (redacted)
  • post/api/v1/admin/config/applyApply a full config from the request body, atomically (live until next reload/restart; health preserved by lane identity)
  • get/api/v1/admin/config/diffStructured hook-surface diff between two retained versions
  • post/api/v1/admin/config/reloadRe-read config.yaml/providers.yaml from disk and apply atomically (health state preserved by lane identity)
  • post/api/v1/admin/config/rollbackRestore a retained version's hook surface (re-validated; a NEW version)
  • get/api/v1/admin/config/settingsRead the API-set single-value config overlay (root section: listen/tls/rate_card/store/security/limits/…), only the operator's overrides; base config.yaml stands for the rest
  • put/api/v1/admin/config/settingsSET any single-value config section durably (1.5.0 full-config coverage): partial RootSettings merged onto the overlay, re-resolved + validated, swapped in. rate_card/per_request_fee/security/limits/… go live; listen/tls/admin_listen/admin_tls/admin_require_mtls/store are stored + flagged restart-to-apply (bound once at start / store reused across a hot reload). NEVER writes config.yaml
  • post/api/v1/admin/config/validateDry-run validate a proposed config
  • get/api/v1/admin/config/versionsConfig version history (newest first; id/ts/principal/summary). Page: ?limit=, ?cursor=; returns {items, next_cursor}
  • get/api/v1/admin/config/versions/{v}One retained config version, with its hook-surface snapshot
  • get/api/v1/admin/exportEvery `export:` DEFINITION (the 1.5.3 named-definition map: name -> {module, settings, ...}, referenced by bare name). Secrets are never projected
  • get/api/v1/admin/export/{name}One `export:` definition
  • put/api/v1/admin/export/{name}Create or REPLACE one `export:` definition (upsert), persisted to the config overlay and live after an atomic rebuild-and-swap. A base-config-defined entry is 409 (edit config.yaml)
  • delete/api/v1/admin/export/{name}Remove one `export:` definition, refused while another config section still references it by bare name
  • patch/api/v1/admin/export/{name}/settingsReplace ONLY the opaque `settings:` bag of one `export:` definition; every other field is left byte-identical
  • get/api/v1/admin/groupsGroup registry: the limit tree (parent chain, limits, child_default budget template)
  • post/api/v1/admin/groupsCreate (or replace) a group at runtime, live immediately (upsert)
  • get/api/v1/admin/groups/{name}One group definition (parent, enabled, limits, child_default)
  • put/api/v1/admin/groups/{name}Replace an overlay group definition, live immediately (limits rebuilt)
  • delete/api/v1/admin/groups/{name}Remove an overlay group at runtime, live immediately
  • patch/api/v1/admin/groups/{name}Partial update: change only the fields present (e.g. raise a budget, freeze a group)
  • get/api/v1/admin/groups/{name}/usageThe group's derived current-window usage per (window, pool) enforcement bucket vs its caps: the self-service dashboard read (spend derives from the token ledger x the CURRENT rate card at read time)
  • get/api/v1/admin/hooksHook registry (definitions)
  • post/api/v1/admin/hooksRegister (or replace) a hook at runtime, live immediately
  • get/api/v1/admin/hooks/{name}One hook definition
  • put/api/v1/admin/hooks/{name}Replace an overlay hook definition, live immediately (grants immutable)
  • delete/api/v1/admin/hooks/{name}Remove a hook at runtime, live immediately
  • get/api/v1/admin/hooks/{name}/healthBest-effort hook transport reachability
  • get/api/v1/admin/hooks/{name}/schemaThe hook's self-described settings JSON Schema (describe proxy)
  • patch/api/v1/admin/hooks/{name}/settingsPush an opaque settings map to the running hook; COMMIT ON ACK
  • get/api/v1/admin/hooks/{name}/statusThe hook's OBSERVED state, live-queried: running settings + version (vs busbar's desired copy, with a drift verdict) and self-reported metrics. reported=null when the hook doesn't answer (fail-open)
  • get/api/v1/admin/identity-providersEvery `identity-providers:` DEFINITION (the 1.5.3 named-definition map: name -> {module, settings, ...}, referenced by bare name). Secrets are never projected
  • get/api/v1/admin/identity-providers/{name}One `identity-providers:` definition
  • put/api/v1/admin/identity-providers/{name}Create or REPLACE one `identity-providers:` definition (upsert), persisted to the config overlay and live after an atomic rebuild-and-swap. A base-config-defined entry is 409 (edit config.yaml); RAISING `max_admin_scope` is refused outright (the trust ceiling is operator file policy)
  • delete/api/v1/admin/identity-providers/{name}Remove one `identity-providers:` definition, refused while another config section still references it by bare name
  • patch/api/v1/admin/identity-providers/{name}/settingsReplace ONLY the opaque `settings:` bag of one `identity-providers:` definition; every other field is left byte-identical
  • get/api/v1/admin/infoVersion, compiled-in plugin proof, uptime, topology
  • get/api/v1/admin/keysList virtual keys (metadata only; never secrets). Filters: ?enabled=, ?prefix=, ?group= (keys bound to a group; a `user:<sub>` leaf's keys are one person's). Paginate: ?limit=, ?cursor= (opaque)
  • post/api/v1/admin/keysMint a virtual key. The secret is returned EXACTLY once. Honors an `Idempotency-Key` header (per-principal ~10min replay)
  • get/api/v1/admin/keys/{id}One key's metadata + `ETag` (never the secret/hash)
  • delete/api/v1/admin/keys/{id}Revoke a key: it stops resolving immediately. Optional `If-Match` (the key's ETag)
  • patch/api/v1/admin/keys/{id}Enable/disable a key or rebind its group. Optional `If-Match` for optimistic concurrency
  • post/api/v1/admin/keys/{id}/revokeREVOKE a signed-token key: denylist it durably WITHOUT deleting the binding (GET /keys/{id} still shows the record; verify now fails). Idempotent: revoking an already-revoked key is 200. DELETE /keys/{id} is the revoke-AND-forget variant (1.5.0)
  • post/api/v1/admin/keys/{id}/rotateMint a fresh secret in place (same id, budgets, usage). The new secret is shown once; the old stops resolving. Honors an `Idempotency-Key` header (per-principal, op+id-scoped, ~10min replay)
  • get/api/v1/admin/keys/{id}/usageCurrent-window usage for one key (spend / tokens / requests)
  • get/api/v1/admin/modelsModel lanes + upstream providers
  • get/api/v1/admin/openapi.jsonThis OpenAPI 3.1 document
  • delete/api/v1/admin/overlay/{section}DISCARD a section's overlay mutations and revert it to base config.yaml (section ∈ groups|hooks|root|plugin_versions). Per-section reset: the OTHER sections' overlay survives. A NEW config version; an already-empty section is an idempotent no-op (changed:false)
  • get/api/v1/admin/pluginsPlugin catalog by type (compiled-in + external + dynamic-library)
  • post/api/v1/admin/pluginsInstall a dynamic-library store plugin: upload the library (base64) + optional signed manifest; the engine RE-VERIFIES against the running trust posture, validates the store ABI, and writes it atomically into the plugins directory. Takes effect on the next store (re)load
  • post/api/v1/admin/plugins/inspectStateless read-only preview of a candidate plugin tarball: verify its signature, parse its manifest, and report its settings schema WITHOUT installing anything
  • post/api/v1/admin/plugins/reloadRe-scan the plugins directory and report the reconciled dynamic-library inventory (the sibling of config/reload). A store change takes effect on the next store (re)load
  • post/api/v1/admin/plugins/rollbackEXPLICIT, authenticated, audited rollback of a plugin to a PRIOR version (1.5.0). Validates the target artifact (structure + trust) with the anti-downgrade floor lowered to EXACTLY the target's own version; a lower or untrusted artifact still fails (a rollback authenticates the OPERATOR, never the bytes). Persists the version pin to the overlay (survives restart) and hot-swaps via the same rebuild-and-swap path as plugins/reload
  • delete/api/v1/admin/plugins/{file}Remove a dynamic-library plugin (library + manifest sidecar) from the plugins directory. A loaded store keeps running until the next store (re)load
  • get/api/v1/admin/plugins/{file}/schemaThe plugin's self-described settings JSON Schema, read from the SIGNED manifest's `settings_schema` field, which works for every plugin kind (store/secret/auth/hook), not just hooks. `hook` plugins keep the live describe-proxy behavior when describe answers (source: describe); a loaded hook whose describe answers null falls back server-side to the manifest baseline (source: manifest)
  • get/api/v1/admin/poolsPool topology (members + weights). ?detail=true inlines live member status (one call, no N+1)
  • get/api/v1/admin/pools/{name}Live per-member status of one pool (breaker/concurrency/latency)
  • get/api/v1/admin/providersDistinct providers + lane counts
  • post/api/v1/admin/restartRestart busbar to apply the restart-scoped settings (listen, admin_listen, tls, admin_tls, admin_require_mtls, store). Drains first; the supervisor brings it back
  • post/api/v1/admin/signing-key/rotateROTATE the busbar key-signing key. Rotation is REVOKE-ALL by design: a new signing key means every token minted under the OLD key stops verifying, so every outstanding key must be re-minted. 1.5.0 is single-key, so this reports the intent + current kid; the actual swap is an operator action (replace auth.signing_key / the persisted key file and restart/reload every node in lockstep) (1.5.0)
  • get/api/v1/admin/usageMetering: current UTC-day bucket ({window, as_of, currency, total, by_model, by_key}), raw token split + derived spend_micros