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. Use the provider-settings field reference below and the credential requirements for your provider family. Managed QuilrAI providers do not require customer credentials.

Family	Provider types	Credential choices
API key	OpenAI, Anthropic/native Messages, DeepSeek, Gemini Chat Completions, Responses, Assistants, Realtime, Cohere/Jina/Voyage rerank, Sarvam.	`api_key`; optional compatible base URL/version where supported.
Azure	`azureopenai`, `openai_responses_azure`, `openai_assistants_azure`, `openai_realtime_azure`.	`api_key`, `azure_endpoint`, optional `azure_api_version`.
Custom endpoint	`general`, `general_rerank`, `anthropic_messages_azure`.	`api_key` and `base_url`.
AWS	`bedrock`, `anthropic_messages_bedrock`, `bedrock_embeddings`, `bedrock_rerank`.	Static keys or assume-role; fields from different modes cannot be mixed.
Vertex AI	`vertex_ai`.	API key, express, service-account JSON or ADC.
Oracle OCI	`oracle`, `oracle_responses`.	API key, gateway user principal, user/session principal, instance/resource principal.
QuilrAI managed	`quilr_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. Values are nullable, non-negative USD rates per million input/output/cache tokens. Null removes a rate override. These values are configuration, not a quotation of provider pricing.

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. Shared-provider deletion is Not Generally Available. Detaching removes a reference from one app only.

Explicit connection/model tests

Saving configuration never contacts the upstream provider. Use a separate test request when you want to:

Run a minimal configured-model check for a provider type listed in capabilities.model_test_provider_types; it may incur usage.
Connection-only tests are Not Generally Available. A kind:"connection" request is recognized but returns outcome:"unsupported" and code:"unsupported_test_kind" for every provider.

Tests use stored credentials and endpoints; they accept no arbitrary payload, URL or credential overrides. Testing a disabled provider does not enable it. A private endpoint unreachable from the central service returns a diagnostic, not a failed configuration save.

Completed tests return test.configuration_version, kind, model, outcome, code and completed_at (Unix seconds). latency_ms is present when a supported model probe runs. Outcomes are passed, failed or unsupported. A connection test never becomes a model call. Model tests are unavailable in a deployment with COMPLETELY_NO_GPU; there are no automatic billable retries.

Provider lists support limit and cursor; filtering by enabled or provider_name is Not Generally Available. Saves and reads return { "provider": { ... }, "request_id": "..." }; ordinary responses omit upstream secrets.

Provider endpoints

GET/providers

List shared providers

Tenant-scoped operation. Resource reads return redacted metadata; writes use the permissions and preconditions shown below.

REQUIRESread

Path, query & header parameters 2

limit (query)integeroptional

min: 1max: 200default: 50

cursor (query)stringoptional

No request body.

curl --request GET \
  'https://management.example.com/llmgateway/management/v1/providers?limit=50' \
  --header 'Authorization: Bearer <management-key>'

Authentication, errors & retry rules

POST/providers

Create a shared provider

Tenant-scoped operation. Resource reads return redacted metadata; writes use the permissions and preconditions shown below.

REQUIRESproviders:write

Path, query & header parameters 1

Idempotency-Key (header)stringrequired

min length: 1max length: 200

Full request body specification application/json

Shared-provider configuration. Creation requires label and provider_name plus credentials for that type. Label and provider type are immutable. Saves never probe upstream.

labelstringrequired

provider_namestringrequired

"openai""azureopenai""general""quilr_ai""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"

provider_settingsobjectoptional

Supply fields for the chosen provider type. Omitted PATCH credentials are preserved. Azure uses azure_api_version. Provider-specific required credentials are validated against the merged configuration.

Object fields

anthropic_versionstringoptional

Optional Anthropic API version header.

api_keystringoptional

Write-only secret. Omission preserves an existing secret on PATCH. Never echo redacted placeholders.

min length: 1write only

auth_typestringoptional

"api_key""express""service_account""adc""gateway_user_principal""user_principal""session_principal""instance_principal""resource_principal"

aws_access_keystringoptional

Write-only secret. Omission preserves an existing secret on PATCH. Never echo redacted placeholders.

min length: 1write only

aws_auth_modestringoptional

"static""assume_role"

aws_external_idstringoptional

Write-only secret. Omission preserves an existing secret on PATCH. Never echo redacted placeholders.

min length: 1write only

aws_regionstringoptional

min length: 1

aws_role_arnstringoptional

min length: 1

aws_role_session_namestringoptional

min length: 2max length: 64

aws_secret_keystringoptional

Write-only secret. Omission preserves an existing secret on PATCH. Never echo redacted placeholders.

min length: 1write only

aws_session_duration_secondsintegeroptional

min: 900max: 43200

aws_session_tokenstringoptional

Write-only secret. Omission preserves an existing secret on PATCH. Never echo redacted placeholders.

min length: 1write only

azure_api_versionstringoptional

Azure API version.

azure_endpointstringoptional

format: uri

base_urlstringoptional

format: uri

gcp_project_idstringoptional

min length: 1

gcp_regionstringoptional

oci_compartment_idstringoptional

min length: 1

oci_fingerprintstringoptional

min length: 1

oci_private_keystringoptional

Write-only secret. Omission preserves an existing secret on PATCH. Never echo redacted placeholders.

min length: 1write only

oci_private_key_passphrasestringoptional

Write-only secret. Omission preserves an existing secret on PATCH. Never echo redacted placeholders.

min length: 1write only

oci_project_idstringoptional

min length: 1

oci_regionstringoptional

min length: 1

oci_session_tokenstringoptional

Write-only secret. Omission preserves an existing secret on PATCH. Never echo redacted placeholders.

min length: 1write only

oci_tenancy_idstringoptional

min length: 1

oci_user_idstringoptional

min length: 1

service_account_jsonstringoptional

JSON-encoded Google service account document.

min length: 1write only

Unknown fields are rejected in this object.

selected_modelsarray<string>optional

max items: 1000

Array item specification

string

model_costsmap<string, object | null>optional

Map value specification

ModelCost object

input_per_1mnumber | nulloptional

USD per million tokens; null removes this override.

Variant 1 number

number

USD per million tokens; null removes this override.

min: 0

Also accepts null.

output_per_1mnumber | nulloptional

USD per million tokens; null removes this override.

Variant 1 number

number

USD per million tokens; null removes this override.

min: 0

Also accepts null.

cache_per_1mnumber | nulloptional

USD per million tokens; null removes this override.

Variant 1 number

number

USD per million tokens; null removes this override.

min: 0

Also accepts null.

Unknown fields are rejected in this object.

Also accepts null.

enabledbooleanoptional

Unknown fields are rejected in this object.

curl --request POST \
  'https://management.example.com/llmgateway/management/v1/providers' \
  --header 'Authorization: Bearer <management-key>' \
  --header 'Idempotency-Key: unique-operation-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "label": "Production OpenAI",
  "provider_name": "openai",
  "provider_settings": {
    "api_key": "<provider-api-key>"
  },
  "selected_models": [
    "gpt-4.1-mini"
  ]
}'

Authentication, errors & retry rules

GET/providers/{label}

Read a shared provider

Tenant-scoped operation. Resource reads return redacted metadata; writes use the permissions and preconditions shown below.

REQUIRESread

Path, query & header parameters 1

label (path)stringrequired

No request body.

curl --request GET \
  'https://management.example.com/llmgateway/management/v1/providers/Production%20OpenAI' \
  --header 'Authorization: Bearer <management-key>'

Authentication, errors & retry rules

PATCH/providers/{label}

Update or disable a provider

Tenant-scoped operation. Resource reads return redacted metadata; writes use the permissions and preconditions shown below.

REQUIRESproviders:write

Path, query & header parameters 2

label (path)stringrequired

If-Match (header)stringrequired

Quoted ETag returned by the latest resource read. Prompt/attachment/rollback writes use the app ETag.

Full request body specification application/json

Shared-provider configuration. Creation requires label and provider_name plus credentials for that type. Label and provider type are immutable. Saves never probe upstream.

labelstringoptional

provider_namestringoptional

provider_settingsobjectoptional

Object fields

anthropic_versionstringoptional

Optional Anthropic API version header.

api_keystringoptional

Write-only secret. Omission preserves an existing secret on PATCH. Never echo redacted placeholders.

min length: 1write only

auth_typestringoptional

"api_key""express""service_account""adc""gateway_user_principal""user_principal""session_principal""instance_principal""resource_principal"

aws_access_keystringoptional

Write-only secret. Omission preserves an existing secret on PATCH. Never echo redacted placeholders.

min length: 1write only

aws_auth_modestringoptional

"static""assume_role"

aws_external_idstringoptional

Write-only secret. Omission preserves an existing secret on PATCH. Never echo redacted placeholders.

min length: 1write only

aws_regionstringoptional

min length: 1

aws_role_arnstringoptional

min length: 1

aws_role_session_namestringoptional

min length: 2max length: 64

aws_secret_keystringoptional

Write-only secret. Omission preserves an existing secret on PATCH. Never echo redacted placeholders.

min length: 1write only

aws_session_duration_secondsintegeroptional

min: 900max: 43200

aws_session_tokenstringoptional

Write-only secret. Omission preserves an existing secret on PATCH. Never echo redacted placeholders.

min length: 1write only

azure_api_versionstringoptional

Azure API version.

azure_endpointstringoptional

format: uri

base_urlstringoptional

format: uri

gcp_project_idstringoptional

min length: 1

gcp_regionstringoptional

oci_compartment_idstringoptional

min length: 1

oci_fingerprintstringoptional

min length: 1

oci_private_keystringoptional

Write-only secret. Omission preserves an existing secret on PATCH. Never echo redacted placeholders.

min length: 1write only

oci_private_key_passphrasestringoptional

Write-only secret. Omission preserves an existing secret on PATCH. Never echo redacted placeholders.

min length: 1write only

oci_project_idstringoptional

min length: 1

oci_regionstringoptional

min length: 1

oci_session_tokenstringoptional

Write-only secret. Omission preserves an existing secret on PATCH. Never echo redacted placeholders.

min length: 1write only

oci_tenancy_idstringoptional

min length: 1

oci_user_idstringoptional

min length: 1

service_account_jsonstringoptional

JSON-encoded Google service account document.

min length: 1write only

Unknown fields are rejected in this object.

selected_modelsarray<string>optional

max items: 1000

Array item specification

string

model_costsmap<string, object | null>optional

Map value specification

ModelCost object

input_per_1mnumber | nulloptional

USD per million tokens; null removes this override.

Variant 1 number

number

USD per million tokens; null removes this override.

min: 0

Also accepts null.

output_per_1mnumber | nulloptional

USD per million tokens; null removes this override.

Variant 1 number

number

USD per million tokens; null removes this override.

min: 0

Also accepts null.

cache_per_1mnumber | nulloptional

USD per million tokens; null removes this override.

Variant 1 number

number

USD per million tokens; null removes this override.

min: 0

Also accepts null.

Unknown fields are rejected in this object.

Also accepts null.

enabledbooleanoptional

Unknown fields are rejected in this object.

curl --request PATCH \
  'https://management.example.com/llmgateway/management/v1/providers/Production%20OpenAI' \
  --header 'Authorization: Bearer <management-key>' \
  --header 'If-Match: "resource-version-from-read"' \
  --header 'Content-Type: application/json' \
  --data '{
  "enabled": false
}'

Authentication, errors & retry rules

POST/providers/{label}/test

Test connection or model

Stored configuration only. Connection tests return unsupported_test_kind. Model tests are limited to model_test_provider_types from capabilities and are disabled under COMPLETELY_NO_GPU. Connection-only testing is Not Generally Available.

REQUIRESproviders:write

Path, query & header parameters 1

label (path)stringrequired

Full request body specification application/json

kindstringrequired

Model tests support the provider types advertised by capabilities. Connection-only tests are Not Generally Available and return unsupported_test_kind.

"connection""model"

modelstringoptional

Unknown fields are rejected in this object.

curl --request POST \
  'https://management.example.com/llmgateway/management/v1/providers/Production%20OpenAI/test' \
  --header 'Authorization: Bearer <management-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "kind": "model",
  "model": "gpt-4.1-mini"
}'

Authentication, errors & retry rules

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

Section	Accepted controls
`detection`	Categories, actions, scopes, sensitivities, existing custom definitions, Guardian Agent, hallucination settings, image OCR and encoded-image OCR.
`routing`	`routing_groups`, `token_based_routing_groups`, `custom_routing`, `routing_thresholds`.
`limits`	Timeout, concurrency, request rates, token limits and per-model limits.
`access`	Source IPs, email/domain restrictions, identity/conversation requirements, identity headers and JWT settings.
`self_service`	`enable_self_service` plus the stored `self_service` object containing `access_control`.
`transformations`	`token_saving`.
`prompts`	`require_system_from_store`. Prompt content uses separate endpoints.
Top-level fields	`enabled`, `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

