Skip to main content

Self-service API

Configure LLM Gateway self-service from scripts and pipelines: access plans, model options and app templates, suspensions, requests for more, app owners and people's personal keys. Every call here is what the console's Self-service tab uses.

The API keeps the older names. The console's terms map as follows:

ConsoleAPI
Access planProfile (/self-service/profiles)
Model optionTier (tiers in /self-service/settings)
App templateBlueprint (blueprints in /self-service/settings)
RequestException (/self-service/exceptions)
App ownerOwner (/apps/{app_name}/self-service-owners)
Viewer access, Settings request access, Direct settings update, View and copy API key values, All-logs visibilityRoles self_service_viewer, settings_update_requester, settings_update_direct, show_api_key, show_logs_for_all_users
CallDoesScope
GET/POST /self-service/profiles, GET/PUT/DELETE /self-service/profiles/{profile_id}List, create, read, replace and delete access plans.read / config:write
PUT /self-service/settingsPeople without a plan (deny_without_profile), model options (tiers) and app templates (blueprints).config:write
PUT /self-service/suspensions, POST /self-service/suspensions/removeSuspend a person or lift it.config:write
POST /self-service/evaluateWhat one person gets and why, optionally with a draft plan.read
GET/POST /self-service/coveragePeople per plan and what a change would cut off, with personal-key impact for drafts.read
GET /self-service/blueprint_eligibilityWhether apps can be app templates, and the policies that block them.read
GET /self-service/exceptions, GET /self-service/exceptions/{exception_id}List or read requests.read
POST /self-service/exceptions/{exception_id}/approve, /reject, /revokeDecide requests.config:write
PUT /apps/{app_name}/self-service-ownersSet an app's owners.config:write
GET /self-service/usageThe self-service usage report.read
GET /self-service-keys, /apps/{app_name}/self-service-keys[/{key_id}]Personal keys across apps, or per app on a person's behalf.read / keys:write
GET /apps?origin=blueprint&created_by=Apps people created from app templates.read

Try them in the Management API playground. Authentication, errors and retry rules are on the Management API page.

Access plans (profiles)​

A profile has name (1-80 characters, unique in any capitalization), description, smart_groups (1-50 existing groups), sections (any of my_usage, llm_gateway, mcp_gateway, workflow_agents, skills), llm_apps (shown or hidden), default_app (the starter app; required when llm_apps is hidden, and it must use personal keys), grants (up to 20 {apps: "all" | [names], roles: [...]}), ceiling ({roles: [...], apps: "all" | [names]}), keys ({max_active_per_person: 1-10, max_lifetime_days: 1-3650 | null}), and optionally models and app_creation. The server adds profile_id, revision, updated_at and updated_by.

The console's ability choices map to grants and ceiling: Always is a grant, Only if the app allows is a role in the ceiling without a grant, and Never is a role left out of the ceiling. ceiling.roles must include self_service_viewer (400 self_service_profile_ceiling_requires_viewer).

  • models: {tiers: [tier_id], tier_names_only, max_reasoning_effort: low | medium | high | null}. It applies to requests made with a person's personal key. With tier_names_only, only the allowed tier models can be called (403 self_service_model_not_allowed) and listed; otherwise other tier models are refused and every other model behaves as before. A higher reasoning effort is lowered to the cap, never refused.
  • app_creation: {blueprints: [names], max_apps_per_person: 0-20, settings: direct | request | hidden}. People create apps from those blueprints up to the cap and own them; past it, they request another app.

