Skip to main content

Providers and configuration API

A shared provider is a reusable tenant-owned connection. Apps hold references to its label, so credential/model changes can affect every linked app after synchronization. Provider label and type are immutable.

Shared providers and model tests​

Provider inputs​

Creation requires label, provider_name and credentials for the selected provider type in provider_settings. Optional selected_models, model_costs and enabled configure availability. Optional tags, upstream_limits and per-model model_metadata describe the provider (region, service tier, context window, capabilities, known upstream limits and shared quota pools); they are descriptive and do not change routing or limit enforcement. Use the provider-settings field reference below and the credential requirements for your provider family. Managed QuilrAI providers do not require customer credentials.

FamilyProvider typesCredential choices
API keyOpenAI, Anthropic/native Messages, DeepSeek, Gemini Chat Completions, Responses, Assistants, Realtime, Cohere/Jina/Voyage rerank, Sarvam, Mistral AI (mistral), xAI (xai, xai_responses), Cerebras (cerebras), Groq (groq), Perplexity (perplexity), Cohere (cohere), ElevenLabs (elevenlabs), TypeSafe (typesafe).api_key; optional compatible base URL/version where supported. Mistral, xAI, Cerebras, Groq, Perplexity and TypeSafe ignore base_url.
Azureazureopenai, openai_responses_azure, openai_assistants_azure, openai_realtime_azure.api_key, azure_endpoint, optional azure_api_version.
Custom endpointgeneral, general_rerank, anthropic_messages_azure.api_key and base_url.
AWSbedrock, anthropic_messages_bedrock, bedrock_embeddings, bedrock_rerank.Static keys or assume-role; fields from different modes cannot be mixed.
Vertex AIvertex_ai.API key, express, service-account JSON or ADC.
Oracle OCIoracle, oracle_responses.API key, gateway user principal, user/session principal, instance/resource principal.
QuilrAI managedquilr_ai.Deployment-owned identity; no customer secret or endpoint.

SDK and Copilot Studio are app modes, not shared-provider types. Provider/protocol support remains deployment-dependent. See provider support.

Models and rates​

selected_models is a full replacement list, with at most 1,000 names of up to 512 characters each. An empty list follows the existing unrestricted-provider convention where supported; it does not necessarily mean zero models are allowed. Use explicit model lists for finite allowlists.

model_costs is keyed by a selected model. Each item needs input_per_1m and output_per_1m (USD per million tokens) and can add cache, reasoning, tiered and per-unit rates; expand the ModelCost schema in the endpoint reference for every field. A supplied item replaces that model's stored item, a null item removes it, and other models keep theirs. These prices are used for request cost and spend budgets, after any tenant-wide budget rate for the same model.

Rotation and disabling​

Omitted credentials remain unchanged on PATCH. Submit a new secret to rotate it. Do not send redacted placeholder values back. Changing authentication mode must supply required new-mode fields and removes incompatible old-mode credentials.

PATCH enabled:false to disable a shared provider. Its record and app attachments remain; re-enabling restores normal availability.

Delete a provider with its current version in If-Match. Deletion is refused with 409 provider_in_use, listing the apps, while any app attaches it: detach it from each app first (an app cannot drop its last provider, so attach a replacement first). A deleted provider leaves every quota pool it belonged to. GET /providers?include_deleted=true still lists deleted providers.

Tests and model discovery​

Saving configuration never contacts the upstream provider. Run a test or a discovery when you want to check credentials or find model IDs. Every probe needs providers:write, can incur upstream usage, always answers 200 with the result in the body, and saves nothing: no provider change, no new version.

OperationUse it toResult
Test a saved providerkind:"model" sends one small request to a selected model. kind:"connection" probes the given model, or the first 10 selected models.test with outcome passed, failed or unsupported, a code, and for connection tests one entry per model in models[]. A connection passes when any model probe passes.
Test draft settingsTry new settings on a saved provider before saving them. Draft settings merge onto the stored ones; a blank secret keeps the stored value.test with connection and models[]; outcomes passed, failed, timeout, skipped or unsupported.
Test an unsaved providerCheck a provider type and credentials before creating it.Same as draft settings.
Discover modelsList the models the provider's credentials can reach, for a saved provider or unsaved settings. validate:true also probes each listed model.discovery with outcome (passed, manual_entry for providers without a model list, failed, timeout, skipped or unsupported), models[] and count.
  • Tests and discovery are bounded in both the number of models they probe and the time they take. When more models are selected than a connection test probes, models_truncated is true. A probe that runs out of time reports timeout.
  • Tests use stored or supplied settings only. They take no arbitrary URL or request payload. Testing a disabled provider does not enable it.
  • Secrets in upstream messages are replaced with [redacted], and discovered models are reduced to non-secret fields such as id, owned_by and modalities.
  • Endpoints the management service cannot reach, such as a provider on a private network, are not probed: the saved-provider test reports code: private_endpoint_unreachable, and the other probes report skipped or unsupported. For such providers, use the console to test or discover models, or enter model IDs manually.
  • GET /capabilities lists the provider types each probe supports: model_test_provider_types, connection_test_provider_types and model_discovery_provider_types.

List filters​

GET /providers supports limit and cursor, plus these filters (all combined with AND):

FilterMatches
provider_nameExact provider type, for example openai.
enabledtrue or false.
modelRepeatable. The exact ID is in selected_models.
tagRepeatable. key matches any non-empty tag value; key:value matches a string, a list member, or a boolean or number by its JSON text. Matches provider tags or any selected model's tags, for example tag=region:us-east-1 or tag=canonical_model:gpt-4.1-mini.
include_deletedtrue adds deleted providers.

Any other query parameter (for example q or label) is 400 invalid_request naming it in fields, instead of being ignored and returning every provider.

Saves and reads return { "provider": { ... }, "request_id": "..." }; ordinary responses omit upstream secrets. A PATCH that sends the same secret already stored returns the warning credentials_unchanged, and credentials_updated_at does not move (it records when the secret last changed). A provider test returns the warning model_deprecated when the provider says a tested model is deprecated or retired.

Provider endpoints​

GET/providers

List shared providers

Shared providers of the tenant with secret settings omitted. Filter by provider type, enabled state, tags (repeatable, ANDed) and selected models (repeatable, ANDed); deleted providers are included only with include_deleted=true.

REQUIRESread
Path, query & header parameters 7
limit (query)integeroptional

Page size.

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

Opaque cursor from the previous page's next_cursor.

provider_name (query)stringoptional

Exact provider type.

enabled (query)booleanoptional
tag (query)array<string>optional

Repeatable (ANDed). `key` matches a present, non-empty tag value; `key:value` (split at the first colon) matches a string exactly, a list member, or a boolean/number as JSON (true, 42). Each condition matches the provider's public tags (with presets) or any selected model's public model_metadata tags (including the derived canonical_model).

Array item specification
string
model (query)array<string>optional

Repeatable (ANDed). Exact ID in selected_models.

Array item specification
string
include_deleted (query)booleanoptional
default: false

No request body.

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

Authentication, errors & retry rules Try it in the playground

POST/providers

Create a shared provider

Creates a tenant-wide provider that apps can attach. `label` and `provider_name` are immutable. Credentials go in `provider_settings` and are never returned. Saving never calls the upstream; use the test and available-models operations to check settings.

REQUIRESproviders:write
Path, query & header parameters 1
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

Shared-provider configuration. Saves never call the upstream; use the test and available-models operations to check settings.

enabledbooleanoptional
labelstringrequired

Tenant-unique display name; immutable.

min length: 1max length: 200
model_costsmap<string, one of 2 variants>optional
Map value specification
ModelCost object
audio_input_per_1mnumber | nulloptional
min: 0
audio_input_per_secondnumber | nulloptional
min: 0
audio_input_per_second_byobject | nulloptional
Map value specification
number
min: 0
audio_output_per_1mnumber | nulloptional
min: 0
audio_output_per_secondnumber | nulloptional
min: 0
audio_output_per_second_byobject | nulloptional
Map value specification
number
min: 0
batch_multipliernumber | nulloptional
max: 1greater than: 0
cache_per_1mnumber | nulloptional

Deprecated alias of cache_read_per_1m. Requests may send it (must equal cache_read_per_1m when both are sent); responses echo it equal to cache_read_per_1m whenever that is set, and it is never stored.

min: 0
cache_read_per_1mnumber | nulloptional
min: 0
cache_write_1h_per_1mnumber | nulloptional
min: 0
cache_write_5m_per_1mnumber | nulloptional
min: 0
cache_write_default_ttlstring | nulloptional
"5m""1h""unpriced"null
cache_write_per_1mnumber | nulloptional
min: 0
code_execution_per_hournumber | nulloptional
min: 0
container_per_sessionnumber | nulloptional
min: 0
document_image_input_per_imagenumber | nulloptional
min: 0
document_image_input_per_image_byobject | nulloptional
Map value specification
number
min: 0
file_search_per_1knumber | nulloptional
min: 0
grounding_per_1knumber | nulloptional
min: 0
image_input_per_1mnumber | nulloptional
min: 0
image_input_per_imagenumber | nulloptional
min: 0
image_input_per_image_byobject | nulloptional
Map value specification
number
min: 0
image_output_per_1mnumber | nulloptional
min: 0
image_output_per_imagenumber | nulloptional
min: 0
image_output_per_image_byobject | nulloptional
Map value specification
number
min: 0
input_per_1mnumber | nullrequired
min: 0
input_per_1m_charactersnumber | nulloptional
min: 0
input_per_1m_characters_byobject | nulloptional
Map value specification
number
min: 0
output_per_1mnumber | nullrequired
min: 0
pages_per_1knumber | nulloptional
min: 0
pages_per_1k_byobject | nulloptional
Map value specification
number
min: 0
reasoning_per_1mnumber | nulloptional
min: 0
regional_multipliersobject | nulloptional
Object fields
data_residencynumber | nulloptional
greater than: 0
geonumber | nulloptional
greater than: 0
regionalnumber | nulloptional
greater than: 0
us_onlynumber | nulloptional
greater than: 0

Unknown fields are rejected in this object.

requests_per_1knumber | nulloptional
min: 0
requests_per_1k_byobject | nulloptional
Map value specification
number
min: 0
search_units_per_1knumber | nulloptional
min: 0
search_units_per_1k_byobject | nulloptional
Map value specification
number
min: 0
service_tier_multipliersobject | nulloptional
Object fields
fastnumber | nulloptional
greater than: 0
flexnumber | nulloptional
greater than: 0
prioritynumber | nulloptional
greater than: 0

Unknown fields are rejected in this object.