Stored app settings. Omitted fields are preserved. Unknown top-level and section fields are rejected. Nested controls follow the existing gateway validators. Responses report settings that are inactive under QuilrQL.

detectionobjectoptional

Object fields

category_actionsmap<string, string>optional

Category ID to action.

Map value specification

string

Adversarial detections do not expose redactable spans; incompatible actions are rejected by catalog validation.

Values: "monitor""partial-redact""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

Full replacement of definition selections; [] removes selections. Does not delete definitions.

max items: 1000

Array item specification

definition_idstringrequired

Stable ID from GET /custom-definitions.

min length: 1max length: 200

enabledbooleanoptional

default: true

actionstringoptional

Adversarial detections do not expose redactable spans; incompatible actions are rejected by catalog validation.

"monitor""partial-redact""redact""block"

scopestringoptional

"request""response""both"

sensitivitystringoptional

"low""medium""high"

Unknown fields are rejected in this object.

data_risk_actionstringoptional

Adversarial detections do not expose redactable spans; incompatible actions are rejected by catalog validation.

"monitor""partial-redact""redact""block"

edm_pattern_sensitivitiesmap<string, string>optional

Map value specification

string

Values: "low""medium""high"

enabled_categoriesmap<string, boolean>optional

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

Map value specification

boolean