Which profile applies: the matching profile whose best Smart Group has the lowest effective priority (the group's priority override, else its priority, else 100); ties go to the lower name, then the lower profile_id. See Smart groups API rank.

Writes send the revision from your latest read (?revision=N on DELETE); a stale one is 409 self_service_profile_revision_conflict with current_revision. Creates take an Idempotency-Key. There are at most 200 profiles per organization (409 self_service_profile_limit_reached).

Settings, model options and app templates​

PUT /self-service/settings takes {deny_without_profile?, tiers?, blueprints?, revision}. Every field except revision is optional: an omitted field keeps its saved value, so you can send only tiers or only blueprints. Send revision: 0 for settings never saved.

  • deny_without_profile: true gives people without a profile no self-service access (their personal keys stop within the access cache lifetime).
  • tiers: at most 10 {tier_id, label, model, rank, description}. model is a model name your policies route; rank 1 is the lowest. The label is a display name, not an alias.
  • blueprints: at most 50 existing apps {app_name, label, description}.

Removing a tier or blueprint a profile still uses is 409 self_service_catalog_in_use with the profiles. The response can carry warnings, for example a tier model that is also an app name or provider model, or a blueprint with app-scoped policies (blueprint_has_app_policies).

Check app templates first​

GET /self-service/blueprint_eligibility?app=A&app=B (1-50 names) answers, per app, {app_name, found, app_scoped_policies, app_scoped_policy_names, eligible}. An app is eligible when it exists and no policy rule could match it by its identity: such rules would not govern the copies, so the app is refused as a blueprint. app_scoped_policy_names lists every such policy by name, in policy order (empty when none), so you can fix each one and check again. Unknown apps come back as given with found: false. A policy read failure is 503, never "eligible".

Check one person: evaluate​

POST /self-service/evaluate {email, draft_profile?, replaces_profile_id?} explains how the person's access is decided: suspended, the winning profile and every matched one, sections, per-app roles in apps[], denied and blocked, and what the profile gives: llm_apps (the starter app and its status), models, keys, app_creation and active exceptions. With draft_profile (validated like a create; errors are reported as draft_profile.<field>), the draft is evaluated as if saved, in place of replaces_profile_id or as an extra profile with id draft. Nothing is stored.

Count people: coverage and key impact​

GET /self-service/coverage counts people per profile (winning and matching), people without one, suspended people, and deny_without_profile.cut_off: people without a profile who would lose access if deny_without_profile were turned on.

POST /self-service/coverage counts the same for an unsaved change. Send any of:

InputCounts as if
draft_profile, replaces_profile_idThis profile were saved (in place of that one).
remove_profile_idThis saved profile were deleted. Not with draft_profile.
deny_without_profileThe no-profile rule had this value.
draft_appsThese apps' self-service settings were saved: 1-50 {app_name, enable_self_service?, access_control?, owners?}; a field left out keeps its stored value.

With any draft input, the response adds key_impact: for every owner of an active personal key and that key's app, whether the key works under the saved state and under the draft (app on personal keys, owner holds viewer access). lost and gained each give counts of people, apps and personal_keys, plus up to 50 entries {email, app_name, personal_keys} and truncated. exact is false when more than 20,000 active personal keys exist. key_impact is null on GET and without a draft.

export API="$MANAGEMENT_URL/llmgateway/management/v1"
auth=(-H "Authorization: Bearer $MANAGEMENT_KEY" -H "Content-Type: application/json")

# Who would lose personal keys if Support Bot moved to a shared key?
curl -s -X POST "$API/self-service/coverage" "${auth[@]}" \
-d '{"draft_apps": [{"app_name": "Support Bot", "enable_self_service": false}]}' \
| jq '.key_impact.lost'

Suspensions​

PUT /self-service/suspensions {email, reason?} suspends a person: no self-service access at all, and their personal keys stop within the access cache lifetime. POST /self-service/suspensions/remove {email} lifts it (removed is null when the person was not suspended).

Requests (exceptions)​

People ask for a budget_increase or app_access on one app (reviewed by the app's owners, or admins when it has none), or a tier_upgrade, key_lifetime or app_create (admins). A budget increase goes to admins when the budget it would raise covers more than that app.

  • GET /self-service/exceptions?status=&kind=&requester=&app= lists them; GET /self-service/exceptions/{exception_id} reads one (404 self_service_exception_not_found outside your organization).
  • POST .../approve {ends_at?, comment?}: every approval ends (ends_at, at most 365 days away, default the requested date), except app_create. After ends_at the effect stops and the request reads expired.
  • POST .../reject {reason} and POST .../revoke {reason?} (ends an approval early).

A management key decides as an administrator: it may decide any request, including those owners review, and decided_by is management_key:<key_id>. Nobody decides their own request (self_service_exception_self_approval). Deciding a request that is no longer pending is 409 self_service_exception_not_pending with its current status. A budget increase with no per-person budget on the app is 409 self_service_exception_no_budget, and the request stays pending.

Statuses: pending, approved, rejected, cancelled, revoked, failed, expired.

App owners​

PUT /apps/{app_name}/self-service-owners {owners: [emails]} (at most 20; [] removes all) sets who reviews the app's requests. It takes the same per-app lock as PATCH /apps/{app_name}, so neither overwrites the other: a PATCH sent meanwhile waits, then answers 412 when its If-Match is stale.

In PATCH /apps/{app_name}, the self_service section replaces the stored self-service object, so send every field you keep (access_control, max_api_key_ttl_days, owners). Two exceptions: omitted or empty owners keep the stored owners, and origin is read-only.

Apps people created​

GET /apps?origin=blueprint lists apps people created from a blueprint; origin=admin lists every other app; created_by=<email> narrows to one creator (case-insensitive). Such apps carry a read-only origin {kind: "blueprint", blueprint_app, blueprint_config_version, created_by, created_at}.

Personal API keys​

Manage a person's personal keys without the person signing in. New keys are sk-quilr-ss-<48 hex>; older sk-quilr-<app>:ss1.<identity>.<suffix> keys keep working.

CallNotes
GET /apps/{app_name}/self-service-keysuser_email, status, limit, cursor.
POST /apps/{app_name}/self-service-keyskeys:write; {user_email, key_name, expires_in_days?} with Idempotency-Key. The same checks as the person's own create (personal keys on, viewer access, lifetime and key caps). The value is returned once, in key.secret. An omitted expires_in_days takes the app's maximum lifetime.
GET/PATCH/DELETE /apps/{app_name}/self-service-keys/{key_id}Read, rename or re-expire ({key_name?, expires_in_days?}), or revoke. Optional If-Match.
GET /self-service-keysEvery app's personal keys, newest first; each item names its app_name. Filters: app_name (404 when unknown), owner_email, status (active, expired, revoked).

Reads return metadata only (key_id, key_name, user_email, app_name, status, created_at, expires_at, last_used_at, revoked_at, created_via, version), never a key value or hash.

Both lists page with limit (1-200, default 50) and cursor. A cursor is bound to its organization and filters: send the same filters with it, or the answer is 400. 409 collection_changed means a key entered or left the listing since the previous page (for example a key was issued, or revoked or expired under a status filter): drop the cursor and restart from the first page with the same filters. Keys already read may appear again.

# Every active personal key of one person, across apps
cursor=""
while :; do
page=$(curl -s "$API/self-service-keys?owner_email=alice%40example.com&status=active&limit=200${cursor:+&cursor=$cursor}" "${auth[@]}")
if [ "$(echo "$page" | jq -r '.error.code // empty')" = "collection_changed" ]; then cursor=""; continue; fi
echo "$page" | jq -r '.items[] | [.app_name, .key_name, .key_id] | @tsv'
cursor=$(echo "$page" | jq -r '.next_cursor // empty')
[ -z "$cursor" ] && break
done

Usage report​

GET /self-service/usage is the report behind the console's Usage report: per app its credential mode, the people its self-service roles reach, personal-key counts, settings change requests and traffic by identity (self_service_api_key, admin_api_key, identified_user, anonymous); per person their apps, roles, keys, change requests and usage.

ParameterMeaning
from_date, to_dateA date or ISO date-time. Default the last 30 UTC days, at most 366.
app_nameRepeatable or comma-separated; 400 when unknown.
include_all_appsInclude every active app, not only apps that use self-service.
top_users_limit1-500, default 25.

Costs are estimates: unpriced models count 0 and are listed in models_without_pricing.

Errors and timing​

Profile and settings writes answer 400 self_service_profile_invalid (with field), self_service_profile_unknown_role, self_service_profile_unknown_section, self_service_profile_default_app_required, self_service_profile_default_app_not_personal_keys, self_service_profile_unknown_smart_group, self_service_profile_unknown_app or self_service_invalid_email; 409 self_service_profile_duplicate_name; 404 self_service_profile_not_found; and 503 self_service_profile_storage_unavailable (retry). A create retried with its Idempotency-Key after its profile was deleted is 409 self_service_profile_deleted.

Changes reach every gateway server within a configuration sync. Personal keys of a person who loses access stop authenticating within the self-service access cache lifetime (default 60 seconds) after that.

Endpoints​

PUT/apps/{app_name}/self-service-owners

Set an app's owners

Up to 20 emails; [] removes every owner. Owners review the app's budget and access requests. On an app a developer created from a blueprint, owners can also see its keys and logs and disable or delete it. Owners are part of the app's settings: this write and app updates (PATCH /apps/{app_name}) never overwrite each other's changes, and a PATCH that omits owners keeps them.

REQUIRESconfig:write

Also at /app/self-service-owners?app_name=... for app names that contain / or %.

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

Exact app name, URL-encoded.

Full request body specification application/json

ownersarray<string>required
max items: 20
Array item specification
string

Unknown fields are rejected in this object.

curl --request PUT \
'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/apps/Support%20Bot/self-service-owners' \
--header 'Authorization: Bearer <management-key>' \
--header 'Content-Type: application/json' \
--data '{
"owners": [
"dana@example.com"
]
}'

Authentication, errors & retry rules Try it in the playground

GET/self-service/blueprint_eligibility

Check whether apps can be blueprints

Read-only: for each named app, whether it exists and whether any of your policy rules could match it by its identity (its group key, name or key). Such an app cannot be a blueprint: those rules would not govern the copies developers create. Check before adding apps to the blueprints in PUT /self-service/settings. 503 when your policies cannot be read; an app is never reported eligible then.

REQUIRESread
Path, query & header parameters 1
app (query)array<string>required

Repeatable: 1 to 50 app names (any capitalization; duplicates collapse).

min items: 1max items: 50
Array item specification
string

No request body.

curl --request GET \
'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/self-service/blueprint_eligibility?app=example' \
--header 'Authorization: Bearer <management-key>'

Authentication, errors & retry rules Try it in the playground

GET/self-service/coverage

Count people per profile

Read-only: how many people each profile applies to (winning) or matches, how many people match no profile, and what turning on deny_without_profile would cut off: people without a profile who hold personal keys or self-service access to an app. People are the members of enabled Smart Groups (the only people a profile can match), your user directory when it is connected, and everyone holding personal keys or named in an app's self-service access list. Suspended people are counted apart. Apps whose access list allows everyone are listed: people only they reach are counted only when known otherwise.

REQUIRESread

No request body.

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

Authentication, errors & retry rules Try it in the playground

POST/self-service/coverage

Count people per profile for a draft

The same counts as GET, as if draft_profile were saved (in place of replaces_profile_id, or as a new profile), remove_profile_id were deleted, deny_without_profile had the given value, and draft_apps' self-service settings were saved. With any of these, key_impact lists the people whose active personal keys would stop (lost) or start (gained) working on an app compared with today. Nothing is stored. An empty body counts the saved profiles.

REQUIRESread
Full request body specification application/json

deny_without_profilebooleanoptional

Count as if deny_without_profile had this value.

draft_appsarray<object>optional

Count as if these apps' self-service settings were saved; a field left out keeps its stored value.

min items: 1max items: 50
Array item specification
access_controlone of 2 variantsoptional

The app's whole self_service.access_control (null clears it).

Variant 1 object
object

Also accepts null.

app_namestringrequired
enable_self_servicebooleanoptional

Personal-key mode. false stops every personal key on the app.

ownersarray<string>optional
max items: 20
Array item specification
string

Unknown fields are rejected in this object.

draft_profileobjectoptional

An unsaved profile, validated like a create. It is evaluated as if saved; nothing is stored.

Object fields
app_creationone of 2 variantsoptional

Developer app creation from blueprints. Null or absent: people cannot create apps.

Variant 1 object
blueprintsarray<string>required

Blueprint app names from the organization's blueprints.

max items: 50
Array item specification
string
max_apps_per_personintegerrequired
min: 0max: 20
settingsstringoptional

What the owner may do with their app's settings: change directly, request changes, or nothing.

"direct""request""hidden"

Unknown fields are rejected in this object.

Also accepts null.

ceilingobjectrequired

The most a person with this profile can ever hold, whatever the app grants.

Object fields
appsone of 2 variantsoptional

"all" or a list of app names.

Variant 1 string
string

Values: "all"

Variant 2 array<string>
array<string>
max items: 200
rolesarray<string>required
Array item specification
string

Values: "self_service_viewer""settings_update_requester""settings_update_direct""show_api_key""show_logs_for_all_users"

Unknown fields are rejected in this object.

default_appstring | nulloptional

App with personal keys enabled; required when llm_apps is hidden.

descriptionstringoptional
max length: 500
grantsarray<object>optional

Roles added on top of each app's own access list.

max items: 20
Array item specification
appsone of 2 variantsrequired

"all" or a list of app names.

Variant 1 string
string

Values: "all"

Variant 2 array<string>
array<string>
max items: 200
rolesarray<string>required
Array item specification
string

Values: "self_service_viewer""settings_update_requester""settings_update_direct""show_api_key""show_logs_for_all_users"

Unknown fields are rejected in this object.

keysobjectrequired
Object fields
max_active_per_personintegerrequired
min: 1max: 10
max_lifetime_daysinteger | nulloptional
min: 1max: 3650

Unknown fields are rejected in this object.

llm_appsstringrequired

hidden: the person works only in default_app, through a personal developer key.

"shown""hidden"
modelsone of 2 variantsoptional

Model tiers for personal-key callers. Null or absent: no tier rules.

Variant 1 object
max_reasoning_effortstring | nulloptional

Higher reasoning effort in a request is lowered to this, never refused.

"low""medium""high"null
tier_names_onlybooleanoptional

Only the allowed tier models can be called and listed; the served model is not revealed.

tiersarray<string>required

tier_id values from the organization's tier catalog.

max items: 10
Array item specification
string

Unknown fields are rejected in this object.

Also accepts null.

namestringrequired

Unique in the organization (case-insensitive).

min length: 1max length: 80
sectionsarray<string>required

Self-service sections the person sees.

Array item specification
string

Values: "my_usage""llm_gateway""mcp_gateway""workflow_agents""skills"

smart_groupsarray<string>required

Smart Group names (stored lowercase). A person in several profiles' groups gets the profile whose best group ranks first (lowest priority number), then the lower name.

min items: 1max items: 50
Array item specification
string

Unknown fields are rejected in this object.

remove_profile_idstringoptional

Count as if this saved profile were deleted. Not with draft_profile.

replaces_profile_idstringoptional

The saved profile the draft replaces (it takes that profile's place in the ranking). Omit to add the draft as a new profile.

Unknown fields are rejected in this object.

curl --request POST \
'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/self-service/coverage' \
--header 'Authorization: Bearer <management-key>' \
--header 'Content-Type: application/json' \
--data '{
"draft_profile": {
"ceiling": {
"apps": "all",
"roles": [
"self_service_viewer",
"show_api_key"
]
},
"default_app": "Developer sandbox",
"description": "",
"grants": [],
"keys": {
"max_active_per_person": 3,
"max_lifetime_days": 90
},
"llm_apps": "hidden",
"name": "Developers",
"sections": [
"my_usage",
"llm_gateway"
],
"smart_groups": [
"engineering"
]
},
"replaces_profile_id": "ssp_0123456789abcdef0123456789abcdef"
}'

Authentication, errors & retry rules Try it in the playground

POST/self-service/evaluate

Explain a person's self-service access

Read-only: the winning profile, every matching profile with its rank, the sections and per-app roles with where they came from (from_app, from_profile) and what the ceiling removed; also the person's model tiers, personal key limits (overall and per app), the default app's status, app creation allowance and their approved and pending exception requests. Send draft_profile (and replaces_profile_id to stand in for a saved profile) to see the answer as if that draft were saved; nothing is stored.

REQUIRESread
Full request body specification application/json

draft_profileobjectoptional

An unsaved profile, validated like a create. It is evaluated as if saved; nothing is stored.

Object fields
app_creationone of 2 variantsoptional

Developer app creation from blueprints. Null or absent: people cannot create apps.

Variant 1 object
blueprintsarray<string>required

Blueprint app names from the organization's blueprints.

max items: 50
Array item specification
string
max_apps_per_personintegerrequired
min: 0max: 20
settingsstringoptional

What the owner may do with their app's settings: change directly, request changes, or nothing.

"direct""request""hidden"

Unknown fields are rejected in this object.

Also accepts null.

ceilingobjectrequired

The most a person with this profile can ever hold, whatever the app grants.

Object fields
appsone of 2 variantsoptional

"all" or a list of app names.

Variant 1 string
string

Values: "all"

Variant 2 array<string>
array<string>
max items: 200
rolesarray<string>required
Array item specification
string

Values: "self_service_viewer""settings_update_requester""settings_update_direct""show_api_key""show_logs_for_all_users"

Unknown fields are rejected in this object.

default_appstring | nulloptional

App with personal keys enabled; required when llm_apps is hidden.

descriptionstringoptional
max length: 500
grantsarray<object>optional

Roles added on top of each app's own access list.

max items: 20
Array item specification
appsone of 2 variantsrequired

"all" or a list of app names.

Variant 1 string
string

Values: "all"

Variant 2 array<string>
array<string>
max items: 200
rolesarray<string>required
Array item specification
string

Values: "self_service_viewer""settings_update_requester""settings_update_direct""show_api_key""show_logs_for_all_users"

Unknown fields are rejected in this object.

keysobjectrequired
Object fields
max_active_per_personintegerrequired
min: 1max: 10
max_lifetime_daysinteger | nulloptional
min: 1max: 3650

Unknown fields are rejected in this object.

llm_appsstringrequired

hidden: the person works only in default_app, through a personal developer key.

"shown""hidden"
modelsone of 2 variantsoptional

Model tiers for personal-key callers. Null or absent: no tier rules.

Variant 1 object
max_reasoning_effortstring | nulloptional

Higher reasoning effort in a request is lowered to this, never refused.

"low""medium""high"null
tier_names_onlybooleanoptional

Only the allowed tier models can be called and listed; the served model is not revealed.

tiersarray<string>required

tier_id values from the organization's tier catalog.

max items: 10
Array item specification
string

Unknown fields are rejected in this object.

Also accepts null.

namestringrequired

Unique in the organization (case-insensitive).

min length: 1max length: 80
sectionsarray<string>required

Self-service sections the person sees.

Array item specification
string

Values: "my_usage""llm_gateway""mcp_gateway""workflow_agents""skills"

smart_groupsarray<string>required

Smart Group names (stored lowercase). A person in several profiles' groups gets the profile whose best group ranks first (lowest priority number), then the lower name.

min items: 1max items: 50
Array item specification
string

Unknown fields are rejected in this object.

emailstringrequired
replaces_profile_idstringoptional

The saved profile the draft replaces (it takes that profile's place in the ranking). Omit to add the draft as a new profile.

Unknown fields are rejected in this object.

curl --request POST \
'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/self-service/evaluate' \
--header 'Authorization: Bearer <management-key>' \
--header 'Content-Type: application/json' \
--data '{
"email": "dana@example.com"
}'

Authentication, errors & retry rules Try it in the playground

GET/self-service/exceptions

List exception requests

Requests people made for more than their profile gives: a budget increase or app access (reviewed by the app's owners, or admins when it has none), a stronger model tier, a longer key lifetime or another app (reviewed by admins). Filter with status (pending, approved, rejected, cancelled, revoked, failed or expired), kind, requester and app.

REQUIRESread
Path, query & header parameters 4
status (query)stringoptional

pending, approved, rejected, cancelled, revoked, failed or expired

kind (query)stringoptional

budget_increase, app_access, tier_upgrade, key_lifetime or app_create

requester (query)stringoptional

The requester's email

app (query)stringoptional

App name

No request body.

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

Authentication, errors & retry rules Try it in the playground

GET/self-service/exceptions/{exception_id}

Read an exception request

One request, with the same fields as the list. 404 self_service_exception_not_found when there is no such request in your organization.

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

No request body.

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

Authentication, errors & retry rules Try it in the playground

POST/self-service/exceptions/{exception_id}/approve

Approve an exception request

Every approval ends: ends_at defaults to the date the person asked for and is at most 365 days away. A budget increase becomes a temporary raise on the person's budget until then; another app is created now (and kept: it has no end). The API key decides as an administrator, so it may decide any request, including those the app's owners review.

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

commentstringoptional
max length: 1000
ends_atstringoptional

ISO date or date-time, at most 365 days away. Defaults to the requested date.

Unknown fields are rejected in this object.

curl --request POST \
'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/self-service/exceptions/exception_id_example/approve' \
--header 'Authorization: Bearer <management-key>' \
--header 'Content-Type: application/json' \
--data '{
"comment": "For the evaluation only",
"ends_at": "2026-12-31"
}'

Authentication, errors & retry rules Try it in the playground

POST/self-service/exceptions/{exception_id}/reject

Reject an exception request

A reason is required; the person sees it.

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

reasonstringrequired
min length: 1max length: 1000

Unknown fields are rejected in this object.

curl --request POST \
'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/self-service/exceptions/exception_id_example/reject' \
--header 'Authorization: Bearer <management-key>' \
--header 'Content-Type: application/json' \
--data '{
"reason": "Use the medium tier for this work"
}'

