Skip to main content

Management API

LLM GATEWAY / MANAGEMENT V1

Configure your gateway.
Keep every change intentional.

Manage apps, shared providers, quota pools, access keys, prompts, budgets, routing, rate limits, incidents, external hooks and self-service, and read usage, guardrail activity, provider health and users, from one tenant-scoped API. Start with a workflow, explore every request field, or try calls live in the playground.

Tenant-bound keys Explicit scopes Central configuration

Use a dedicated management key to configure the LLM Gateway from deployment pipelines, internal tools and administration scripts. Each key belongs to one tenant, carries explicit permissions, and works only when both deployment enablement and tenant opt-in are active.

Use the Management API to configure LLM Gateway apps, shared providers, quota pools, credentials, prompts, budgets, routing and failover, rate limits, incident controls, external hooks and stored configuration, and to read usage, guardrail activity, provider health, users and the explanation of a single request. Explore complete input specifications and examples, download the OpenAPI reference, or send live calls from the Management API playground.

Enable in the console​

  1. Go to Settings > AI Gateway > LLM Gateway and open the Management API tab.
  2. Turn on Allow management keys for this organization. Turning it off later suspends every management key until you turn it back on.

  1. Under Issue a management key, enter a Key name, an optional Expiry, and the Scopes it needs.
  2. Click Issue key and store the value. It is shown only once.

Console scopeAPI scopeGrants
ReadreadApps, providers, quota pools, key metadata, prompts, catalogs, history, usage, guardrail activity, provider health, request explanations, users, self-service settings and reports, new-model reviews and the OpenAPI document
Configure appsconfig:writeCreate apps and change their settings, availability, providers and prompts; configure self-service (access plans, model options, app templates, suspensions, app owners) and decide self-service requests
Manage providersproviders:writeCreate, update, delete and test shared providers and quota pools, and discover models
Issue app keyscredentials:writeIssue, extend and revoke Quilr keys for apps
Reveal app keyscredentials:readRead the value of an active app key. Every reveal is audited.
Read budgetsbudgets:readBudgets, usage, subjects, grants, pricing, exemptions, alerts and events
Manage budget grantsbudgets:grantIssue, change and revoke budget grants
Configure budgetsbudgets:policyEdit budgets, pricing, exemptions and alert destinations
Manage hookshooks:writeCreate, change, delete and test external hooks
Manage personal keyskeys:writeIssue, rename, change the expiry of and revoke personal API keys on a user's behalf
Manage agentsagents:writeDeclare and undeclare agents and create, change and delete agent groups

Routing, rate limit and incident scopes (routing:*, limits:*, incidents:*) are described under Scopes.

A key acts for the whole organization within its scopes and cannot be limited to one app. Revoke a key from the keys table on the same tab. See Authentication and management keys for details.

Choose a resource​

The management model​

Enable
Deployment switch
Tenant opt-in
Authorize
One tenant per key
Explicit scopes
Configure
Central management API
Validated changes
Apply
Configuration reaches gateways
Policy-aware runtime
QuilrAI
ResourceWhat you can doWhat stays separate
AppsCreate, read, configure, disable and enable; address by app name.App deletion/rename: Not Generally Available.
Shared providersCreate, read, filter, rotate credentials, configure models, disable, enable, delete, test and discover models, and approve or reject new models a provider starts offering.Deleting needs every app detached first. Detaching affects one app only.
Quota poolsRegister, read, update and delete shared upstream ceilings; assign providers and models to them.Pools describe limits; they do not enforce them.
Gateway keysIssue, list metadata, rename, change expiry, reveal with a dedicated scope and revoke.Management keys are a different credential type.
BudgetsCreate and edit spend, request and token budgets and group budget sets, read usage, issue grants, set prices and exemptions.Each budget, pricing or exemption edit publishes a policy revision. Needs the Policy Engine on.
Routing and failoverRoutes, weighted and ordered destinations, failover profiles, rules and default, routing constraints and model access; dry runs, revision history and restore, routing diagnostics.Each write publishes a policy revision with no QuilrQL to write. Needs the Policy Engine on.
Rate limitsRequest and token rate limits, temporary raises, request guards, model limits, exemptions, custom limit responses, live usage and effective limits.Counters are regional. Each limit write publishes a policy revision; raises do not. Needs the Policy Engine on.
Access and gateway featuresAccess controls (block, require identity or a conversation ID, allowed source IPs) and gateway features: token saving, response cache, cache warm, model visibility, error messages, conversation headers and prompt enforcement. See the Access and gateway features API.Each write publishes a policy revision. Needs the Policy Engine on.
IncidentsMark a provider down for every app or chosen apps with an expiry, preview, restore, reset cooldowns and drop session pins.Not a policy change; works with the Policy Engine on or off.
HooksCall your own HTTPS API before the model call (pre_call) or before a non-streaming response is returned (post_call) to allow, flag or block, or export finished requests in batches (on_complete). Preview, test and stats. See the Hooks API.Each write publishes a policy revision. Needs the Policy Engine on. The console lists hooks read-only under Configured hooks.
UsageRequests, outcomes, tokens and cost over all time or any range, by period and up to two of app, model, provider, user, key, source and outcome. Per-key last use. See the Usage API.Aggregates only; bulk request logs come from the Log Export API.
MonitoringLatency distributions, gateway feature metrics (cache, token saving, failover), a filterable request list, guardrail activity, provider and model health with routing state, and why one request was routed, blocked, limited or failed over. See the Monitoring API.Read only. Never returns prompt or response text or detected values.
UsersEveryone who uses the gateway, with app access, personal keys, last activity and usage. See the Users API.Read only; people are added through your identity provider or the console.
Self-serviceAccess plans (profiles), model options, app templates, suspensions, evaluate and coverage with personal-key impact, requests, app owners, personal keys across apps and the usage report. See the Self-service API.No policy revision is published.
QuilrQL behaviorRead authority metadata; eligible new apps receive allowed-models defaults when authority is already enabled.General policy authoring and publishing: Not Generally Available. The typed budgets, routing and limits APIs cover those cards without QuilrQL.
Prompt StoreList, read, create, replace and delete app prompts.Prompt content and policy enforcement are distinct.
Smart groupsList groups with their rank (priority) and strength (rank), create and edit virtual groups and their members, override a synced group's rank (priority), and preview who changes governing group. See the Smart groups API.Synced groups' members come from your directory; only their rank can be overridden.
AgentsList agents and coding tools seen in gateway traffic, declare agents with an owner and tags, create agent groups with match rules, and read families. See the Agents API.Agent identity is self-reported by the client: a label, not authentication. Writes are not policy changes.
Custom definitionsRead and use existing definitions in app configuration.Definition editing: Not Generally Available.
HistoryRead redacted config versions and audit, restore eligible app settings.Request logs come from the Log Export API. Red-team jobs: Not Generally Available through management v1.

Availability​

Not Generally Available means the feature is not currently supported by management v1. The label does not promise preview access or a release date. The endpoint reference and OpenAPI paths contain only implemented operations.

