QuilrQL lifecycle

QuilrQL governs policy at the tenant level. Keep source authoring, draft storage and runtime publication as separate operations. These management endpoints preserve the gateway policy engine's authority boundaries.

The publication workflow

Discover

Schema and tenant catalogs

Prepare

Preview conversion or author source

Verify

Validate and simulate

Publish

Check revisions

Activate immutable source

QuilrAI

Action	Permission	Runtime effect
Schema/catalog, preview, validate, simulate	read	None.
Create/update a draft	policy:write	None.
Publish/rollback a revision	policy:publish	Changes the active tenant-wide policy revision.
Enable/disable authority	policy:publish	Switches which controls govern runtime.

Source and input boundaries

source is QuilrQL text. The request schema accepts at most 400,000 characters and the service must additionally enforce 400,000 UTF-8 bytes. The authoring schema supplies valid fields, effects, stages, value sources and conditional shapes. Tenant catalogs supply valid app/provider/group/definition references.

Simulation accepts 1-100 synthetic cases. The case input includes an app name, direction, user/group identity, model/provider, method type, detected data types and scalar metadata. It performs policy evaluation; it does not invoke a model or read production request logs.

For policy language and supported controls, see LLM Gateway policies and authoring and publishing. Source strings shown as <source ...> in reference examples are placeholders: use source returned by preview, a saved revision, a suggested policy or the editor.

Concurrency and activation

• Draft replacement and publication require the draft ETag in If-Match.
• Publication also provides expected_active_revision, including explicit null before the first revision. This protects against a competing publication.
• Authority enable/disable and policy rollback require the authority ETag from status.
• Enable references the reviewed conversion-preview checksum. A changed live snapshot requires a fresh preview.
• Rollback republishes eligible historical source as a new revision after validating current references. It does not erase history.

What happens to app settings

While authority is enabled, governed app settings may still save but are inactive during healthy policy evaluation. Disabling authority makes saved values live again. A healthy no-match policy result is neutral; new apps do not automatically receive matching rules.

Provider secrets/availability and prompt contents remain live dependencies. Whole-app disable remains effective independently of policy. App configuration history is distinct from policy revision history.

Historical production replay, usage reporting and per-policy traffic reporting are outside the management v1 scope. Existing groups and custom definitions can be referenced; this API cannot modify their content or membership.

Endpoint reference

GET/policy/status

Read policy authority

Read tenant policy discovery data. Use the returned schema/catalog rather than hardcoding selectors or effect values.

REQUIRESread

No request body.

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

Authentication, errors & retry rules

GET/policy/metadata

Read policy metadata

Read tenant policy discovery data. Use the returned schema/catalog rather than hardcoding selectors or effect values.

REQUIRESread

No request body.

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

Authentication, errors & retry rules

GET/policy/authoring-schema

Read policy authoring schema

Read tenant policy discovery data. Use the returned schema/catalog rather than hardcoding selectors or effect values.

REQUIRESread

No request body.

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

Authentication, errors & retry rules

GET/policy/authoring-catalog

Read policy authoring catalog

Read tenant policy discovery data. Use the returned schema/catalog rather than hardcoding selectors or effect values.

REQUIRESread

No request body.

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

Authentication, errors & retry rules

GET/policy/suggested-policies

Read suggested policies

Read tenant policy discovery data. Use the returned schema/catalog rather than hardcoding selectors or effect values.

REQUIRESread

No request body.

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

Authentication, errors & retry rules

GET/policy/authoring-catalog/search

Search policy values

Search one value-source kind advertised by the authoring schema. parent is required only when the selected field has a parent_field.

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.

kind (query)stringrequired

A supported autofill kind from authoring-schema.

q (query)stringoptional

Search string.

parent (query)stringoptional

Parent selector, when required by schema.

No request body.

curl --request GET \
  'https://management.example.com/llmgateway/management/v1/policy/authoring-catalog/search?limit=50&kind=applications' \
  --header 'Authorization: Bearer <management-key>'

Authentication, errors & retry rules

POST/policy/conversion-preview

Preview policy conversion

Read current app settings and return a credential-free proposed policy plus review evidence. Does not activate authority.

REQUIRESread

No request body.

curl --request POST \
  'https://management.example.com/llmgateway/management/v1/policy/conversion-preview' \
  --header 'Authorization: Bearer <management-key>'