text_input_per_requestnumber | nulloptional
min: 0
text_input_per_request_byobject | nulloptional
Map value specification
number
min: 0
tiersarray | nulloptional
max items: 8
video_input_per_secondnumber | nulloptional
min: 0
video_input_per_second_byobject | nulloptional
Map value specification
number
min: 0
video_output_per_secondnumber | nulloptional
min: 0
video_output_per_second_byobject | nulloptional
Map value specification
number
min: 0
web_fetch_per_1knumber | nulloptional
min: 0
web_search_per_1knumber | nulloptional
min: 0

Unknown fields are rejected in this object.

Also accepts null.

model_metadataobject | nulloptional

Model facts keyed by selected ID. Absent fields inherit compatible catalog defaults; nested nulls remain unknown. A null model item resets its saved overrides to the catalog.

Map value specification
cachingobject | nulloptional
Object fields
min_cacheable_tokensinteger | nulloptional
min: 0max: 9007199254740991
supportstring | nulloptional
"supported""unsupported""conditional""unknown"null
supported_ttlsarray | nulloptional
max items: 16unique items

Unknown fields are rejected in this object.

capabilitiesobject | nulloptional
Object fields
supports_json_modeboolean | nulloptional
supports_json_schemaboolean | nulloptional
supports_parallel_tool_callsboolean | nulloptional
supports_streamingboolean | nulloptional
supports_tool_callingboolean | nulloptional

Unknown fields are rejected in this object.

input_formatsarray | nulloptional
max items: 32unique items
input_modalitiesarray | nulloptional
max items: 32unique items
lifecycleobject | nulloptional
Object fields
retirement_datestring | nulloptional
format: date
statusstring | nulloptional
"unknown""preview""stable""deprecated""retired"null

Unknown fields are rejected in this object.

limitsobject | nulloptional
Object fields
context_window_tokensinteger | nulloptional
min: 1max: 9007199254740991
max_input_tokensinteger | nulloptional
min: 1max: 9007199254740991
max_output_tokensinteger | nulloptional
min: 1max: 9007199254740991
max_reasoning_tokensinteger | nulloptional
min: 0max: 9007199254740991

Unknown fields are rejected in this object.

output_formatsarray | nulloptional
max items: 32unique items
output_modalitiesarray | nulloptional
max items: 32unique items
provenanceobject | nulloptional
Object fields
last_verified_atstring | nulloptional
format: date-time
sourcestring | nulloptional
"manual""provider_api""catalog"null
source_urlstring | nulloptional
max length: 2048
updated_atstring | nulloptional
format: date-time

Unknown fields are rejected in this object.

reasoning_tokens_in_output_budgetboolean | nulloptional
supported_reasoning_effortsarray | nulloptional
max items: 16unique items
tagsobject | nulloptional

At most 64 active tags including the canonical identity preset, plus 1024 stored null clears. Null custom tags are hidden from public views; canonical_model:null resets the identity to its catalog default or model ID.

Map value specification
Variant 1 string
string
max length: 512
Variant 2 boolean
boolean
Variant 3 number
number
Variant 4 array | null
array | null
max items: 32unique items

Also accepts null.

temperatureobject | nulloptional
Object fields
conditionsstring | nulloptional
max length: 1024
defaultnumber | nulloptional
min: 0
maxnumber | nulloptional
min: 0
minnumber | nulloptional
min: 0
supportstring | nulloptional
"supported""unsupported""conditional""unknown"null

Unknown fields are rejected in this object.

upstream_limitsobject | nulloptional
Object fields
input_tpminteger | nulloptional
min: 0max: 9007199254740991
max_inflight_requestsinteger | nulloptional
min: 0max: 9007199254740991
output_tpminteger | nulloptional
min: 0max: 9007199254740991
rpminteger | nulloptional
min: 0max: 9007199254740991
shared_quota_pool_idsarray | nulloptional
max items: 32unique items
total_tpminteger | nulloptional
min: 0max: 9007199254740991

Unknown fields are rejected in this object.

Unknown fields are rejected in this object.

model_metadata_resetmap<string, array<string>>optional

Dotted metadata paths per selected model whose stored override is removed, so the catalog default shows through again. Distinct from null (= unknown).

Map value specification
array<string>
max items: 64
provider_namestringrequired

Provider type; immutable.

"openai""azureopenai""general""anthropic""anthropic_messages""anthropic_messages_bedrock""anthropic_messages_azure""deepseek""vertex_ai""gemini_chatcompletions""oracle""openai_responses""openai_responses_azure""oracle_responses""openai_assistants""openai_assistants_azure""openai_realtime""openai_realtime_azure""bedrock""bedrock_embeddings""cohere_rerank""bedrock_rerank""jina_rerank""voyage_rerank""general_rerank""sarvam""mistral""xai""xai_responses""cerebras""typesafe""groq""perplexity""cohere"
provider_settingsobjectoptional

Settings for the chosen provider type; required credentials depend on it and are validated against the merged configuration. Secret values are never returned.

write only
Object fields
anthropic_versionstringoptional

Anthropic API version header.

api_keystringoptional

Provider API key. Write-only.

min length: 1write only
auth_typestringoptional

Authentication mode for providers that support several.

aws_access_keystringoptional

Secret. Write-only.

min length: 1write only
aws_auth_modestringoptional

static (access keys) or assume_role.

aws_bedrock_api_keystringoptional

Secret. Write-only.

min length: 1write only
aws_bedrock_chat_apistringoptional
aws_bedrock_endpointstringoptional
aws_bedrock_openai_pathstringoptional
aws_external_idstringoptional

Secret. Write-only.

min length: 1write only
aws_regionstringoptional
aws_role_arnstringoptional
aws_role_session_namestringoptional
aws_secret_keystringoptional

Secret. Write-only.

min length: 1write only
aws_session_duration_secondsintegeroptional

Assumed-role session length, 900-43200.

min: 900max: 43200
aws_session_tokenstringoptional

Secret. Write-only.

min length: 1write only
azure_api_versionstringoptional

Azure API version.

azure_auth_headerstringoptional

Azure providers: the header the key is sent in. Omit (or api-key) for api-key, authorization_bearer for 'Authorization: Bearer <key>', or a header name such as Ocp-Apim-Subscription-Key (the raw key is sent in it).

azure_endpointstringoptional

Azure resource endpoint, or a custom API base ending in /deployments (e.g. an API Management route).

base_urlstringoptional

Endpoint base URL for OpenAI-compatible and self-hosted providers.

gcp_project_idstringoptional
gcp_regionstringoptional
gpu_connector_idstringoptional
oci_compartment_idstringoptional
oci_fingerprintstringoptional
oci_private_keystringoptional

Secret. Write-only.

min length: 1write only
oci_private_key_passphrasestringoptional

Secret. Write-only.

min length: 1write only
oci_project_idstringoptional
oci_regionstringoptional
oci_session_tokenstringoptional

Secret. Write-only.

min length: 1write only
oci_tenancy_idstringoptional
oci_user_idstringoptional
preferred_upstream_apistringoptional

Prefer another endpoint of the client's API family.

remote_connector_idstringoptional
service_account_jsonstringoptional

JSON-encoded Google service account document. Write-only.

min length: 1write only
upstream_apisarray<string>optional

Other wire APIs this upstream also serves.

max items: 16
Array item specification
string
use_outbound_ipsboolean | string | nulloptional

This provider's own Quilr outbound IP setting: a region code calls it from that region's outbound IPs (listed by GET /outbound-ips), true from the account's region, false calls it directly, null or omitted follows the account-wide setting (/outbound-ips). Refused for a provider linked to a connector, and for one whose endpoint is not a public host over https on port 443.

truefalse"us""eu""in"null

Unknown fields are rejected in this object.

selected_modelsarray<string>optional
max items: 1000
Array item specification
string
tagsobject | nulloptional
Map value specification
Variant 1 string
string
max length: 512
Variant 2 boolean
boolean
Variant 3 number
number
Variant 4 array | null
array | null
max items: 32unique items

Also accepts null.

tags_resetarray<object>optional

Return provider tag presets to their derived/default values. geo is derived at read time from the region (us|eu|uk|ca|apac|jp|au|in|sa|me|global); tags.geo: null instead clears it to unknown and stops derivation. Reads add tag_sources {provider, models} naming each tag's source (derived|manual|catalog).

unique items
Array item specification
object

Values: "region""service_tier""geo"

upstream_limitsobject | nulloptional
Object fields
input_tpminteger | nulloptional
min: 0max: 9007199254740991
max_inflight_requestsinteger | nulloptional
min: 0max: 9007199254740991
output_tpminteger | nulloptional
min: 0max: 9007199254740991
rpminteger | nulloptional
min: 0max: 9007199254740991
shared_quota_pool_idsarray | nulloptional
max items: 32unique items
total_tpminteger | nulloptional
min: 0max: 9007199254740991

Unknown fields are rejected in this object.

Unknown fields are rejected in this object.

curl --request POST \
'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/providers' \
--header 'Authorization: Bearer <management-key>' \
--header 'Idempotency-Key: create-support-bot-001' \
--header 'Content-Type: application/json' \
--data '{
"label": "Bedrock US",
"provider_name": "bedrock",
"provider_settings": {
"aws_auth_mode": "assume_role",
"aws_external_id": "<external-id>",
"aws_region": "us-east-1",
"aws_role_arn": "arn:aws:iam::123456789012:role/gateway"
},
"selected_models": [
"anthropic.claude-sonnet-4-20250514-v1:0"
],
"tags": {
"region": "us-east-1"
}
}'

Authentication, errors & retry rules Try it in the playground

POST/providers/available-models

Discover models for draft settings

Lists the models the upstream offers for draft settings, before the provider is saved. `validate: true` also probes every listed model (slower, can incur upstream usage). Providers that cannot list models return outcome manual_entry. Nothing is saved.

REQUIRESproviders:write
Full request body specification application/json

provider_namestringrequired
provider_settingsobjectoptional

Draft settings, validated like a provider save. On a stored provider they merge onto the saved settings; a blank secret keeps the stored value. Never persisted.

write only
validatebooleanoptional

Also probe every listed model (slower; can incur upstream usage).

default: false

Unknown fields are rejected in this object.

curl --request POST \
'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/providers/available-models' \
--header 'Authorization: Bearer <management-key>' \
--header 'Content-Type: application/json' \
--data '{
"provider_name": "openai",
"provider_settings": {
"api_key": "<provider-api-key>"
},
"validate": false
}'

Authentication, errors & retry rules Try it in the playground

POST/providers/test-settings

Test draft provider settings

Tests settings for a provider that does not exist yet, before saving it: a connection check plus one probe per listed model. Nothing is saved. Outcomes include timeout and skipped (with a reason code) in addition to passed, failed and unsupported.

REQUIRESproviders:write
Full request body specification application/json

modelsarray<string>optional
max items: 10unique items
Array item specification
string
min length: 1
provider_namestringrequired
provider_settingsobjectoptional

Draft settings, validated like a provider save. On a stored provider they merge onto the saved settings; a blank secret keeps the stored value. Never persisted.