Authentication, errors & retry rules Try it in the playground

POST/self-service/exceptions/{exception_id}/revoke

Revoke an approved exception

Ends an approved request now. A budget raise is withdrawn; an app it created stays (disable or delete it separately).

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

reasonstringoptional
max length: 1000

Unknown fields are rejected in this object.

curl --request POST \
'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/self-service/exceptions/exception_id_example/revoke' \
--header 'Authorization: Bearer <management-key>' \
--header 'Content-Type: application/json' \
--data '{
"reason": "Evaluation finished"
}'

Authentication, errors & retry rules Try it in the playground

GET/self-service/profiles

List self-service profiles

Profiles in rank order (each profile's best Smart Group priority, then name), the organization setting, suspended people and every Smart Group's display name and effective priority.

REQUIRESread

No request body.

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

Authentication, errors & retry rules Try it in the playground

POST/self-service/profiles

Create a self-service profile

A profile caps what its people can hold: each app's own roles plus the profile's grants, never above the ceiling, and nothing without self_service_viewer. An app's explicit deny always wins. Requires an Idempotency-Key. Groups and apps must exist; default_app must have personal keys enabled.

REQUIRESconfig:write
Path, query & header parameters 1
Idempotency-Key (header)stringrequired

Unique per logical write. A retry with the same key and body replays the original result.

min length: 1max length: 200
Full request body specification application/json

app_creationone of 2 variantsoptional

Developer app creation from blueprints. Null or absent: people cannot create apps.

Variant 1 object
blueprintsarray<string>required

Blueprint app names from the organization's blueprints.

max items: 50
Array item specification
string
max_apps_per_personintegerrequired
min: 0max: 20
settingsstringoptional

What the owner may do with their app's settings: change directly, request changes, or nothing.

"direct""request""hidden"

Unknown fields are rejected in this object.

Also accepts null.

ceilingobjectrequired

The most a person with this profile can ever hold, whatever the app grants.

Object fields
appsone of 2 variantsoptional

"all" or a list of app names.

Variant 1 string
string

Values: "all"

Variant 2 array<string>
array<string>
max items: 200
rolesarray<string>required
Array item specification
string

Values: "self_service_viewer""settings_update_requester""settings_update_direct""show_api_key""show_logs_for_all_users"

Unknown fields are rejected in this object.

default_appstring | nulloptional

App with personal keys enabled; required when llm_apps is hidden.

descriptionstringoptional
max length: 500
grantsarray<object>optional

Roles added on top of each app's own access list.

max items: 20
Array item specification
appsone of 2 variantsrequired

"all" or a list of app names.

Variant 1 string
string

Values: "all"

Variant 2 array<string>
array<string>
max items: 200
rolesarray<string>required
Array item specification
string

Values: "self_service_viewer""settings_update_requester""settings_update_direct""show_api_key""show_logs_for_all_users"

Unknown fields are rejected in this object.

keysobjectrequired
Object fields
max_active_per_personintegerrequired
min: 1max: 10
max_lifetime_daysinteger | nulloptional
min: 1max: 3650

Unknown fields are rejected in this object.

llm_appsstringrequired

hidden: the person works only in default_app, through a personal developer key.

"shown""hidden"
modelsone of 2 variantsoptional

Model tiers for personal-key callers. Null or absent: no tier rules.

Variant 1 object
max_reasoning_effortstring | nulloptional

Higher reasoning effort in a request is lowered to this, never refused.

"low""medium""high"null
tier_names_onlybooleanoptional

Only the allowed tier models can be called and listed; the served model is not revealed.

tiersarray<string>required

tier_id values from the organization's tier catalog.

max items: 10
Array item specification
string

Unknown fields are rejected in this object.

Also accepts null.

namestringrequired

Unique in the organization (case-insensitive).

min length: 1max length: 80
sectionsarray<string>required

Self-service sections the person sees.

Array item specification
string

Values: "my_usage""llm_gateway""mcp_gateway""workflow_agents""skills"

smart_groupsarray<string>required

Smart Group names (stored lowercase). A person in several profiles' groups gets the profile whose best group ranks first (lowest priority number), then the lower name.

min items: 1max items: 50
Array item specification
string

Unknown fields are rejected in this object.

curl --request POST \
'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/self-service/profiles' \
--header 'Authorization: Bearer <management-key>' \
--header 'Idempotency-Key: create-developers-001' \
--header 'Content-Type: application/json' \
--data '{
"ceiling": {
"apps": "all",
"roles": [
"self_service_viewer",
"show_api_key"
]
},
"default_app": "Developer sandbox",
"description": "",
"grants": [],
"keys": {
"max_active_per_person": 3,
"max_lifetime_days": 90
},
"llm_apps": "hidden",
"name": "Developers",
"sections": [
"my_usage",
"llm_gateway"
],
"smart_groups": [
"engineering"
]
}'