FeatureAvailabilityCurrent behavior
Policy schema/catalog, preview, validation, simulation, drafts, publication, policy rollback and authority changesNot Generally AvailableUse the existing policy workflow. Management keys cannot use policy scopes or policy lifecycle endpoints. The policy-backed writes are typed: the Budgets API, the Routing and failover API and the Rate limits API.
App rename and deletionNot Generally AvailableEnable/disable existing apps. Shared providers can be deleted once no app attaches them.
Custom-definition authoring and synced smart-group membership writesNot Generally AvailableRead and reference existing definitions. Virtual groups and rank overrides are available through the Smart groups API.
Dedicated key rotation and individual management-key pause/resumeNot Generally AvailableIssue a replacement and revoke the old key; tenant-wide suspension is supported.
Later management-key secret retrieval and expired/revoked gateway-key revealNot Generally AvailableManagement secrets are returned on issuance/replay; explicit gateway-key reveal requires an active key.
Create-only prompt preconditionsNot Generally AvailablePUT creates a new prompt without If-Match and replaces an existing one with the app ETag.
Catalog searchNot Generally AvailableUse documented pagination. App lists filter by name, tag and enabled state; provider lists by type, enabled state, tag and model. Audit lists filter by actor, operation, resource, since and until.
App-restricted management-key scopes and red-team job APIsNot Generally AvailableManagement scopes apply tenant-wide; red-team jobs are outside this API.

Defaults​

  • Management keys have no expiry by default. An administrator can supply one.
  • Creating an app issues one gateway key, named Default unless specified.
  • Disabling tenant management suspends its keys. Unexpired, unrevoked keys work again when the tenant is re-enabled.
  • Disabling an app preserves its keys, settings and history. Disabling a shared provider preserves its attachments.
  • Provider saves validate the input but never contact the provider. Connection tests, model tests and model discovery are separate explicit requests.
  • Configuration applies per region: manage it through the regional host your organization uses. Saved changes reach that region's gateways asynchronously.
Policy authority

When QuilrQL is enabled, updates to governed app settings still save. The response identifies the fields that remain inactive until QuilrQL authority is disabled. Creating an eligible app under existing authority can publish an app-specific allowed-models default. See QuilrQL behavior.

Find an endpoint​

Search by resource, path, action or HTTP method. Open an endpoint to see its scopes, parameters, complete body schema and examples.

276 of 276 operations (plus 25 /app?app_name= aliases for app names that contain / or %)