write only

Unknown fields are rejected in this object.

curl --request POST \
'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/providers/test-settings' \
--header 'Authorization: Bearer <management-key>' \
--header 'Content-Type: application/json' \
--data '{
"models": [
"gpt-4.1-mini"
],
"provider_name": "openai",
"provider_settings": {
"api_key": "<provider-api-key>"
}
}'

Authentication, errors & retry rules Try it in the playground

DELETE/providers/{label}

Delete a shared provider

Deletes the provider. Refused with 409 provider_in_use while any app attaches it; detach it first. Send the quoted version from the latest read in If-Match.

REQUIRESproviders:write
Path, query & header parameters 2
label (path)stringrequired

Shared-provider label, URL-encoded.

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/v1/providers/Production%20OpenAI' \
--header 'Authorization: Bearer <management-key>' \
--header 'If-Match: "3f1c0a9e5b7d"'

Authentication, errors & retry rules Try it in the playground

GET/providers/{label}

Read a shared provider

One shared provider with secret settings omitted. `version` is its ETag.

REQUIRESread
Path, query & header parameters 1
label (path)stringrequired

Shared-provider label, URL-encoded.

No request body.

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

Authentication, errors & retry rules Try it in the playground

PATCH/providers/{label}

Update or disable a provider

Partial update. Omitted secret settings keep their stored value; `enabled: false` disables the provider for every app. `model_metadata_reset` and `tags_reset` return values to their catalog or derived defaults. Send the quoted version from the latest read in If-Match.

REQUIRESproviders:write
Path, query & header parameters 2
label (path)stringrequired

Shared-provider label, URL-encoded.

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

Shared-provider configuration. Saves never call the upstream; use the test and available-models operations to check settings.

enabledbooleanoptional
labelstringoptional

Tenant-unique display name; immutable.

min length: 1max length: 200
model_costsmap<string, one of 2 variants>optional
Map value specification
ModelCost object
audio_input_per_1mnumber | nulloptional
min: 0
audio_input_per_secondnumber | nulloptional
min: 0
audio_input_per_second_byobject | nulloptional
Map value specification
number
min: 0
audio_output_per_1mnumber | nulloptional
min: 0
audio_output_per_secondnumber | nulloptional
min: 0
audio_output_per_second_byobject | nulloptional
Map value specification
number
min: 0
batch_multipliernumber | nulloptional
max: 1greater than: 0
cache_per_1mnumber | nulloptional

Deprecated alias of cache_read_per_1m. Requests may send it (must equal cache_read_per_1m when both are sent); responses echo it equal to cache_read_per_1m whenever that is set, and it is never stored.

min: 0
cache_read_per_1mnumber | nulloptional
min: 0
cache_write_1h_per_1mnumber | nulloptional
min: 0
cache_write_5m_per_1mnumber | nulloptional
min: 0
cache_write_default_ttlstring | nulloptional
"5m""1h""unpriced"null
cache_write_per_1mnumber | nulloptional
min: 0
code_execution_per_hournumber | nulloptional
min: 0
container_per_sessionnumber | nulloptional
min: 0
document_image_input_per_imagenumber | nulloptional
min: 0
document_image_input_per_image_byobject | nulloptional
Map value specification
number
min: 0
file_search_per_1knumber | nulloptional
min: 0
grounding_per_1knumber | nulloptional
min: 0
image_input_per_1mnumber | nulloptional
min: 0
image_input_per_imagenumber | nulloptional
min: 0
image_input_per_image_byobject | nulloptional
Map value specification
number
min: 0
image_output_per_1mnumber | nulloptional
min: 0
image_output_per_imagenumber | nulloptional
min: 0
image_output_per_image_byobject | nulloptional
Map value specification
number
min: 0
input_per_1mnumber | nullrequired
min: 0
input_per_1m_charactersnumber | nulloptional
min: 0
input_per_1m_characters_byobject | nulloptional
Map value specification
number
min: 0
output_per_1mnumber | nullrequired
min: 0
pages_per_1knumber | nulloptional
min: 0
pages_per_1k_byobject | nulloptional
Map value specification
number
min: 0
reasoning_per_1mnumber | nulloptional
min: 0
regional_multipliersobject | nulloptional
Object fields
data_residencynumber | nulloptional
greater than: 0
geonumber | nulloptional
greater than: 0
regionalnumber | nulloptional
greater than: 0
us_onlynumber | nulloptional
greater than: 0

Unknown fields are rejected in this object.

requests_per_1knumber | nulloptional
min: 0
requests_per_1k_byobject | nulloptional
Map value specification
number
min: 0
search_units_per_1knumber | nulloptional
min: 0
search_units_per_1k_byobject | nulloptional
Map value specification
number
min: 0
service_tier_multipliersobject | nulloptional
Object fields
fastnumber | nulloptional
greater than: 0
flexnumber | nulloptional
greater than: 0
prioritynumber | nulloptional
greater than: 0

Unknown fields are rejected in this object.

text_input_per_requestnumber | nulloptional
min: 0
text_input_per_request_byobject | nulloptional
Map value specification
number
min: 0
tiersarray | nulloptional
max items: 8
video_input_per_secondnumber | nulloptional
min: 0
video_input_per_second_byobject | nulloptional
Map value specification
number
min: 0
video_output_per_secondnumber | nulloptional
min: 0
video_output_per_second_byobject | nulloptional
Map value specification
number
min: 0
web_fetch_per_1knumber | nulloptional
min: 0
web_search_per_1knumber | nulloptional
min: 0

Unknown fields are rejected in this object.

Also accepts null.

model_metadataobject | nulloptional

Model facts keyed by selected ID. Absent fields inherit compatible catalog defaults; nested nulls remain unknown. A null model item resets its saved overrides to the catalog.

Map value specification
cachingobject | nulloptional
Object fields
min_cacheable_tokensinteger | nulloptional
min: 0max: 9007199254740991
supportstring | nulloptional
"supported""unsupported""conditional""unknown"null
supported_ttlsarray | nulloptional
max items: 16unique items

Unknown fields are rejected in this object.

capabilitiesobject | nulloptional
Object fields
supports_json_modeboolean | nulloptional
supports_json_schemaboolean | nulloptional
supports_parallel_tool_callsboolean | nulloptional
supports_streamingboolean | nulloptional
supports_tool_callingboolean | nulloptional

Unknown fields are rejected in this object.

input_formatsarray | nulloptional
max items: 32unique items
input_modalitiesarray | nulloptional
max items: 32unique items
lifecycleobject | nulloptional
Object fields
retirement_datestring | nulloptional
format: date
statusstring | nulloptional
"unknown""preview""stable""deprecated""retired"null

Unknown fields are rejected in this object.

limitsobject | nulloptional
Object fields
context_window_tokensinteger | nulloptional
min: 1max: 9007199254740991
max_input_tokensinteger | nulloptional
min: 1max: 9007199254740991
max_output_tokensinteger | nulloptional
min: 1max: 9007199254740991
max_reasoning_tokensinteger | nulloptional
min: 0max: 9007199254740991

Unknown fields are rejected in this object.

output_formatsarray | nulloptional
max items: 32unique items
output_modalitiesarray | nulloptional
max items: 32unique items
provenanceobject | nulloptional
Object fields
last_verified_atstring | nulloptional
format: date-time
sourcestring | nulloptional
"manual""provider_api""catalog"null
source_urlstring | nulloptional
max length: 2048
updated_atstring | nulloptional
format: date-time

Unknown fields are rejected in this object.

reasoning_tokens_in_output_budgetboolean | nulloptional
supported_reasoning_effortsarray | nulloptional
max items: 16unique items
tagsobject | nulloptional

At most 64 active tags including the canonical identity preset, plus 1024 stored null clears. Null custom tags are hidden from public views; canonical_model:null resets the identity to its catalog default or model ID.

Map value specification
Variant 1 string
string
max length: 512
Variant 2 boolean
boolean
Variant 3 number
number
Variant 4 array | null
array | null
max items: 32unique items

Also accepts null.

temperatureobject | nulloptional
Object fields
conditionsstring | nulloptional
max length: 1024
defaultnumber | nulloptional
min: 0
maxnumber | nulloptional
min: 0
minnumber | nulloptional
min: 0
supportstring | nulloptional
"supported""unsupported""conditional""unknown"null

Unknown fields are rejected in this object.

upstream_limitsobject | nulloptional
Object fields
input_tpminteger | nulloptional
min: 0max: 9007199254740991
max_inflight_requestsinteger | nulloptional
min: 0max: 9007199254740991
output_tpminteger | nulloptional
min: 0max: 9007199254740991
rpminteger | nulloptional
min: 0max: 9007199254740991
shared_quota_pool_idsarray | nulloptional
max items: 32unique items
total_tpminteger | nulloptional
min: 0max: 9007199254740991

Unknown fields are rejected in this object.

Unknown fields are rejected in this object.

model_metadata_resetmap<string, array<string>>optional

Dotted metadata paths per selected model whose stored override is removed, so the catalog default shows through again. Distinct from null (= unknown).

Map value specification
array<string>
max items: 64
provider_namestringoptional

Provider type; immutable.

"openai""azureopenai""general""anthropic""anthropic_messages""anthropic_messages_bedrock""anthropic_messages_azure""deepseek""vertex_ai""gemini_chatcompletions""oracle""openai_responses""openai_responses_azure""oracle_responses""openai_assistants""openai_assistants_azure""openai_realtime""openai_realtime_azure""bedrock""bedrock_embeddings""cohere_rerank""bedrock_rerank""jina_rerank""voyage_rerank""general_rerank""sarvam""mistral""xai""xai_responses""cerebras""typesafe""groq""perplexity""cohere"
provider_settingsobjectoptional

Settings for the chosen provider type; required credentials depend on it and are validated against the merged configuration. Secret values are never returned.

write only
Object fields
anthropic_versionstringoptional

Anthropic API version header.

api_keystringoptional

Provider API key. Write-only; omit or send an empty string to keep the stored value.

write only
auth_typestringoptional

Authentication mode for providers that support several.

aws_access_keystringoptional

Secret. Write-only; omit or send an empty string to keep the stored value.

write only
aws_auth_modestringoptional

static (access keys) or assume_role.

aws_bedrock_api_keystringoptional

Secret. Write-only; omit or send an empty string to keep the stored value.

write only
aws_bedrock_chat_apistringoptional
aws_bedrock_endpointstringoptional
aws_bedrock_openai_pathstringoptional
aws_external_idstringoptional

Secret. Write-only; omit or send an empty string to keep the stored value.

write only
aws_regionstringoptional
aws_role_arnstringoptional
aws_role_session_namestringoptional
aws_secret_keystringoptional

Secret. Write-only; omit or send an empty string to keep the stored value.

write only
aws_session_duration_secondsintegeroptional

