Apps & provider attachments

An app owns its gateway credentials, stored controls, routing, prompts and configuration history. Manage it by app name within the key's tenant. There is no app-delete API.

Naming and identity

Names are trimmed and compared case-insensitively. New names must be unique among enabled and disabled apps. A disabled app continues to reserve its name. If multiple legacy apps match a name, the API returns 409 ambiguous_app_name instead of choosing one silently.

Encode names as one URL path segment: Support Bot becomes Support%20Bot. Handling existing names containing slashes and Unicode still needs proxy/router verification before release. Renaming is not part of v1. Changing an individual credential does not change the canonical app or log attribution.

Creating an app

Input	Rule
name	Required display name, 1-200 characters.
mode	gateway by default; sdk and copilot_studio preserve their existing providerless app modes.
provider_labels	Required, ordered, nonempty list for gateway apps. First is primary. Omit for providerless modes.
initial_key	Optional. Omission still issues one key named Default. Optional expiry applies to the gateway key, not the management key.
Configuration sections	See full configuration input. Omitted controls begin unset, with runtime defaults advertised by capabilities.

App creation validates configuration without contacting an upstream model. It does not publish QuilrQL or imply that a model is reachable.

Disable means the whole app

PATCH enabled:false to prevent newly admitted runtime traffic once the new configuration has propagated. Settings, provider references, keys, prompts and history remain available to management. Setting enabled:true resumes normal authentication, provider and policy checks.

Whole-app availability is independent of QuilrQL. Disabling an app does not become an inactive policy-governed setting, and re-enabling it does not resurrect expired/revoked keys. This is different from disabling just its primary provider.

Attachment and conversion rules

• Attach an existing enabled shared provider by label. primary:false preserves the current primary; primary:true deliberately promotes the attachment.
• provider_labels on an app PATCH replaces the entire ordered selection. Omission preserves it.
• A detach is app-local. Reject unresolved routing/policy references and invalid primary/last-provider removal. Replace selection and routing together when needed.
• Legacy inline-provider apps can be read and receive non-provider edits. Provider changes require the explicit conversion endpoint first.
• Conversion supplies the complete shared-provider selection. It preserves the canonical app and its keys; it does not silently create shared providers or publish policy.

Endpoint reference

Expand Full request body specification for every field, including nested configuration. For a focused view, see the configuration schema.

GET/apps

List apps

List enabled and disabled apps in the key's tenant. Credentials are never included.

REQUIRESread

Path, query & header parameters 5

limit (query)integeroptional

Items per page.

min: 1max: 200default: 50

cursor (query)stringoptional

Opaque cursor returned by this same collection and filters.

name (query)stringoptional

Optional name search.

tag (query)stringoptional

Match a tag.

enabled (query)booleanoptional

Optional enabled-state filter.

No request body.

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

Authentication, errors & retry rules

POST/apps

Create an app

Create a named app and exactly one initial gateway credential. Default key name is Default. Shared providers only. Does not call upstream or publish policy.

REQUIRESconfig:writecredentials:write

Path, query & header parameters 1

Idempotency-Key (header)stringrequired

Unique operation key. Reuse only with the identical request; mismatch returns 409.

min length: 1max length: 128

Full request body specification application/json

Defaults: enabled true; mode gateway; initial key named Default with no expiry. New omitted guardrail/control sections begin unset, and capability/schema metadata supplies runtime defaults. QuilrQL can independently govern requests.

namestringrequired

Trimmed display name. App lookup is case-insensitive within the authenticated tenant. Ambiguous legacy names return 409.

min length: 1max length: 200

modestringoptional

default: "gateway"

"gateway""sdk""copilot_studio"

initial_keyobjectoptional

Initial key uses Default when omitted. Additional key creation requires a name.

Object fields

namestringoptional

Trimmed, case-insensitively unique among non-revoked keys of this app.

min length: 1max length: 120default: "Default"

expires_atstring | nulloptional