GET
/admin/tenants/{tenant_id}/hooksList the tenant's external hooks
GET
/admin/tenants/{tenant_id}/keysList management keys
POST
/admin/tenants/{tenant_id}/keysIssue a management key
DELETE
/admin/tenants/{tenant_id}/keys/{key_id}Revoke a management key
PATCH
/admin/tenants/{tenant_id}/keys/{key_id}Update a management key
GET
/admin/tenants/{tenant_id}/outbound-ipsRead the tenant's outbound IP setting
PUT
/admin/tenants/{tenant_id}/outbound-ipsSet the tenant's outbound IP setting
GET
/admin/tenants/{tenant_id}/settingsRead tenant management settings
PATCH
/admin/tenants/{tenant_id}/settingsEnable or suspend tenant management
GET
/appsList apps
POST
/appsCreate an app
GET
/apps/{app_name}Read an app
PATCH
/apps/{app_name}Update or disable an app
GET
/apps/{app_name}/keysList gateway credentials
POST
/apps/{app_name}/keysIssue a gateway credential
DELETE
/apps/{app_name}/keys/{key_id}Revoke a gateway credential
GET
/apps/{app_name}/keys/{key_id}Read a gateway credential
PATCH
/apps/{app_name}/keys/{key_id}Rename a gateway key or change its expiry
POST
/apps/{app_name}/keys/{key_id}/revealReveal a gateway credential
GET
/apps/{app_name}/promptsList prompts
DELETE
/apps/{app_name}/prompts/{prompt_id}Delete a prompt
GET
/apps/{app_name}/prompts/{prompt_id}Read a prompt
PUT
/apps/{app_name}/prompts/{prompt_id}Create or replace a prompt
POST
/apps/{app_name}/provider-conversionConvert inline providers
GET
/apps/{app_name}/providersList app providers
DELETE
/apps/{app_name}/providers/{label}Detach an app provider
PUT
/apps/{app_name}/providers/{label}Attach a shared provider
GET
/apps/{app_name}/self-service-keysList an app's personal API keys
POST
/apps/{app_name}/self-service-keysIssue a personal API key for a user
DELETE
/apps/{app_name}/self-service-keys/{key_id}Revoke a personal API key
GET
/apps/{app_name}/self-service-keys/{key_id}Read a personal API key
PATCH
/apps/{app_name}/self-service-keys/{key_id}Rename a personal API key or change its expiry
PUT
/apps/{app_name}/self-service-ownersSet an app's owners
GET
/apps/{app_name}/versionsList app configuration versions
GET
/apps/{app_name}/versions/{version_id}Read a configuration version
POST
/apps/{app_name}/versions/{version_id}/rollbackRoll back app configuration
GET
/auditList audit events
GET
/budget-alert-destinationsRead budget alert destinations
PUT
/budget-alert-destinationsReplace budget alert destinations
GET
/budget-alertsList budget alerts
GET
/budget-eventsList budget events
GET
/budget-exemptionsList budget exemptions
POST
/budget-exemptionsCreate a budget exemption
DELETE
/budget-exemptions/{exemption_id}Delete a budget exemption
GET
/budget-forecastRead budget forecast
GET
/budget-grantsList budget grants
DELETE
/budget-grants/{grant_id}Revoke a budget grant
GET
/budget-grants/{grant_id}Read a budget grant
PATCH
/budget-grants/{grant_id}Update a budget grant
GET
/budget-pricingRead budget pricing
PATCH
/budget-pricingUpdate unpriced model handling
DELETE
/budget-pricing/rates/{provider}/{model}Remove a model rate
PUT
/budget-pricing/rates/{provider}/{model}Set a model rate
GET
/budget-setsList group budget sets
POST
/budget-setsCreate a group budget set
DELETE
/budget-sets/{set_id}Delete a group budget set
GET
/budget-sets/{set_id}Read a group budget set
PATCH
/budget-sets/{set_id}Switch how a group budget set resolves
POST
/budget-sets/{set_id}/groupsAdd a group to a budget set
DELETE
/budget-sets/{set_id}/groups/{group}Remove a group from a budget set
GET
/budget-subjectsList budget subjects
GET
/budget-subjects/{kind}/{value}Read a budget subject
GET
/budget-usage-summaryRead budget usage summary
GET
/budgetsList budgets
POST
/budgetsCreate a budget
POST
/budgets/_batchApply budget changes in a batch
DELETE
/budgets/{budget_id}Delete a budget
GET
/budgets/{budget_id}Read a budget
PATCH
/budgets/{budget_id}Update a budget
GET
/budgets/{budget_id}/burn-rateRead budget burn rate
POST
/budgets/{budget_id}/grantsIssue a budget grant
POST
/budgets/{budget_id}/grants/_bulkIssue budget grants in bulk
GET
/budgets/{budget_id}/usageRead budget usage
GET
/capabilitiesRead capabilities
POST
/controls/_batchApply a batch of control changes
GET
/controls/_capacityRead policy capacity
GET
/controls/accessList access controls
DELETE
/controls/access/{resource_id}Delete an access control
GET
/controls/access/{resource_id}Read an access control
PATCH
/controls/access/{resource_id}Update an access control
PUT
/controls/access/{resource_id}Create or replace an access control
GET
/controls/cache-warmList cache warm settings
DELETE
/controls/cache-warm/{resource_id}Delete a cache warm setting
GET
/controls/cache-warm/{resource_id}Read a cache warm setting
PATCH
/controls/cache-warm/{resource_id}Update a cache warm setting
PUT
/controls/cache-warm/{resource_id}Create or replace a cache warm setting
GET
/controls/complexity-levelsList complexity levels
DELETE
/controls/complexity-levels/{resource_id}Delete a complexity levels
GET
/controls/complexity-levels/{resource_id}Read a complexity levels
PATCH
/controls/complexity-levels/{resource_id}Update a complexity levels
PUT
/controls/complexity-levels/{resource_id}Create or replace a complexity levels
GET
/controls/conversation-headersList conversation header settings
DELETE
/controls/conversation-headers/{resource_id}Delete a conversation header setting
GET
/controls/conversation-headers/{resource_id}Read a conversation header setting
PATCH
/controls/conversation-headers/{resource_id}Update a conversation header setting
PUT
/controls/conversation-headers/{resource_id}Create or replace a conversation header setting
GET
/controls/destinationsList destinations
DELETE
/controls/destinations/{resource_id}Delete a destination
GET
/controls/destinations/{resource_id}Read a destination
PATCH
/controls/destinations/{resource_id}Update a destination
PUT
/controls/destinations/{resource_id}Create or replace a destination
POST
/controls/destinations/{resource_id}:replace-memberReplace member of a destination
POST
/controls/destinations/{resource_id}:set-weightsSet weights of a destination
GET
/controls/error-messagesList error message settings
DELETE
/controls/error-messages/{resource_id}Delete an error message setting
GET
/controls/error-messages/{resource_id}Read an error message setting
PATCH
/controls/error-messages/{resource_id}Update an error message setting
PUT
/controls/error-messages/{resource_id}Create or replace an error message setting
DELETE
/controls/failover-defaultReset the failover default
GET
/controls/failover-defaultRead the failover default
PUT
/controls/failover-defaultCreate or replace the failover default
GET
/controls/failover-profilesList failover profiles
DELETE
/controls/failover-profiles/{resource_id}Delete a failover profile
GET
/controls/failover-profiles/{resource_id}Read a failover profile
PATCH
/controls/failover-profiles/{resource_id}Update a failover profile
PUT
/controls/failover-profiles/{resource_id}Create or replace a failover profile
GET
/controls/failover-rulesList failover rules
DELETE
/controls/failover-rules/{resource_id}Delete a failover rule
GET
/controls/failover-rules/{resource_id}Read a failover rule
PATCH
/controls/failover-rules/{resource_id}Update a failover rule
PUT
/controls/failover-rules/{resource_id}Create or replace a failover rule
GET
/controls/hooksList hooks
GET
/controls/hooks/field-catalogList the fields a hook can send
POST
/controls/hooks/previewPreview the call a hook would make
DELETE
/controls/hooks/{resource_id}Delete a hook
GET
/controls/hooks/{resource_id}Read a hook
PATCH
/controls/hooks/{resource_id}Update a hook
PUT
/controls/hooks/{resource_id}Create or replace a hook
GET
/controls/hooks/{resource_id}/statsRead hook delivery stats
POST
/controls/hooks/{resource_id}/testSend a test call with a saved hook
GET
/controls/limit-exemptionsList limit exemptions
DELETE
/controls/limit-exemptions/{resource_id}Delete a limit exemption
GET
/controls/limit-exemptions/{resource_id}Read a limit exemption
PATCH
/controls/limit-exemptions/{resource_id}Update a limit exemption
PUT
/controls/limit-exemptions/{resource_id}Create or replace a limit exemption
GET
/controls/limit-responsesList limit responses
DELETE
/controls/limit-responses/{resource_id}Delete a limit response
GET
/controls/limit-responses/{resource_id}Read a limit response
PATCH
/controls/limit-responses/{resource_id}Update a limit response
PUT
/controls/limit-responses/{resource_id}Create or replace a limit response
GET
/controls/model-accessList model access rules
DELETE
/controls/model-access/{resource_id}Delete a model access rule
GET
/controls/model-access/{resource_id}Read a model access rule
PATCH
/controls/model-access/{resource_id}Update a model access rule
PUT
/controls/model-access/{resource_id}Create or replace a model access rule
GET
/controls/model-limitsList model limits
DELETE
/controls/model-limits/{resource_id}Delete a model limit
GET
/controls/model-limits/{resource_id}Read a model limit
PATCH
/controls/model-limits/{resource_id}Update a model limit
PUT
/controls/model-limits/{resource_id}Create or replace a model limit
GET
/controls/model-visibilityList model visibility settings
DELETE
/controls/model-visibility/{resource_id}Delete a model visibility setting
GET
/controls/model-visibility/{resource_id}Read a model visibility setting
PATCH
/controls/model-visibility/{resource_id}Update a model visibility setting
PUT
/controls/model-visibility/{resource_id}Create or replace a model visibility setting
GET
/controls/prompt-enforcementList prompt enforcement settings
DELETE
/controls/prompt-enforcement/{resource_id}Delete a prompt enforcement setting
GET
/controls/prompt-enforcement/{resource_id}Read a prompt enforcement setting
PATCH
/controls/prompt-enforcement/{resource_id}Update a prompt enforcement setting
PUT
/controls/prompt-enforcement/{resource_id}Create or replace a prompt enforcement setting
GET
/controls/rate-limitsList rate limits
DELETE
/controls/rate-limits/{resource_id}Delete a rate limit
GET
/controls/rate-limits/{resource_id}Read a rate limit
PATCH
/controls/rate-limits/{resource_id}Update a rate limit
PUT
/controls/rate-limits/{resource_id}Create or replace a rate limit
GET
/controls/rate-limits/{resource_id}/grantsList rate limit grants
POST
/controls/rate-limits/{resource_id}/grantsGrant a temporary raise
DELETE
/controls/rate-limits/{resource_id}/grants/{grant_id}Revoke a grant
GET
/controls/rate-limits/{resource_id}/usageRead rate limit usage
POST
/controls/rate-limits:migrate-legacyMigrate legacy limits
GET
/controls/referencesList references to a provider label
GET
/controls/request-guardsList request guards
DELETE
/controls/request-guards/{resource_id}Delete a request guard
GET
/controls/request-guards/{resource_id}Read a request guard
PATCH
/controls/request-guards/{resource_id}Update a request guard
PUT
/controls/request-guards/{resource_id}Create or replace a request guard
GET
/controls/response-cacheList response cache settings
DELETE
/controls/response-cache/{resource_id}Delete a response cache setting
GET
/controls/response-cache/{resource_id}Read a response cache setting
PATCH
/controls/response-cache/{resource_id}Update a response cache setting
PUT
/controls/response-cache/{resource_id}Create or replace a response cache setting
GET
/controls/revisionsList policy revisions
GET
/controls/revisions/{revision}/resources/{collection}/{resource_id}Read a resource at a revision
GET
/controls/revisions/{revision}/statusRead revision rollout
POST
/controls/revisions/{revision}:restoreRestore controls from a revision
GET
/controls/routesList routes
DELETE
/controls/routes/{resource_id}Delete a route
GET
/controls/routes/{resource_id}Read a route
PATCH
/controls/routes/{resource_id}Update a route
PUT
/controls/routes/{resource_id}Create or replace a route
POST
/controls/routes/{resource_id}:set-modeSet mode of a route
GET
/controls/routing-constraintsList routing constraints
DELETE
/controls/routing-constraints/{resource_id}Delete a routing constraint
GET
/controls/routing-constraints/{resource_id}Read a routing constraint
PATCH
/controls/routing-constraints/{resource_id}Update a routing constraint
PUT
/controls/routing-constraints/{resource_id}Create or replace a routing constraint
GET
/controls/token-savingList token saving settings
DELETE
/controls/token-saving/{resource_id}Delete a token saving setting
GET
/controls/token-saving/{resource_id}Read a token saving setting
PATCH
/controls/token-saving/{resource_id}Update a token saving setting
PUT
/controls/token-saving/{resource_id}Create or replace a token saving setting
GET
/custom-definitionsList custom definitions
GET
/custom-definitions/{definition_id}Read a custom definition
GET
/failover/summaryRead the failover summary
GET
/features/summarySummarize gateway feature metrics
GET
/guardrails/summarySummarize guardrail activity
POST
/incidents/drop-pinsDrop session pins
GET
/incidents/mark-downsList mark-downs
DELETE
/incidents/mark-downs/{mark_down_id}Restore a provider
GET
/incidents/mark-downs/{mark_down_id}Read a mark-down
PUT
/incidents/mark-downs/{mark_down_id}Mark a provider down
POST
/incidents/mark-downs:previewPreview a mark-down
POST
/incidents/reset-cooldownsReset cooldowns
GET
/incidents/statusIncident propagation status
GET
/latencySummarize request latency
GET
/limits/effectiveRead effective limits
GET
/operations/{operation_id}Read operation status
POST
/operations/{operation_id}/recoverRecover a pending operation
GET
/outbound-ipsRead the outbound IP setting
PUT
/outbound-ipsTurn Quilr outbound IPs on or off
GET
/provider-healthRead provider health
GET
/provider-model-reviewsList new-model reviews
GET
/provider-model-reviews/{label}Read one provider's new-model reviews
POST
/provider-model-reviews/{label}/app-decisionsApprove or reject new models of an app's own provider
POST
/provider-model-reviews/{label}/decisionsApprove or reject new models of a shared provider
GET
/providersList shared providers
POST
/providersCreate a shared provider
POST
/providers/available-modelsDiscover models for draft settings
POST
/providers/test-settingsTest draft provider settings
DELETE
/providers/{label}Delete a shared provider
GET
/providers/{label}Read a shared provider
PATCH
/providers/{label}Update or disable a provider
POST
/providers/{label}/available-modelsDiscover provider models
POST
/providers/{label}/testTest connection or model
POST
/providers/{label}/test-settingsTest provider settings
GET
/quota-poolsList quota pools
POST
/quota-poolsCreate a quota pool
DELETE
/quota-pools/{pool_id}Delete a quota pool
GET
/quota-pools/{pool_id}Read a quota pool
PATCH
/quota-pools/{pool_id}Update a quota pool
GET
/requestsList gateway requests
GET
/requests/{request_id}/explainExplain a request
GET
/routing/effectiveExplain the effective route
GET
/routing/summaryRead the routing summary
POST
/routing/target-checkCheck routing targets
POST
/routing/testTest routing for a sample request
GET
/self-service-keysList personal API keys across apps
GET
/self-service/blueprint_eligibilityCheck whether apps can be blueprints
GET
/self-service/coverageCount people per profile
POST
/self-service/coverageCount people per profile for a draft
POST
/self-service/evaluateExplain a person's self-service access
GET
/self-service/exceptionsList exception requests
GET
/self-service/exceptions/{exception_id}Read an exception request
POST
/self-service/exceptions/{exception_id}/approveApprove an exception request
POST
/self-service/exceptions/{exception_id}/rejectReject an exception request
POST
/self-service/exceptions/{exception_id}/revokeRevoke an approved exception
GET
/self-service/profilesList self-service profiles
POST
/self-service/profilesCreate a self-service profile
DELETE
/self-service/profiles/{profile_id}Delete a self-service profile
GET
/self-service/profiles/{profile_id}Read a self-service profile
PUT
/self-service/profiles/{profile_id}Replace a self-service profile
PUT
/self-service/settingsUpdate the self-service setting
PUT
/self-service/suspensionsSuspend a person
POST
/self-service/suspensions/removeLift a suspension
GET
/self-service/usageReport self-service usage
GET
/smart-groupsList smart groups
POST
/smart-groupsCreate a virtual smart group
POST
/smart-groups/_priority-previewPreview priority changes
DELETE
/smart-groups/{group_name}Delete a virtual smart group
GET
/smart-groups/{group_name}Read a smart group
PATCH
/smart-groups/{group_name}Update a smart group or its priority
POST
/smart-groups/{group_name}/membersAdd or remove smart group members
GET
/usageRead usage
GET
/usersList gateway users
GET
/users/{email}Read a gateway user
GET
/llmgateway_management_apis/v1/openapi.jsonDownload the OpenAPI document