Authentication, errors & retry rules Try it in the playground

DELETE/self-service/profiles/{profile_id}

Delete a self-service profile

Its people fall back to the next matching profile, or to their apps' own access lists (none at all when deny_without_profile is on). Needs the current revision.

REQUIRESconfig:write
Path, query & header parameters 2
profile_id (path)stringrequired
revision (query)integerrequired

The profile's revision from your latest read.

min: 1
Full request body specification application/json

Unknown fields are rejected in this object.

curl --request DELETE \
'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/self-service/profiles/profile_id_example?revision=example' \
--header 'Authorization: Bearer <management-key>'

Authentication, errors & retry rules Try it in the playground

PUT/self-service/profiles/{profile_id}

Replace a self-service profile

A profile caps what its people can hold: each app's own roles plus the profile's grants, never above the ceiling, and nothing without self_service_viewer. An app's explicit deny always wins. Send every field and the revision from your latest read; a stale revision is 409 self_service_profile_revision_conflict.

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

Full replacement; revision from the latest read.

app_creationone of 2 variantsoptional

Developer app creation from blueprints. Null or absent: people cannot create apps.

Variant 1 object
blueprintsarray<string>required

Blueprint app names from the organization's blueprints.

max items: 50
Array item specification
string
max_apps_per_personintegerrequired
min: 0max: 20
settingsstringoptional