guardian_agentobjectoptional

Partial update of Guardian branches. Set a branch enabled:false to disable it. Model-backed checks follow deployment capability.

Object fields

enabledbooleanoptional

coding_helpersobjectoptional

Object fields

enabledbooleanoptional

dependency_security_checkbooleanoptional

latest_version_suggestionsbooleanoptional

task_adherenceobjectoptional

Object fields

enabledbooleanoptional

actionstringoptional

"nudge""block"

sensitivitystringoptional

"low""medium""high"

agent_purposestringoptional

guardian_agent_promptstringoptional

hallucination_check_actionstringoptional

"block""monitor"

hallucination_check_risk_levelstringoptional

hallucination_check_score_thresholdnumberoptional

min: 0max: 1

is_hallucination_check_enabledbooleanoptional

scan_encoded_imagesbooleanoptional

scan_encoded_images_scopestringoptional

"request""response""both"

scan_imagesbooleanoptional

scan_images_scopestringoptional

"request""response""both"

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.

limitsobjectoptional

Object fields

concurrency_per_minuteinteger | nulloptional

min: 0

model_rate_limitsarray<object>optional

Array item specification

provider_labelstringrequired

Exact, trimmed tenant-wide provider label. Immutable after creation.

min length: 1max length: 200

modelstringrequired

