Management API
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.
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
- Go to Settings > AI Gateway > LLM Gateway and open the Management API tab.
- Turn on Allow management keys for this organization. Turning it off later suspends every management key until you turn it back on.
- Under Issue a management key, enter a Key name, an optional Expiry, and the Scopes it needs.
- Click Issue key and store the value. It is shown only once.
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
Create, read, configure and pause applications.
Explore referenceProviders & catalogsConfigure shared credentials, test and discover models, review new models, and read catalogs and config history.
Explore referenceQuota poolsDescribe upstream limits that several providers or models share.
Explore referenceBudgetsSet spend, request and token budgets and group budget sets, track usage and issue grants.
Explore referenceSmart groupsRank groups, manage virtual groups and preview who changes governing group.
Explore referenceAgentsList agents and coding tools seen in traffic, declare agents and build agent groups.
Explore referenceRouting and failoverRoutes, weighted destinations, failover and constraints, with dry runs, history and restore.
Explore referenceRate limitsRequest and token rate limits, request guards, temporary raises and effective limits.
Explore referenceAccess and featuresAccess controls, token saving, response cache, cache warm, model visibility, error messages and prompt enforcement.
Explore referenceIncidentsMark a provider down during an outage, check it applied, then restore it.
Explore referenceHooksCall your own API to allow, flag or block requests and responses, or export finished requests.
Explore referenceUsageRequests, tokens and cost by period, app, model, provider, user, key, source or outcome.
Explore referenceMonitoringGuardrail activity, provider health, and why one request was routed, blocked or failed over.
Explore referenceUsersWho uses the gateway: app access, personal keys, last activity and usage.
Explore referenceSelf-serviceAccess plans, model options, app templates, requests, app owners and personal keys for the developer portal.
Explore referenceAuthenticationEnable access and issue scoped management keys.
Explore referenceGateway credentialsIssue, rename, reveal, expire and revoke app keys.
Explore referenceQuilrQL behaviorUnderstand app defaults and policy-governed settings.
Explore referencePromptsManage Prompt Store content.
Explore referenceThe management model
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.
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.
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 %)
/admin/tenants/{tenant_id}/hooksList the tenant's external hooks/admin/tenants/{tenant_id}/keysList management keys/admin/tenants/{tenant_id}/keysIssue a management key/admin/tenants/{tenant_id}/keys/{key_id}Revoke a management key/admin/tenants/{tenant_id}/keys/{key_id}Update a management key/admin/tenants/{tenant_id}/outbound-ipsRead the tenant's outbound IP setting/admin/tenants/{tenant_id}/outbound-ipsSet the tenant's outbound IP setting/admin/tenants/{tenant_id}/settingsRead tenant management settings/admin/tenants/{tenant_id}/settingsEnable or suspend tenant management/appsList apps/appsCreate an app/apps/{app_name}Read an app/apps/{app_name}Update or disable an app/apps/{app_name}/keysList gateway credentials/apps/{app_name}/keysIssue a gateway credential/apps/{app_name}/keys/{key_id}Revoke a gateway credential/apps/{app_name}/keys/{key_id}Read a gateway credential/apps/{app_name}/keys/{key_id}Rename a gateway key or change its expiry/apps/{app_name}/keys/{key_id}/revealReveal a gateway credential/apps/{app_name}/promptsList prompts/apps/{app_name}/prompts/{prompt_id}Delete a prompt/apps/{app_name}/prompts/{prompt_id}Read a prompt/apps/{app_name}/prompts/{prompt_id}Create or replace a prompt/apps/{app_name}/provider-conversionConvert inline providers/apps/{app_name}/providersList app providers/apps/{app_name}/providers/{label}Detach an app provider/apps/{app_name}/providers/{label}Attach a shared provider/apps/{app_name}/self-service-keysList an app's personal API keys/apps/{app_name}/self-service-keysIssue a personal API key for a user/apps/{app_name}/self-service-keys/{key_id}Revoke a personal API key/apps/{app_name}/self-service-keys/{key_id}Read a personal API key/apps/{app_name}/self-service-keys/{key_id}Rename a personal API key or change its expiry/apps/{app_name}/self-service-ownersSet an app's owners/apps/{app_name}/versionsList app configuration versions/apps/{app_name}/versions/{version_id}Read a configuration version/apps/{app_name}/versions/{version_id}/rollbackRoll back app configuration/auditList audit events/budget-alert-destinationsRead budget alert destinations/budget-alert-destinationsReplace budget alert destinations/budget-alertsList budget alerts/budget-eventsList budget events/budget-exemptionsList budget exemptions/budget-exemptionsCreate a budget exemption/budget-exemptions/{exemption_id}Delete a budget exemption/budget-forecastRead budget forecast/budget-grantsList budget grants/budget-grants/{grant_id}Revoke a budget grant/budget-grants/{grant_id}Read a budget grant/budget-grants/{grant_id}Update a budget grant/budget-pricingRead budget pricing/budget-pricingUpdate unpriced model handling/budget-pricing/rates/{provider}/{model}Remove a model rate/budget-pricing/rates/{provider}/{model}Set a model rate/budget-setsList group budget sets/budget-setsCreate a group budget set/budget-sets/{set_id}Delete a group budget set/budget-sets/{set_id}Read a group budget set/budget-sets/{set_id}Switch how a group budget set resolves/budget-sets/{set_id}/groupsAdd a group to a budget set/budget-sets/{set_id}/groups/{group}Remove a group from a budget set/budget-subjectsList budget subjects/budget-subjects/{kind}/{value}Read a budget subject/budget-usage-summaryRead budget usage summary/budgetsList budgets/budgetsCreate a budget/budgets/_batchApply budget changes in a batch/budgets/{budget_id}Delete a budget/budgets/{budget_id}Read a budget/budgets/{budget_id}Update a budget/budgets/{budget_id}/burn-rateRead budget burn rate/budgets/{budget_id}/grantsIssue a budget grant/budgets/{budget_id}/grants/_bulkIssue budget grants in bulk/budgets/{budget_id}/usageRead budget usage/capabilitiesRead capabilities/controls/_batchApply a batch of control changes/controls/_capacityRead policy capacity/controls/accessList access controls/controls/access/{resource_id}Delete an access control/controls/access/{resource_id}Read an access control/controls/access/{resource_id}Update an access control/controls/access/{resource_id}Create or replace an access control/controls/cache-warmList cache warm settings/controls/cache-warm/{resource_id}Delete a cache warm setting/controls/cache-warm/{resource_id}Read a cache warm setting/controls/cache-warm/{resource_id}Update a cache warm setting/controls/cache-warm/{resource_id}Create or replace a cache warm setting/controls/complexity-levelsList complexity levels/controls/complexity-levels/{resource_id}Delete a complexity levels/controls/complexity-levels/{resource_id}Read a complexity levels/controls/complexity-levels/{resource_id}Update a complexity levels/controls/complexity-levels/{resource_id}Create or replace a complexity levels/controls/conversation-headersList conversation header settings/controls/conversation-headers/{resource_id}Delete a conversation header setting/controls/conversation-headers/{resource_id}Read a conversation header setting/controls/conversation-headers/{resource_id}Update a conversation header setting/controls/conversation-headers/{resource_id}Create or replace a conversation header setting/controls/destinationsList destinations/controls/destinations/{resource_id}Delete a destination/controls/destinations/{resource_id}Read a destination/controls/destinations/{resource_id}Update a destination/controls/destinations/{resource_id}Create or replace a destination/controls/destinations/{resource_id}:replace-memberReplace member of a destination/controls/destinations/{resource_id}:set-weightsSet weights of a destination/controls/error-messagesList error message settings/controls/error-messages/{resource_id}Delete an error message setting/controls/error-messages/{resource_id}Read an error message setting/controls/error-messages/{resource_id}Update an error message setting/controls/error-messages/{resource_id}Create or replace an error message setting/controls/failover-defaultReset the failover default/controls/failover-defaultRead the failover default/controls/failover-defaultCreate or replace the failover default/controls/failover-profilesList failover profiles/controls/failover-profiles/{resource_id}Delete a failover profile/controls/failover-profiles/{resource_id}Read a failover profile/controls/failover-profiles/{resource_id}Update a failover profile/controls/failover-profiles/{resource_id}Create or replace a failover profile/controls/failover-rulesList failover rules/controls/failover-rules/{resource_id}Delete a failover rule/controls/failover-rules/{resource_id}Read a failover rule/controls/failover-rules/{resource_id}Update a failover rule/controls/failover-rules/{resource_id}Create or replace a failover rule/controls/hooksList hooks/controls/hooks/field-catalogList the fields a hook can send/controls/hooks/previewPreview the call a hook would make/controls/hooks/{resource_id}Delete a hook/controls/hooks/{resource_id}Read a hook/controls/hooks/{resource_id}Update a hook/controls/hooks/{resource_id}Create or replace a hook/controls/hooks/{resource_id}/statsRead hook delivery stats/controls/hooks/{resource_id}/testSend a test call with a saved hook/controls/limit-exemptionsList limit exemptions/controls/limit-exemptions/{resource_id}Delete a limit exemption/controls/limit-exemptions/{resource_id}Read a limit exemption/controls/limit-exemptions/{resource_id}Update a limit exemption/controls/limit-exemptions/{resource_id}Create or replace a limit exemption/controls/limit-responsesList limit responses/controls/limit-responses/{resource_id}Delete a limit response/controls/limit-responses/{resource_id}Read a limit response/controls/limit-responses/{resource_id}Update a limit response/controls/limit-responses/{resource_id}Create or replace a limit response/controls/model-accessList model access rules/controls/model-access/{resource_id}Delete a model access rule/controls/model-access/{resource_id}Read a model access rule/controls/model-access/{resource_id}Update a model access rule/controls/model-access/{resource_id}Create or replace a model access rule/controls/model-limitsList model limits/controls/model-limits/{resource_id}Delete a model limit/controls/model-limits/{resource_id}Read a model limit/controls/model-limits/{resource_id}Update a model limit/controls/model-limits/{resource_id}Create or replace a model limit/controls/model-visibilityList model visibility settings/controls/model-visibility/{resource_id}Delete a model visibility setting/controls/model-visibility/{resource_id}Read a model visibility setting/controls/model-visibility/{resource_id}Update a model visibility setting/controls/model-visibility/{resource_id}Create or replace a model visibility setting/controls/prompt-enforcementList prompt enforcement settings/controls/prompt-enforcement/{resource_id}Delete a prompt enforcement setting/controls/prompt-enforcement/{resource_id}Read a prompt enforcement setting/controls/prompt-enforcement/{resource_id}Update a prompt enforcement setting/controls/prompt-enforcement/{resource_id}Create or replace a prompt enforcement setting/controls/rate-limitsList rate limits/controls/rate-limits/{resource_id}Delete a rate limit/controls/rate-limits/{resource_id}Read a rate limit/controls/rate-limits/{resource_id}Update a rate limit/controls/rate-limits/{resource_id}Create or replace a rate limit/controls/rate-limits/{resource_id}/grantsList rate limit grants/controls/rate-limits/{resource_id}/grantsGrant a temporary raise/controls/rate-limits/{resource_id}/grants/{grant_id}Revoke a grant/controls/rate-limits/{resource_id}/usageRead rate limit usage/controls/rate-limits:migrate-legacyMigrate legacy limits/controls/referencesList references to a provider label/controls/request-guardsList request guards/controls/request-guards/{resource_id}Delete a request guard/controls/request-guards/{resource_id}Read a request guard/controls/request-guards/{resource_id}Update a request guard/controls/request-guards/{resource_id}Create or replace a request guard/controls/response-cacheList response cache settings/controls/response-cache/{resource_id}Delete a response cache setting/controls/response-cache/{resource_id}Read a response cache setting/controls/response-cache/{resource_id}Update a response cache setting/controls/response-cache/{resource_id}Create or replace a response cache setting/controls/revisionsList policy revisions/controls/revisions/{revision}/resources/{collection}/{resource_id}Read a resource at a revision/controls/revisions/{revision}/statusRead revision rollout/controls/revisions/{revision}:restoreRestore controls from a revision/controls/routesList routes/controls/routes/{resource_id}Delete a route/controls/routes/{resource_id}Read a route/controls/routes/{resource_id}Update a route/controls/routes/{resource_id}Create or replace a route/controls/routes/{resource_id}:set-modeSet mode of a route/controls/routing-constraintsList routing constraints/controls/routing-constraints/{resource_id}Delete a routing constraint/controls/routing-constraints/{resource_id}Read a routing constraint/controls/routing-constraints/{resource_id}Update a routing constraint/controls/routing-constraints/{resource_id}Create or replace a routing constraint/controls/token-savingList token saving settings/controls/token-saving/{resource_id}Delete a token saving setting/controls/token-saving/{resource_id}Read a token saving setting/controls/token-saving/{resource_id}Update a token saving setting/controls/token-saving/{resource_id}Create or replace a token saving setting/custom-definitionsList custom definitions/custom-definitions/{definition_id}Read a custom definition/failover/summaryRead the failover summary/features/summarySummarize gateway feature metrics/guardrails/summarySummarize guardrail activity/incidents/drop-pinsDrop session pins/incidents/mark-downsList mark-downs/incidents/mark-downs/{mark_down_id}Restore a provider/incidents/mark-downs/{mark_down_id}Read a mark-down/incidents/mark-downs/{mark_down_id}Mark a provider down/incidents/mark-downs:previewPreview a mark-down/incidents/reset-cooldownsReset cooldowns/incidents/statusIncident propagation status/latencySummarize request latency/limits/effectiveRead effective limits/operations/{operation_id}Read operation status/operations/{operation_id}/recoverRecover a pending operation/outbound-ipsRead the outbound IP setting/outbound-ipsTurn Quilr outbound IPs on or off/provider-healthRead provider health/provider-model-reviewsList new-model reviews/provider-model-reviews/{label}Read one provider's new-model reviews/provider-model-reviews/{label}/app-decisionsApprove or reject new models of an app's own provider/provider-model-reviews/{label}/decisionsApprove or reject new models of a shared provider/providersList shared providers/providersCreate a shared provider/providers/available-modelsDiscover models for draft settings/providers/test-settingsTest draft provider settings/providers/{label}Delete a shared provider/providers/{label}Read a shared provider/providers/{label}Update or disable a provider/providers/{label}/available-modelsDiscover provider models/providers/{label}/testTest connection or model/providers/{label}/test-settingsTest provider settings/quota-poolsList quota pools/quota-poolsCreate a quota pool/quota-pools/{pool_id}Delete a quota pool/quota-pools/{pool_id}Read a quota pool/quota-pools/{pool_id}Update a quota pool/requestsList gateway requests/requests/{request_id}/explainExplain a request/routing/effectiveExplain the effective route/routing/summaryRead the routing summary/routing/target-checkCheck routing targets/routing/testTest routing for a sample request/self-service-keysList personal API keys across apps/self-service/blueprint_eligibilityCheck whether apps can be blueprints/self-service/coverageCount people per profile/self-service/coverageCount people per profile for a draft/self-service/evaluateExplain a person's self-service access/self-service/exceptionsList exception requests/self-service/exceptions/{exception_id}Read an exception request/self-service/exceptions/{exception_id}/approveApprove an exception request/self-service/exceptions/{exception_id}/rejectReject an exception request/self-service/exceptions/{exception_id}/revokeRevoke an approved exception/self-service/profilesList self-service profiles/self-service/profilesCreate a self-service profile/self-service/profiles/{profile_id}Delete a self-service profile/self-service/profiles/{profile_id}Read a self-service profile/self-service/profiles/{profile_id}Replace a self-service profile/self-service/settingsUpdate the self-service setting/self-service/suspensionsSuspend a person/self-service/suspensions/removeLift a suspension/self-service/usageReport self-service usage/smart-groupsList smart groups/smart-groupsCreate a virtual smart group/smart-groups/_priority-previewPreview priority changes/smart-groups/{group_name}Delete a virtual smart group/smart-groups/{group_name}Read a smart group/smart-groups/{group_name}Update a smart group or its priority/smart-groups/{group_name}/membersAdd or remove smart group members/usageRead usage/usersList gateway users/users/{email}Read a gateway user/llmgateway_management_apis/v1/openapi.jsonDownload the OpenAPI documentContinue
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:
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:
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.
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
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.
Enablement and lifecycle
- Self-hosted only: management is on by default. Your operator can turn it off for the whole deployment; every management route then returns
404. - An authorized administrator enables management for the tenant.
- The administrator creates a named key with explicit scopes and, optionally, an expiry.
- 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.
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.
/admin/tenants/{tenant_id}/hooksList 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": []}.
Verified tenant administratorPath, query & header parameters 1
tenant_id (path)stringrequiredQuilr 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
/admin/tenants/{tenant_id}/keysList management keys
Management keys of the tenant: metadata, scopes, status and version, never the secret.
Verified tenant administratorPath, query & header parameters 3
tenant_id (path)stringrequiredQuilr tenant ID.
limit (query)integeroptionalPage size.
cursor (query)stringoptionalOpaque 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
/admin/tenants/{tenant_id}/keysIssue 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.
Verified tenant administratorPath, query & header parameters 2
tenant_id (path)stringrequiredQuilr tenant ID.
Idempotency-Key (header)stringrequiredUnique 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.
Full request body specification application/json
expires_atstring | nulloptionalFuture RFC 3339 time with a timezone; null never expires.
namestringrequiredscopesarray<object>requiredArray item specification
objectValues: "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
/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.
Verified tenant administratorPath, query & header parameters 3
tenant_id (path)stringrequiredQuilr tenant ID.
key_id (path)stringrequiredIf-Match (header)stringrequiredQuoted 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
/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.
Verified tenant administratorPath, query & header parameters 3
tenant_id (path)stringrequiredQuilr tenant ID.
key_id (path)stringrequiredIf-Match (header)stringrequiredQuoted 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 | nulloptionalFuture RFC 3339 time with a timezone; null never expires.
namestringoptionalscopesarray<object>optionalArray item specification
objectValues: "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
/admin/tenants/{tenant_id}/outbound-ipsRead the tenant's outbound IP setting
The same view as GET /outbound-ips, plus the settings version.
Verified tenant administratorPath, query & header parameters 1
tenant_id (path)stringrequiredQuilr 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
/admin/tenants/{tenant_id}/outbound-ipsSet the tenant's outbound IP setting
Sets enabled, region, or both. Send the quoted version from the latest read in If-Match.
Verified tenant administratorPath, query & header parameters 2
tenant_id (path)stringrequiredQuilr tenant ID.
If-Match (header)stringrequiredQuoted 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 | nulloptionaltrue: 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 | nulloptionalThe region whose Quilr outbound IPs are used; null: the gateway's own region.
"us""eu""in"nullUnknown 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
/admin/tenants/{tenant_id}/settingsRead tenant management settings
Whether management is enabled for the tenant (off by default) and the settings version.
Verified tenant administratorPath, query & header parameters 1
tenant_id (path)stringrequiredQuilr 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
/admin/tenants/{tenant_id}/settingsEnable 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.
Verified tenant administratorPath, query & header parameters 2
tenant_id (path)stringrequiredQuilr tenant ID.
If-Match (header)stringrequiredQuoted version from the latest read of the resource. Prompt, attachment, conversion and rollback writes use the app version.
Full request body specification application/json
enabledbooleanrequiredUnknown 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
*_atandtimestamptext field is UTC RFC 3339 with seconds andZ, for example2026-11-05T10:00:00Z. Numeric times (such ascompleted_atand auditcreated_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 bodyversion. Header names are case-insensitive: over HTTP/1.1 it can arrive asEtag. - Unknown fields. A body field or query parameter the operation does not take is refused (
400or422). The message andfieldsname 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"
}
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.
/capabilitiesRead 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.
readNo 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
/llmgateway_management_apis/v1/openapi.jsonDownload 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.
readPath, query & header parameters 1
region (query)stringoptionalPublish 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.