Omit on create or send null for no expiry. On PATCH, omission preserves the current expiry and null removes it. Expired/revoked credentials cannot be resurrected.

Variant 1 string

string

Future RFC 3339 timestamp with an explicit timezone.

format: date-time

Also accepts null.

Unknown fields are rejected in this object.

enabledbooleanoptional

Whole-app availability, independent of QuilrQL. Disabled apps retain keys/configuration.

default: true

tagsarray<string>optional

Complete replacement.

unique items

Array item specification

string

min length: 1max length: 120

provider_labelsarray<string>optional

Ordered complete provider selection, primary first. Mutating this field on an inline app requires explicit conversion.

min items: 1unique items

Array item specification

string

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

min length: 1max length: 200

detectionobjectoptional

Stored detection controls. Catalogs validate IDs and action/scope compatibility. Governed updates remain inactive while QuilrQL owns enforcement.

Object fields

data_risk_actionstringoptional

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

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

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>

min items: 1unique items

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

Map value specification

map<string, array<string>>

edm_pattern_sensitivitiesmap<string, string>optional

Map value specification

string

Values: "low""medium""high"

custom_definitionsarray<object>optional

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

Array item specification

definition_idstringrequired

Stable ID from GET /custom-definitions.

min length: 1

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.

Unknown fields are rejected in this object.

routingobjectoptional

Targets reference attached shared providers and configured models. No inline credentials are accepted. Surface compatibility and sum-of-weights checks are mandatory.

Object fields

groupsarray<object>optional

Complete replacement; [] clears all named request/token groups.

Array item specification

namestringrequired

App-scoped routing alias.

min length: 1max length: 200

kindstringrequired

Must match the models and supported API surface.

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

modestringrequired

Balance by request count or token usage.

"requests""tokens"

membersarray<object>required

min items: 1

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

weightnumberrequired

Positive percentage. All members of a group must sum to 100.

max: 100greater than: 0

Unknown fields are rejected in this object.

Unknown fields are rejected in this object.

context_routesarray<object>optional

Complete replacement; [] clears custom context routes.

Array item specification

kindstringrequired

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

contextstringrequired

Only the supported low-context override is active in this v1 contract.

"low"

enabledbooleanoptional

default: true

targetsarray<object>required

Ordered fallback targets.

min items: 1

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

Unknown fields are rejected in this object.

Unknown fields are rejected in this object.

context_thresholdsobjectoptional

Object fields

low_max_wordsintegerrequired

min: 0

medium_max_wordsintegerrequired

Must be greater than or equal to low_max_words.

min: 0

Unknown fields are rejected in this object.

Unknown fields are rejected in this object.

limitsobjectoptional

Object fields

timeoutnumber | nulloptional

Upstream timeout in seconds; null clears the configured override.

Variant 1 number

number

Upstream timeout in seconds; null clears the configured override.

min: 0

Also accepts null.

concurrency_per_minuteinteger | nulloptional

Admission count over the existing 60-second window.

Variant 1 integer

integer

Admission count over the existing 60-second window.

min: 0

Also accepts null.

rate_limitobject | nulloptional

Null clears the request limit.

RateLimit object

valueintegerrequired

Maximum events in the window; zero disables this limit.

min: 0

durationstringrequired

"minute""hour""day"

Unknown fields are rejected in this object.

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"

Unknown fields are rejected in this object.

Also accepts null.

outputobject | nulloptional

RateLimit object

valueintegerrequired

Maximum events in the window; zero disables this limit.

min: 0

durationstringrequired

"minute""hour""day"

Unknown fields are rejected in this object.

Also accepts null.

Unknown fields are rejected in this object.

Also accepts null.

model_rate_limitsarray<object>optional

Full replacement; [] removes all model overrides. App and model limits both apply.

unique items

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"

Unknown fields are rejected in this object.

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"

Unknown fields are rejected in this object.

Also accepts null.

outputobject | nulloptional

RateLimit object

valueintegerrequired