Exact configured model identifier; availability depends on the provider and deployment.

min length: 1max length: 512

timeoutnumber | nulloptional

Seconds.

Variant 1 number

number

Seconds.

min: 0

Also accepts null.

concurrency_per_minuteinteger | nulloptional

Request admissions per 60 seconds, following existing gateway semantics.

Variant 1 integer

integer

Request admissions per 60 seconds, following existing gateway semantics.

min: 0

Also accepts null.

rate_limitobject | nulloptional

RateLimit object

valueintegerrequired

Maximum events in the window; zero disables this limit.

min: 0

durationstringrequired

"minute""hour""day"

Also accepts null.

token_limitsobject | nulloptional

TokenLimits object

max_per_requestinteger | nulloptional

Maximum input tokens per request; zero disables.

Variant 1 integer

integer

Maximum input tokens per request; zero disables.

min: 0

Also accepts null.

inputobject | nulloptional

RateLimit object

valueintegerrequired

Maximum events in the window; zero disables this limit.

min: 0

durationstringrequired

"minute""hour""day"

Also accepts null.

outputobject | nulloptional

RateLimit object

valueintegerrequired

Maximum events in the window; zero disables this limit.

min: 0

durationstringrequired

"minute""hour""day"

Also accepts null.

rate_limitobject | nulloptional

RateLimit object

valueintegerrequired

Maximum events in the window; zero disables this limit.

min: 0