What the owner may do with their app's settings: change directly, request changes, or nothing.

"direct""request""hidden"

Unknown fields are rejected in this object.

Also accepts null.

ceilingobjectrequired

The most a person with this profile can ever hold, whatever the app grants.

Object fields
appsone of 2 variantsoptional

"all" or a list of app names.

Variant 1 string
string

Values: "all"

Variant 2 array<string>
array<string>
max items: 200
rolesarray<string>required
Array item specification
string

Values: "self_service_viewer""settings_update_requester""settings_update_direct""show_api_key""show_logs_for_all_users"

Unknown fields are rejected in this object.

default_appstring | nulloptional

App with personal keys enabled; required when llm_apps is hidden.

descriptionstringoptional
max length: 500
grantsarray<object>optional

Roles added on top of each app's own access list.

max items: 20
Array item specification
appsone of 2 variantsrequired

"all" or a list of app names.

Variant 1 string
string

Values: "all"

Variant 2 array<string>
array<string>
max items: 200
rolesarray<string>required
Array item specification
string

Values: "self_service_viewer""settings_update_requester""settings_update_direct""show_api_key""show_logs_for_all_users"

Unknown fields are rejected in this object.

keysobjectrequired
Object fields
max_active_per_personintegerrequired
min: 1max: 10
max_lifetime_daysinteger | nulloptional
min: 1max: 3650