Assumed-role session length, 900-43200.

min: 900max: 43200
aws_session_tokenstringoptional

Secret. Write-only; omit or send an empty string to keep the stored value.

write only
azure_api_versionstringoptional

Azure API version.

azure_auth_headerstringoptional

Azure providers: the header the key is sent in. Omit (or api-key) for api-key, authorization_bearer for 'Authorization: Bearer <key>', or a header name such as Ocp-Apim-Subscription-Key (the raw key is sent in it).

azure_endpointstringoptional

Azure resource endpoint, or a custom API base ending in /deployments (e.g. an API Management route).

base_urlstringoptional

Endpoint base URL for OpenAI-compatible and self-hosted providers.

gcp_project_idstringoptional
gcp_regionstringoptional
gpu_connector_idstringoptional
oci_compartment_idstringoptional
oci_fingerprintstringoptional
oci_private_keystringoptional

Secret. Write-only; omit or send an empty string to keep the stored value.

write only
oci_private_key_passphrasestringoptional

Secret. Write-only; omit or send an empty string to keep the stored value.

write only
oci_project_idstringoptional
oci_regionstringoptional
oci_session_tokenstringoptional

Secret. Write-only; omit or send an empty string to keep the stored value.

write only
oci_tenancy_idstringoptional
oci_user_idstringoptional
preferred_upstream_apistringoptional

Prefer another endpoint of the client's API family.

remote_connector_idstringoptional
service_account_jsonstringoptional

JSON-encoded Google service account document. Write-only; omit or send an empty string to keep the stored value.

write only
upstream_apisarray<string>optional

Other wire APIs this upstream also serves.

max items: 16
Array item specification
string
use_outbound_ipsboolean | string | nulloptional

This provider's own Quilr outbound IP setting: a region code calls it from that region's outbound IPs (listed by GET /outbound-ips), true from the account's region, false calls it directly, null or omitted follows the account-wide setting (/outbound-ips). Refused for a provider linked to a connector, and for one whose endpoint is not a public host over https on port 443.

truefalse"us""eu""in"null

Unknown fields are rejected in this object.

selected_modelsarray<string>optional
max items: 1000
Array item specification
string
tagsobject | nulloptional
Map value specification
Variant 1 string
string
max length: 512
Variant 2 boolean
boolean
Variant 3 number
number
Variant 4 array | null
array | null
max items: 32unique items

Also accepts null.

tags_resetarray<object>optional

Return provider tag presets to their derived/default values. geo is derived at read time from the region (us|eu|uk|ca|apac|jp|au|in|sa|me|global); tags.geo: null instead clears it to unknown and stops derivation. Reads add tag_sources {provider, models} naming each tag's source (derived|manual|catalog).

unique items
Array item specification
object

Values: "region""service_tier""geo"

upstream_limitsobject | nulloptional
Object fields
input_tpminteger | nulloptional
min: 0max: 9007199254740991
max_inflight_requestsinteger | nulloptional
min: 0max: 9007199254740991
output_tpminteger | nulloptional
min: 0max: 9007199254740991
rpminteger | nulloptional
min: 0max: 9007199254740991
shared_quota_pool_idsarray | nulloptional
max items: 32unique items
total_tpminteger | nulloptional
min: 0max: 9007199254740991

Unknown fields are rejected in this object.

Unknown fields are rejected in this object.

curl --request PATCH \
'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/providers/Production%20OpenAI' \
--header 'Authorization: Bearer <management-key>' \
--header 'If-Match: "3f1c0a9e5b7d"' \
--header 'Content-Type: application/json' \
--data '{
"enabled": false
}'

Authentication, errors & retry rules Try it in the playground

POST/providers/{label}/available-models

Discover provider models

Lists the models the upstream offers for a stored provider, optionally with draft settings merged on top. Nothing is saved; update `selected_models` separately.

REQUIRESproviders:write
Path, query & header parameters 1
label (path)stringrequired

Shared-provider label, URL-encoded.

Full request body specification application/json

provider_settingsobjectoptional

Draft settings, validated like a provider save. On a stored provider they merge onto the saved settings; a blank secret keeps the stored value. Never persisted.

write only
validatebooleanoptional

Also probe every listed model (slower; can incur upstream usage).

default: false

Unknown fields are rejected in this object.

curl --request POST \
'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/providers/Production%20OpenAI/available-models' \
--header 'Authorization: Bearer <management-key>' \
--header 'Content-Type: application/json' \
--data '{
"validate": false
}'

Authentication, errors & retry rules Try it in the playground

POST/providers/{label}/test

Test connection or model

Tests the stored configuration. `kind: model` sends one small request to a selected model; `kind: connection` probes the selected models (up to a fixed number) and reports each. Outcomes are passed, failed or unsupported (provider types outside `model_test_provider_types`). Probes can incur upstream usage. Nothing is saved.

REQUIRESproviders:write
Path, query & header parameters 1
label (path)stringrequired

Shared-provider label, URL-encoded.

Full request body specification application/json

kindobjectrequired
"connection""model"
modelstringoptional

A selected model; required for kind model.

Unknown fields are rejected in this object.

curl --request POST \
'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/providers/Production%20OpenAI/test' \
--header 'Authorization: Bearer <management-key>' \
--header 'Content-Type: application/json' \
--data '{
"kind": "connection"
}'

Authentication, errors & retry rules Try it in the playground

POST/providers/{label}/test-settings

Test provider settings

Tests draft changes to a stored provider before saving them. Draft settings merge onto the stored ones; a blank secret keeps the stored value. With no body, tests the stored configuration. Nothing is saved.

REQUIRESproviders:write
Path, query & header parameters 1
label (path)stringrequired

Shared-provider label, URL-encoded.

Full request body specification application/json

modelsarray<string>optional
max items: 10unique items
Array item specification
string
min length: 1
provider_settingsobjectoptional

Draft settings, validated like a provider save. On a stored provider they merge onto the saved settings; a blank secret keeps the stored value. Never persisted.

write only

Unknown fields are rejected in this object.

curl --request POST \
'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/providers/Production%20OpenAI/test-settings' \
--header 'Authorization: Bearer <management-key>' \
--header 'Content-Type: application/json' \
--data '{
"models": [
"gpt-4.1"
],
"provider_settings": {
"base_url": "https://api.openai.com/v1"
}
}'

Authentication, errors & retry rules Try it in the playground

Review new models​

When a provider starts offering a model after the gateway began watching it, the model is held for an admin decision. A provider with a model list serves only listed models, so a pending model is not callable until you approve it. Providers without a model list serve every model and are not reviewed, and models already offered when watching began are never listed.