durationstringrequired

"minute""hour""day"

Also accepts null.

rate_limit_per_minuteintegeroptional

min: 0

timeoutinteger | nulloptional

min: 0

token_limitsobjectoptional

Object fields

max_per_requestinteger | nulloptional

Maximum input tokens per request; zero disables.

Variant 1 integer

integer

Maximum input tokens per request; zero disables.

min: 0

Also accepts null.

inputobject | nulloptional

RateLimit object

valueintegerrequired

Maximum events in the window; zero disables this limit.

min: 0

durationstringrequired

"minute""hour""day"

Also accepts null.

outputobject | nulloptional

RateLimit object

valueintegerrequired

Maximum events in the window; zero disables this limit.

min: 0

durationstringrequired

"minute""hour""day"

Also accepts null.

Unknown fields are rejected in this object.

routingobjectoptional

Object fields

custom_routingarray<object>optional

Array item specification

groupstringoptional

"chat_completion""anthropic_messages""vertex_ai""responses""bedrock_runtime"

typestringrequired

"Low_Context_Request""Medium_Context_Request""High_Context_Request"

is_publishedbooleanrequired

modelsarray<object>required

Array item specification

provider_namestringrequired

modelstringrequired

labelstringoptional

credential_sourcestringoptional

routing_groupsarray<object>optional

Array item specification

group_namestringrequired

group_kindstringoptional

"chat_completion""anthropic_messages""vertex_ai""responses""realtime""bedrock_runtime"

modelsarray<object>required

min items: 1

Array item specification

provider_namestringrequired

model_namestringrequired

credential_sourcestringoptional

Attached shared-provider label; no inline credentials.

weightnumberrequired

greater than: 0

routing_thresholdsobjectoptional

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_namestringrequired

group_kindstringoptional

"chat_completion""anthropic_messages""vertex_ai""responses""realtime""bedrock_runtime"

modelsarray<object>required

min items: 1

Array item specification

provider_namestringrequired

model_namestringrequired

credential_sourcestringoptional

Attached shared-provider label; no inline credentials.

weightnumberrequired

greater than: 0

Unknown fields are rejected in this object.

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

enabledbooleanoptional

allowed_issuersarray<string>optional

Array item specification

string

allowed_client_idsarray<string>optional

Array item specification

string

public_key_pemstringoptional

RSA public key in PEM format. Required for an enabled configuration; saves do not fetch JWKS URLs.

kidstringoptional

Unknown fields are rejected in this object.

Also accepts null.

Unknown fields are rejected in this object.

transformationsobjectoptional

Object fields

token_savingobjectoptional

Object fields

smart_json_compressionbooleanoptional

html_to_textbooleanoptional

markdown_to_textbooleanoptional

text_compressionbooleanoptional

Unknown fields are rejected in this object.

self_serviceobjectoptional

Object fields

enable_self_servicebooleanoptional

self_serviceobjectoptional

Stored self-service configuration. Access-control roles live inside this object. Omit to preserve; the section itself does not accept null.

Object fields

access_controlobject | nulloptional

Variant 1 object

version1optional

self_service_viewerobjectoptional

Deny rules win. A group reference never changes group membership.

Object fields

allow_allbooleanoptional

default: false

allow_emailsarray<string>optional

unique items

Array item specification

string

format: email

deny_emailsarray<string>optional

unique items

Array item specification

string

format: email

allow_smart_groupsarray<string>optional

unique items

Array item specification

string

Existing gateway smart-group name.

min length: 1

deny_smart_groupsarray<string>optional

unique items

Array item specification

string

Existing gateway smart-group name.

min length: 1

settings_update_requesterobjectoptional

Deny rules win. A group reference never changes group membership.

Object fields

allow_allbooleanoptional

default: false

allow_emailsarray<string>optional

unique items

Array item specification

string

format: email

deny_emailsarray<string>optional

unique items

Array item specification

string

format: email

allow_smart_groupsarray<string>optional

unique items

Array item specification

string

Existing gateway smart-group name.

min length: 1

deny_smart_groupsarray<string>optional

unique items

Array item specification

string

Existing gateway smart-group name.

min length: 1

settings_update_directobjectoptional

Deny rules win. A group reference never changes group membership.

Object fields

allow_allbooleanoptional

default: false

allow_emailsarray<string>optional