Continue​

Start with the end-to-end example, inspect the full app configuration schema, or review errors, concurrency and retry semantics. Download the OpenAPI 3.1 reference for all operations and input schemas, or open the Management API playground to connect with your key and send any operation from the browser. Every endpoint below has a Try it in the playground link.

Quick start​

This workflow checks access, creates a shared provider, creates an app, reads it, then disables it without losing configuration. To try the same steps without a terminal, use the Management API playground.

1. Prepare access​

Management requests go to the same regional hosts as inference traffic. Configuration, keys and limits apply per region, so use the region your organization uses for the gateway:

RegionBase URL
USA 1 (US Central West)https://guardrails-usa-1.quilr.ai
USA 2 (US East)https://guardrails-usa-2.quilr.ai
Europehttps://guardrails-europe-1.quilr.ai
India 1 (Mumbai)https://guardrails-india-1.quilr.ai
India 2 (Mumbai)https://guardrails-india-2.quilr.ai
Japan (Tokyo)https://guardrails-jp-1.quilr.ai

Self-hosted deployments use their own gateway URL. A self-hosted node that is connected to a QuilrAI-hosted service answers management calls with 503 central_service_required; call the regional host instead.

In the console, turn on Allow management keys for this organization and issue a key (see Enable in the console). For this workflow, the key needs read, providers:write, config:write and credentials:write.

export MANAGEMENT_URL='https://guardrails-usa-1.quilr.ai'   # your region from the table above
export MANAGEMENT_KEY='<management-key>'
export PROVIDER_API_KEY='<provider-api-key>'