Discovered
Provider lists a new model
status: pending
Review
GET /provider-model-reviews
?status=pending
Decide
approved: added to the model list
rejected: kept off the list
Serve
Approved models are callable
Rejected models stay off
QuilrAI
ActionCallScope
List reviews across providers, newest first (status: pending, approved or rejected)GET /provider-model-reviews with optional status, provider, app, limit, cursorread
Read one provider's last model listing and its pending, approved and rejected modelsGET /provider-model-reviews/{label} (a provider one app holds with its own keys is found without app_name; pass app_name or app when several apps use the label, otherwise 409 app_name_required lists them)read
Approve or reject models of a shared providerPOST /provider-model-reviews/{label}/decisionsproviders:write
Approve or reject models of a provider an app holds with its own keys ({label} is the app's own provider label)POST /provider-model-reviews/{label}/app-decisions with app_nameconfig:write
  • Decisions. status: "approved" adds the models to the provider's model list and closes the reviews; for a shared provider you can send model_costs (as on update a provider) in the same call. rejected rejects pending models and pending restores rejected ones; neither changes what the provider serves.
  • Saves. Approving on a shared provider is the same save as updating the provider, and the response carries its new provider_version (the If-Match for your next PATCH). Approving on an app's own provider creates a new app configuration version, and returns 409 if the app changed meanwhile. A shared provider without a model list cannot be approved on (409).
  • Retries. Decisions need an Idempotency-Key: a retry with the same key and body replays the first result for 24 hours.
  • Validation. Every model must be a reviewed model of this provider in a state the decision can leave (422 otherwise). A decision that already holds is accepted and changes nothing.
  • Background checks. settings in every read reports whether the gateway checks providers for new models in the background and how often. available: false means reviews are not managed on this deployment.
export API="$MANAGEMENT_URL/llmgateway/management/v1"
auth=(-H "Authorization: Bearer $MANAGEMENT_KEY" -H 'Content-Type: application/json')

# Pending models across every provider
curl -s "$API/provider-model-reviews?status=pending" "${auth[@]}" \
| jq -r '.items[] | [.label, .app_name // "shared", .model_id] | @tsv'

# Approve one on a shared provider, with prices
curl -s -X POST "$API/provider-model-reviews/Production%20OpenAI/decisions" "${auth[@]}" \
-H 'Idempotency-Key: approve-gpt-5-2-mini-001' \
-d '{"status": "approved", "models": ["gpt-5.2-mini"], "model_costs": {"gpt-5.2-mini": {"input_per_1m": 0.25, "output_per_1m": 2.0}}}'
GET/provider-model-reviews

List new-model reviews

Models your providers started offering after the gateway began watching them, one item per model, with status pending, approved or rejected. A provider with a model list serves only listed models, so a pending model is not callable until approved. Providers without a model list serve every model and are not reviewed; models already offered when watching began are never listed. Filter by status, provider label or app (an app's own provider keys). Newest first; page with `limit` (1 to 200, default 50) and `cursor`. settings reports the background check switch.

REQUIRESread
Path, query & header parameters 5
status (query)objectoptional

Only models in this state; omit for all three.

"pending""approved""rejected"
provider (query)stringoptional

Exact provider label.

app (query)stringoptional

Only providers this app holds with its own keys (case-insensitive name).

limit (query)integeroptional

Page size: 1 to 200, default 50.

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

next_cursor from the previous page; send the same other parameters.

No request body.

curl --request GET \
'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/provider-model-reviews?limit=50' \
--header 'Authorization: Bearer <management-key>'

Authentication, errors & retry rules Try it in the playground

GET/provider-model-reviews/{label}

Read one provider's new-model reviews

The last model listing of one provider and its pending, approved and rejected models. Without app_name the label names a shared provider; with app_name, a provider that app holds with its own keys.

REQUIRESread
Path, query & header parameters 2
label (path)stringrequired

Provider label, URL-encoded: a shared provider's label, or with app_name the label of a provider that app holds with its own keys.

app_name (query)stringoptional

Name of the app holding the provider with its own keys; omit for a shared provider.

No request body.

curl --request GET \
'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/provider-model-reviews/Production%20OpenAI' \
--header 'Authorization: Bearer <management-key>'

Authentication, errors & retry rules Try it in the playground

POST/provider-model-reviews/{label}/app-decisions

Approve or reject new models of an app's own provider

For a provider an app holds with its own keys: `{label}` is that provider's label and app_name the app. approved adds the models to that provider's model list in one versioned app save (a new configuration version; 409 if the app changed meanwhile), then closes the reviews. rejected and pending work as for shared providers. An app that uses shared providers has no own providers: decide on the shared provider instead. Writes need an Idempotency-Key: a retry with the same key and body replays the first result for 24 hours. Every model must be a reviewed model of this provider in a state the decision can leave (422 otherwise); a decision that already holds is accepted and changes nothing.

REQUIRESconfig:write
Path, query & header parameters 2
label (path)stringrequired

The app's own provider label, URL-encoded: the label of a provider the app named by app_name holds with its own keys (not a shared provider).

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

app_namestringrequired
min length: 1max length: 200
modelsarray<string>required
min items: 1max items: 1000unique items
Array item specification
string
min length: 1max length: 512
statusobjectrequired

approved: add to the app provider's model list (a new app configuration version) and close the review. rejected / pending as for shared providers.

"approved""rejected""pending"

Unknown fields are rejected in this object.

curl --request POST \
'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/provider-model-reviews/Production%20OpenAI/app-decisions' \
--header 'Authorization: Bearer <management-key>' \
--header 'Idempotency-Key: approve-gpt-5-2-mini-001' \
--header 'Content-Type: application/json' \
--data '{
"app_name": "Support Bot",
"models": [
"gpt-5.2-mini"
],
"status": "approved"
}'

Authentication, errors & retry rules Try it in the playground

POST/provider-model-reviews/{label}/decisions

Approve or reject new models of a shared provider

approved adds the models to the shared provider's model list (optionally with prices) through the same save as updating the provider, then closes the reviews; the response carries the provider's new version. A provider without a model list cannot be approved on (409). rejected rejects pending models; pending restores rejected ones. Neither changes what the provider serves. Writes need an Idempotency-Key: a retry with the same key and body replays the first result for 24 hours. Every model must be a reviewed model of this provider in a state the decision can leave (422 otherwise); a decision that already holds is accepted and changes nothing.

REQUIRESproviders:write
Path, query & header parameters 2
label (path)stringrequired

Shared-provider label, URL-encoded.

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

model_costsmap<string, object>optional

Optional prices for approved models, as on PATCH /providers/{label}.

Map value specification
audio_input_per_1mnumber | nulloptional
min: 0
audio_input_per_secondnumber | nulloptional
min: 0
audio_input_per_second_byobject | nulloptional
Map value specification
number
min: 0
audio_output_per_1mnumber | nulloptional
min: 0
audio_output_per_secondnumber | nulloptional
min: 0
audio_output_per_second_byobject | nulloptional
Map value specification
number
min: 0
batch_multipliernumber | nulloptional
max: 1greater than: 0
cache_per_1mnumber | nulloptional

Deprecated alias of cache_read_per_1m. Requests may send it (must equal cache_read_per_1m when both are sent); responses echo it equal to cache_read_per_1m whenever that is set, and it is never stored.

min: 0
cache_read_per_1mnumber | nulloptional
min: 0
cache_write_1h_per_1mnumber | nulloptional
min: 0
cache_write_5m_per_1mnumber | nulloptional
min: 0
cache_write_default_ttlstring | nulloptional
"5m""1h""unpriced"null
cache_write_per_1mnumber | nulloptional
min: 0
code_execution_per_hournumber | nulloptional
min: 0
container_per_sessionnumber | nulloptional
min: 0
document_image_input_per_imagenumber | nulloptional
min: 0
document_image_input_per_image_byobject | nulloptional
Map value specification
number
min: 0
file_search_per_1knumber | nulloptional
min: 0
grounding_per_1knumber | nulloptional
min: 0
image_input_per_1mnumber | nulloptional
min: 0
image_input_per_imagenumber | nulloptional
min: 0
image_input_per_image_byobject | nulloptional
Map value specification
number
min: 0
image_output_per_1mnumber | nulloptional
min: 0
image_output_per_imagenumber | nulloptional
min: 0
image_output_per_image_byobject | nulloptional
Map value specification
number
min: 0
input_per_1mnumber | nullrequired
min: 0
input_per_1m_charactersnumber | nulloptional
min: 0
input_per_1m_characters_byobject | nulloptional
Map value specification
number
min: 0
output_per_1mnumber | nullrequired
min: 0
pages_per_1knumber | nulloptional
min: 0
pages_per_1k_byobject | nulloptional
Map value specification
number
min: 0
reasoning_per_1mnumber | nulloptional
min: 0
regional_multipliersobject | nulloptional
Object fields
data_residencynumber | nulloptional
greater than: 0
geonumber | nulloptional
greater than: 0
regionalnumber | nulloptional
greater than: 0
us_onlynumber | nulloptional
greater than: 0

Unknown fields are rejected in this object.

requests_per_1knumber | nulloptional
min: 0
requests_per_1k_byobject | nulloptional
Map value specification
number
min: 0
search_units_per_1knumber | nulloptional
min: 0
search_units_per_1k_byobject | nulloptional
Map value specification
number
min: 0
service_tier_multipliersobject | nulloptional
Object fields
fastnumber | nulloptional
greater than: 0
flexnumber | nulloptional
greater than: 0
prioritynumber | nulloptional
greater than: 0

Unknown fields are rejected in this object.

text_input_per_requestnumber | nulloptional
min: 0
text_input_per_request_byobject | nulloptional
Map value specification
number
min: 0
tiersarray | nulloptional
max items: 8
video_input_per_secondnumber | nulloptional
min: 0
video_input_per_second_byobject | nulloptional
Map value specification
number
min: 0
video_output_per_secondnumber | nulloptional
min: 0
video_output_per_second_byobject | nulloptional
Map value specification
number
min: 0
web_fetch_per_1knumber | nulloptional
min: 0
web_search_per_1knumber | nulloptional
min: 0

Unknown fields are rejected in this object.

modelsarray<string>required
min items: 1max items: 1000unique items
Array item specification
string
min length: 1max length: 512
statusobjectrequired

approved: add to the provider's model list and close the review (from pending or rejected). rejected: reject a pending model. pending: restore a rejected model.

"approved""rejected""pending"

Unknown fields are rejected in this object.

curl --request POST \
'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/provider-model-reviews/Production%20OpenAI/decisions' \
--header 'Authorization: Bearer <management-key>' \
--header 'Idempotency-Key: approve-gpt-5-2-mini-001' \
--header 'Content-Type: application/json' \
--data '{
"model_costs": {
"gpt-5.2-mini": {
"input_per_1m": 0.25,
"output_per_1m": 2
}
},
"models": [
"gpt-5.2-mini"
],
"status": "approved"
}'

Authentication, errors & retry rules Try it in the playground

Quota pools​

A quota pool names an upstream ceiling that several providers or models share, such as one provider organization's tokens-per-minute limit used by two credentials. Pools are descriptive: they document limits and membership, and do not change routing or enforce limits.

Register
POST /quota-pools
pool_id, name, limits
Assign
Provider or model upstream_limits
shared_quota_pool_ids
Review
GET /quota-pools
members per pool
QuilrAI
  • Register before you assign. A provider write that names an unregistered pool ID returns 400 invalid_provider naming the unknown IDs. GET /quota-pools returns unregistered, the pool IDs that providers already reference but that were never registered; create a pool with that pool_id to adopt it.
  • Membership lives on providers. Set upstream_limits.shared_quota_pool_ids on a provider, or on one model in model_metadata. Each pool's members lists the providers and {provider_label, model} pairs that reference it.
  • IDs and limits. New pool_id values use lowercase letters, digits, ., _, : and - (up to 128 characters) and cannot change. limits (rpm, rpd, input_tpm, output_tpm, max_inflight_requests and more) are positive integers; null means unknown. PATCH merges limit keys.
  • Writes need providers:write. Creation takes an Idempotency-Key; updates and deletes take the pool version in If-Match. Deleting a pool that still has members returns 409 quota_pool_in_use unless you pass detach=true, which removes it from every member first.
GET/quota-pools

List quota pools

Registered pools with their member providers and models. `unregistered` lists pool IDs that providers reference but that were never registered; create one with that pool_id to adopt it.

REQUIRESread
Path, query & header parameters 2
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/v1/quota-pools?limit=50' \
--header 'Authorization: Bearer <management-key>'

Authentication, errors & retry rules Try it in the playground

POST/quota-pools

Create a quota pool

Registers a pool of upstream limits shared by several providers or models. Limits are descriptive ceilings (null means unknown). Membership is set on providers, not here.

REQUIRESproviders:write
Path, query & header parameters 1
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

descriptionstring | nulloptional
max length: 1000
last_verified_atstring | nulloptional
format: date-time
limitsone of 2 variantsoptional
QuotaPoolLimits object
input_tpminteger | nulloptional
min: 1max: 9007199254740991
max_inflight_requestsinteger | nulloptional
min: 1max: 9007199254740991
output_tpminteger | nulloptional
min: 1max: 9007199254740991
rpdinteger | nulloptional
min: 1max: 9007199254740991
rpminteger | nulloptional
min: 1max: 9007199254740991
total_tpminteger | nulloptional
min: 1max: 9007199254740991

Unknown fields are rejected in this object.

Also accepts null.

namestringrequired
min length: 1max length: 200
pool_idstringrequired

Immutable. A new id must match ^[a-z0-9][a-z0-9._:-]{0,127}$; an unregistered legacy id already referenced by a provider may be adopted verbatim (no control characters, '/' or surrounding whitespace), so stored ids need not match.

min length: 1max length: 128
sourceobjectoptional
default: "manual"
"manual""provider_docs""provider_api"
source_urlstring | nulloptional
max length: 2048format: uri

Unknown fields are rejected in this object.

curl --request POST \
'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/quota-pools' \
--header 'Authorization: Bearer <management-key>' \
--header 'Idempotency-Key: create-support-bot-001' \
--header 'Content-Type: application/json' \
--data '{
"limits": {
"input_tpm": 2000000,
"rpm": 5000
},
"name": "OpenAI organization",
"pool_id": "openai-org-main"
}'

Authentication, errors & retry rules Try it in the playground

DELETE/quota-pools/{pool_id}

Delete a quota pool

Deletes the pool. Refused with 409 quota_pool_in_use while providers or models reference it, unless detach=true, which first removes it from every member. Send the quoted version from the latest read in If-Match.

REQUIRESproviders:write
Path, query & header parameters 3
pool_id (path)stringrequired
detach (query)booleanoptional

Remove the pool from every member provider/model first (409 quota_pool_in_use otherwise).

default: false
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/v1/quota-pools/openai-org-main' \
--header 'Authorization: Bearer <management-key>' \
--header 'If-Match: "3f1c0a9e5b7d"'