Maximum events in the window; zero disables this limit.

min: 0

durationstringrequired

"minute""hour""day"

Unknown fields are rejected in this object.

Also accepts null.

Unknown fields are rejected in this object.

Also accepts null.

Unknown fields are rejected in this object.

Unknown fields are rejected in this object.

identityobjectoptional

Object fields

jwt_authobject | nulloptional

JwtAuth object

enabledbooleanoptional

allowed_issuersarray<string>optional

unique items

Array item specification

string

format: uri

allowed_client_idsarray<string>optional

unique items

Array item specification

string

min length: 1

jwks_urlstringoptional

HTTPS JWKS URL.

format: uri

Unknown fields are rejected in this object.

Also accepts null.

identity_header_modebooleanoptional

identity_token_headersarray<string>optional

unique items

Array item specification

string

Additional forwarded identity header name.

min length: 1

identity_token_oid_fallbackbooleanoptional

default: true

enforce_identitybooleanoptional

enforce_conversation_idbooleanoptional

allowed_user_domainsarray<string>optional

unique items

Array item specification

string

Email domain without @.

min length: 1

allowed_user_emailsarray<string>optional

unique items

Array item specification

string

format: email

allowed_source_ipsarray<string> | nulloptional

Variant 1 array<string>

array<string>

unique items

Also accepts null.

Unknown fields are rejected in this object.

guardian_agentobject | nulloptional

Null removes the complete Guardian configuration.

Guardian object

enabledbooleanoptional

coding_helpersobjectoptional

Object fields

enabledbooleanoptional

dependency_security_checkbooleanoptional

latest_version_suggestionsbooleanoptional

Unknown fields are rejected in this object.

task_adherenceobjectoptional

Object fields

enabledbooleanoptional

actionstringoptional

"nudge""block"

sensitivitystringoptional

"low""medium""high"

agent_purposestringoptional

guardian_agent_promptstringoptional

Unknown fields are rejected in this object.

Unknown fields are rejected in this object.

Also accepts null.

hallucinationobjectoptional

Object fields

enabledbooleanoptional

actionstringoptional

"monitor""block"

score_thresholdnumberoptional

Confidence threshold from 0 to 1.

min: 0max: 1

risk_levelstringoptional

Stored compatibility setting; does not independently select worker behavior.

"low""medium""high"

Unknown fields are rejected in this object.

self_serviceobject | nulloptional

Null clears self-service configuration.

SelfService object

enabledbooleanoptional

Enable stored personal self-service credential mode.

access_controlobjectoptional

Object fields

version1required

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

Unknown fields are rejected in this object.

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

Unknown fields are rejected in this object.

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

Unknown fields are rejected in this object.

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

Unknown fields are rejected in this object.

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

Unknown fields are rejected in this object.

Unknown fields are rejected in this object.

Unknown fields are rejected in this object.

Also accepts null.

smart_group_policiesarray<object>optional

Complete replacement of app-local overrides referencing existing groups.

Array item specification

group_namestringrequired

Existing smart-group name.

min length: 1

enabledbooleanoptional

default: true

detectionobjectrequired

Stored detection controls. Catalogs validate IDs and action/scope compatibility. Governed updates remain inactive while QuilrQL owns enforcement.

Object fields

data_risk_actionstringoptional

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

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

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>

min items: 1unique items

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

Map value specification

map<string, array<string>>

edm_pattern_sensitivitiesmap<string, string>optional

Map value specification

string

Values: "low""medium""high"

custom_definitionsarray<object>optional

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

Array item specification

definition_idstringrequired

Stable ID from GET /custom-definitions.

min length: 1

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.

Unknown fields are rejected in this object.

Unknown fields are rejected in this object.

token_savingobjectoptional

Object fields

smart_json_compressionbooleanoptional

html_to_textbooleanoptional

markdown_to_textbooleanoptional

text_compressionbooleanoptional

Unknown fields are rejected in this object.

prompt_storeobjectoptional