Keep secrets in your automation secret store. These example values are placeholders, not live credentials.

Check the URL and key with a read-only call. It changes nothing and needs only the read scope:

curl --fail-with-body \
"$MANAGEMENT_URL/llmgateway/management/v1/capabilities" \
--header "Authorization: Bearer $MANAGEMENT_KEY"

A 200 response lists every scopes value, your key's own scopes in caller.scopes, provider_types, app_fields, writes_available and which provider types support tests and model discovery. If it fails:

ResponseMeaning
401 invalid_management_keyThe key is missing, wrong, expired or revoked.
403 insufficient_scopeThe key lacks read.
403 management_disabled_for_tenantAllow management keys for this organization is off.
404Management is turned off for this deployment, or the URL or path is wrong.
503 central_service_requiredYou called a self-hosted node connected to a QuilrAI-hosted service. Use the regional host.

2. Create a shared provider​

curl --request POST \
"$MANAGEMENT_URL/llmgateway/management/v1/providers" \
--header "Authorization: Bearer $MANAGEMENT_KEY" \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: support-provider-001' \
--data "{\"label\":\"Production OpenAI\",\"provider_name\":\"openai\",\"provider_settings\":{\"api_key\":\"$PROVIDER_API_KEY\"},\"selected_models\":[\"gpt-4.1-mini\"]}"

A 201 response returns provider metadata with credential_configured and an opaque version. Saving does not contact the provider. Use explicit testing when you want to verify connectivity or model access.

3. Create an app​

curl --request POST \
"$MANAGEMENT_URL/llmgateway/management/v1/apps" \
--header "Authorization: Bearer $MANAGEMENT_KEY" \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: support-app-001' \
--data '{
"name": "Support Bot",
"provider_labels": ["Production OpenAI"],
"tags": ["production", "support"]
}'

Abbreviated creation response; additional stored-setting sections and metadata may be present:

{
"app": {
"name": "Support Bot",
"mode": "gateway",
"enabled": true,
"version": "app-v1",
"provider_labels": ["Production OpenAI"],
"tags": ["production", "support"],
"policy_authority": {"enabled": false, "active_revision": null, "active_checksum": null}
},
"key": {
"key_id": "key_example",
"name": "Default",
"secret": "<new-gateway-key>",
"status": "active",
"expires_at": null
},
"warnings": [],
"operation_id": "operation_example",
"request_id": "req_example"
}

The initial key is issued even when initial_key is omitted. Use the gateway credential for runtime calls. Keep using the management credential for configuration.

New apps under QuilrQL

When tenant-wide QuilrQL authority is already enabled, app creation captures the app baseline and can publish an app-specific allowed-models default for all app users. Finite configured model lists receive this default; unrestricted providers and SDK/Copilot Studio apps do not get a finite model list. Matching tenant policies, including explicit model denials, still apply. Creation does not enable authority or change existing drafts. See QuilrQL behavior.

4. Read the current version​

curl --include \
"$MANAGEMENT_URL/llmgateway/management/v1/apps/Support%20Bot" \
--header "Authorization: Bearer $MANAGEMENT_KEY"

Use the returned ETag in updates. The example below assumes it is "app-v1"; use the actual value from your read.

5. Disable and re-enable​

curl --request PATCH \
"$MANAGEMENT_URL/llmgateway/management/v1/apps/Support%20Bot" \
--header "Authorization: Bearer $MANAGEMENT_KEY" \
--header 'Content-Type: application/json' \
--header 'If-Match: "app-v1"' \
--data '{"enabled":false}'

This preserves the app, prompts, provider references and keys. After a gateway observes the change, newly admitted traffic is rejected for all app authentication modes. Existing requests finish normally.

To re-enable, read the latest ETag and PATCH {"enabled":true}. Keys that expired or were revoked while the app was disabled remain invalid. Propagation is asynchronous; the API does not promise an instantaneous global kill switch.

Next steps​

TaskReference
Add another shared providerAttach a provider
Configure guardrails, routing or limitsFull configuration input
Issue a separate automation keyGateway credentials
Understand new-app policy defaultsQuilrQL behavior
Add a system promptPrompt Store
Set spend or usage budgetsBudgets API
Route a model alias, shift traffic or set failoverRouting and failover API
Set request and token rate limitsRate limits API
Take a provider out of routing during an outageIncidents API
Report spend, requests and tokensUsage API
Build latency, cache or error dashboards, list requests, check guardrail activity or provider health, or explain one requestMonitoring API
Review who uses the gatewayUsers API
Configure self-service access plans, decide requests or manage personal keysSelf-service API
Approve models a provider started offeringReview new models
Try any call from the browserManagement API playground

Authentication and management keys​

Two gates enable access: the deployment switch and tenant opt-in. Every management key belongs to exactly one tenant; one tenant can have multiple keys for independent automation clients.

Request authentication​

Authorization: Bearer <management-key>

The key establishes the tenant. Caller-supplied tenant headers cannot expand that scope. Gateway inference keys, log-export credentials and management keys are not interchangeable.

CredentialPurposeSecret retrieval
Management keyRead/write authorized tenant configuration.Issuance only; cannot reveal it later.
Gateway app keyRuntime access to one canonical gateway app.Explicit reveal with credentials:read.
Verified administrator identityOpt in a tenant; create, change or revoke management keys.Follows the administration identity provider.

Enablement and lifecycle​

  1. Self-hosted only: management is on by default. Your operator can turn it off for the whole deployment; every management route then returns 404.
  2. An authorized administrator enables management for the tenant.
  3. The administrator creates a named key with explicit scopes and, optionally, an expiry.
  4. Store the returned secret. Issue a replacement key before revoking a key used by an existing integration.

Disabling tenant management suspends its keys. Re-enabling restores keys that remain unexpired and unrevoked. This does not enable/disable gateway apps. Tenant admins may continue to inspect enablement and revoke keys while tenant management is suspended, provided the deployment gate is enabled.

Management keys do not expire by default. expires_at is a future RFC 3339 timestamp or null. On PATCH, omission preserves the current expiry and null clears it. Expired and revoked keys are terminal: issue a new key instead of resurrecting one.

Scopes​

All scopes listed for an operation are required. No scope implies another.