Authentication, errors & retry rules Try it in the playground

GET/quota-pools/{pool_id}

Read a quota pool

One pool with its members. `version` is its ETag.

REQUIRESread
Path, query & header parameters 1
pool_id (path)stringrequired

No request body.

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

Authentication, errors & retry rules Try it in the playground

PATCH/quota-pools/{pool_id}

Update a quota pool

Partial update; omitted limit keys keep their value. `pool_id` is immutable. Send the quoted version from the latest read in If-Match.

REQUIRESproviders:write
Path, query & header parameters 2
pool_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

descriptionstring | nulloptional
max length: 1000
last_verified_atstring | nulloptional
format: date-time
limitsone of 2 variantsoptional
QuotaPoolLimits object
input_tpminteger | nulloptional
min: 1max: 9007199254740991
max_inflight_requestsinteger | nulloptional
min: 1max: 9007199254740991
output_tpminteger | nulloptional
min: 1max: 9007199254740991
rpdinteger | nulloptional
min: 1max: 9007199254740991
rpminteger | nulloptional
min: 1max: 9007199254740991
total_tpminteger | nulloptional
min: 1max: 9007199254740991

Unknown fields are rejected in this object.

Also accepts null.

namestringoptional
min length: 1max length: 200
pool_idstringoptional

Immutable. A new id must match ^[a-z0-9][a-z0-9._:-]{0,127}$; an unregistered legacy id already referenced by a provider may be adopted verbatim (no control characters, '/' or surrounding whitespace), so stored ids need not match.

min length: 1max length: 128
sourceobjectoptional
default: "manual"
"manual""provider_docs""provider_api"
source_urlstring | nulloptional
max length: 2048format: uri

Unknown fields are rejected in this object.

curl --request PATCH \
'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/quota-pools/openai-org-main' \
--header 'Authorization: Bearer <management-key>' \
--header 'If-Match: "3f1c0a9e5b7d"' \
--header 'Content-Type: application/json' \
--data '{
"limits": {
"rpm": 10000
}
}'

Authentication, errors & retry rules Try it in the playground

Outbound IPs​

Quilr outbound IPs give a provider's calls fixed source addresses per region that you allowlist on the provider. See Outbound IPs for the addresses and the console steps.

  • Default for all providers. GET /outbound-ips returns enabled, region and regions (each with code, name, ips and available). PUT /outbound-ips takes enabled, region or both, and needs config:write. Region codes are us, eu and in. Changes reach every gateway server within applies_within_seconds.
  • One provider. Set provider_settings.use_outbound_ips on the provider: a region code for that region, true for the default's region, false for direct, or null to follow the default. It always wins over the default.
  • Refused routes. use_outbound_ips is refused with 422 for a provider linked to a remote connector or GPU server, and for one whose endpoint is not a public host over https on port 443.
  • No fallback. A call that can't go through the chosen region fails with 503 outbound_ips_unreachable; it is never sent directly.
GET/outbound-ips

Read the outbound IP setting

The account-wide Quilr outbound IP setting and every region's addresses. A provider's own use_outbound_ips setting (in its provider_settings) always wins: a region code or true calls it from the Quilr outbound IPs, false calls it directly. A provider without one follows this account-wide setting; with neither set, the provider is called directly. Outbound IPs work for a provider on a public host over https on port 443; a provider linked to a connector keeps its connector. region picks which Quilr region's outbound IPs are used (GET lists every region's addresses). The setting is kept per region.

REQUIRESread

No request body.

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

Authentication, errors & retry rules Try it in the playground

PUT/outbound-ips

Turn Quilr outbound IPs on or off