unique items

Array item specification

string

format: email

deny_emailsarray<string>optional

unique items

Array item specification

string

format: email

allow_smart_groupsarray<string>optional

unique items

Array item specification

string

Existing gateway smart-group name.

min length: 1

deny_smart_groupsarray<string>optional

unique items

Array item specification

string

Existing gateway smart-group name.

min length: 1

show_api_keyobjectoptional

Deny rules win. A group reference never changes group membership.

Object fields

allow_allbooleanoptional

default: false

allow_emailsarray<string>optional

unique items

Array item specification

string

format: email

deny_emailsarray<string>optional

unique items

Array item specification

string

format: email

allow_smart_groupsarray<string>optional

unique items

Array item specification

string

Existing gateway smart-group name.

min length: 1

deny_smart_groupsarray<string>optional

unique items

Array item specification

string

Existing gateway smart-group name.

min length: 1

show_logs_for_all_usersobjectoptional

Deny rules win. A group reference never changes group membership.

Object fields

allow_allbooleanoptional

default: false

allow_emailsarray<string>optional

unique items

Array item specification

string

format: email

deny_emailsarray<string>optional

unique items

Array item specification

string

format: email

allow_smart_groupsarray<string>optional

unique items

Array item specification

string

Existing gateway smart-group name.

min length: 1

deny_smart_groupsarray<string>optional

unique items

Array item specification

string

Existing gateway smart-group name.

min length: 1

Also accepts null.

Unknown fields are rejected in this object.

promptsobjectoptional

Object fields

require_system_from_storebooleanoptional

Unknown fields are rejected in this object.

enabledbooleanoptional

smart_group_policiesarray<object>optional

Array item specification

enabled_categoriesmap<string, boolean>optional

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

Map value specification

boolean

category_actionsmap<string, string>optional

Category ID to action.

Map value specification

string

Adversarial detections do not expose redactable spans; incompatible actions are rejected by catalog validation.

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

sub_category_actionsmap<string, map<string, string>>optional

Category ID to subcategory name to action.

Map value specification

map<string, string>

category_scopesmap<string, string>optional

Map value specification

string

Values: "request""response""both"

category_sensitivitiesmap<string, array<string>>optional

Map value specification

array<string>

group_namestringrequired

enabledbooleanoptional

actionsobjectoptional

Object fields

data_risk_actionstringoptional

Adversarial detections do not expose redactable spans; incompatible actions are rejected by catalog validation.

"monitor""partial-redact""redact""block"

hallucination_check_actionstringoptional

"block""monitor"

sub_category_sensitivitiesmap<string, map<string, string>>optional

Map value specification

map<string, string>

Unknown fields are rejected in this object.

alertingobject | nulloptional

Alerting object

app_levelobjectoptional

Object fields

enabledbooleanoptional

default: false

window_minutesintegeroptional

min: 5max: 1440default: 15

failure_rate_thresholdnumberoptional

Percentage.

min: 0max: 100default: 10

minimum_requestsintegeroptional

min: 0default: 20

cooldown_minutesintegeroptional

min: 1default: 10

notify_on_recoverybooleanoptional

default: true

provider_levelobjectoptional

Object fields

enabledbooleanoptional

default: false

window_minutesintegeroptional

min: 5max: 1440default: 15

failure_rate_thresholdnumberoptional

Percentage.

min: 0max: 100default: 10

minimum_requestsintegeroptional

min: 0default: 20

cooldown_minutesintegeroptional

min: 1default: 10

notify_on_recoverybooleanoptional

default: true

channelsobjectoptional

Object fields

emailsarray<string>optional

unique items

Array item specification

string

format: email

webhooksarray<object>optional

Array item specification

idstringoptional

min length: 1

typestringoptional

default: "generic"

"slack""generic"

labelstringoptional

urlstringrequired

HTTPS webhook URL, required for each submitted webhook. Omit the whole alerting field to preserve stored configuration.

format: uriwrite only

Also accepts null.

provider_labelsarray<string>optional

max items: 1000

Array item specification

string

tagsarray<string>optional

max items: 1000

Array item specification

string

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 APIs do not expose inference traffic logs or operational reporting.

Catalogs

GET /smart-groups and GET /custom-definitions support limit and cursor; a q search filter is Not Generally Available. Individual resource reads use group_name or definition_id. Definition catalog records use the stable edm_id; pass that value as definition_id when selecting it in an app.