Object fields

require_system_from_storebooleanoptional

Only enforcement is controlled here; use prompt endpoints for content.

Unknown fields are rejected in this object.

alertingobject | nulloptional

Null clears alert configuration.

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

Unknown fields are rejected in this object.

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

Unknown fields are rejected in this object.

channelsobjectoptional

Object fields

emailsarray<string>optional

unique items

Array item specification

string

format: email

webhooksarray<object>optional

Array item specification

idstringrequired

min length: 1

typestringrequired

"slack""generic"

labelstringoptional

urlstringoptional

Secret webhook URL. Omission on an existing webhook preserves it.

format: uriwrite only

Unknown fields are rejected in this object.

Unknown fields are rejected in this object.

Unknown fields are rejected in this object.

Also accepts null.

Unknown fields are rejected in this object.

Conditional requirements

[
  {
    "if": {
      "properties": {
        "mode": {
          "const": "gateway"
        }
      }
    },
    "then": {
      "required": [
        "provider_labels"
      ]
    },
    "else": {
      "not": {
        "required": [
          "provider_labels"
        ]
      }
    }
  }
]

curl --request POST \
  'https://management.example.com/llmgateway/management/v1/apps' \
  --header 'Authorization: Bearer <management-key>' \
  --header 'Idempotency-Key: operation-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Support Bot",
  "provider_labels": [
    "Production OpenAI"
  ],
  "tags": [
    "production"
  ]
}'

Authentication, errors & retry rules

GET/apps/{app_name}

Read an app

Read stored configuration, provider references, version and policy authority. Governed settings are not a universal effective policy result.

REQUIRESread

Path, query & header parameters 1

app_name (path)stringrequired

Trimmed display name. App lookup is case-insensitive within the authenticated tenant. Ambiguous legacy names return 409.

min length: 1max length: 200

No request body.

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

Authentication, errors & retry rules

PATCH/apps/{app_name}

Update or disable an app

Partial update; enabled false suspends the whole app. No app-delete operation. Governed fields save with an inactive_under_quilrql warning when authority is active.

REQUIRESconfig:write

Path, query & header parameters 2

app_name (path)stringrequired

Trimmed display name. App lookup is case-insensitive within the authenticated tenant. Ambiguous legacy names return 409.

min length: 1max length: 200

If-Match (header)stringrequired

Exact quoted ETag from a current resource read.

Full request body specification application/json

Omitted fields are preserved. Objects merge declared fields, arrays replace, and null clears only explicitly nullable fields. All changes are validated together.

enabledbooleanoptional

Whole-app availability, independent of QuilrQL. Disabled apps retain keys/configuration.

default: true

tagsarray<string>optional

Complete replacement.

unique items

Array item specification

string

min length: 1max length: 120

provider_labelsarray<string>optional

Ordered complete provider selection, primary first. Mutating this field on an inline app requires explicit conversion.

min items: 1unique items

Array item specification

string

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

min length: 1max length: 200

detectionobjectoptional

Stored detection controls. Catalogs validate IDs and action/scope compatibility. Governed updates remain inactive while QuilrQL owns enforcement.

Object fields

data_risk_actionstringoptional

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

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

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>

min items: 1unique items

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

Map value specification

map<string, array<string>>

edm_pattern_sensitivitiesmap<string, string>optional

Map value specification

string

Values: "low""medium""high"

custom_definitionsarray<object>optional

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

Array item specification

definition_idstringrequired

Stable ID from GET /custom-definitions.

min length: 1

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.

Unknown fields are rejected in this object.

routingobjectoptional

Targets reference attached shared providers and configured models. No inline credentials are accepted. Surface compatibility and sum-of-weights checks are mandatory.

Object fields

groupsarray<object>optional

Complete replacement; [] clears all named request/token groups.

Array item specification

namestringrequired

App-scoped routing alias.

min length: 1max length: 200

kindstringrequired

Must match the models and supported API surface.

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

modestringrequired