ScopeGrants
readRead apps, providers, quota pools, credentials metadata, prompts, catalogs, history, operation status, usage (including per-key last use), guardrail activity, provider health, request explanations, users, self-service profiles, evaluate, coverage, requests, personal keys and the usage report, new-model reviews and the OpenAPI document.
config:writeChange app settings, attachments and prompts; roll back and recover app writes; decide new-model reviews of providers an app holds with its own keys; change self-service profiles, settings (model options and app templates), suspensions and app owners, and approve, reject or revoke self-service requests.
providers:writeCreate, update and delete shared providers and quota pools; run provider tests and model discovery; decide new-model reviews of shared providers.
credentials:writeIssue, change expiry of and revoke gateway keys.
credentials:readReveal the secret of an active gateway key.
budgets:readRead budgets, usage, subjects, grants, pricing, exemptions, alerts and events. Does not need read.
budgets:grantIssue, change and revoke budget grants.
budgets:policyEdit budgets, pricing, exemptions and alert destinations. Each budget, pricing or exemption edit publishes a policy revision.
routing:readRead routes, destinations, failover, routing constraints, model access, provider references, revision history and rollout, and run the routing diagnostics. Does not need read.
routing:writeChange routes, destinations, failover profiles, rules and default, and model access. Each write publishes a policy revision. A revision restore needs the write scope of every collection it restores.
routing:constraintsChange routing constraints.
limits:readRead rate limits, request guards, model limits, exemptions, limit responses, live usage, grants and effective limits. Does not need read.
limits:writeChange rate limits, request guards, model limits, exemptions and limit responses, and migrate older app limits. Each write publishes a policy revision.
limits:grantIssue and revoke temporary rate limit raises.
incidents:readRead incident mark-downs and status. read and incidents:write also allow these reads.
incidents:writeMark providers down, preview, restore, reset cooldowns and drop session pins. Never a policy revision.
hooks:writeCreate, change, delete and test external hooks. Each write publishes a policy revision. Reading hooks, the field catalog, previews and stats needs read.
keys:writeIssue, rename, change the expiry of and revoke personal API keys on a user's behalf. Reading them needs read (see the Self-service API).
agents:writeDeclare, change and undeclare agents, and create, change and delete agent groups (see the Agents API). Reading agents, groups and families needs read.

App creation requires both config:write and credentials:write because it issues an initial gateway credential. Attaching an existing provider needs config:write; changing that shared provider needs providers:write. GET /capabilities returns the calling key's scopes in caller.scopes, so a tool can hide actions it cannot perform.

Policy scopes (policy:write, policy:publish) and app-restricted management keys are Not Generally Available. The nineteen scopes above are the accepted scopes and apply tenant-wide.

Administration boundary​

The /llmgateway/management-admin/v1 routes require Authorization: Bearer <Quilr user JWT>, the signed token of a console user. The verified JWT must include the selected tenant in tenantIds and identify the user with sub, userId or email. Tenant headers and other credentials do not authorize access. A management key cannot grant itself permissions or enable its tenant.

GET/PATCH tenant settings controls { "enabled": true }. GET/POST tenant keys lists metadata or creates a management key. PATCH/DELETE a key changes its name/scopes/expiry or revokes it. Dedicated rotation and per-key pause/resume are Not Generally Available; issue a replacement and then revoke the old key.

Lists return each key's version, status, creator, creation/expiry/revocation times and last_used_at. Use the quoted version as If-Match for editing or revoking that key. Management-key timestamps are Unix seconds, potentially fractional; request expires_at values use RFC 3339. List responses never include the secret. Later management-secret retrieval is Not Generally Available; retain the issuance response.

Key creation requires Idempotency-Key. The same administrator can replay the completed issuance response, including its secret, for 24 hours using the same key and payload. After that window, the token cannot create another key. See retry and recovery.

GET/admin/tenants/{tenant_id}/hooks

List the tenant's external hooks

Read-only view of the tenant's external hooks for the console: the active policy revision and every hook in the same view as GET /controls/hooks (secrets masked as ********). Hooks are configured only through the Management API. While the policy engine is off for the tenant the answer is {"revision": null, "hooks": []}.

REQUIRESVerified tenant administrator
Path, query & header parameters 1
tenant_id (path)stringrequired

Quilr tenant ID.

No request body.

curl --request GET \
'https://guardrails-usa-1.quilr.ai/llmgateway/management-admin/v1/tenants/your-tenant-id/hooks' \
--header 'Authorization: Bearer <tenant-admin-token>'

Authentication, errors & retry rules Try it in the playground

GET/admin/tenants/{tenant_id}/keys

List management keys

Management keys of the tenant: metadata, scopes, status and version, never the secret.

REQUIRESVerified tenant administrator
Path, query & header parameters 3
tenant_id (path)stringrequired

Quilr tenant ID.

limit (query)integeroptional

Page size.

min: 1max: 200default: 50
cursor (query)stringoptional

Opaque cursor from the previous page's next_cursor.

No request body.

curl --request GET \
'https://guardrails-usa-1.quilr.ai/llmgateway/management-admin/v1/tenants/your-tenant-id/keys?limit=50' \
--header 'Authorization: Bearer <tenant-admin-token>'

Authentication, errors & retry rules Try it in the playground

POST/admin/tenants/{tenant_id}/keys

Issue a management key

Issues a management key with the given scopes; the secret is returned once. Management must be enabled for the tenant (403 management_disabled_for_tenant). A retry by the same administrator with the same Idempotency-Key within 24 hours returns the same key.

REQUIRESVerified tenant administrator
Path, query & header parameters 2
tenant_id (path)stringrequired

Quilr tenant ID.

Idempotency-Key (header)stringrequired

Unique per logical write. A retry with the same key and body replays the original result for 24 hours; the same key with a different body is a 409.

min length: 1max length: 200
Full request body specification application/json

expires_atstring | nulloptional

Future RFC 3339 time with a timezone; null never expires.

format: date-time
namestringrequired
min length: 1max length: 120
scopesarray<object>required
min items: 1
Array item specification
object

Values: "budgets:grant""budgets:policy""budgets:read""config:write""credentials:read""credentials:write""hooks:write""incidents:read""incidents:write""keys:write""limits:grant""limits:read""limits:write""providers:write""read""routing:constraints""routing:read""routing:write"

Unknown fields are rejected in this object.

curl --request POST \
'https://guardrails-usa-1.quilr.ai/llmgateway/management-admin/v1/tenants/your-tenant-id/keys' \
--header 'Authorization: Bearer <tenant-admin-token>' \
--header 'Idempotency-Key: create-support-bot-001' \
--header 'Content-Type: application/json' \
--data '{
"expires_at": null,
"name": "Deployment automation",
"scopes": [
"read",
"config:write",
"providers:write",
"credentials:write"
]
}'

Authentication, errors & retry rules Try it in the playground

DELETE/admin/tenants/{tenant_id}/keys/{key_id}

Revoke a management key

Revokes the key immediately; it can no longer authenticate. Use key.version from the list as a quoted If-Match.

REQUIRESVerified tenant administrator
Path, query & header parameters 3
tenant_id (path)stringrequired

Quilr tenant ID.

key_id (path)stringrequired
If-Match (header)stringrequired

Quoted version from the latest read of the resource. Prompt, attachment, conversion and rollback writes use the app version.

Full request body specification application/json

Unknown fields are rejected in this object.

curl --request DELETE \
'https://guardrails-usa-1.quilr.ai/llmgateway/management-admin/v1/tenants/your-tenant-id/keys/6b0e2c1a-4f3d-4c55-9a1e-0d2b7f8c9e10' \
--header 'Authorization: Bearer <tenant-admin-token>' \
--header 'If-Match: "3f1c0a9e5b7d"'

Authentication, errors & retry rules Try it in the playground

PATCH/admin/tenants/{tenant_id}/keys/{key_id}

Update a management key

Changes the name, scopes or expiry of a management key. Use key.version from the list as a quoted If-Match.

REQUIRESVerified tenant administrator
Path, query & header parameters 3
tenant_id (path)stringrequired