Unknown fields are rejected in this object.

llm_appsstringrequired

hidden: the person works only in default_app, through a personal developer key.

"shown""hidden"
modelsone of 2 variantsoptional

Model tiers for personal-key callers. Null or absent: no tier rules.

Variant 1 object
max_reasoning_effortstring | nulloptional

Higher reasoning effort in a request is lowered to this, never refused.

"low""medium""high"null
tier_names_onlybooleanoptional

Only the allowed tier models can be called and listed; the served model is not revealed.

tiersarray<string>required

tier_id values from the organization's tier catalog.

max items: 10
Array item specification
string

Unknown fields are rejected in this object.

Also accepts null.

namestringrequired

Unique in the organization (case-insensitive).

min length: 1max length: 80
revisionintegerrequired
sectionsarray<string>required

Self-service sections the person sees.

Array item specification
string

Values: "my_usage""llm_gateway""mcp_gateway""workflow_agents""skills"

smart_groupsarray<string>required

Smart Group names (stored lowercase). A person in several profiles' groups gets the profile whose best group ranks first (lowest priority number), then the lower name.

min items: 1max items: 50
Array item specification
string

Unknown fields are rejected in this object.

curl --request PUT \
'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/self-service/profiles/profile_id_example' \
--header 'Authorization: Bearer <management-key>' \
--header 'Content-Type: application/json' \
--data '{
"ceiling": {
"apps": "all",
"roles": [
"self_service_viewer",
"show_api_key"
]
},
"default_app": "Developer sandbox",
"description": "",
"grants": [],
"keys": {
"max_active_per_person": 3,
"max_lifetime_days": 90
},
"llm_apps": "hidden",
"name": "Developers",
"revision": 1,
"sections": [
"my_usage",
"llm_gateway"
],
"smart_groups": [
"engineering"
]
}'