Balance by request count or token usage.

"requests""tokens"

membersarray<object>required

min items: 1

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

weightnumberrequired

Positive percentage. All members of a group must sum to 100.

max: 100greater than: 0

Unknown fields are rejected in this object.

Unknown fields are rejected in this object.

context_routesarray<object>optional

Complete replacement; [] clears custom context routes.

Array item specification

kindstringrequired

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

contextstringrequired

Only the supported low-context override is active in this v1 contract.

"low"

enabledbooleanoptional

default: true

targetsarray<object>required

Ordered fallback targets.

min items: 1

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

Unknown fields are rejected in this object.

Unknown fields are rejected in this object.

context_thresholdsobjectoptional

Object fields

low_max_wordsintegerrequired

min: 0

medium_max_wordsintegerrequired

Must be greater than or equal to low_max_words.

min: 0

Unknown fields are rejected in this object.

Unknown fields are rejected in this object.

limitsobjectoptional

Object fields

timeoutnumber | nulloptional

Upstream timeout in seconds; null clears the configured override.

Variant 1 number

number

Upstream timeout in seconds; null clears the configured override.

min: 0

Also accepts null.

concurrency_per_minuteinteger | nulloptional

Admission count over the existing 60-second window.

Variant 1 integer

integer

Admission count over the existing 60-second window.

min: 0

Also accepts null.

rate_limitobject | nulloptional

Null clears the request limit.

RateLimit object

valueintegerrequired

Maximum events in the window; zero disables this limit.

min: 0

durationstringrequired

"minute""hour""day"

Unknown fields are rejected in this object.

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"

Unknown fields are rejected in this object.

Also accepts null.

outputobject | nulloptional

RateLimit object

valueintegerrequired

Maximum events in the window; zero disables this limit.

min: 0

durationstringrequired

"minute""hour""day"

Unknown fields are rejected in this object.

Also accepts null.

Unknown fields are rejected in this object.

Also accepts null.

model_rate_limitsarray<object>optional

Full replacement; [] removes all model overrides. App and model limits both apply.

unique items

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"

Unknown fields are rejected in this object.

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"

Unknown fields are rejected in this object.

Also accepts null.

outputobject | nulloptional

RateLimit object

valueintegerrequired

Maximum events in the window; zero disables this limit.

min: 0

durationstringrequired

"minute""hour""day"

Unknown fields are rejected in this object.

Also accepts null.

Unknown fields are rejected in this object.

Also accepts null.

Unknown fields are rejected in this object.

Unknown fields are rejected in this object.

identityobjectoptional

Object fields

jwt_authobject | nulloptional

JwtAuth object

enabledbooleanoptional

allowed_issuersarray<string>optional

unique items

Array item specification

string

format: uri

allowed_client_idsarray<string>optional

unique items

Array item specification

string

min length: 1

jwks_urlstringoptional

HTTPS JWKS URL.

format: uri

Unknown fields are rejected in this object.

Also accepts null.

identity_header_modebooleanoptional

identity_token_headersarray<string>optional

unique items

Array item specification

string

Additional forwarded identity header name.

min length: 1

identity_token_oid_fallbackbooleanoptional

default: true

enforce_identitybooleanoptional

enforce_conversation_idbooleanoptional

allowed_user_domainsarray<string>optional

unique items

Array item specification

string

Email domain without @.

min length: 1

allowed_user_emailsarray<string>optional

unique items

Array item specification

string

format: email

allowed_source_ipsarray<string> | nulloptional

Variant 1 array<string>

array<string>

unique items

Also accepts null.

Unknown fields are rejected in this object.

guardian_agentobject | nulloptional

Null removes the complete Guardian configuration.

Guardian object

enabledbooleanoptional

coding_helpersobjectoptional

Object fields

enabledbooleanoptional

dependency_security_checkbooleanoptional

latest_version_suggestionsbooleanoptional

Unknown fields are rejected in this object.

task_adherenceobjectoptional