Quilr tenant ID.

key_id (path)stringrequired
If-Match (header)stringrequired

Quoted version from the latest read of the resource. Prompt, attachment, conversion and rollback writes use the app version.

Full request body specification application/json

expires_atstring | nulloptional

Future RFC 3339 time with a timezone; null never expires.

format: date-time
namestringoptional
min length: 1max length: 120
scopesarray<object>optional
min items: 1
Array item specification
object

Values: "budgets:grant""budgets:policy""budgets:read""config:write""credentials:read""credentials:write""hooks:write""incidents:read""incidents:write""keys:write""limits:grant""limits:read""limits:write""providers:write""read""routing:constraints""routing:read""routing:write"

Unknown fields are rejected in this object.

curl --request PATCH \
'https://guardrails-usa-1.quilr.ai/llmgateway/management-admin/v1/tenants/your-tenant-id/keys/6b0e2c1a-4f3d-4c55-9a1e-0d2b7f8c9e10' \
--header 'Authorization: Bearer <tenant-admin-token>' \
--header 'If-Match: "3f1c0a9e5b7d"' \
--header 'Content-Type: application/json' \
--data '{
"name": "Production automation",
"scopes": [
"read",
"config:write"
]
}'

Authentication, errors & retry rules Try it in the playground

GET/admin/tenants/{tenant_id}/outbound-ips

Read the tenant's outbound IP setting

The same view as GET /outbound-ips, plus the settings version.

REQUIRESVerified tenant administrator
Path, query & header parameters 1
tenant_id (path)stringrequired

Quilr tenant ID.

No request body.

curl --request GET \
'https://guardrails-usa-1.quilr.ai/llmgateway/management-admin/v1/tenants/your-tenant-id/outbound-ips' \
--header 'Authorization: Bearer <tenant-admin-token>'

Authentication, errors & retry rules Try it in the playground

PUT/admin/tenants/{tenant_id}/outbound-ips

Set the tenant's outbound IP setting

Sets enabled, region, or both. Send the quoted version from the latest read in If-Match.

REQUIRESVerified tenant administrator
Path, query & header parameters 2
tenant_id (path)stringrequired

Quilr tenant ID.

If-Match (header)stringrequired

Quoted version from the latest read of the resource. Prompt, attachment, conversion and rollback writes use the app version.

Full request body specification application/json

enabledboolean | nulloptional

true: every provider without a use_outbound_ips setting of its own calls out from the Quilr outbound IPs. false or null: those providers are called directly.

regionstring | nulloptional

The region whose Quilr outbound IPs are used; null: the gateway's own region.

"us""eu""in"null

Unknown fields are rejected in this object.

curl --request PUT \
'https://guardrails-usa-1.quilr.ai/llmgateway/management-admin/v1/tenants/your-tenant-id/outbound-ips' \
--header 'Authorization: Bearer <tenant-admin-token>' \
--header 'If-Match: "3f1c0a9e5b7d"' \
--header 'Content-Type: application/json' \
--data '{
"enabled": true,
"region": "in"
}'

Authentication, errors & retry rules Try it in the playground

GET/admin/tenants/{tenant_id}/settings

Read tenant management settings

Whether management is enabled for the tenant (off by default) and the settings version.

REQUIRESVerified tenant administrator
Path, query & header parameters 1
tenant_id (path)stringrequired

Quilr tenant ID.

No request body.

curl --request GET \
'https://guardrails-usa-1.quilr.ai/llmgateway/management-admin/v1/tenants/your-tenant-id/settings' \
--header 'Authorization: Bearer <tenant-admin-token>'

Authentication, errors & retry rules Try it in the playground

PATCH/admin/tenants/{tenant_id}/settings

Enable or suspend tenant management

Turns management on or off for the tenant. Suspending keeps keys; unexpired, unrevoked keys work again when management is re-enabled. Send the quoted version from the latest read in If-Match.

REQUIRESVerified tenant administrator
Path, query & header parameters 2
tenant_id (path)stringrequired

Quilr tenant ID.

If-Match (header)stringrequired

Quoted version from the latest read of the resource. Prompt, attachment, conversion and rollback writes use the app version.

Full request body specification application/json

enabledbooleanrequired

Unknown fields are rejected in this object.

curl --request PATCH \
'https://guardrails-usa-1.quilr.ai/llmgateway/management-admin/v1/tenants/your-tenant-id/settings' \
--header 'Authorization: Bearer <tenant-admin-token>' \
--header 'If-Match: "3f1c0a9e5b7d"' \
--header 'Content-Type: application/json' \
--data '{
"enabled": true
}'

Authentication, errors & retry rules Try it in the playground

API conventions and errors​

Enablement and authentication​

Call the regional host your organization uses. Self-hosted deployments can turn management off; both route families then return 404. Self-hosted nodes connected to a QuilrAI-hosted service return 503 central_service_required.

Resource routes use /llmgateway/management/v1 and Authorization: Bearer <qlmgmt_...>. The key establishes the tenant. Administrator routes use /llmgateway/management-admin/v1 and a verified tenant-admin JWT; see authentication.

Send JSON bodies with Content-Type: application/json. Requests are capped at 1 MiB, request bodies must arrive within a bounded time (408 otherwise), and concurrent management requests are limited (429 when reached). Provider tests and model discovery are time-bounded. Secret-bearing values are omitted from ordinary reads. Responses use Cache-Control: no-store and X-Request-ID.

Response formats​

  • Timestamps. Every *_at and timestamp text field is UTC RFC 3339 with seconds and Z, for example 2026-11-05T10:00:00Z. Numeric times (such as completed_at and audit created_at) stay Unix seconds. Text you wrote yourself, such as hook templates, tags and prompt content, is returned exactly as written.
  • ETag header. Single-resource reads send ETag, the quoted body version. Header names are case-insensitive: over HTTP/1.1 it can arrive as Etag.
  • Unknown fields. A body field or query parameter the operation does not take is refused (400 or 422). The message and fields name every one of them.

Names and pagination​

Use URL-encoded paths for simple names. For app names containing /, % or other proxy-sensitive characters, use the /app query aliases and encode app_name once. Every app subresource supports the same alias, for example /app/keys?app_name=Team%20%2F%20Support. The reference lists each operation once, in its path form; the aliases take the same inputs and are marked x-alias-of in the OpenAPI document.

Paginated lists accept limit (1-200, default 50) and cursor:

{"items": [], "next_cursor": null, "request_id": "req_example"}

There is no has_more; continue while next_cursor is non-null. A changed collection returns 409 collection_changed; restart pagination. App lists additionally support name substring, tag, enabled=true|false, and origin=blueprint|admin with created_by for apps people created in self-service. Provider lists support type, enabled, tag and model filters. Group and definition lists support no additional filters; audit lists filter by actor, operation, resource, since and until. Budget lists have their own filters and accept limit up to 500 (default 100). Routing and limit control lists also accept limit up to 500 (default 100) and filter by source, app, requested_model, mode and references; see Writes, versions and idempotency. App-provider attachments return an ordered provider_labels array and app version, not a paginated collection.

Versions and preconditions​

