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:
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. Withtier_names_only, only the allowed tier models can be called (403self_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:truegives 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}.modelis 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:
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 (404self_service_exception_not_foundoutside your organization).POST .../approve {ends_at?, comment?}: every approval ends (ends_at, at most 365 days away, default the requested date), exceptapp_create. Afterends_atthe effect stops and the request readsexpired.POST .../reject {reason}andPOST .../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.
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.
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
/apps/{app_name}/self-service-ownersSet 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.
config:writeAlso at /app/self-service-owners?app_name=... for app names that contain / or %.
Path, query & header parameters 1
app_name (path)stringrequiredExact app name, URL-encoded.
Full request body specification application/json
ownersarray<string>requiredArray item specification
stringUnknown 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
/self-service/blueprint_eligibilityCheck 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.
readPath, query & header parameters 1
app (query)array<string>requiredRepeatable: 1 to 50 app names (any capitalization; duplicates collapse).
Array item specification
stringNo 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
/self-service/coverageCount 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.
readNo 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
/self-service/coverageCount 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.
readFull request body specification application/json
deny_without_profilebooleanoptionalCount as if deny_without_profile had this value.
draft_appsarray<object>optionalCount as if these apps' self-service settings were saved; a field left out keeps its stored value.
Array item specification
access_controlone of 2 variantsoptionalThe app's whole self_service.access_control (null clears it).
Variant 1 object
objectAlso accepts null.
app_namestringrequiredenable_self_servicebooleanoptionalPersonal-key mode. false stops every personal key on the app.
ownersarray<string>optionalArray item specification
stringUnknown fields are rejected in this object.
draft_profileobjectoptionalAn unsaved profile, validated like a create. It is evaluated as if saved; nothing is stored.
Object fields
app_creationone of 2 variantsoptionalDeveloper app creation from blueprints. Null or absent: people cannot create apps.
Variant 1 object
blueprintsarray<string>requiredBlueprint app names from the organization's blueprints.
Array item specification
stringmax_apps_per_personintegerrequiredsettingsstringoptionalWhat 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.
ceilingobjectrequiredThe 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
stringValues: "all"
Variant 2 array<string>
array<string>rolesarray<string>requiredArray item specification
stringValues: "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 | nulloptionalApp with personal keys enabled; required when llm_apps is hidden.
descriptionstringoptionalgrantsarray<object>optionalRoles added on top of each app's own access list.
Array item specification
appsone of 2 variantsrequired"all" or a list of app names.
Variant 1 string
stringValues: "all"
Variant 2 array<string>
array<string>rolesarray<string>requiredArray item specification
stringValues: "self_service_viewer""settings_update_requester""settings_update_direct""show_api_key""show_logs_for_all_users"
Unknown fields are rejected in this object.
keysobjectrequiredObject fields
max_active_per_personintegerrequiredmax_lifetime_daysinteger | nulloptionalUnknown fields are rejected in this object.
llm_appsstringrequiredhidden: the person works only in default_app, through a personal developer key.
"shown""hidden"modelsone of 2 variantsoptionalModel tiers for personal-key callers. Null or absent: no tier rules.
Variant 1 object
max_reasoning_effortstring | nulloptionalHigher reasoning effort in a request is lowered to this, never refused.
"low""medium""high"nulltier_names_onlybooleanoptionalOnly the allowed tier models can be called and listed; the served model is not revealed.
tiersarray<string>requiredtier_id values from the organization's tier catalog.
Array item specification
stringUnknown fields are rejected in this object.
Also accepts null.
namestringrequiredUnique in the organization (case-insensitive).
sectionsarray<string>requiredSelf-service sections the person sees.
Array item specification
stringValues: "my_usage""llm_gateway""mcp_gateway""workflow_agents""skills"
smart_groupsarray<string>requiredSmart 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.
Array item specification
stringUnknown fields are rejected in this object.
remove_profile_idstringoptionalCount as if this saved profile were deleted. Not with draft_profile.
replaces_profile_idstringoptionalThe 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
/self-service/evaluateExplain 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.
readFull request body specification application/json
draft_profileobjectoptionalAn unsaved profile, validated like a create. It is evaluated as if saved; nothing is stored.
Object fields
app_creationone of 2 variantsoptionalDeveloper app creation from blueprints. Null or absent: people cannot create apps.
Variant 1 object
blueprintsarray<string>requiredBlueprint app names from the organization's blueprints.
Array item specification
stringmax_apps_per_personintegerrequiredsettingsstringoptionalWhat 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.
ceilingobjectrequiredThe 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
stringValues: "all"
Variant 2 array<string>
array<string>rolesarray<string>requiredArray item specification
stringValues: "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 | nulloptionalApp with personal keys enabled; required when llm_apps is hidden.
descriptionstringoptionalgrantsarray<object>optionalRoles added on top of each app's own access list.
Array item specification
appsone of 2 variantsrequired"all" or a list of app names.
Variant 1 string
stringValues: "all"
Variant 2 array<string>
array<string>rolesarray<string>requiredArray item specification
stringValues: "self_service_viewer""settings_update_requester""settings_update_direct""show_api_key""show_logs_for_all_users"
Unknown fields are rejected in this object.
keysobjectrequiredObject fields
max_active_per_personintegerrequiredmax_lifetime_daysinteger | nulloptionalUnknown fields are rejected in this object.
llm_appsstringrequiredhidden: the person works only in default_app, through a personal developer key.
"shown""hidden"modelsone of 2 variantsoptionalModel tiers for personal-key callers. Null or absent: no tier rules.
Variant 1 object
max_reasoning_effortstring | nulloptionalHigher reasoning effort in a request is lowered to this, never refused.
"low""medium""high"nulltier_names_onlybooleanoptionalOnly the allowed tier models can be called and listed; the served model is not revealed.
tiersarray<string>requiredtier_id values from the organization's tier catalog.
Array item specification
stringUnknown fields are rejected in this object.
Also accepts null.
namestringrequiredUnique in the organization (case-insensitive).
sectionsarray<string>requiredSelf-service sections the person sees.
Array item specification
stringValues: "my_usage""llm_gateway""mcp_gateway""workflow_agents""skills"
smart_groupsarray<string>requiredSmart 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.
Array item specification
stringUnknown fields are rejected in this object.
emailstringrequiredreplaces_profile_idstringoptionalThe 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
/self-service/exceptionsList 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.
readPath, query & header parameters 4
status (query)stringoptionalpending, approved, rejected, cancelled, revoked, failed or expired
kind (query)stringoptionalbudget_increase, app_access, tier_upgrade, key_lifetime or app_create
requester (query)stringoptionalThe requester's email
app (query)stringoptionalApp 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
/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.
readPath, query & header parameters 1
exception_id (path)stringrequiredNo 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
/self-service/exceptions/{exception_id}/approveApprove 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.
config:writePath, query & header parameters 1
exception_id (path)stringrequiredFull request body specification application/json
commentstringoptionalends_atstringoptionalISO 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
/self-service/exceptions/{exception_id}/rejectReject an exception request
A reason is required; the person sees it.
config:writePath, query & header parameters 1
exception_id (path)stringrequiredFull request body specification application/json
reasonstringrequiredUnknown 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
/self-service/exceptions/{exception_id}/revokeRevoke an approved exception
Ends an approved request now. A budget raise is withdrawn; an app it created stays (disable or delete it separately).
config:writePath, query & header parameters 1
exception_id (path)stringrequiredFull request body specification application/json
reasonstringoptionalUnknown 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
/self-service/profilesList 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.
readNo 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
/self-service/profilesCreate 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.
config:writePath, query & header parameters 1
Idempotency-Key (header)stringrequiredUnique per logical write. A retry with the same key and body replays the original result.
Full request body specification application/json
app_creationone of 2 variantsoptionalDeveloper app creation from blueprints. Null or absent: people cannot create apps.
Variant 1 object
blueprintsarray<string>requiredBlueprint app names from the organization's blueprints.
Array item specification
stringmax_apps_per_personintegerrequiredsettingsstringoptionalWhat 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.
ceilingobjectrequiredThe 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
stringValues: "all"
Variant 2 array<string>
array<string>rolesarray<string>requiredArray item specification
stringValues: "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 | nulloptionalApp with personal keys enabled; required when llm_apps is hidden.
descriptionstringoptionalgrantsarray<object>optionalRoles added on top of each app's own access list.
Array item specification
appsone of 2 variantsrequired"all" or a list of app names.
Variant 1 string
stringValues: "all"
Variant 2 array<string>
array<string>rolesarray<string>requiredArray item specification
stringValues: "self_service_viewer""settings_update_requester""settings_update_direct""show_api_key""show_logs_for_all_users"
Unknown fields are rejected in this object.
keysobjectrequiredObject fields
max_active_per_personintegerrequiredmax_lifetime_daysinteger | nulloptionalUnknown fields are rejected in this object.
llm_appsstringrequiredhidden: the person works only in default_app, through a personal developer key.
"shown""hidden"modelsone of 2 variantsoptionalModel tiers for personal-key callers. Null or absent: no tier rules.
Variant 1 object
max_reasoning_effortstring | nulloptionalHigher reasoning effort in a request is lowered to this, never refused.
"low""medium""high"nulltier_names_onlybooleanoptionalOnly the allowed tier models can be called and listed; the served model is not revealed.
tiersarray<string>requiredtier_id values from the organization's tier catalog.
Array item specification
stringUnknown fields are rejected in this object.
Also accepts null.
namestringrequiredUnique in the organization (case-insensitive).
sectionsarray<string>requiredSelf-service sections the person sees.
Array item specification
stringValues: "my_usage""llm_gateway""mcp_gateway""workflow_agents""skills"
smart_groupsarray<string>requiredSmart 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.
Array item specification
stringUnknown 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
/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.
config:writePath, query & header parameters 2
profile_id (path)stringrequiredrevision (query)integerrequiredThe profile's revision from your latest read.
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
/self-service/profiles/{profile_id}Read a self-service profile
One profile.
readPath, query & header parameters 1
profile_id (path)stringrequiredNo request body.
curl --request GET \
'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/self-service/profiles/profile_id_example' \
--header 'Authorization: Bearer <management-key>'
Authentication, errors & retry rules Try it in the playground
/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.
config:writePath, query & header parameters 1
profile_id (path)stringrequiredFull request body specification application/json
Full replacement; revision from the latest read.
app_creationone of 2 variantsoptionalDeveloper app creation from blueprints. Null or absent: people cannot create apps.
Variant 1 object
blueprintsarray<string>requiredBlueprint app names from the organization's blueprints.
Array item specification
stringmax_apps_per_personintegerrequiredsettingsstringoptionalWhat 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.
ceilingobjectrequiredThe 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
stringValues: "all"
Variant 2 array<string>
array<string>rolesarray<string>requiredArray item specification
stringValues: "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 | nulloptionalApp with personal keys enabled; required when llm_apps is hidden.
descriptionstringoptionalgrantsarray<object>optionalRoles added on top of each app's own access list.
Array item specification
appsone of 2 variantsrequired"all" or a list of app names.
Variant 1 string
stringValues: "all"
Variant 2 array<string>
array<string>rolesarray<string>requiredArray item specification
stringValues: "self_service_viewer""settings_update_requester""settings_update_direct""show_api_key""show_logs_for_all_users"
Unknown fields are rejected in this object.
keysobjectrequiredObject fields
max_active_per_personintegerrequiredmax_lifetime_daysinteger | nulloptionalUnknown fields are rejected in this object.
llm_appsstringrequiredhidden: the person works only in default_app, through a personal developer key.
"shown""hidden"modelsone of 2 variantsoptionalModel tiers for personal-key callers. Null or absent: no tier rules.
Variant 1 object
max_reasoning_effortstring | nulloptionalHigher reasoning effort in a request is lowered to this, never refused.
"low""medium""high"nulltier_names_onlybooleanoptionalOnly the allowed tier models can be called and listed; the served model is not revealed.
tiersarray<string>requiredtier_id values from the organization's tier catalog.
Array item specification
stringUnknown fields are rejected in this object.
Also accepts null.
namestringrequiredUnique in the organization (case-insensitive).
revisionintegerrequiredsectionsarray<string>requiredSelf-service sections the person sees.
Array item specification
stringValues: "my_usage""llm_gateway""mcp_gateway""workflow_agents""skills"
smart_groupsarray<string>requiredSmart 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.
Array item specification
stringUnknown 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
/self-service/settingsUpdate 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.
config:writeFull request body specification application/json
Send only what you change: an omitted field keeps its saved value. revision from your latest read.
blueprintsarray<object>optionalApps developers may copy. Omit to keep them.
Array item specification
app_namestringrequiredAn existing app developers may copy.
descriptionstringoptionallabelstringoptionalUnknown fields are rejected in this object.
deny_without_profilebooleanoptionalrevisionintegerrequiredtiersarray<object>optionalThe tier catalog. Omit to keep it.
Array item specification
descriptionstringoptionallabelstringrequiredmodelstringrequiredThe model name callers send; a routing group in your policies serves it.
rankintegerrequired1 is the lowest tier.
tier_idstringrequiredUnknown 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
/self-service/suspensionsSuspend a person
The person loses every self-service role and section at once, and their personal keys stop authenticating. Suspending again updates the reason.
config:writeFull request body specification application/json
emailstringrequiredreasonstringoptionalUnknown 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
/self-service/suspensions/removeLift a suspension
removed is null when the person was not suspended.
config:writeFull request body specification application/json
emailstringrequiredUnknown 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
/self-service/usageReport 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.
readPath, query & header parameters 5
from_date (query)stringoptionalStart, inclusive: a date (UTC midnight) or ISO date-time. Default: 29 days before today.
to_date (query)stringoptionalEnd: a date (its end of day, UTC) or ISO date-time. Default: now.
app_name (query)array<string>optionalRepeatable (or comma-separated): only these apps, exact names. 400 when one does not exist.
Array item specification
stringinclude_all_apps (query)booleanoptionalAlso report apps without self-service configuration or activity.
top_users_limit (query)integeroptionalHow many of the busiest identified users the traffic breakdown ranks.
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
/apps/{app_name}/self-service-keysList 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.
readAlso at /app/self-service-keys?app_name=... for app names that contain / or %.
Path, query & header parameters 5
app_name (path)stringrequiredExact app name, URL-encoded.
user_email (query)stringoptionalOnly this person's keys (case-insensitive).
status (query)objectoptionalOnly keys in this state; omit for all.
"active""expired""revoked"limit (query)integeroptionalPage size: 1 to 200, default 50.
cursor (query)stringoptionalnext_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
/apps/{app_name}/self-service-keysIssue 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.
keys:writeAlso at /app/self-service-keys?app_name=... for app names that contain / or %.
Path, query & header parameters 2
app_name (path)stringrequiredExact app name, URL-encoded.
Idempotency-Key (header)stringrequiredUnique 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.
Full request body specification application/json
expires_in_daysintegeroptionalLifetime in days, at most the app's maximum key lifetime. Omitted: the app's maximum; never expires only when the app sets no maximum.
key_namestringrequiredUnique (case-insensitive) among the person's active keys of this app.
user_emailstringrequiredEmail of the person the key is for (case-insensitive).
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
/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).
keys:writeAlso at /app/self-service-keys/{key_id}?app_name=... for app names that contain / or %.
Path, query & header parameters 3
app_name (path)stringrequiredExact app name, URL-encoded.
key_id (path)stringrequiredIf-Match (header)stringoptionalOptional 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
/apps/{app_name}/self-service-keys/{key_id}Read a personal API key
One personal API key of the app, metadata only.
readAlso at /app/self-service-keys/{key_id}?app_name=... for app names that contain / or %.
Path, query & header parameters 2
app_name (path)stringrequiredExact app name, URL-encoded.
key_id (path)stringrequiredNo 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
/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).
keys:writeAlso at /app/self-service-keys/{key_id}?app_name=... for app names that contain / or %.
Path, query & header parameters 3
app_name (path)stringrequiredExact app name, URL-encoded.
key_id (path)stringrequiredIf-Match (header)stringoptionalOptional 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_daysintegeroptionalNew expiry, counted from now; at most the app's maximum key lifetime. An expiry can be changed but not removed.
key_namestringoptionalUnknown 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
/self-service-keysList 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.
readPath, query & header parameters 5
app_name (query)stringoptionalOnly this app's keys (any capitalization); 404 when there is no such app.
owner_email (query)stringoptionalOnly this person's keys (case-insensitive).
status (query)objectoptionalOnly keys in this state; omit for all.
"active""expired""revoked"limit (query)integeroptionalPage size: 1 to 200, default 50.
cursor (query)stringoptionalnext_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
Related
- Self-service overview - concepts and how access is decided.
- Self-service admin guide - the same setup in the console.
- Smart groups API - the groups and ranks profiles match on.
- Users API - everyone who uses the gateway.
- Management API - authentication, errors and retry rules.