Object fields

enabledbooleanoptional

actionstringoptional

"nudge""block"

sensitivitystringoptional

"low""medium""high"

agent_purposestringoptional

guardian_agent_promptstringoptional

Unknown fields are rejected in this object.

Unknown fields are rejected in this object.

Also accepts null.

hallucinationobjectoptional

Object fields

enabledbooleanoptional

actionstringoptional

"monitor""block"

score_thresholdnumberoptional

Confidence threshold from 0 to 1.

min: 0max: 1

risk_levelstringoptional

Stored compatibility setting; does not independently select worker behavior.

"low""medium""high"

Unknown fields are rejected in this object.

self_serviceobject | nulloptional

Null clears self-service configuration.

SelfService object

enabledbooleanoptional

Enable stored personal self-service credential mode.

access_controlobjectoptional

Object fields

version1required

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

Unknown fields are rejected in this object.

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

Unknown fields are rejected in this object.

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

Unknown fields are rejected in this object.

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

Unknown fields are rejected in this object.

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

Unknown fields are rejected in this object.

Unknown fields are rejected in this object.

Unknown fields are rejected in this object.

Also accepts null.

smart_group_policiesarray<object>optional

Complete replacement of app-local overrides referencing existing groups.

Array item specification

group_namestringrequired

Existing smart-group name.

min length: 1

enabledbooleanoptional

default: true

detectionobjectrequired

Stored detection controls. Catalogs validate IDs and action/scope compatibility. Governed updates remain inactive while QuilrQL owns enforcement.

Object fields

data_risk_actionstringoptional

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

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

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>

min items: 1unique items

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

Map value specification

map<string, array<string>>

edm_pattern_sensitivitiesmap<string, string>optional

Map value specification

string

Values: "low""medium""high"

custom_definitionsarray<object>optional

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

Array item specification

definition_idstringrequired

Stable ID from GET /custom-definitions.

min length: 1

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.

Unknown fields are rejected in this object.

Unknown fields are rejected in this object.

token_savingobjectoptional

Object fields

smart_json_compressionbooleanoptional

html_to_textbooleanoptional

markdown_to_textbooleanoptional

text_compressionbooleanoptional

Unknown fields are rejected in this object.

prompt_storeobjectoptional

Object fields

require_system_from_storebooleanoptional

Only enforcement is controlled here; use prompt endpoints for content.

Unknown fields are rejected in this object.

alertingobject | nulloptional

Null clears alert configuration.

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

Unknown fields are rejected in this object.

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

Unknown fields are rejected in this object.

channelsobjectoptional

Object fields

emailsarray<string>optional

unique items

Array item specification

string

format: email

webhooksarray<object>optional

Array item specification

idstringrequired

min length: 1

typestringrequired

"slack""generic"

labelstringoptional

urlstringoptional

Secret webhook URL. Omission on an existing webhook preserves it.

format: uriwrite only

Unknown fields are rejected in this object.

Unknown fields are rejected in this object.

Unknown fields are rejected in this object.

Also accepts null.

Unknown fields are rejected in this object.

Request example for Update or disable an appDisable appDetection and limitsAttach provider selection

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

Authentication, errors & retry rules

GET/apps/{app_name}/providers

List app providers

Read ordered attachments and primary status, with no upstream secrets.

REQUIRESread

Path, query & header parameters 1

app_name (path)stringrequired

Trimmed display name. App lookup is case-insensitive within the authenticated tenant. Ambiguous legacy names return 409.

min length: 1max length: 200

No request body.

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

Authentication, errors & retry rules

PUT/apps/{app_name}/providers/{label}

Attach a shared provider

Idempotently attach an existing enabled provider; preserve other attachments. primary true explicitly promotes it. Inline apps require conversion first.

REQUIRESconfig:write

Path, query & header parameters 3

app_name (path)stringrequired

Trimmed display name. App lookup is case-insensitive within the authenticated tenant. Ambiguous legacy names return 409.