Authentication, errors & retry rules Try it in the playground

PUT/self-service/settings

Update the self-service setting

deny_without_profile: true refuses self-service to anyone who matches no profile. tiers is the model tier catalog and blueprints the apps developers may copy. Send only what you change (an omitted field keeps its saved value) with the revision from your latest read (0 before the first save); a stale revision is 409 self_service_profile_revision_conflict. Removing a tier or blueprint a profile still uses is 409 self_service_catalog_in_use, naming those profiles.

REQUIRESconfig:write
Full request body specification application/json

Send only what you change: an omitted field keeps its saved value. revision from your latest read.

blueprintsarray<object>optional

Apps developers may copy. Omit to keep them.

max items: 50
Array item specification
app_namestringrequired

An existing app developers may copy.

descriptionstringoptional
max length: 500
labelstringoptional
max length: 80

Unknown fields are rejected in this object.

deny_without_profilebooleanoptional
revisionintegerrequired
tiersarray<object>optional

The tier catalog. Omit to keep it.

max items: 10
Array item specification
descriptionstringoptional
max length: 300
labelstringrequired
min length: 1max length: 40
modelstringrequired

The model name callers send; a routing group in your policies serves it.

min length: 1max length: 200
rankintegerrequired

1 is the lowest tier.

min: 1max: 100
tier_idstringrequired
pattern: ^[a-z0-9][a-z0-9_-]{0,39}$

Unknown fields are rejected in this object.

Unknown fields are rejected in this object.

curl --request PUT \
'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/self-service/settings' \
--header 'Authorization: Bearer <management-key>' \
--header 'Content-Type: application/json' \
--data '{
"deny_without_profile": true,
"revision": 0
}'

Authentication, errors & retry rules Try it in the playground

PUT/self-service/suspensions

Suspend a person

The person loses every self-service role and section at once, and their personal keys stop authenticating. Suspending again updates the reason.

REQUIRESconfig:write
Full request body specification application/json

emailstringrequired
reasonstringoptional
max length: 500

Unknown fields are rejected in this object.

curl --request PUT \
'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/self-service/suspensions' \
--header 'Authorization: Bearer <management-key>' \
--header 'Content-Type: application/json' \
--data '{
"email": "dana@example.com",
"reason": "Offboarding"
}'

Authentication, errors & retry rules Try it in the playground

POST/self-service/suspensions/remove

Lift a suspension

removed is null when the person was not suspended.

REQUIRESconfig:write
Full request body specification application/json

emailstringrequired

Unknown fields are rejected in this object.

curl --request POST \
'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/self-service/suspensions/remove' \
--header 'Authorization: Bearer <management-key>' \
--header 'Content-Type: application/json' \
--data '{
"email": "dana@example.com"
}'

Authentication, errors & retry rules Try it in the playground

GET/self-service/usage

Report self-service usage