Existing groups/definitions can be referenced in app configuration. Group/membership writes and regex/EDM/semantic/intent authoring are Not Generally Available through these APIs.

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 with event_id, actor, operation, resource, request_id, result, created_at and changes. created_at uses Unix seconds. Only limit and cursor are supported; app-name, operation, management-key and time-range filters are Not Generally Available.

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/apps/{app_name}/versions

List app configuration versions

Tenant-scoped operation. Resource reads return redacted metadata; writes use the permissions and preconditions shown below.

REQUIRESread

Path, query & header parameters 3

app_name (path)stringrequired

limit (query)integeroptional

min: 1max: 200default: 50

cursor (query)stringoptional

No request body.

curl --request GET \
  'https://management.example.com/llmgateway/management/v1/apps/Support%20Bot/versions?limit=50' \
  --header 'Authorization: Bearer <management-key>'

Authentication, errors & retry rules

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

Read a configuration version

Tenant-scoped operation. Resource reads return redacted metadata; writes use the permissions and preconditions shown below.

REQUIRESread

Path, query & header parameters 2

app_name (path)stringrequired

version_id (path)stringrequired

No request body.

curl --request GET \
  'https://management.example.com/llmgateway/management/v1/apps/Support%20Bot/versions/version_example' \
  --header 'Authorization: Bearer <management-key>'

Authentication, errors & retry rules

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

Roll back app configuration

Restricted app configuration rollback; no policy rollback. Requires the current app ETag and Idempotency-Key.

REQUIRESconfig:write

Path, query & header parameters 4

app_name (path)stringrequired

version_id (path)stringrequired

If-Match (header)stringrequired

Quoted ETag returned by the latest resource read. Prompt/attachment/rollback writes use the app ETag.

Idempotency-Key (header)stringrequired

min length: 1max length: 200

Full request body specification application/json

Unknown fields are rejected in this object.

curl --request POST \
  'https://management.example.com/llmgateway/management/v1/apps/Support%20Bot/versions/version_example/rollback' \
  --header 'Authorization: Bearer <management-key>' \
  --header 'If-Match: "resource-version-from-read"' \
  --header 'Idempotency-Key: unique-operation-001' \
  --header 'Content-Type: application/json' \
  --data '{}'

Authentication, errors & retry rules

GET/smart-groups

List smart groups

Tenant-scoped operation. Resource reads return redacted metadata; writes use the permissions and preconditions shown below.

REQUIRESread

Path, query & header parameters 2

limit (query)integeroptional

min: 1max: 200default: 50

cursor (query)stringoptional

No request body.

curl --request GET \
  'https://management.example.com/llmgateway/management/v1/smart-groups?limit=50' \
  --header 'Authorization: Bearer <management-key>'

Authentication, errors & retry rules

GET/smart-groups/{group_name}

Read a smart group

Tenant-scoped operation. Resource reads return redacted metadata; writes use the permissions and preconditions shown below.

REQUIRESread

Path, query & header parameters 1

group_name (path)stringrequired

No request body.

curl --request GET \
  'https://management.example.com/llmgateway/management/v1/smart-groups/engineering' \
  --header 'Authorization: Bearer <management-key>'

Authentication, errors & retry rules

GET/custom-definitions

List custom definitions

Tenant-scoped operation. Resource reads return redacted metadata; writes use the permissions and preconditions shown below.

REQUIRESread

Path, query & header parameters 2

limit (query)integeroptional

min: 1max: 200default: 50

cursor (query)stringoptional

No request body.

curl --request GET \
  'https://management.example.com/llmgateway/management/v1/custom-definitions?limit=50' \
  --header 'Authorization: Bearer <management-key>'

Authentication, errors & retry rules

GET/custom-definitions/{definition_id}

Read a custom definition

Tenant-scoped operation. Resource reads return redacted metadata; writes use the permissions and preconditions shown below.

REQUIRESread

Path, query & header parameters 1

definition_id (path)stringrequired

No request body.

curl --request GET \
  'https://management.example.com/llmgateway/management/v1/custom-definitions/employee_id' \
  --header 'Authorization: Bearer <management-key>'

Authentication, errors & retry rules

GET/audit

Get audit