Set the account-wide setting: enabled true, false, or null to clear it, and the region. A provider's own use_outbound_ips setting (in its provider_settings) always wins: a region code or true calls it from the Quilr outbound IPs, false calls it directly. A provider without one follows this account-wide setting; with neither set, the provider is called directly. Outbound IPs work for a provider on a public host over https on port 443; a provider linked to a connector keeps its connector. region picks which Quilr region's outbound IPs are used (GET lists every region's addresses). The setting is kept per region.

REQUIRESconfig:write
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/v1/outbound-ips' \
--header 'Authorization: Bearer <management-key>' \
--header 'Content-Type: application/json' \
--data '{
"enabled": true,
"region": "in"
}'

Authentication, errors & retry rules Try it in the playground

Full app configuration input​

Use PATCH /llmgateway/management/v1/apps/{app_name} with the current app ETag. The same settings sections are accepted during app creation. The reference below uses the implemented wire names.

Partial updates​

Omitted fields preserve stored values. Unknown top-level and section fields are rejected. Nested maps such as category actions and sensitivities use the existing gateway merge semantics; an empty map is not a global reset. Lists such as tags, routing groups and custom-definition selections replace the list. [] clears a list where an empty list is supported; a provider-backed app must retain providers.

Only timeout, concurrency_per_minute, rate_limit, allowed_source_ips, jwt_auth and alerting accept a null reset at the public field level. Other fields, including token_limits, reject null. App-level timeout is a nonnegative integer in seconds.

When updating alerting, send its complete configuration, including the HTTPS URL for every submitted webhook. Omit the entire field to preserve it. Redacted webhook URLs from a read cannot be reused as credentials.

Configuration map​

SectionAccepted controls
detectionCategories, actions, scopes, sensitivities, existing custom definitions, Guardian Agent, hallucination settings, image OCR and encoded-image OCR.
routingrouting_groups, token_based_routing_groups, custom_routing, routing_thresholds.
limitsTimeout, concurrency, request rates, token limits and per-model limits.
accessSource IPs, email/domain restrictions, identity/conversation requirements, identity headers and JWT settings.
self_serviceenable_self_service plus the stored self_service object containing access_control.
transformationstoken_saving, response_cache (including match and similarity; see Response cache).
promptsrequire_system_from_store. Prompt content uses separate endpoints.
Top-level fieldsenabled, provider_labels, tags, alerting, smart_group_policies.

detection.enabled_categories maps existing built-in category IDs, or already-selected custom IDs, to booleans. Use detection.custom_definitions to select existing tenant definitions by ID; new regex/EDM/semantic/intent content is not accepted.

JWT authentication​

Use access.jwt_auth with allowed_issuers, allowed_client_ids, an RSA public_key_pem, optional kid and optional enabled. Enabled configuration requires nonempty issuer/client-ID lists. Saves do not fetch JWKS URLs. null, {} or { "enabled": false } disables JWT authentication.

Settings under QuilrQL​

Policy-governed changes can save and return inactive_under_quilrql, including affected fields and active_revision. Shared-provider credentials/availability, prompt contents and whole-app availability have independent runtime effects. See QuilrQL behavior, including the allowed-models default for eligible new apps.

Complete PATCH schema​

INPUT SCHEMAAppPatch
accessobjectoptional
Object fields
allowed_source_ipsone of 3 variantsoptional
Variant 1 array<string>
array<string>
Variant 2 object
enabledbooleanoptional
ipsarray<string>optional
Array item specification
string

Unknown fields are rejected in this object.

Also accepts null.

allowed_user_domainsarray<string>optional
max items: 1000
Array item specification
string
allowed_user_emailsarray<string>optional
max items: 1000
Array item specification
string
enforce_conversation_idbooleanoptional
enforce_identitybooleanoptional
identity_header_modebooleanoptional
identity_token_headersarray<string>optional
max items: 1000
Array item specification
string
identity_token_oid_fallbackbooleanoptional
jwt_authobject | nulloptional
JwtAuth object
allowed_audiencesarray | nulloptional

Omitted or null keeps the stored list.

allowed_client_idsarray<string>optional
Array item specification
string
allowed_issuersarray<string>optional
Array item specification
string
email_claimstring | nulloptional

Claim read first for the user's email.

enabledbooleanoptional
kidstringoptional
default: "default"
public_key_pemstringoptional

RSA public key (PEM). Required when enabling; this API does not fetch JWKS URLs.

subject_fallbackboolean | nulloptional

Use the token subject as identity when it has no email.

verify_audienceboolean | nulloptional

Requires a non-empty allowed_audiences. Omitted keeps the stored value (default false).

Unknown fields are rejected in this object.

Also accepts null.

Unknown fields are rejected in this object.

alertingobject | nulloptional
Alerting object
app_levelobjectoptional
Object fields
cooldown_minutesintegeroptional
min: 1default: 10
enabledbooleanoptional
default: false
failure_rate_thresholdnumberoptional

Percentage.

min: 0max: 100default: 10
minimum_requestsintegeroptional
min: 0default: 20
notify_on_recoverybooleanoptional
default: true
window_minutesintegeroptional
min: 5max: 1440default: 15
channelsobjectoptional
Object fields
emailsarray<string>optional
unique items
Array item specification
string
format: email
webhooksarray<object>optional
Array item specification
idstringoptional
min length: 1
labelstringoptional
typestringoptional
default: "generic"
"slack""generic"
urlstringrequired

HTTPS webhook URL, required for every submitted webhook.

format: uriwrite only
provider_levelobjectoptional
Object fields
cooldown_minutesintegeroptional
min: 1default: 10
enabledbooleanoptional
default: false
failure_rate_thresholdnumberoptional

Percentage.

min: 0max: 100default: 10
minimum_requestsintegeroptional
min: 0default: 20
notify_on_recoverybooleanoptional
default: true
window_minutesintegeroptional
min: 5max: 1440default: 15

Also accepts null.

detectionobjectoptional
Object fields
attachment_scanningobjectoptional

Request attachment scanning (images, PDFs, office documents): limits, text extraction and actions. Off by default. Partial updates merge. Under QuilrQL the policy decides enabled; attachments.* effects override the other fields (type_actions per kind).

Object fields
enabledbooleanoptional
default: false
image_classificationbooleanoptional
default: true
max_file_bytesintegeroptional
min: 1max: 536870912default: 20971520
max_filesintegeroptional
min: 1max: 1000default: 20
max_request_bytesintegeroptional
min: 1max: 2147483648default: 52428800
ocrobjectoptional
default: "no_text_layer"
"off""no_text_layer""always"
ocr_scriptsarray<object>optional
default: []
Array item specification
object

Values: "latin""cjk""korean""cyrillic""arabic""devanagari""tamil""telugu""thai""greek"

on_limit_violationobjectoptional
default: "block"
"monitor""strip""block"
on_macrosobjectoptional
default: "monitor"
"monitor""strip""block"
on_unscannableobjectoptional

What happens to an attachment the file itself makes unscannable: encrypted, unparseable, a remote URL or a provider file ID. Scan failures (timeouts, scanner errors, text past the scan limit) always fail open and never use this action.

default: "monitor"
"monitor""strip""block"
pdf_max_pagesintegeroptional
min: 1max: 10000default: 200
redact_documents_as_textbooleanoptional
default: false
text_extractionbooleanoptional
default: true
type_actionsobjectoptional

Per detected kind: allow, strip or block. Kinds not listed are allowed; updates merge per kind and {} resets every kind to allow.

default: {}
Object fields
archiveobjectoptional
"allow""strip""block"
audioobjectoptional
"allow""strip""block"
documentobjectoptional
"allow""strip""block"
imageobjectoptional
"allow""strip""block"
otherobjectoptional
"allow""strip""block"
pdfobjectoptional
"allow""strip""block"
presentationobjectoptional
"allow""strip""block"
spreadsheetobjectoptional
"allow""strip""block"
textobjectoptional
"allow""strip""block"
videoobjectoptional
"allow""strip""block"

Unknown fields are rejected in this object.

Unknown fields are rejected in this object.

category_actionsmap<string, string>optional

Category ID to action.

Map value specification
string

Adversarial detections have no redactable spans; actions they cannot apply are rejected.

Values: "monitor""partial-redact""tokenize""redact""block"

category_scopesmap<string, string>optional
Map value specification
string

Values: "request""response""both"

category_sensitivitiesmap<string, array<string>>optional
Map value specification
array<string>
custom_definitionsarray<object>optional

Replaces the whole selection; [] clears it. Never deletes definitions.

max items: 1000
Array item specification
actionstringoptional

Adversarial detections have no redactable spans; actions they cannot apply are rejected.

"monitor""partial-redact""tokenize""redact""block"
definition_idstringrequired

Stable ID from GET /custom-definitions.

min length: 1max length: 200
enabledbooleanoptional
default: true
scopestringoptional
"request""response""both"
sensitivitystringoptional
"low""medium""high"

Unknown fields are rejected in this object.

data_risk_actionstringoptional
"block""redact""partial-redact""tokenize""monitor"
edm_pattern_sensitivitiesmap<string, string>optional
Map value specification
string

Values: "low""medium""high"

enabled_categoriesmap<string, boolean>optional

Catalog category or subcategory IDs mapped to enabled state. Unknown IDs are rejected.

Map value specification
boolean
guardian_agentobjectoptional

Partial update of Guardian branches; set a branch's enabled to false to turn it off. Model-backed checks follow what the deployment supports.

Object fields
coding_helpersobjectoptional
Object fields
dependency_security_checkbooleanoptional
enabledbooleanoptional
latest_version_suggestionsbooleanoptional
enabledbooleanoptional
task_adherenceobjectoptional
Object fields
actionstringoptional
"nudge""block"
agent_purposestringoptional
enabledbooleanoptional
guardian_agent_promptstringoptional
sensitivitystringoptional
"low""medium""high"
hallucination_check_actionstringoptional
"block""monitor"
hallucination_check_risk_levelstringoptional
hallucination_check_score_thresholdnumberoptional
min: 0max: 1
is_hallucination_check_enabledbooleanoptional
sub_category_actionsmap<string, map<string, string>>optional

Category ID to subcategory name to action.

Map value specification
map<string, string>
sub_category_sensitivitiesmap<string, map<string, string>>optional
Map value specification
map<string, string>

Unknown fields are rejected in this object.

enabledbooleanoptional
limitsobjectoptional
Object fields
concurrency_per_minuteinteger | nulloptional
min: 0
model_rate_limitsarray<object>optional
Array item specification
concurrency_per_minuteinteger | nulloptional

Request admissions per 60 seconds.

min: 0
modelstringrequired

Exact configured model identifier.

min length: 1max length: 512
provider_labelstringrequired

Exact shared-provider label.

min length: 1max length: 200
rate_limitobject | nulloptional
RateLimit object
durationstringrequired
"minute""hour""day"
valueintegerrequired

Maximum events in the window; 0 disables.

min: 0

Also accepts null.

timeoutnumber | nulloptional

Seconds.

min: 0
token_limitsobject | nulloptional
TokenLimits object
inputobject | nulloptional
RateLimit object
durationstringrequired
"minute""hour""day"
valueintegerrequired

Maximum events in the window; 0 disables.

min: 0

Also accepts null.

max_per_requestinteger | nulloptional

Maximum input tokens per request; 0 disables.

min: 0
outputobject | nulloptional
RateLimit object
durationstringrequired
"minute""hour""day"
valueintegerrequired

Maximum events in the window; 0 disables.

min: 0

Also accepts null.

Also accepts null.

rate_limitobject | nulloptional
RateLimit object
durationstringrequired
"minute""hour""day"
valueintegerrequired

Maximum events in the window; 0 disables.

min: 0

Also accepts null.

rate_limit_per_minuteintegeroptional
min: 0
timeoutinteger | nulloptional
min: 0
token_limitsobjectoptional
Object fields
inputobject | nulloptional
RateLimit object
durationstringrequired
"minute""hour""day"
valueintegerrequired

Maximum events in the window; 0 disables.

min: 0

Also accepts null.

max_per_requestinteger | nulloptional

Maximum input tokens per request; 0 disables.

min: 0
outputobject | nulloptional
RateLimit object
durationstringrequired
"minute""hour""day"
valueintegerrequired

Maximum events in the window; 0 disables.

min: 0

Also accepts null.

Unknown fields are rejected in this object.

promptsobjectoptional
Object fields
require_system_from_storebooleanoptional
universal_system_promptobjectoptional

Prepended to the system prompt of every request when enabled; partial objects merge onto the stored value.

Object fields
contentstringoptional
max length: 100000
enabledbooleanoptional

Unknown fields are rejected in this object.

Unknown fields are rejected in this object.

provider_labelsarray<string>optional
max items: 1000
Array item specification
string
routingobjectoptional
Object fields
custom_routingarray<object>optional
Array item specification
groupstringoptional
default: "chat_completion"
"anthropic_messages""bedrock_runtime""chat_completion""responses""vertex_ai"
is_publishedbooleanrequired
modelsarray<object>required
Array item specification
credential_sourcestringoptional
labelstringoptional
modelstringrequired
provider_namestringrequired
typestringrequired
"High_Context_Request""Low_Context_Request""Medium_Context_Request"
routing_groupsarray<object>optional
Array item specification
group_kindstringoptional

Client API family the group serves.

"chat_completion""anthropic_messages""vertex_ai""responses""realtime""bedrock_runtime"
group_namestringrequired
modelsarray<object>required
min items: 1
Array item specification
credential_sourcestringoptional

Label of a shared provider attached to the app; inline credentials are not accepted.

model_namestringrequired
provider_namestringrequired
weightnumberrequired
greater than: 0
routing_thresholdsobjectoptional

Word-count boundaries of context routes: 0 <= low_max_words <= medium_max_words.

Object fields
low_max_wordsintegerrequired
min: 0
medium_max_wordsintegerrequired
min: 0

Unknown fields are rejected in this object.

token_based_routing_groupsarray<object>optional
Array item specification
group_kindstringoptional

Client API family the group serves.

"chat_completion""anthropic_messages""vertex_ai""responses""realtime""bedrock_runtime"
group_namestringrequired
modelsarray<object>required
min items: 1
Array item specification
credential_sourcestringoptional

Label of a shared provider attached to the app; inline credentials are not accepted.

model_namestringrequired
provider_namestringrequired
weightnumberrequired
greater than: 0

Unknown fields are rejected in this object.

self_serviceobjectoptional
Object fields
enable_self_servicebooleanoptional
self_serviceobjectoptional

Self-service configuration, including access-control roles. A save replaces the whole object (send every field you keep), except owners (kept when omitted) and origin (read-only). Omit to keep; null is not accepted.

Object fields
access_controlobject | nulloptional
Variant 1 object
self_service_viewerobjectoptional

Deny rules win. Referencing a group never changes its membership.

Object fields
allow_allbooleanoptional
default: false
allow_emailsarray<string>optional
unique items
Array item specification
string
format: email
allow_smart_groupsarray<string>optional
unique items
Array item specification
string

Existing smart-group name.

min length: 1
deny_emailsarray<string>optional
unique items
Array item specification
string
format: email
deny_smart_groupsarray<string>optional
unique items
Array item specification
string

Existing smart-group name.

min length: 1
settings_update_directobjectoptional

Deny rules win. Referencing a group never changes its membership.

Object fields
allow_allbooleanoptional
default: false
allow_emailsarray<string>optional
unique items
Array item specification
string
format: email
allow_smart_groupsarray<string>optional
unique items
Array item specification
string

Existing smart-group name.

min length: 1
deny_emailsarray<string>optional
unique items
Array item specification
string
format: email
deny_smart_groupsarray<string>optional
unique items
Array item specification
string

Existing smart-group name.

min length: 1
settings_update_requesterobjectoptional

Deny rules win. Referencing a group never changes its membership.

Object fields
allow_allbooleanoptional
default: false
allow_emailsarray<string>optional
unique items
Array item specification
string
format: email
allow_smart_groupsarray<string>optional
unique items
Array item specification
string

Existing smart-group name.

min length: 1
deny_emailsarray<string>optional
unique items
Array item specification
string
format: email
deny_smart_groupsarray<string>optional
unique items
Array item specification
string

Existing smart-group name.

min length: 1
show_api_keyobjectoptional

Deny rules win. Referencing a group never changes its membership.

Object fields
allow_allbooleanoptional
default: false
allow_emailsarray<string>optional
unique items
Array item specification
string
format: email
allow_smart_groupsarray<string>optional
unique items
Array item specification
string

Existing smart-group name.

min length: 1
deny_emailsarray<string>optional
unique items
Array item specification
string
format: email
deny_smart_groupsarray<string>optional
unique items
Array item specification
string

Existing smart-group name.

min length: 1
show_logs_for_all_usersobjectoptional

Deny rules win. Referencing a group never changes its membership.

Object fields
allow_allbooleanoptional
default: false
allow_emailsarray<string>optional
unique items
Array item specification
string
format: email
allow_smart_groupsarray<string>optional
unique items
Array item specification
string

Existing smart-group name.

min length: 1
deny_emailsarray<string>optional
unique items
Array item specification
string
format: email
deny_smart_groupsarray<string>optional
unique items
Array item specification
string

Existing smart-group name.

min length: 1
version1optional

Also accepts null.

max_api_key_ttl_daysinteger | nulloptional

Longest lifetime, in days, of a personal API key of this app. When set, every new key needs an expiry within it. null or omitted: no limit.

min: 1max: 3650
originobjectoptional

Present only on apps a person created from a blueprint in self-service. Set by the server; read-only (never changed by a save).

Object fields
blueprint_appstringoptional

The app it was copied from.

blueprint_config_versioninteger | nulloptional

The blueprint's configuration version at the copy.

created_atstring | nulloptional
created_bystringoptional

Email of the person who created it.

kindstringoptional
"blueprint"
ownersarray<string>optional

Emails of the app's owners: they review its budget and access requests (and own it when a person created it from a blueprint). A list replaces them; omitted or empty, the stored owners are kept. To remove every owner use PUT /apps/{app_name}/self-service-owners with [].

max items: 20
Array item specification
string

Unknown fields are rejected in this object.

smart_group_policiesarray<object>optional
Array item specification
actionsobjectoptional
Object fields
data_risk_actionstringoptional

Adversarial detections have no redactable spans; actions they cannot apply are rejected.

"monitor""partial-redact""tokenize""redact""block"
hallucination_check_actionstringoptional
"block""monitor"
category_actionsmap<string, string>optional
Map value specification
string

Adversarial detections have no redactable spans; actions they cannot apply are rejected.

Values: "monitor""partial-redact""tokenize""redact""block"

category_scopesmap<string, string>optional
Map value specification
string

Values: "request""response""both"

category_sensitivitiesmap<string, array<string>>optional
Map value specification
array<string>
enabledbooleanoptional
enabled_categoriesmap<string, boolean>optional

Catalog category or subcategory IDs to enabled state.

Map value specification
boolean
group_namestringrequired
sub_category_actionsmap<string, map<string, string>>optional
Map value specification
map<string, string>
sub_category_sensitivitiesmap<string, map<string, string>>optional
Map value specification
map<string, string>

Unknown fields are rejected in this object.

tagsarray<string>optional
max items: 1000
Array item specification
string
transformationsobjectoptional
Object fields
response_cacheobjectoptional

Response cache for non-streaming requests. Partial updates merge. Under QuilrQL the policy decides enabled, match and similarity.

Object fields
enabledbooleanoptional
default: false
flushbooleanoptional

true discards every cached response of the app.

write only
matchobjectoptional

exact: same prompt after whitespace cleanup. normalized: also ignores case, repeated spaces, punctuation around words and a fixed set of filler words. semantic: also matches a reworded last user message (chat and Anthropic Messages). Exact and normalized repeats skip every guardrail; a reworded match is served only after request guardrails pass the new prompt and skips the model call and response guardrails. Semantic can answer for a different name, title, username or filename in templated prompts: use it for human-typed FAQ or helpdesk apps, not programmatic pipelines.

default: "exact"
"exact""normalized""semantic"
max_size_mbintegeroptional
min: 1max: 1024default: 32
scopeobjectoptional
default: "app"
"app""user"
similarityobjectoptional

How close a semantic match must be. Used only when match is semantic.

default: "narrow"
"narrow""balanced""wider"
ttl_secondsintegeroptional
min: 60max: 604800default: 86400

Unknown fields are rejected in this object.

token_savingobjectoptional

Request-body transforms that reduce input tokens.

Object fields
base64_blob_elisionbooleanoptional
html_to_textbooleanoptional
json_minificationbooleanoptional
markdown_to_textbooleanoptional
smart_json_compressionbooleanoptional
text_compressionbooleanoptional
tool_output_cleanupbooleanoptional

Unknown fields are rejected in this object.

Unknown fields are rejected in this object.

Unknown fields are rejected in this object.

Example: guardrails, limits and an existing group​

{
"detection": {
"data_risk_action": "redact",
"enabled_categories": {"data_risk_category_pii": true},
"custom_definitions": [{
"definition_id": "employee_id",
"enabled": true,
"action": "block",
"scope": "request"
}],
"scan_images": true,
"scan_images_scope": "request"
},
"limits": {
"timeout": 60,
"rate_limit": {"value": 1000, "duration": "minute"},
"token_limits": {"max_per_request": 16000}
},
"smart_group_policies": [{
"group_name": "engineering",
"enabled": true,
"actions": {"data_risk_action": "monitor"}
}],
"transformations": {"token_saving": {"smart_json_compression": true}},
"prompts": {"require_system_from_store": true}
}

This assumes employee_id and engineering exist in the authenticated tenant. Query the catalogs first. OCR availability follows the deployment's model capability.

Example: weighted routing​

{
"routing": {
"routing_groups": [{
"group_name": "support-chat",
"group_kind": "chat_completion",
"models": [
{"provider_name": "openai", "credential_source": "Production OpenAI", "model_name": "gpt-4.1-mini", "weight": 80},
{"provider_name": "openai", "credential_source": "Backup OpenAI", "model_name": "gpt-4.1-mini", "weight": 20}
]
}],
"custom_routing": [],
"routing_thresholds": {"low_max_words": 200, "medium_max_words": 1000}
}
}

Both providers must already be attached with compatible models. Weights sum to 100. routing_groups and token_based_routing_groups are separate lists; omission preserves the other list. Use shared-provider references rather than inline credentials.

Catalogs and configuration history​

Read existing tenant resources and inspect configuration changes. These endpoints cover configuration and catalogs. For operational reporting, see the Usage API and the Monitoring API.

Catalogs​

GET /custom-definitions supports limit and cursor; a q search filter is Not Generally Available. Read one definition by definition_id (the same value as edm_id): use it in the path and as definition_id when selecting it in an app. Existing definitions can be referenced in app configuration; regex/EDM/semantic/intent authoring is Not Generally Available through these APIs.

Smart groups, their rank and virtual groups have their own page: the Smart groups API.

Configuration history​

List versions with /apps/{app_name}/versions; read one with /versions/{version_id}. Individual reads return version_record, with metadata and redacted previous_config/new_config snapshots when present. Unsafe legacy diffs are omitted.

Rollback requires the current app ETag and Idempotency-Key. It restores eligible settings as a new configuration change. It cannot rename the app, alter credential expiry, mutate provider/definition resources, restore inline credentials, change JWT keys or restore internal-only settings. Routing/group references are revalidated. App rollback does not roll back policy revisions.

Audit​

GET /audit returns tenant management events, newest first, with event_id, actor, operation, resource, request_id, result, created_at and changes. Rejected writes are recorded with their error code, and provider tests and discovery with their outcome only. created_at uses Unix seconds. Events are kept for 90 days. New events never invalidate a cursor; they appear on a fresh listing. Filter with actor (a management key id or administrator), operation (for example provider_update), resource, and since / until (RFC 3339 time, a date meaning UTC midnight, or epoch seconds). Unknown parameters are 400.

Operation recovery​

After 503 operation_pending, retain error.operation_id. Read /operations/{operation_id} with read using the same key that initiated the operation. The response contains operation_id, state, created_at and request_id.

POST /operations/{operation_id}/recover with config:write retries a saved configuration write and audit. It refuses to overwrite a later different configuration. An already completed operation returns its ID/state; a recovered configuration can also include app and warnings.

App/provider/credential creation recovers by retrying the original POST and Idempotency-Key, not the recovery endpoint. Read the retry contract before automating recovery.

GET/custom-definitions

List custom definitions

Custom detection definitions that apps can select by `edm_id` in detection.custom_definitions. Definitions are authored in the console; this API only references them.

REQUIRESread
Path, query & header parameters 2
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/v1/custom-definitions?limit=50' \
--header 'Authorization: Bearer <management-key>'

Authentication, errors & retry rules Try it in the playground

GET/custom-definitions/{definition_id}

Read a custom definition

One custom definition by its stable ID.

REQUIRESread
Path, query & header parameters 1
definition_id (path)stringrequired

No request body.

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

Authentication, errors & retry rules Try it in the playground

GET/apps/{app_name}/versions

List app configuration versions

Saved configuration versions of the app, newest first: version metadata only (id, version, time, operation, actor). Read one version for its before and after snapshots.

REQUIRESread

Also at /app/versions?app_name=... for app names that contain / or %.

Path, query & header parameters 3
app_name (path)stringrequired

Exact app name, URL-encoded.

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/v1/apps/Support%20Bot/versions?limit=50' \
--header 'Authorization: Bearer <management-key>'

Authentication, errors & retry rules Try it in the playground

GET/apps/{app_name}/versions/{version_id}

Read a configuration version

One configuration version with before and after snapshots (secret values omitted).

REQUIRESread

Also at /app/versions/{version_id}?app_name=... for app names that contain / or %.

Path, query & header parameters 2
app_name (path)stringrequired

Exact app name, URL-encoded.

version_id (path)stringrequired

No request body.

curl --request GET \
'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/apps/Support%20Bot/versions/ver_01' \
--header 'Authorization: Bearer <management-key>'

Authentication, errors & retry rules Try it in the playground

POST/apps/{app_name}/versions/{version_id}/rollback

Roll back app configuration

Restores the app settings saved in a version. Provider credentials and QuilrQL policy are not rolled back. Requires the current app ETag and an Idempotency-Key.

REQUIRESconfig:write

Also at /app/versions/{version_id}/rollback?app_name=... for app names that contain / or %.

Path, query & header parameters 4
app_name (path)stringrequired

Exact app name, URL-encoded.

version_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.

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

Unknown fields are rejected in this object.

curl --request POST \
'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/apps/Support%20Bot/versions/ver_01/rollback' \
--header 'Authorization: Bearer <management-key>' \
--header 'If-Match: "3f1c0a9e5b7d"' \
--header 'Idempotency-Key: create-support-bot-001'

Authentication, errors & retry rules Try it in the playground

GET/audit

List audit events

Management events of the tenant, newest first: actor, operation, resource, result and time. Rejected writes are recorded with their error code. Events are kept for 90 days. New events never invalidate a cursor.

REQUIRESread
Path, query & header parameters 7
limit (query)integeroptional

Page size.

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

Opaque cursor from the previous page's next_cursor.

actor (query)stringoptional

Exact actor (a management key id or administrator).

operation (query)stringoptional

Exact operation, for example provider_update.

resource (query)stringoptional

Exact resource name or id as recorded.

since (query)stringoptional

Inclusive start: RFC 3339 time, date (UTC midnight) or epoch seconds.

until (query)stringoptional

Exclusive end: RFC 3339 time, date (UTC midnight) or epoch seconds.

No request body.

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

Authentication, errors & retry rules Try it in the playground

GET/operations/{operation_id}

Read operation status

State of an idempotent write started by the same management key (other keys get 404). An operation left pending by an interruption can be finished with recover.

REQUIRESread
Path, query & header parameters 1
operation_id (path)stringrequired

No request body.

curl --request GET \
'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/operations/5b1d2e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f' \
--header 'Authorization: Bearer <management-key>'

Authentication, errors & retry rules Try it in the playground

POST/operations/{operation_id}/recover

Recover a pending operation

Finishes an interrupted app write (a 503 operation_pending response names its operation_id). Only the key that started it can recover it. Interrupted creations are not recovered here: retry the original POST with the same Idempotency-Key (409 retry_original_request).

REQUIRESconfig:write
Path, query & header parameters 1
operation_id (path)stringrequired
Full request body specification application/json

Unknown fields are rejected in this object.

curl --request POST \
'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/operations/5b1d2e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f/recover' \
--header 'Authorization: Bearer <management-key>'

Authentication, errors & retry rules Try it in the playground