How self-service is used across your organization in a time window (default: the last 30 UTC days including today, at most 366 days): per app, its credential mode, the people its self-service roles reach, personal API keys, settings change requests and request traffic split by identity (personal key, the app's own key, other identified users, anonymous); per person, their apps, roles, keys, change requests and usage. Covers apps with self-service configured, personal keys or change requests in the window; include_all_apps=true adds every app. Costs are estimates; models without a known price count as 0 and are listed in models_without_pricing.

REQUIRESread
Path, query & header parameters 5
from_date (query)stringoptional

Start, inclusive: a date (UTC midnight) or ISO date-time. Default: 29 days before today.

to_date (query)stringoptional

End: a date (its end of day, UTC) or ISO date-time. Default: now.

app_name (query)array<string>optional

Repeatable (or comma-separated): only these apps, exact names. 400 when one does not exist.

Array item specification
string
include_all_apps (query)booleanoptional

Also report apps without self-service configuration or activity.

top_users_limit (query)integeroptional

How many of the busiest identified users the traffic breakdown ranks.

min: 1max: 500default: 25

No request body.

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

Authentication, errors & retry rules Try it in the playground

Personal key endpoints​

GET/apps/{app_name}/self-service-keys

List an app's personal API keys

Personal (self-service) API keys of one app, newest first, metadata only: never a key value. Filter by user_email and status (active, expired or revoked); page with limit (1 to 200, default 50) and cursor.

REQUIRESread

Also at /app/self-service-keys?app_name=... for app names that contain / or %.

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

Exact app name, URL-encoded.

user_email (query)stringoptional

Only this person's keys (case-insensitive).

status (query)objectoptional

Only keys in this state; omit for all.

"active""expired""revoked"
limit (query)integeroptional

Page size: 1 to 200, default 50.

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

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

No request body.

curl --request GET \
'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/apps/Support%20Bot/self-service-keys?limit=50' \
--header 'Authorization: Bearer <management-key>'

Authentication, errors & retry rules Try it in the playground

POST/apps/{app_name}/self-service-keys

Issue a personal API key for a user

Create a personal API key on a person's behalf. The person needs self-service access to the app exactly as if they created the key themselves: the app must allow personal API keys (user API-key mode), and the person must hold the self-service viewer role (a requester or direct-update role implies it; a deny wins). The app's maximum key lifetime applies, and an omitted expires_in_days takes it (the key never expires only when the app sets no maximum). Names are unique among the person's active keys of the app (case-insensitive), and the per-person limit of active keys applies. The key value is in this response only: a retry with the same Idempotency-Key and body replays it for 24 hours, after which it is never shown again. Calls authenticate as the person.

REQUIRESkeys:write

Also at /app/self-service-keys?app_name=... for app names that contain / or %.

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

Exact app name, URL-encoded.

Idempotency-Key (header)stringrequired

Unique per logical write. A retry with the same key and body replays the original result (including the key value) for 24 hours; the same key with a different body is a 409.

min length: 1max length: 200
Full request body specification application/json

expires_in_daysintegeroptional

Lifetime in days, at most the app's maximum key lifetime. Omitted: the app's maximum; never expires only when the app sets no maximum.

min: 1max: 3650
key_namestringrequired

Unique (case-insensitive) among the person's active keys of this app.

min length: 1max length: 120
user_emailstringrequired

Email of the person the key is for (case-insensitive).

max length: 320

Unknown fields are rejected in this object.

curl --request POST \
'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/apps/Support%20Bot/self-service-keys' \
--header 'Authorization: Bearer <management-key>' \
--header 'Idempotency-Key: issue-dana-laptop-cli-001' \
--header 'Content-Type: application/json' \
--data '{
"expires_in_days": 90,
"key_name": "laptop-cli",
"user_email": "dana@example.com"
}'

Authentication, errors & retry rules Try it in the playground

DELETE/apps/{app_name}/self-service-keys/{key_id}

Revoke a personal API key

Revoke the key at once; it stops authenticating. Revocation is permanent. Applies to any personal key of the app, including keys the person created themselves; the person's current access is not checked. Send the key's version in If-Match to guard against concurrent changes (optional).

REQUIRESkeys:write

Also at /app/self-service-keys/{key_id}?app_name=... for app names that contain / or %.

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

Exact app name, URL-encoded.

key_id (path)stringrequired
If-Match (header)stringoptional

Optional quoted version from the latest read of the key; 412 when it changed.

Full request body specification application/json

Unknown fields are rejected in this object.

curl --request DELETE \
'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/apps/Support%20Bot/self-service-keys/6b0e2c1a-4f3d-4c55-9a1e-0d2b7f8c9e10' \
--header 'Authorization: Bearer <management-key>' \
--header 'If-Match: "9b2e4f0c7a1d"'

Authentication, errors & retry rules Try it in the playground

GET/apps/{app_name}/self-service-keys/{key_id}

Read a personal API key

One personal API key of the app, metadata only.

REQUIRESread

Also at /app/self-service-keys/{key_id}?app_name=... for app names that contain / or %.

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

Exact app name, URL-encoded.

key_id (path)stringrequired

No request body.

curl --request GET \
'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/apps/Support%20Bot/self-service-keys/6b0e2c1a-4f3d-4c55-9a1e-0d2b7f8c9e10' \
--header 'Authorization: Bearer <management-key>'

Authentication, errors & retry rules Try it in the playground

PATCH/apps/{app_name}/self-service-keys/{key_id}

Rename a personal API key or change its expiry

Rename the key (unique among its owner's active keys of the app) and/or set a new expiry counted from now, capped by the app's maximum key lifetime. Revoked keys cannot be changed, and expired keys cannot get a new expiry. Applies to any personal key of the app, including keys the person created themselves; the person's current access is not checked. Send the key's version in If-Match to guard against concurrent changes (optional).

REQUIRESkeys:write

Also at /app/self-service-keys/{key_id}?app_name=... for app names that contain / or %.

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

Exact app name, URL-encoded.

key_id (path)stringrequired
If-Match (header)stringoptional

Optional quoted version from the latest read of the key; 412 when it changed.

Full request body specification application/json

At least one field.

expires_in_daysintegeroptional

New expiry, counted from now; at most the app's maximum key lifetime. An expiry can be changed but not removed.

min: 1max: 3650
key_namestringoptional
min length: 1max length: 120

Unknown fields are rejected in this object.

curl --request PATCH \
'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/apps/Support%20Bot/self-service-keys/6b0e2c1a-4f3d-4c55-9a1e-0d2b7f8c9e10' \
--header 'Authorization: Bearer <management-key>' \
--header 'If-Match: "9b2e4f0c7a1d"' \
--header 'Content-Type: application/json' \
--data '{
"expires_in_days": 30,
"key_name": "build-agent"
}'

Authentication, errors & retry rules Try it in the playground

GET/self-service-keys

List personal API keys across apps

Personal (self-service) API keys of every app, newest first, metadata only: never a key value. Each item names its app. Filter by app_name, owner_email and status (active, expired or revoked); page with limit (1 to 200, default 50) and cursor.

REQUIRESread
Path, query & header parameters 5
app_name (query)stringoptional

Only this app's keys (any capitalization); 404 when there is no such app.

owner_email (query)stringoptional

Only this person's keys (case-insensitive).

status (query)objectoptional

Only keys in this state; omit for all.

"active""expired""revoked"
limit (query)integeroptional

Page size: 1 to 200, default 50.

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

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

No request body.

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

Authentication, errors & retry rules Try it in the playground