Read the current resource version, then send its quoted value in If-Match. Missing preconditions return 428; stale versions return 412. Re-read and reconcile the intended change.

App updates, provider attachments/conversion, all prompt mutations and configuration rollback use the app ETag. Provider changes use the provider ETag. Gateway credential changes use the individual credential GET version. Management-key changes use key.version from the admin list. Tenant enablement changes use the settings version.

Creating a new prompt needs no If-Match; replacing or deleting one needs the app ETag. If-None-Match has no create-only semantics. App and provider lists do not return a collection ETag for editing their members.

Routing and limit controls are the exception: each resource has its own ETag, If-None-Match: * creates only, a PUT of unchanged content is a no-op, and the collection ETag "r<revision>" is accepted in If-Match. Incident mark-downs use mark_down.version. See the Routing and failover API.

Idempotency and recovery​

App, provider, quota-pool, gateway-key and management-key creation and app rollback require a distinct Idempotency-Key per intended operation. Reusing it with different input returns 409. Completed responses are encrypted and replayable for 24 hours to the same principal. Expiry does not permit duplicate issuance using that token. Budget, exemption and grant creates also take an Idempotency-Key; see the Budgets API. Routing and limit quick operations, batches, restores and grants, and incident resets and pin drops, require one; it is optional on control PUT, PATCH and DELETE and on mark-down PUT.

A timeout or 503 does not prove that nothing changed. 503 operation_pending includes error.operation_id when a configuration/creation operation remains incomplete. Configuration recovery uses /operations/{operation_id} and /operations/{operation_id}/recover with the initiating key. Creation recovery retries the original POST and token. See operation recovery.

Provider/credential PATCH and revocation, and provider conversion, have no idempotent replay contract. After a transport/storage error, read current state/version before deciding whether another mutation is needed.

Dates and response formats​

Request expires_at values are future RFC 3339 timestamps with a timezone, or null. Gateway credential expiry responses also use RFC 3339. Management-key metadata, management audit, operation creation and provider-test completion times use Unix seconds, potentially fractional. Treat opaque IDs, versions and fingerprints as strings.

Capabilities fields are at the response root, including schema_version, scopes, caller, app_fields, writes_available, policy_updates, policy_authority, managed_controls (enabled, the available domains, and policy capacity used against the caps), provider_list_filters and the provider types that support tests and model discovery. There is no wrapping capabilities object. Configuration history detail uses version_record. All ordinary JSON responses include request_id; the OpenAPI document is returned as is, without request_id.

Errors​

{
"error": {
"code": "operation_pending",
"message": "Creation is incomplete; retry the same Idempotency-Key to recover",
"operation_id": "operation_example"
},
"request_id": "req_example"
}
StatusMeaning
200Read/update/reveal, revocation, detach, prompt deletion or recovery completed.
201App/provider/key or a previously missing prompt created.
400Invalid fields, values or pagination.
401Invalid, expired or revoked credential.
403Tenant suspended or insufficient permission.
404Deployment disabled or resource missing/outside tenant.
408Request body read timed out.
409Identity/dependency/idempotency conflict, changed collection or report rows between pages, terminal key state, or policy_not_enabled for routing and limit controls while the Policy Engine is off.
412Stale version.
413Request exceeds 1 MiB.
422Unprocessable request, such as a model review decision a model cannot take, or a usage query over 100,000 result rows (result_too_large).
428Required If-Match missing.
429Management concurrency limit reached.
503Storage unavailable, operation pending, or a node that does not accept management calls. Reports (usage, guardrail activity, provider health, users, request explanations) answer 503 query_timeout when a query exceeds its time or read limits (narrow it and retry) and 503 data_unavailable when their data cannot be read right now.

Deletes return JSON with 200, not 204. Provider tests and model discovery always return 200 with the outcome in the body; inspect outcome and code. See tests and model discovery.

Propagation and deployment​

Saved configuration reaches the gateway asynchronously. Whole-app disable rejects new admissions once the change takes effect; existing requests and streams finish.

Management keys, configuration and limits apply per region: use the regional host your organization uses. New keys, revocations and tenant suspension propagate asynchronously, so a change may not be visible on every gateway at once.

Use one base URL per automation run. Retry a create with the same base URL and the same Idempotency-Key, and recover an operation through the same base URL as the original request. Send writes for the same resource through one base URL.

Capability and schema reference​

Features marked Not Generally Available in the availability table are not currently supported. The server publishes its OpenAPI 3.1 document at GET /llmgateway_management_apis/v1/openapi.json (management key with read). It is generated from the deployed routes, carries the required scopes of every operation in x-scopes, and is the same document as the download on this site. Use /capabilities for deployed fields, provider types and test support.

GET/capabilities

Read capabilities

What this deployment supports: every scope, the scopes of the calling key (`caller.scopes`), provider types, writable app fields per section, provider test and model discovery support, and the tenant's QuilrQL authority. Use it to build forms and to hide actions the caller cannot perform.

REQUIRESread

No request body.

curl --request GET \
'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/capabilities' \
--header 'Authorization: Bearer <management-key>'

Authentication, errors & retry rules Try it in the playground

GET/llmgateway_management_apis/v1/openapi.json

Download the OpenAPI document

This OpenAPI 3.1 document, generated by the server from its route table, so it always matches the deployed API. Requires a management key with the read scope.

REQUIRESread
Path, query & header parameters 1
region (query)stringoptional

Publish this region's URL as the only server (e.g. `guardrails-europe-1`). Import into an API gateway with one region only: management idempotency and operation records stay in the region that took the request. Default: a `region` server variable.

"guardrails-usa-1""guardrails-usa-2""guardrails-europe-1""guardrails-india-1""guardrails-india-2""guardrails-jp-1""guardrails"

No request body.

curl --request GET \
'https://guardrails-usa-1.quilr.ai/llmgateway_management_apis/v1/openapi.json' \
--header 'Authorization: Bearer <management-key>'

Authentication, errors & retry rules Try it in the playground

Management API behind Kong​

You can import the Management API's OpenAPI document into Kong the same way as the Inference API, with deck file openapi2kong and deck gateway sync. The spec has one server, https://{region}.quilr.ai.

AreaWhat to do
RegionImport one region per Kong setup. Request a pinned copy with GET /llmgateway_management_apis/v1/openapi.json?region=<value> (for example ?region=guardrails-europe-1), or set the region variable's default before converting. Management configuration and idempotency are per region, so never pool several regions in one upstream.
RetriesSet the Kong upstream retries to 0 for the management service. Retry writes yourself with the same Idempotency-Key (see conventions).
CredentialsPass Authorization: Bearer qlmgmt_... through unchanged. The Management API accepts only that header, not apikey or x-api-key, so do not let key-auth strip or replace it.
HeadersPass the If-Match, If-None-Match and Idempotency-Key request headers, and keep the ETag and X-Request-ID response headers.
ValidationRequest validation is safe here: the management schemas are strict and match the server.
App namesFor app names that contain / or %, use the /app?app_name= aliases: proxies may normalize encoded slashes in paths. See names and pagination.
Admin endpoints/llmgateway/management-admin/v1/* takes a tenant administrator JWT and usually stays off Kong.