Full app configuration input

Use PATCH /llmgateway/management/v1/apps/{app_name} to update stored controls. The complete input schema below covers routing, detection, limits, identity, self-service, existing group/definition references, alerts and transformations.

The public schema groups app configuration by function. All nested fields are typed. Unknown fields are rejected.

How partial updates work

Input	Meaning
Omit a field	Preserve its current value.
Send an object	Merge only the supplied declared fields; required nested shapes must be valid after merge.
Send an array	Replace the entire collection. [] clears it only where an empty collection is permitted.
Send null	Clear only an explicitly nullable field. It is not a universal reset instruction.
Send false	Disable that boolean control.
Send a new provider selection	Validate the complete selection and all retained routes together.

Stored settings and policy authority

With QuilrQL enabled, governed changes save and return an inactive_under_quilrql warning. Disabling authority activates those stored values. Shared-provider credentials/availability and prompt contents remain live dependencies; whole-app availability is always enforced independently.

{
  "warnings": [{
    "code": "inactive_under_quilrql",
    "fields": ["detection.data_risk_action"],
    "message": "Saved settings take effect when QuilrQL authority is disabled."
  }],
  "request_id": "req_example"
}

This is a partial response example showing warnings. A successful update also returns the updated resource/version. There is no single effective configuration for every user/model/content combination: use simulation for a specific request.

Configuration map

Section	Includes	Behavior to understand
detection	Category selection, category/subcategory actions, sensitivity, request/response scope and existing custom definitions.	Catalogs validate selectors and action compatibility. No definition authoring.
routing	Request/token weighted groups, low-context routes and thresholds.	Shared-provider labels only; weights sum to 100; supported protocol surfaces only.
limits	Timeouts, request rates, token budgets and per-model limits.	App and model limits both apply. Quotas/pricing can also be authored through QuilrQL.
identity	JWT/JWKS, identity headers, email/domain restrictions, conversation requirement and source IPs.	Runtime identity configuration is separate from management authentication.
guardian_agent	Coding checks and task adherence.	Deployment model availability still applies.
hallucination	Enablement, action and score threshold.	Threshold is 0-1. Stored risk level is compatibility metadata, not an independent worker switch.
self_service	Credential mode and the five access roles.	Does not add personal-key or approval-workflow administration to this API.
smart_group_policies	App overrides for existing smart groups.	Cannot edit membership.
token_saving	JSON, HTML, Markdown and text transformations.	Request-side support varies by protocol surface.
prompt_store	System-prompt enforcement.	Prompt content uses the separate prompt endpoints.
alerting	App/provider failure thresholds and delivery channels.	Configuration only; no alert test/reporting API. Webhook URLs are secrets.

Complete PATCH schema

Expand any object, array item or map value to inspect its complete nested specification. Dynamic maps have typed values and must use IDs from the appropriate catalog.

INPUT SCHEMAAppPatch

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.

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"
    }]
  },
  "limits": {
    "timeout": 60,
    "rate_limit": {"value": 1000, "duration": "minute"},
    "token_limits": {"max_per_request": 16000}
  },
  "smart_group_policies": [{
    "group_name": "engineering",
    "enabled": true,
    "detection": {"data_risk_action": "monitor"}
  }],
  "token_saving": {"smart_json_compression": true},
  "prompt_store": {"require_system_from_store": true}
}

The example assumes employee_id and engineering already exist in the tenant. Query the catalogs before using their names/IDs.

Example: weighted routing

{
  "routing": {
    "groups": [{
      "name": "support-chat",
      "kind": "chat_completion",
      "mode": "requests",
      "members": [
        {"provider_label": "Production OpenAI", "model": "gpt-4.1-mini", "weight": 80},
        {"provider_label": "Backup OpenAI", "model": "gpt-4.1-mini", "weight": 20}
      ]
    }],
    "context_routes": [],
    "context_thresholds": {"low_max_words": 200, "medium_max_words": 1000}
  }
}

Both providers must already be attached with compatible models. The groups array replaces all request/token routing groups; include every group you intend to retain. Policies may govern which routes actually run.