min length: 1max length: 200

label (path)stringrequired

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

min length: 1max length: 200

If-Match (header)stringrequired

Exact quoted ETag from a current resource read.

Full request body specification application/json

primarybooleanoptional

Make this provider primary. false appends without changing the existing primary.

default: false

Unknown fields are rejected in this object.

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

Authentication, errors & retry rules

DELETE/apps/{app_name}/providers/{label}

Detach an app provider

Detach from this app only. Reject last-provider/primary and routing/policy dependency conflicts; use an app PATCH to supply a complete valid replacement selection and routes.

REQUIRESconfig:write

Path, query & header parameters 3

app_name (path)stringrequired

Trimmed display name. App lookup is case-insensitive within the authenticated tenant. Ambiguous legacy names return 409.

min length: 1max length: 200

label (path)stringrequired

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

min length: 1max length: 200

If-Match (header)stringrequired

Exact quoted ETag from a current resource read.

No request body.

curl --request DELETE \
  'https://management.example.com/llmgateway/management/v1/apps/Support%20Bot/providers/Production%20OpenAI' \
  --header 'Authorization: Bearer <management-key>' \
  --header 'If-Match: "resource-version"'

Authentication, errors & retry rules

POST/apps/{app_name}/provider-conversion

Convert inline providers

Replace the complete inline selection with existing shared provider references. Preserve canonical app identity, keys and unrelated settings. No implicit provider creation.

REQUIRESconfig:write

Path, query & header parameters 3

app_name (path)stringrequired

Trimmed display name. App lookup is case-insensitive within the authenticated tenant. Ambiguous legacy names return 409.

min length: 1max length: 200

If-Match (header)stringrequired

Exact quoted ETag from a current resource read.

Idempotency-Key (header)stringrequired

Unique operation key. Reuse only with the identical request; mismatch returns 409.

min length: 1max length: 128

Full request body specification application/json

Explicitly replace inline providers with shared references. Supply matching route replacements when required. Preserves gateway keys and unrelated app state.

provider_labelsarray<string>required

Complete desired provider selection, primary first.

min items: 1unique items

Array item specification

string

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

min length: 1max length: 200

routingobjectoptional

Targets reference attached shared providers and configured models. No inline credentials are accepted. Surface compatibility and sum-of-weights checks are mandatory.

Object fields

groupsarray<object>optional

Complete replacement; [] clears all named request/token groups.

Array item specification

namestringrequired

App-scoped routing alias.

min length: 1max length: 200

kindstringrequired

Must match the models and supported API surface.

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

modestringrequired

Balance by request count or token usage.

"requests""tokens"

membersarray<object>required

min items: 1

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

weightnumberrequired

Positive percentage. All members of a group must sum to 100.

max: 100greater than: 0

Unknown fields are rejected in this object.

Unknown fields are rejected in this object.

context_routesarray<object>optional

Complete replacement; [] clears custom context routes.

Array item specification

kindstringrequired

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

contextstringrequired

Only the supported low-context override is active in this v1 contract.

"low"

enabledbooleanoptional

default: true

targetsarray<object>required

Ordered fallback targets.

min items: 1

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

Unknown fields are rejected in this object.

Unknown fields are rejected in this object.

context_thresholdsobjectoptional

Object fields

low_max_wordsintegerrequired

min: 0

medium_max_wordsintegerrequired

Must be greater than or equal to low_max_words.

min: 0

Unknown fields are rejected in this object.

Unknown fields are rejected in this object.

Unknown fields are rejected in this object.

curl --request POST \
  'https://management.example.com/llmgateway/management/v1/apps/Support%20Bot/provider-conversion' \
  --header 'Authorization: Bearer <management-key>' \
  --header 'If-Match: "resource-version"' \
  --header 'Idempotency-Key: operation-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider_labels": [
    "Production OpenAI"
  ],
  "routing": {
    "groups": [],
    "context_routes": []
  }
}'

Authentication, errors & retry rules