Authentication, errors & retry rules

POST/policy/validate

Validate policy source

Compile source and validate tenant references without publishing or invoking a model. Semantic validation can return valid false with diagnostics.

REQUIRESread

Full request body specification application/json

sourcestringrequired

QuilrQL source. Also enforce the server byte limit of 400,000 UTF-8 bytes.

max length: 400000

Unknown fields are rejected in this object.

curl --request POST \
  'https://management.example.com/llmgateway/management/v1/policy/validate' \
  --header 'Authorization: Bearer <management-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "source": "<source from conversion-preview or the policy editor>"
}'

Authentication, errors & retry rules

POST/policy/simulate

Simulate policy source

Evaluate up to 100 synthetic cases. This is policy evaluation, not a model call or replay of production logs.

REQUIRESread

Full request body specification application/json

sourcestringrequired

QuilrQL source. Also enforce the server byte limit of 400,000 UTF-8 bytes.

max length: 400000

casesarray<object>required

min items: 1max items: 100

Array item specification

app_namestringrequired

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

min length: 1max length: 200

stagestringoptional

default: "request"

"request""response"

user_emailstringoptional

format: email

smart_groupsarray<string>optional

unique items

Array item specification

string

min length: 1

modelstringoptional

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

min length: 1max length: 512

provider_labelstringoptional

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

min length: 1max length: 200

method_typestringoptional

"chat""responses""assistants""embeddings""rerank""tts""stt""bedrock""vertex""sdk_check"

data_typesarray<string>optional

unique items

Array item specification

string

Existing catalog selector.

min length: 1

metadatamap<string, string | number | integer | boolean | null>optional

Synthetic request metadata. No recorded traffic is read.

Map value specification

string | number | integer | boolean | null

Unknown fields are rejected in this object.

Unknown fields are rejected in this object.

curl --request POST \
  'https://management.example.com/llmgateway/management/v1/policy/simulate' \
  --header 'Authorization: Bearer <management-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "source": "<source from the policy editor>",
  "cases": [
    {
      "app_name": "Support Bot",
      "stage": "request",
      "user_email": "developer@example.com",
      "model": "gpt-4.1-mini",
      "data_types": [
        "Email Address"
      ]
    }
  ]
}'

Authentication, errors & retry rules

GET/policy/drafts

List policy drafts

List draft metadata. Drafts do not govern runtime traffic.

REQUIRESread

Path, query & header parameters 2

limit (query)integeroptional

Items per page.

min: 1max: 200default: 50

cursor (query)stringoptional

Opaque cursor returned by this same collection and filters.

No request body.

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

Authentication, errors & retry rules

POST/policy/drafts

Create a policy draft

Save source as a draft. Validation/publication is explicit.

REQUIRESpolicy: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

namestringoptional

min length: 1max length: 200default: "Untitled draft"

sourcestringrequired

QuilrQL source. Also enforce the server byte limit of 400,000 UTF-8 bytes.

max length: 400000

Unknown fields are rejected in this object.

curl --request POST \
  'https://management.example.com/llmgateway/management/v1/policy/drafts' \
  --header 'Authorization: Bearer <management-key>' \
  --header 'Idempotency-Key: operation-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Support guardrails",
  "source": "<source from conversion-preview or the policy editor>"
}'

Authentication, errors & retry rules

GET/policy/drafts/{draft_id}

Read a policy draft

Read source and current draft revision.

REQUIRESread

Path, query & header parameters 1

draft_id (path)stringrequired

min length: 1

No request body.

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

Authentication, errors & retry rules

PUT/policy/drafts/{draft_id}

Replace a policy draft

Replace draft name/source using its current ETag. Does not publish.

REQUIRESpolicy:write

Path, query & header parameters 2

draft_id (path)stringrequired

min length: 1

If-Match (header)stringrequired

Exact quoted ETag from a current resource read.

Full request body specification application/json

namestringoptional

min length: 1max length: 200default: "Untitled draft"

sourcestringrequired

QuilrQL source. Also enforce the server byte limit of 400,000 UTF-8 bytes.

max length: 400000

Unknown fields are rejected in this object.

curl --request PUT \
  'https://management.example.com/llmgateway/management/v1/policy/drafts/draft_example' \
  --header 'Authorization: Bearer <management-key>' \
  --header 'If-Match: "resource-version"' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Support guardrails",
  "source": "<updated QuilrQL source>"
}'