Tenant management events, including actor, resource, result and created_at in Unix seconds. Only limit/cursor are supported; no app/key/time filters.

REQUIRESread

Path, query & header parameters 2

limit (query)integeroptional

min: 1max: 200default: 50

cursor (query)stringoptional

No request body.

curl --request GET \
  'https://management.example.com/llmgateway/management/v1/audit?limit=50' \
  --header 'Authorization: Bearer <management-key>'

Authentication, errors & retry rules

GET/operations/{operation_id}

Get operation

Status is visible only to the same management key that initiated the operation.

REQUIRESread

Path, query & header parameters 1

operation_id (path)stringrequired

No request body.

curl --request GET \
  'https://management.example.com/llmgateway/management/v1/operations/operation_example' \
  --header 'Authorization: Bearer <management-key>'

Authentication, errors & retry rules

POST/operations/{operation_id}/recover

Post recover

Retry a saved configuration write using the initiating key. Requires config:write. Creation must instead retry the original POST with its original Idempotency-Key.

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://management.example.com/llmgateway/management/v1/operations/operation_example/recover' \
  --header 'Authorization: Bearer <management-key>' \
  --header 'Content-Type: application/json' \
  --data '{}'

Authentication, errors & retry rules

GET/app/versions

List app configuration versions (query locator)

Tenant-scoped operation. Resource reads return redacted metadata; writes use the permissions and preconditions shown below. Use app_name in the query for names containing slashes or literal percent signs; URL-encode the query value once.

REQUIRESread

Path, query & header parameters 3

app_name (query)stringrequired

Exact display name; encode with standard query URL encoding.

limit (query)integeroptional

min: 1max: 200default: 50

cursor (query)stringoptional

No request body.

curl --request GET \
  'https://management.example.com/llmgateway/management/v1/app/versions?app_name=Support%20Bot&limit=50' \
  --header 'Authorization: Bearer <management-key>'

Authentication, errors & retry rules

GET/app/versions/{version_id}

Read a configuration version (query locator)

REQUIRESread

Path, query & header parameters 2

version_id (path)stringrequired

app_name (query)stringrequired

Exact display name; encode with standard query URL encoding.

No request body.

curl --request GET \
  'https://management.example.com/llmgateway/management/v1/app/versions/version_example?app_name=Support%20Bot' \
  --header 'Authorization: Bearer <management-key>'

Authentication, errors & retry rules

POST/app/versions/{version_id}/rollback

Roll back app configuration (query locator)

Restricted app configuration rollback; no policy rollback. Requires the current app ETag and Idempotency-Key. Use app_name in the query for names containing slashes or literal percent signs; URL-encode the query value once.

REQUIRESconfig:write

Path, query & header parameters 4

version_id (path)stringrequired

app_name (query)stringrequired

Exact display name; encode with standard query URL encoding.

If-Match (header)stringrequired

Quoted ETag returned by the latest resource read. Prompt/attachment/rollback writes use the app ETag.

Idempotency-Key (header)stringrequired

min length: 1max length: 200

Full request body specification application/json

Unknown fields are rejected in this object.

curl --request POST \
  'https://management.example.com/llmgateway/management/v1/app/versions/version_example/rollback?app_name=Support%20Bot' \
  --header 'Authorization: Bearer <management-key>' \
  --header 'If-Match: "resource-version-from-read"' \
  --header 'Idempotency-Key: unique-operation-001' \
  --header 'Content-Type: application/json' \
  --data '{}'

Authentication, errors & retry rules

Shared providers and model tests​

Provider inputs​

Models and rates​

Rotation and disabling​

Explicit connection/model tests​

Provider endpoints​

Full app configuration input​

Partial updates​

Configuration map​

JWT authentication​

Settings under QuilrQL​

Complete PATCH schema​

Example: guardrails, limits and an existing group​

Example: weighted routing​

Catalogs and configuration history​

Catalogs​

Configuration history​

Audit​

Operation recovery​

Shared providers and model tests

Provider inputs

Models and rates

Rotation and disabling

Explicit connection/model tests

Provider endpoints

Full app configuration input

Partial updates

Configuration map

JWT authentication

Settings under QuilrQL

Complete PATCH schema

Example: guardrails, limits and an existing group

Example: weighted routing

Catalogs and configuration history

Catalogs

Configuration history

Audit

Operation recovery