Authentication, errors & retry rules

POST/policy/drafts/{draft_id}/publish

Publish a policy draft

Validate the selected draft and publish an immutable tenant-wide revision. If-Match refers to the draft; expected_active_revision protects against another publication.

REQUIRESpolicy:publish

Path, query & header parameters 3

draft_id (path)stringrequired

min length: 1

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

messagestringoptional

Optional audit note.

max length: 500

expected_active_revisioninteger | nullrequired

Active revision observed during review, or null before the first publication.

Variant 1 integer

integer

Active revision observed during review, or null before the first publication.

min: 1

Also accepts null.

Unknown fields are rejected in this object.

curl --request POST \
  'https://management.example.com/llmgateway/management/v1/policy/drafts/draft_example/publish' \
  --header 'Authorization: Bearer <management-key>' \
  --header 'If-Match: "resource-version"' \
  --header 'Idempotency-Key: operation-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "message": "Deploy reviewed support rules",
  "expected_active_revision": 12
}'

Authentication, errors & retry rules

GET/policy/revisions

List policy revisions

List immutable policy history; separate from app configuration versions.

REQUIRESread

Path, query & header parameters 2

limit (query)integeroptional

Items per page.

min: 1max: 200default: 50

cursor (query)stringoptional

Opaque cursor returned by this same collection and filters.

No request body.

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

Authentication, errors & retry rules

GET/policy/revisions/{revision}

Read policy revision metadata

Read revision checksum, publication metadata and diagnostics.

REQUIRESread

Path, query & header parameters 1

revision (path)integerrequired

min: 1

No request body.

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

Authentication, errors & retry rules

GET/policy/revisions/{revision}/source

Read policy revision source

Return the stored source for one immutable revision.

REQUIRESread

Path, query & header parameters 1

revision (path)integerrequired

min: 1

No request body.

curl --request GET \
  'https://management.example.com/llmgateway/management/v1/policy/revisions/12/source' \
  --header 'Authorization: Bearer <management-key>'

Authentication, errors & retry rules

POST/policy/revisions/{revision}/rollback

Roll back policy authority

Validate the historical source against current catalogs and publish it as a new revision. If-Match is the authority ETag from policy/status.

REQUIRESpolicy:publish

Path, query & header parameters 3

revision (path)integerrequired

min: 1

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

messagestringoptional

Optional audit reason.

max length: 500

Unknown fields are rejected in this object.

curl --request POST \
  'https://management.example.com/llmgateway/management/v1/policy/revisions/12/rollback' \
  --header 'Authorization: Bearer <management-key>' \
  --header 'If-Match: "resource-version"' \
  --header 'Idempotency-Key: operation-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "message": "Restore the last reviewed policy"
}'

Authentication, errors & retry rules

POST/policy/enable

Enable policy authority

Activate the reviewed conversion snapshot. If-Match is the authority ETag; checksum must match a fresh conversion-preview. Existing app governed settings become dormant.

REQUIRESpolicy:publish

Path, query & header parameters 2

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

Recheck the live configuration snapshot before activating. Reject a stale preview rather than enabling an unreviewed conversion.

conversion_checksumstringrequired

Checksum returned by a reviewed conversion-preview.

min length: 1

Unknown fields are rejected in this object.

curl --request POST \
  'https://management.example.com/llmgateway/management/v1/policy/enable' \
  --header 'Authorization: Bearer <management-key>' \
  --header 'If-Match: "resource-version"' \
  --header 'Idempotency-Key: operation-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "conversion_checksum": "conversion_example"
}'

Authentication, errors & retry rules

POST/policy/disable

Disable policy authority

Disable tenant-wide QuilrQL authority. Stored app settings, including dormant edits, become live. Does not enable a disabled app or provider.

REQUIRESpolicy:publish

Path, query & header parameters 2

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

messagestringoptional

Optional audit reason.

max length: 500

Unknown fields are rejected in this object.

curl --request POST \
  'https://management.example.com/llmgateway/management/v1/policy/disable' \
  --header 'Authorization: Bearer <management-key>' \
  --header 'If-Match: "resource-version"' \
  --header 'Idempotency-Key: operation-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "message": "Return authority to app settings"
}'

Authentication, errors & retry rules