{ "openapi": "3.1.0", "info": { "title": "LLM Gateway management", "version": "1.0.0", "description": "Implemented LLM Gateway management v1. Tenant-admin bootstrap and scoped tenant configuration. Policy lifecycle APIs are Not Generally Available. Existing QuilrQL authority can add app-specific model-access defaults during app creation. Only implemented operations appear in paths." }, "paths": { "/llmgateway/management/v1/capabilities": { "get": { "operationId": "Read_capabilities", "security": [ { "ManagementKey": [] } ], "parameters": [], "responses": { "200": { "description": "Success", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "no-store" }, "X-Request-ID": { "schema": { "type": "string" }, "description": "Request correlation ID." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "schema_version": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "provider_types": { "type": "array", "items": { "type": "string" } }, "app_fields": { "type": "object" }, "app_top_level_fields": { "type": "array", "items": { "type": "string" } }, "modes": { "type": "array", "items": { "type": "string" } }, "policy_updates": { "type": "boolean" }, "policy_authority": { "type": "object" }, "writes_available": { "type": "boolean" }, "configuration_propagation": { "type": "string" }, "model_tests_available": { "type": "boolean" }, "model_test_provider_types": { "type": "array", "items": { "type": "string" } }, "connection_test_provider_types": { "type": "array", "items": { "type": "string" } }, "provider_saves_call_upstream": { "type": "boolean" }, "completely_no_gpu": { "type": "boolean" }, "request_id": { "type": "string" } }, "additionalProperties": true, "required": [ "schema_version", "scopes", "provider_types", "app_fields", "app_top_level_fields", "modes", "policy_updates", "policy_authority", "writes_available", "configuration_propagation", "model_tests_available", "model_test_provider_types", "connection_test_provider_types", "provider_saves_call_upstream", "completely_no_gpu", "request_id" ] }, "example": { "schema_version": "1", "scopes": [ "config:write", "credentials:read", "credentials:write", "providers:write", "read" ], "provider_types": [ "openai", "azureopenai", "general", "quilr_ai", "anthropic", "anthropic_messages", "anthropic_messages_bedrock", "anthropic_messages_azure", "deepseek", "vertex_ai", "gemini_chatcompletions", "oracle", "openai_responses", "openai_responses_azure", "oracle_responses", "openai_assistants", "openai_assistants_azure", "openai_realtime", "openai_realtime_azure", "bedrock", "bedrock_embeddings", "cohere_rerank", "bedrock_rerank", "jina_rerank", "voyage_rerank", "general_rerank", "sarvam" ], "app_fields": { "detection": [ "category_actions", "category_scopes", "category_sensitivities", "custom_definitions", "data_risk_action", "edm_pattern_sensitivities", "enabled_categories", "guardian_agent", "hallucination_check_action", "hallucination_check_risk_level", "hallucination_check_score_threshold", "is_hallucination_check_enabled", "scan_encoded_images", "scan_encoded_images_scope", "scan_images", "scan_images_scope", "sub_category_actions", "sub_category_sensitivities" ], "limits": [ "concurrency_per_minute", "model_rate_limits", "rate_limit", "rate_limit_per_minute", "timeout", "token_limits" ], "routing": [ "custom_routing", "routing_groups", "routing_thresholds", "token_based_routing_groups" ], "access": [ "allowed_source_ips", "allowed_user_domains", "allowed_user_emails", "enforce_conversation_id", "enforce_identity", "identity_header_mode", "identity_token_headers", "identity_token_oid_fallback", "jwt_auth" ], "transformations": [ "token_saving" ], "self_service": [ "enable_self_service", "self_service" ], "prompts": [ "require_system_from_store" ] }, "app_top_level_fields": [ "access", "alerting", "detection", "enabled", "limits", "prompts", "provider_labels", "routing", "self_service", "smart_group_policies", "tags", "transformations" ], "modes": [ "gateway", "sdk", "copilot_studio" ], "policy_updates": false, "policy_authority": { "enabled": false, "active_revision": null, "active_checksum": null }, "writes_available": true, "configuration_propagation": "asynchronous", "model_tests_available": true, "model_test_provider_types": [ "anthropic", "anthropic_messages", "anthropic_messages_bedrock", "azureopenai", "bedrock", "deepseek", "general", "openai", "openai_responses", "openai_responses_azure", "oracle", "oracle_responses", "sarvam" ], "connection_test_provider_types": [], "provider_saves_call_upstream": false, "completely_no_gpu": false, "request_id": "req_example" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Tenant suspended or insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Missing resource or deployment disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Body read timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict or recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Stale resource version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Missing If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Management concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Central service, storage or operation recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Read capabilities", "tags": [ "Reference" ], "description": "Deployment support, exact app fields and supported provider/model tests. Fields are returned at the response root.", "x-scopes": [ "read" ] } }, "/llmgateway/management/v1/openapi.json": { "get": { "operationId": "Get_openapi", "security": [ { "ManagementKey": [] } ], "parameters": [], "responses": { "200": { "description": "Success", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "no-store" }, "X-Request-ID": { "schema": { "type": "string" }, "description": "Request correlation ID." } }, "content": { "application/json": { "schema": { "type": "object" }, "example": { "openapi": "3.1.0", "info": { "title": "LLM Gateway management", "version": "1.0.0" }, "paths": {}, "components": {} } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Tenant suspended or insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Missing resource or deployment disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Body read timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict or recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Stale resource version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Missing If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Management concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Central service, storage or operation recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Get openapi", "tags": [ "Reference" ], "description": "Backend-generated OpenAPI document. This endpoint requires read; the downloaded documentation reference adds descriptions and examples.", "x-scopes": [ "read" ] } }, "/llmgateway/management/v1/apps": { "get": { "operationId": "List_apps", "security": [ { "ManagementKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "example": 50 }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "example": "cursor-from-previous-page" }, { "name": "name", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Case-insensitive name substring." }, { "name": "tag", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Exact tag." }, { "name": "enabled", "in": "query", "required": false, "schema": { "type": "string" }, "description": "true or false." } ], "responses": { "200": { "description": "Success", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "no-store" }, "X-Request-ID": { "schema": { "type": "string" }, "description": "Request correlation ID." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AppView" } }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "request_id": { "type": "string" } }, "additionalProperties": true, "required": [ "items", "next_cursor", "request_id" ] }, "example": { "items": [ { "name": "Support Bot", "enabled": true, "mode": "gateway", "provider_labels": [ "Production OpenAI" ], "provider_mode": "shared", "version": "app-v1", "policy_authority": { "enabled": false, "active_revision": null, "active_checksum": null }, "tags": [ "production" ], "detection": { "enabled_categories": {}, "custom_definitions": [] }, "limits": {}, "routing": { "routing_groups": [], "token_based_routing_groups": [], "custom_routing": [] }, "access": {}, "transformations": {}, "self_service": {}, "prompts": {} } ], "next_cursor": null, "request_id": "req_example" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Tenant suspended or insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Missing resource or deployment disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Body read timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict or recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Stale resource version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Missing If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Management concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Central service, storage or operation recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "List apps", "tags": [ "Apps" ], "description": "Tenant app collection. Creation requires config:write and credentials:write and issues one gateway credential. Existing QuilrQL authority can publish app-specific model-access defaults.", "x-scopes": [ "read" ] }, "post": { "operationId": "Create_an_app", "security": [ { "ManagementKey": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "example": "unique-operation-001" } ], "responses": { "201": { "description": "Created", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "no-store" }, "X-Request-ID": { "schema": { "type": "string" }, "description": "Request correlation ID." }, "ETag": { "schema": { "type": "string" }, "description": "Quoted resource version. Lists expose per-resource versions in their metadata." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "app": { "$ref": "#/components/schemas/AppView" }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/Warning" } }, "request_id": { "type": "string" }, "key": { "$ref": "#/components/schemas/GatewayKey" }, "operation_id": { "type": "string" } }, "additionalProperties": true, "required": [ "app", "warnings", "request_id" ] }, "example": { "app": { "name": "Support Bot", "enabled": true, "mode": "gateway", "provider_labels": [ "Production OpenAI" ], "provider_mode": "shared", "version": "app-v1", "policy_authority": { "enabled": false, "active_revision": null, "active_checksum": null }, "tags": [ "production" ], "detection": { "enabled_categories": {}, "custom_definitions": [] }, "limits": {}, "routing": { "routing_groups": [], "token_based_routing_groups": [], "custom_routing": [] }, "access": {}, "transformations": {}, "self_service": {}, "prompts": {} }, "warnings": [], "key": { "key_id": "key_example", "name": "Default", "created_at": "2026-09-24T12:00:00Z", "expires_at": null, "status": "active", "fingerprint": "0123456789ab", "secret": "" }, "operation_id": "operation_example", "request_id": "req_example" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Tenant suspended or insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Missing resource or deployment disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Body read timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict or recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Stale resource version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Missing If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Management concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Central service, storage or operation recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppCreate" }, "example": { "name": "Support Bot", "provider_labels": [ "Production OpenAI" ], "tags": [ "production" ] } } } }, "summary": "Create an app", "tags": [ "Apps" ], "description": "Tenant app collection. Creation requires config:write and credentials:write and issues one gateway credential. Existing QuilrQL authority can publish app-specific model-access defaults.", "x-scopes": [ "config:write", "credentials:write" ] } }, "/llmgateway/management/v1/apps/{app_name}": { "get": { "operationId": "Read_an_app", "security": [ { "ManagementKey": [] } ], "parameters": [ { "name": "app_name", "in": "path", "required": true, "schema": { "type": "string" }, "example": "Support Bot" } ], "responses": { "200": { "description": "Success", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "no-store" }, "X-Request-ID": { "schema": { "type": "string" }, "description": "Request correlation ID." }, "ETag": { "schema": { "type": "string" }, "description": "Quoted resource version. Lists expose per-resource versions in their metadata." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "app": { "$ref": "#/components/schemas/AppView" }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/Warning" } }, "request_id": { "type": "string" } }, "additionalProperties": true, "required": [ "app", "warnings", "request_id" ] }, "example": { "app": { "name": "Support Bot", "enabled": true, "mode": "gateway", "provider_labels": [ "Production OpenAI" ], "provider_mode": "shared", "version": "app-v1", "policy_authority": { "enabled": false, "active_revision": null, "active_checksum": null }, "tags": [ "production" ], "detection": { "enabled_categories": {}, "custom_definitions": [] }, "limits": {}, "routing": { "routing_groups": [], "token_based_routing_groups": [], "custom_routing": [] }, "access": {}, "transformations": {}, "self_service": {}, "prompts": {} }, "warnings": [], "request_id": "req_example" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Tenant suspended or insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Missing resource or deployment disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Body read timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict or recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Stale resource version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Missing If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Management concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Central service, storage or operation recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Read an app", "tags": [ "Apps" ], "description": "Read or update stored settings. App enablement is enforced independently of QuilrQL.", "x-scopes": [ "read" ] }, "patch": { "operationId": "Update_or_disable_an_app", "security": [ { "ManagementKey": [] } ], "parameters": [ { "name": "app_name", "in": "path", "required": true, "schema": { "type": "string" }, "example": "Support Bot" }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Quoted ETag returned by the latest resource read. Prompt/attachment/rollback writes use the app ETag.", "example": "\"resource-version-from-read\"" } ], "responses": { "200": { "description": "Success", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "no-store" }, "X-Request-ID": { "schema": { "type": "string" }, "description": "Request correlation ID." }, "ETag": { "schema": { "type": "string" }, "description": "Quoted resource version. Lists expose per-resource versions in their metadata." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "app": { "$ref": "#/components/schemas/AppView" }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/Warning" } }, "request_id": { "type": "string" } }, "additionalProperties": true, "required": [ "app", "warnings", "request_id" ] }, "example": { "app": { "name": "Support Bot", "enabled": true, "mode": "gateway", "provider_labels": [ "Production OpenAI" ], "provider_mode": "shared", "version": "app-v1", "policy_authority": { "enabled": false, "active_revision": null, "active_checksum": null }, "tags": [ "production" ], "detection": { "enabled_categories": {}, "custom_definitions": [] }, "limits": {}, "routing": { "routing_groups": [], "token_based_routing_groups": [], "custom_routing": [] }, "access": {}, "transformations": {}, "self_service": {}, "prompts": {} }, "warnings": [], "request_id": "req_example" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Tenant suspended or insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Missing resource or deployment disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Body read timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict or recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Stale resource version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Missing If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Management concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Central service, storage or operation recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppPatch" }, "example": { "detection": { "data_risk_action": "redact" }, "limits": { "timeout": 30 } } } } }, "summary": "Update or disable an app", "tags": [ "Apps" ], "description": "Read or update stored settings. App enablement is enforced independently of QuilrQL.", "x-scopes": [ "config:write" ] } }, "/llmgateway/management/v1/providers": { "get": { "operationId": "List_shared_providers", "security": [ { "ManagementKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "example": 50 }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "example": "cursor-from-previous-page" } ], "responses": { "200": { "description": "Success", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "no-store" }, "X-Request-ID": { "schema": { "type": "string" }, "description": "Request correlation ID." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ProviderView" } }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "request_id": { "type": "string" } }, "additionalProperties": true, "required": [ "items", "next_cursor", "request_id" ] }, "example": { "items": [ { "provider_id": "provider_example", "label": "Production OpenAI", "provider_name": "openai", "selected_models": [ "gpt-4.1-mini" ], "model_costs": {}, "enabled": true, "is_active": true, "version": "provider-v1", "credential_configured": true, "connection": {} } ], "next_cursor": null, "request_id": "req_example" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Tenant suspended or insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Missing resource or deployment disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Body read timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict or recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Stale resource version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Missing If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Management concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Central service, storage or operation recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "List shared providers", "tags": [ "Providers" ], "description": "Tenant-scoped operation. Resource reads return redacted metadata; writes use the permissions and preconditions shown below.", "x-scopes": [ "read" ] }, "post": { "operationId": "Create_a_shared_provider", "security": [ { "ManagementKey": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "example": "unique-operation-001" } ], "responses": { "201": { "description": "Created", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "no-store" }, "X-Request-ID": { "schema": { "type": "string" }, "description": "Request correlation ID." }, "ETag": { "schema": { "type": "string" }, "description": "Quoted resource version. Lists expose per-resource versions in their metadata." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "provider": { "$ref": "#/components/schemas/ProviderView" }, "request_id": { "type": "string" } }, "additionalProperties": true, "required": [ "provider", "request_id" ] }, "example": { "provider": { "provider_id": "provider_example", "label": "Production OpenAI", "provider_name": "openai", "selected_models": [ "gpt-4.1-mini" ], "model_costs": {}, "enabled": true, "is_active": true, "version": "provider-v1", "credential_configured": true, "connection": {} }, "request_id": "req_example" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Tenant suspended or insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Missing resource or deployment disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Body read timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict or recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Stale resource version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Missing If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Management concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Central service, storage or operation recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderCreate" }, "example": { "label": "Production OpenAI", "provider_name": "openai", "provider_settings": { "api_key": "" }, "selected_models": [ "gpt-4.1-mini" ] } } } }, "summary": "Create a shared provider", "tags": [ "Providers" ], "description": "Tenant-scoped operation. Resource reads return redacted metadata; writes use the permissions and preconditions shown below.", "x-scopes": [ "providers:write" ] } }, "/llmgateway/management/v1/providers/{label}": { "get": { "operationId": "Read_a_shared_provider", "security": [ { "ManagementKey": [] } ], "parameters": [ { "name": "label", "in": "path", "required": true, "schema": { "type": "string" }, "example": "Production OpenAI" } ], "responses": { "200": { "description": "Success", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "no-store" }, "X-Request-ID": { "schema": { "type": "string" }, "description": "Request correlation ID." }, "ETag": { "schema": { "type": "string" }, "description": "Quoted resource version. Lists expose per-resource versions in their metadata." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "provider": { "$ref": "#/components/schemas/ProviderView" }, "request_id": { "type": "string" } }, "additionalProperties": true, "required": [ "provider", "request_id" ] }, "example": { "provider": { "provider_id": "provider_example", "label": "Production OpenAI", "provider_name": "openai", "selected_models": [ "gpt-4.1-mini" ], "model_costs": {}, "enabled": true, "is_active": true, "version": "provider-v1", "credential_configured": true, "connection": {} }, "request_id": "req_example" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Tenant suspended or insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Missing resource or deployment disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Body read timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict or recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Stale resource version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Missing If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Management concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Central service, storage or operation recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Read a shared provider", "tags": [ "Providers" ], "description": "Tenant-scoped operation. Resource reads return redacted metadata; writes use the permissions and preconditions shown below.", "x-scopes": [ "read" ] }, "patch": { "operationId": "Update_or_disable_a_provider", "security": [ { "ManagementKey": [] } ], "parameters": [ { "name": "label", "in": "path", "required": true, "schema": { "type": "string" }, "example": "Production OpenAI" }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Quoted ETag returned by the latest resource read. Prompt/attachment/rollback writes use the app ETag.", "example": "\"resource-version-from-read\"" } ], "responses": { "200": { "description": "Success", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "no-store" }, "X-Request-ID": { "schema": { "type": "string" }, "description": "Request correlation ID." }, "ETag": { "schema": { "type": "string" }, "description": "Quoted resource version. Lists expose per-resource versions in their metadata." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "provider": { "$ref": "#/components/schemas/ProviderView" }, "request_id": { "type": "string" } }, "additionalProperties": true, "required": [ "provider", "request_id" ] }, "example": { "provider": { "provider_id": "provider_example", "label": "Production OpenAI", "provider_name": "openai", "selected_models": [ "gpt-4.1-mini" ], "model_costs": {}, "enabled": true, "is_active": true, "version": "provider-v1", "credential_configured": true, "connection": {} }, "request_id": "req_example" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Tenant suspended or insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Missing resource or deployment disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Body read timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict or recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Stale resource version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Missing If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Management concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Central service, storage or operation recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderPatch" }, "example": { "enabled": false } } } }, "summary": "Update or disable a provider", "tags": [ "Providers" ], "description": "Tenant-scoped operation. Resource reads return redacted metadata; writes use the permissions and preconditions shown below.", "x-scopes": [ "providers:write" ] } }, "/llmgateway/management/v1/providers/{label}/test": { "post": { "operationId": "Test_connection_or_model", "security": [ { "ManagementKey": [] } ], "parameters": [ { "name": "label", "in": "path", "required": true, "schema": { "type": "string" }, "example": "Production OpenAI" } ], "responses": { "200": { "description": "Success", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "no-store" }, "X-Request-ID": { "schema": { "type": "string" }, "description": "Request correlation ID." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "test": { "type": "object", "properties": { "configuration_version": { "type": "string" }, "kind": { "type": "string" }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "outcome": { "type": "string", "enum": [ "passed", "failed", "unsupported" ] }, "code": { "type": "string" }, "latency_ms": { "type": "number" }, "completed_at": { "type": "number", "description": "Unix epoch seconds, potentially fractional." } }, "additionalProperties": true, "required": [ "configuration_version", "kind", "outcome", "code", "completed_at" ] }, "request_id": { "type": "string" } }, "additionalProperties": true, "required": [ "test", "request_id" ] }, "example": { "test": { "configuration_version": "provider-v1", "kind": "model", "model": "gpt-4.1-mini", "outcome": "passed", "code": "probe_passed", "latency_ms": 320.0, "completed_at": 1790251200.0 }, "request_id": "req_example" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Tenant suspended or insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Missing resource or deployment disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Body read timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict or recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Stale resource version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Missing If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Management concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Central service, storage or operation recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderTest" }, "example": { "kind": "model", "model": "gpt-4.1-mini" } } } }, "summary": "Test connection or model", "tags": [ "Providers" ], "description": "Stored configuration only. Connection tests return unsupported_test_kind. Model tests are limited to model_test_provider_types from capabilities and are disabled under COMPLETELY_NO_GPU. Connection-only testing is Not Generally Available.", "x-scopes": [ "providers:write" ] } }, "/llmgateway/management/v1/apps/{app_name}/providers": { "get": { "operationId": "List_app_providers", "security": [ { "ManagementKey": [] } ], "parameters": [ { "name": "app_name", "in": "path", "required": true, "schema": { "type": "string" }, "example": "Support Bot" } ], "responses": { "200": { "description": "Success", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "no-store" }, "X-Request-ID": { "schema": { "type": "string" }, "description": "Request correlation ID." }, "ETag": { "schema": { "type": "string" }, "description": "Quoted resource version. Lists expose per-resource versions in their metadata." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "provider_labels": { "type": "array", "items": { "type": "string" } }, "version": { "type": "string", "description": "Opaque resource version. Send its quoted value in If-Match." }, "request_id": { "type": "string" } }, "additionalProperties": true, "required": [ "provider_labels", "version", "request_id" ] }, "example": { "provider_labels": [ "Production OpenAI" ], "version": "app-v1", "request_id": "req_example" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Tenant suspended or insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Missing resource or deployment disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Body read timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict or recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Stale resource version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Missing If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Management concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Central service, storage or operation recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "List app providers", "tags": [ "Apps" ], "description": "Returns ordered provider_labels and the app version, not a paginated provider collection.", "x-scopes": [ "read" ] } }, "/llmgateway/management/v1/apps/{app_name}/providers/{label}": { "put": { "operationId": "Attach_a_shared_provider", "security": [ { "ManagementKey": [] } ], "parameters": [ { "name": "app_name", "in": "path", "required": true, "schema": { "type": "string" }, "example": "Support Bot" }, { "name": "label", "in": "path", "required": true, "schema": { "type": "string" }, "example": "Production OpenAI" }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Quoted ETag returned by the latest resource read. Prompt/attachment/rollback writes use the app ETag.", "example": "\"resource-version-from-read\"" } ], "responses": { "200": { "description": "Success", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "no-store" }, "X-Request-ID": { "schema": { "type": "string" }, "description": "Request correlation ID." }, "ETag": { "schema": { "type": "string" }, "description": "Quoted resource version. Lists expose per-resource versions in their metadata." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "app": { "$ref": "#/components/schemas/AppView" }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/Warning" } }, "request_id": { "type": "string" } }, "additionalProperties": true, "required": [ "app", "warnings", "request_id" ] }, "example": { "app": { "name": "Support Bot", "enabled": true, "mode": "gateway", "provider_labels": [ "Production OpenAI" ], "provider_mode": "shared", "version": "app-v1", "policy_authority": { "enabled": false, "active_revision": null, "active_checksum": null }, "tags": [ "production" ], "detection": { "enabled_categories": {}, "custom_definitions": [] }, "limits": {}, "routing": { "routing_groups": [], "token_based_routing_groups": [], "custom_routing": [] }, "access": {}, "transformations": {}, "self_service": {}, "prompts": {} }, "warnings": [], "request_id": "req_example" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Tenant suspended or insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Missing resource or deployment disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Body read timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict or recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Stale resource version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Missing If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Management concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Central service, storage or operation recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Attachment" }, "example": { "primary": false } } } }, "summary": "Attach a shared provider", "tags": [ "Apps" ], "description": "Use the current app ETag. PUT preserves unrelated attachments; DELETE validates remaining routes. Provider removal while QuilrQL is enabled returns policy_dependency.", "x-scopes": [ "config:write" ] }, "delete": { "operationId": "Detach_an_app_provider", "security": [ { "ManagementKey": [] } ], "parameters": [ { "name": "app_name", "in": "path", "required": true, "schema": { "type": "string" }, "example": "Support Bot" }, { "name": "label", "in": "path", "required": true, "schema": { "type": "string" }, "example": "Production OpenAI" }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Quoted ETag returned by the latest resource read. Prompt/attachment/rollback writes use the app ETag.", "example": "\"resource-version-from-read\"" } ], "responses": { "200": { "description": "Success", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "no-store" }, "X-Request-ID": { "schema": { "type": "string" }, "description": "Request correlation ID." }, "ETag": { "schema": { "type": "string" }, "description": "Quoted resource version. Lists expose per-resource versions in their metadata." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "app": { "$ref": "#/components/schemas/AppView" }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/Warning" } }, "request_id": { "type": "string" } }, "additionalProperties": true, "required": [ "app", "warnings", "request_id" ] }, "example": { "app": { "name": "Support Bot", "enabled": true, "mode": "gateway", "provider_labels": [ "Production OpenAI" ], "provider_mode": "shared", "version": "app-v1", "policy_authority": { "enabled": false, "active_revision": null, "active_checksum": null }, "tags": [ "production" ], "detection": { "enabled_categories": {}, "custom_definitions": [] }, "limits": {}, "routing": { "routing_groups": [], "token_based_routing_groups": [], "custom_routing": [] }, "access": {}, "transformations": {}, "self_service": {}, "prompts": {} }, "warnings": [], "request_id": "req_example" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Tenant suspended or insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Missing resource or deployment disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Body read timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict or recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Stale resource version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Missing If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Management concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Central service, storage or operation recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" }, "example": {} } } }, "summary": "Detach an app provider", "tags": [ "Apps" ], "description": "Use the current app ETag. PUT preserves unrelated attachments; DELETE validates remaining routes. Provider removal while QuilrQL is enabled returns policy_dependency.", "x-scopes": [ "config:write" ] } }, "/llmgateway/management/v1/apps/{app_name}/provider-conversion": { "post": { "operationId": "Convert_inline_providers", "security": [ { "ManagementKey": [] } ], "parameters": [ { "name": "app_name", "in": "path", "required": true, "schema": { "type": "string" }, "example": "Support Bot" }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Quoted ETag returned by the latest resource read. Prompt/attachment/rollback writes use the app ETag.", "example": "\"resource-version-from-read\"" } ], "responses": { "200": { "description": "Success", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "no-store" }, "X-Request-ID": { "schema": { "type": "string" }, "description": "Request correlation ID." }, "ETag": { "schema": { "type": "string" }, "description": "Quoted resource version. Lists expose per-resource versions in their metadata." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "app": { "$ref": "#/components/schemas/AppView" }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/Warning" } }, "request_id": { "type": "string" } }, "additionalProperties": true, "required": [ "app", "warnings", "request_id" ] }, "example": { "app": { "name": "Support Bot", "enabled": true, "mode": "gateway", "provider_labels": [ "Production OpenAI" ], "provider_mode": "shared", "version": "app-v1", "policy_authority": { "enabled": false, "active_revision": null, "active_checksum": null }, "tags": [ "production" ], "detection": { "enabled_categories": {}, "custom_definitions": [] }, "limits": {}, "routing": { "routing_groups": [], "token_based_routing_groups": [], "custom_routing": [] }, "access": {}, "transformations": {}, "self_service": {}, "prompts": {} }, "warnings": [], "request_id": "req_example" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Tenant suspended or insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Missing resource or deployment disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Body read timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict or recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Stale resource version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Missing If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Management concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Central service, storage or operation recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conversion" }, "example": { "provider_labels": [ "Production OpenAI" ] } } } }, "summary": "Convert inline providers", "tags": [ "Apps" ], "description": "Convert an inline app using a complete shared-provider selection. Uses the app ETag; no idempotency replay contract.", "x-scopes": [ "config:write" ] } }, "/llmgateway/management/v1/apps/{app_name}/keys": { "get": { "operationId": "List_gateway_credentials", "security": [ { "ManagementKey": [] } ], "parameters": [ { "name": "app_name", "in": "path", "required": true, "schema": { "type": "string" }, "example": "Support Bot" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "example": 50 }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "example": "cursor-from-previous-page" } ], "responses": { "200": { "description": "Success", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "no-store" }, "X-Request-ID": { "schema": { "type": "string" }, "description": "Request correlation ID." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/GatewayKey" } }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "request_id": { "type": "string" } }, "additionalProperties": true, "required": [ "items", "next_cursor", "request_id" ] }, "example": { "items": [ { "key_id": "key_example", "name": "Default", "created_at": "2026-09-24T12:00:00Z", "expires_at": null, "status": "active", "fingerprint": "0123456789ab" } ], "next_cursor": null, "request_id": "req_example" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Tenant suspended or insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Missing resource or deployment disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Body read timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict or recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Stale resource version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Missing If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Management concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Central service, storage or operation recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "List gateway credentials", "tags": [ "Credentials" ], "description": "Tenant-scoped operation. Resource reads return redacted metadata; writes use the permissions and preconditions shown below.", "x-scopes": [ "read" ] }, "post": { "operationId": "Issue_a_gateway_credential", "security": [ { "ManagementKey": [] } ], "parameters": [ { "name": "app_name", "in": "path", "required": true, "schema": { "type": "string" }, "example": "Support Bot" }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "example": "unique-operation-001" } ], "responses": { "201": { "description": "Created", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "no-store" }, "X-Request-ID": { "schema": { "type": "string" }, "description": "Request correlation ID." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "$ref": "#/components/schemas/GatewayKey" }, "request_id": { "type": "string" }, "operation_id": { "type": "string" } }, "additionalProperties": true, "required": [ "key", "request_id" ] }, "example": { "key": { "key_id": "key_example", "name": "Default", "created_at": "2026-09-24T12:00:00Z", "expires_at": null, "status": "active", "fingerprint": "0123456789ab", "secret": "" }, "operation_id": "operation_example", "request_id": "req_example" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Tenant suspended or insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Missing resource or deployment disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Body read timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict or recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Stale resource version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Missing If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Management concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Central service, storage or operation recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayKeyCreate" }, "example": { "name": "Deployment", "expires_at": null } } } }, "summary": "Issue a gateway credential", "tags": [ "Credentials" ], "description": "Tenant-scoped operation. Resource reads return redacted metadata; writes use the permissions and preconditions shown below.", "x-scopes": [ "credentials:write" ] } }, "/llmgateway/management/v1/apps/{app_name}/keys/{key_id}": { "get": { "operationId": "Get_key", "security": [ { "ManagementKey": [] } ], "parameters": [ { "name": "app_name", "in": "path", "required": true, "schema": { "type": "string" }, "example": "Support Bot" }, { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "key_example" } ], "responses": { "200": { "description": "Success", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "no-store" }, "X-Request-ID": { "schema": { "type": "string" }, "description": "Request correlation ID." }, "ETag": { "schema": { "type": "string" }, "description": "Quoted resource version. Lists expose per-resource versions in their metadata." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "$ref": "#/components/schemas/GatewayKey" }, "request_id": { "type": "string" }, "version": { "type": "string", "description": "Opaque resource version. Send its quoted value in If-Match." } }, "additionalProperties": true, "required": [ "key", "request_id" ] }, "example": { "key": { "key_id": "key_example", "name": "Default", "created_at": "2026-09-24T12:00:00Z", "expires_at": null, "status": "active", "fingerprint": "0123456789ab" }, "version": "key-v1", "request_id": "req_example" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Tenant suspended or insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Missing resource or deployment disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Body read timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict or recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Stale resource version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Missing If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Management concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Central service, storage or operation recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Get key", "tags": [ "Credentials" ], "description": "Tenant-scoped operation. Resource reads return redacted metadata; writes use the permissions and preconditions shown below.", "x-scopes": [ "read" ] }, "patch": { "operationId": "Change_gateway_key_expiry", "security": [ { "ManagementKey": [] } ], "parameters": [ { "name": "app_name", "in": "path", "required": true, "schema": { "type": "string" }, "example": "Support Bot" }, { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "key_example" }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Quoted ETag returned by the latest resource read. Prompt/attachment/rollback writes use the app ETag.", "example": "\"resource-version-from-read\"" } ], "responses": { "200": { "description": "Success", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "no-store" }, "X-Request-ID": { "schema": { "type": "string" }, "description": "Request correlation ID." }, "ETag": { "schema": { "type": "string" }, "description": "Quoted resource version. Lists expose per-resource versions in their metadata." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "$ref": "#/components/schemas/GatewayKey" }, "request_id": { "type": "string" }, "version": { "type": "string", "description": "Opaque resource version. Send its quoted value in If-Match." } }, "additionalProperties": true, "required": [ "key", "request_id" ] }, "example": { "key": { "key_id": "key_example", "name": "Default", "created_at": "2026-09-24T12:00:00Z", "expires_at": null, "status": "active", "fingerprint": "0123456789ab" }, "version": "key-v1", "request_id": "req_example" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Tenant suspended or insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Missing resource or deployment disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Body read timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict or recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Stale resource version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Missing If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Management concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Central service, storage or operation recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayKeyPatch" }, "example": { "expires_at": null } } } }, "summary": "Change gateway key expiry", "tags": [ "Credentials" ], "description": "Tenant-scoped operation. Resource reads return redacted metadata; writes use the permissions and preconditions shown below.", "x-scopes": [ "credentials:write" ] }, "delete": { "operationId": "Revoke_a_gateway_credential", "security": [ { "ManagementKey": [] } ], "parameters": [ { "name": "app_name", "in": "path", "required": true, "schema": { "type": "string" }, "example": "Support Bot" }, { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "key_example" }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Quoted ETag returned by the latest resource read. Prompt/attachment/rollback writes use the app ETag.", "example": "\"resource-version-from-read\"" } ], "responses": { "200": { "description": "Success", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "no-store" }, "X-Request-ID": { "schema": { "type": "string" }, "description": "Request correlation ID." }, "ETag": { "schema": { "type": "string" }, "description": "Quoted resource version. Lists expose per-resource versions in their metadata." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "$ref": "#/components/schemas/GatewayKey" }, "request_id": { "type": "string" }, "version": { "type": "string", "description": "Opaque resource version. Send its quoted value in If-Match." } }, "additionalProperties": true, "required": [ "key", "request_id" ] }, "example": { "key": { "key_id": "key_example", "name": "Default", "created_at": "2026-09-24T12:00:00Z", "expires_at": null, "status": "revoked", "fingerprint": "0123456789ab" }, "version": "key-v1", "request_id": "req_example" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Tenant suspended or insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Missing resource or deployment disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Body read timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict or recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Stale resource version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Missing If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Management concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Central service, storage or operation recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" }, "example": {} } } }, "summary": "Revoke a gateway credential", "tags": [ "Credentials" ], "description": "Tenant-scoped operation. Resource reads return redacted metadata; writes use the permissions and preconditions shown below.", "x-scopes": [ "credentials:write" ] } }, "/llmgateway/management/v1/apps/{app_name}/keys/{key_id}/reveal": { "post": { "operationId": "Reveal_a_gateway_credential", "security": [ { "ManagementKey": [] } ], "parameters": [ { "name": "app_name", "in": "path", "required": true, "schema": { "type": "string" }, "example": "Support Bot" }, { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "key_example" } ], "responses": { "200": { "description": "Success", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "no-store" }, "X-Request-ID": { "schema": { "type": "string" }, "description": "Request correlation ID." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "$ref": "#/components/schemas/GatewayKey" }, "request_id": { "type": "string" } }, "additionalProperties": true, "required": [ "key", "request_id" ] }, "example": { "key": { "key_id": "key_example", "name": "Default", "created_at": "2026-09-24T12:00:00Z", "expires_at": null, "status": "active", "fingerprint": "0123456789ab", "secret": "" }, "request_id": "req_example" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Tenant suspended or insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Missing resource or deployment disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Body read timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict or recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Stale resource version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Missing If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Management concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Central service, storage or operation recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" }, "example": {} } } }, "summary": "Reveal a gateway credential", "tags": [ "Credentials" ], "description": "Explicitly reveal an active gateway credential. Expired/revoked credentials return terminal_key_state.", "x-scopes": [ "credentials:read" ] } }, "/llmgateway/management/v1/apps/{app_name}/prompts": { "get": { "operationId": "List_prompts", "security": [ { "ManagementKey": [] } ], "parameters": [ { "name": "app_name", "in": "path", "required": true, "schema": { "type": "string" }, "example": "Support Bot" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "example": 50 }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "example": "cursor-from-previous-page" } ], "responses": { "200": { "description": "Success", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "no-store" }, "X-Request-ID": { "schema": { "type": "string" }, "description": "Request correlation ID." }, "ETag": { "schema": { "type": "string" }, "description": "Quoted resource version. Lists expose per-resource versions in their metadata." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "prompt_id": { "type": "string" }, "content": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "additionalProperties": true } }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "request_id": { "type": "string" }, "version": { "type": "string", "description": "Opaque resource version. Send its quoted value in If-Match." } }, "additionalProperties": true, "required": [ "items", "next_cursor", "request_id" ] }, "example": { "items": [], "next_cursor": null, "version": "app-v1", "request_id": "req_example" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Tenant suspended or insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Missing resource or deployment disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Body read timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict or recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Stale resource version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Missing If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Management concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Central service, storage or operation recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "List prompts", "tags": [ "Prompts" ], "description": "Tenant-scoped operation. Resource reads return redacted metadata; writes use the permissions and preconditions shown below.", "x-scopes": [ "read" ] } }, "/llmgateway/management/v1/apps/{app_name}/prompts/{prompt_id}": { "get": { "operationId": "Read_a_prompt", "security": [ { "ManagementKey": [] } ], "parameters": [ { "name": "app_name", "in": "path", "required": true, "schema": { "type": "string" }, "example": "Support Bot" }, { "name": "prompt_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "support" } ], "responses": { "200": { "description": "Success", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "no-store" }, "X-Request-ID": { "schema": { "type": "string" }, "description": "Request correlation ID." }, "ETag": { "schema": { "type": "string" }, "description": "Quoted resource version. Lists expose per-resource versions in their metadata." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt_id": { "type": "string" }, "prompt": { "anyOf": [ { "type": "object" }, { "type": "null" } ] }, "version": { "type": "string", "description": "Opaque resource version. Send its quoted value in If-Match." }, "request_id": { "type": "string" } }, "additionalProperties": true, "required": [ "prompt_id", "prompt", "version", "request_id" ] }, "example": { "prompt_id": "support", "prompt": { "content": "You help customers with support questions.", "created_at": "2026-09-24T12:00:00+00:00", "updated_at": "2026-09-24T12:00:00+00:00" }, "version": "app-v1", "request_id": "req_example" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Tenant suspended or insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Missing resource or deployment disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Body read timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict or recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Stale resource version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Missing If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Management concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Central service, storage or operation recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Read a prompt", "tags": [ "Prompts" ], "description": "Use the current app ETag for every mutation, including creation. PUT creates or replaces; If-None-Match is not a create-only guard.", "x-scopes": [ "read" ] }, "put": { "operationId": "Create_or_replace_a_prompt", "security": [ { "ManagementKey": [] } ], "parameters": [ { "name": "app_name", "in": "path", "required": true, "schema": { "type": "string" }, "example": "Support Bot" }, { "name": "prompt_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "support" }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Quoted ETag returned by the latest resource read. Prompt/attachment/rollback writes use the app ETag.", "example": "\"resource-version-from-read\"" } ], "responses": { "200": { "description": "Success", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "no-store" }, "X-Request-ID": { "schema": { "type": "string" }, "description": "Request correlation ID." }, "ETag": { "schema": { "type": "string" }, "description": "Quoted resource version. Lists expose per-resource versions in their metadata." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt_id": { "type": "string" }, "prompt": { "anyOf": [ { "type": "object" }, { "type": "null" } ] }, "version": { "type": "string", "description": "Opaque resource version. Send its quoted value in If-Match." }, "request_id": { "type": "string" } }, "additionalProperties": true, "required": [ "prompt_id", "prompt", "version", "request_id" ] }, "example": { "prompt_id": "support", "prompt": { "content": "You help customers with support questions.", "created_at": "2026-09-24T12:00:00+00:00", "updated_at": "2026-09-24T12:00:00+00:00" }, "version": "app-v1", "request_id": "req_example" } } } }, "201": { "description": "Prompt created; 200 means replaced.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "no-store" }, "X-Request-ID": { "schema": { "type": "string" }, "description": "Request correlation ID." }, "ETag": { "schema": { "type": "string" }, "description": "Quoted resource version. Lists expose per-resource versions in their metadata." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt_id": { "type": "string" }, "prompt": { "anyOf": [ { "type": "object" }, { "type": "null" } ] }, "version": { "type": "string", "description": "Opaque resource version. Send its quoted value in If-Match." }, "request_id": { "type": "string" } }, "additionalProperties": true, "required": [ "prompt_id", "prompt", "version", "request_id" ] }, "example": { "prompt_id": "support", "prompt": { "content": "You help customers with support questions.", "created_at": "2026-09-24T12:00:00+00:00", "updated_at": "2026-09-24T12:00:00+00:00" }, "version": "app-v1", "request_id": "req_example" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Tenant suspended or insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Missing resource or deployment disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Body read timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict or recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Stale resource version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Missing If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Management concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Central service, storage or operation recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Prompt" }, "example": { "content": "You help customers with support questions." } } } }, "summary": "Create or replace a prompt", "tags": [ "Prompts" ], "description": "Use the current app ETag for every mutation, including creation. PUT creates or replaces; If-None-Match is not a create-only guard.", "x-scopes": [ "config:write" ] }, "delete": { "operationId": "Delete_a_prompt", "security": [ { "ManagementKey": [] } ], "parameters": [ { "name": "app_name", "in": "path", "required": true, "schema": { "type": "string" }, "example": "Support Bot" }, { "name": "prompt_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "support" }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Quoted ETag returned by the latest resource read. Prompt/attachment/rollback writes use the app ETag.", "example": "\"resource-version-from-read\"" } ], "responses": { "200": { "description": "Success", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "no-store" }, "X-Request-ID": { "schema": { "type": "string" }, "description": "Request correlation ID." }, "ETag": { "schema": { "type": "string" }, "description": "Quoted resource version. Lists expose per-resource versions in their metadata." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt_id": { "type": "string" }, "prompt": { "anyOf": [ { "type": "object" }, { "type": "null" } ] }, "version": { "type": "string", "description": "Opaque resource version. Send its quoted value in If-Match." }, "request_id": { "type": "string" } }, "additionalProperties": true, "required": [ "prompt_id", "prompt", "version", "request_id" ] }, "example": { "prompt_id": "support", "prompt": null, "version": "app-v1", "request_id": "req_example" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Tenant suspended or insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Missing resource or deployment disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Body read timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict or recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Stale resource version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Missing If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Management concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Central service, storage or operation recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" }, "example": {} } } }, "summary": "Delete a prompt", "tags": [ "Prompts" ], "description": "Use the current app ETag for every mutation, including creation. PUT creates or replaces; If-None-Match is not a create-only guard.", "x-scopes": [ "config:write" ] } }, "/llmgateway/management/v1/apps/{app_name}/versions": { "get": { "operationId": "List_app_configuration_versions", "security": [ { "ManagementKey": [] } ], "parameters": [ { "name": "app_name", "in": "path", "required": true, "schema": { "type": "string" }, "example": "Support Bot" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "example": 50 }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "example": "cursor-from-previous-page" } ], "responses": { "200": { "description": "Success", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "no-store" }, "X-Request-ID": { "schema": { "type": "string" }, "description": "Request correlation ID." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/VersionRecord" } }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "request_id": { "type": "string" } }, "additionalProperties": true, "required": [ "items", "next_cursor", "request_id" ] }, "example": { "items": [], "next_cursor": null, "request_id": "req_example" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Tenant suspended or insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Missing resource or deployment disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Body read timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict or recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Stale resource version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Missing If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Management concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Central service, storage or operation recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "List app configuration versions", "tags": [ "History" ], "description": "Tenant-scoped operation. Resource reads return redacted metadata; writes use the permissions and preconditions shown below.", "x-scopes": [ "read" ] } }, "/llmgateway/management/v1/apps/{app_name}/versions/{version_id}": { "get": { "operationId": "Read_a_configuration_version", "security": [ { "ManagementKey": [] } ], "parameters": [ { "name": "app_name", "in": "path", "required": true, "schema": { "type": "string" }, "example": "Support Bot" }, { "name": "version_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "version_example" } ], "responses": { "200": { "description": "Success", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "no-store" }, "X-Request-ID": { "schema": { "type": "string" }, "description": "Request correlation ID." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "version_record": { "$ref": "#/components/schemas/VersionRecord" }, "request_id": { "type": "string" } }, "additionalProperties": true, "required": [ "version_record", "request_id" ] }, "example": { "version_record": { "version_id": "version_example", "version": 1, "changed_at": "2026-09-24T12:00:00Z", "operation": "management_update", "actor_type": "management_key", "actor_user_id": "management_key_example", "actor_email": null, "previous_config": {}, "new_config": {} }, "request_id": "req_example" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Tenant suspended or insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Missing resource or deployment disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Body read timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict or recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Stale resource version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Missing If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Management concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Central service, storage or operation recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Read a configuration version", "tags": [ "History" ], "description": "Tenant-scoped operation. Resource reads return redacted metadata; writes use the permissions and preconditions shown below.", "x-scopes": [ "read" ] } }, "/llmgateway/management/v1/apps/{app_name}/versions/{version_id}/rollback": { "post": { "operationId": "Roll_back_app_configuration", "security": [ { "ManagementKey": [] } ], "parameters": [ { "name": "app_name", "in": "path", "required": true, "schema": { "type": "string" }, "example": "Support Bot" }, { "name": "version_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "version_example" }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Quoted ETag returned by the latest resource read. Prompt/attachment/rollback writes use the app ETag.", "example": "\"resource-version-from-read\"" }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "example": "unique-operation-001" } ], "responses": { "200": { "description": "Success", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "no-store" }, "X-Request-ID": { "schema": { "type": "string" }, "description": "Request correlation ID." }, "ETag": { "schema": { "type": "string" }, "description": "Quoted resource version. Lists expose per-resource versions in their metadata." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "app": { "$ref": "#/components/schemas/AppView" }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/Warning" } }, "request_id": { "type": "string" } }, "additionalProperties": true, "required": [ "app", "warnings", "request_id" ] }, "example": { "app": { "name": "Support Bot", "enabled": true, "mode": "gateway", "provider_labels": [ "Production OpenAI" ], "provider_mode": "shared", "version": "app-v1", "policy_authority": { "enabled": false, "active_revision": null, "active_checksum": null }, "tags": [ "production" ], "detection": { "enabled_categories": {}, "custom_definitions": [] }, "limits": {}, "routing": { "routing_groups": [], "token_based_routing_groups": [], "custom_routing": [] }, "access": {}, "transformations": {}, "self_service": {}, "prompts": {} }, "warnings": [], "request_id": "req_example" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Tenant suspended or insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Missing resource or deployment disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Body read timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict or recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Stale resource version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Missing If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Management concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Central service, storage or operation recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" }, "example": {} } } }, "summary": "Roll back app configuration", "tags": [ "History" ], "description": "Restricted app configuration rollback; no policy rollback. Requires the current app ETag and Idempotency-Key.", "x-scopes": [ "config:write" ] } }, "/llmgateway/management/v1/smart-groups": { "get": { "operationId": "List_smart_groups", "security": [ { "ManagementKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "example": 50 }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "example": "cursor-from-previous-page" } ], "responses": { "200": { "description": "Success", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "no-store" }, "X-Request-ID": { "schema": { "type": "string" }, "description": "Request correlation ID." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object" } }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "request_id": { "type": "string" } }, "additionalProperties": true, "required": [ "items", "next_cursor", "request_id" ] }, "example": { "items": [], "next_cursor": null, "request_id": "req_example" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Tenant suspended or insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Missing resource or deployment disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Body read timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict or recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Stale resource version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Missing If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Management concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Central service, storage or operation recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "List smart groups", "tags": [ "Catalogs" ], "description": "Tenant-scoped operation. Resource reads return redacted metadata; writes use the permissions and preconditions shown below.", "x-scopes": [ "read" ] } }, "/llmgateway/management/v1/smart-groups/{group_name}": { "get": { "operationId": "Read_a_smart_group", "security": [ { "ManagementKey": [] } ], "parameters": [ { "name": "group_name", "in": "path", "required": true, "schema": { "type": "string" }, "example": "engineering" } ], "responses": { "200": { "description": "Success", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "no-store" }, "X-Request-ID": { "schema": { "type": "string" }, "description": "Request correlation ID." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "smart_group": { "type": "object" }, "request_id": { "type": "string" } }, "additionalProperties": true, "required": [ "smart_group", "request_id" ] }, "example": { "smart_group": { "group_name": "engineering" }, "request_id": "req_example" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Tenant suspended or insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Missing resource or deployment disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Body read timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict or recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Stale resource version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Missing If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Management concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Central service, storage or operation recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Read a smart group", "tags": [ "Catalogs" ], "description": "Tenant-scoped operation. Resource reads return redacted metadata; writes use the permissions and preconditions shown below.", "x-scopes": [ "read" ] } }, "/llmgateway/management/v1/custom-definitions": { "get": { "operationId": "List_custom_definitions", "security": [ { "ManagementKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "example": 50 }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "example": "cursor-from-previous-page" } ], "responses": { "200": { "description": "Success", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "no-store" }, "X-Request-ID": { "schema": { "type": "string" }, "description": "Request correlation ID." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object" } }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "request_id": { "type": "string" } }, "additionalProperties": true, "required": [ "items", "next_cursor", "request_id" ] }, "example": { "items": [], "next_cursor": null, "request_id": "req_example" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Tenant suspended or insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Missing resource or deployment disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Body read timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict or recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Stale resource version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Missing If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Management concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Central service, storage or operation recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "List custom definitions", "tags": [ "Catalogs" ], "description": "Tenant-scoped operation. Resource reads return redacted metadata; writes use the permissions and preconditions shown below.", "x-scopes": [ "read" ] } }, "/llmgateway/management/v1/custom-definitions/{definition_id}": { "get": { "operationId": "Read_a_custom_definition", "security": [ { "ManagementKey": [] } ], "parameters": [ { "name": "definition_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "employee_id" } ], "responses": { "200": { "description": "Success", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "no-store" }, "X-Request-ID": { "schema": { "type": "string" }, "description": "Request correlation ID." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "definition": { "type": "object" }, "request_id": { "type": "string" } }, "additionalProperties": true, "required": [ "definition", "request_id" ] }, "example": { "definition": { "reference": "employee_id", "edm_id": "employee_id", "display_name": "Employee ID", "name": "Employee ID", "type": "precision", "enabled": true, "globally_enabled": true }, "request_id": "req_example" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Tenant suspended or insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Missing resource or deployment disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Body read timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict or recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Stale resource version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Missing If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Management concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Central service, storage or operation recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Read a custom definition", "tags": [ "Catalogs" ], "description": "Tenant-scoped operation. Resource reads return redacted metadata; writes use the permissions and preconditions shown below.", "x-scopes": [ "read" ] } }, "/llmgateway/management/v1/audit": { "get": { "operationId": "Get_audit", "security": [ { "ManagementKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "example": 50 }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "example": "cursor-from-previous-page" } ], "responses": { "200": { "description": "Success", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "no-store" }, "X-Request-ID": { "schema": { "type": "string" }, "description": "Request correlation ID." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AuditEvent" } }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "request_id": { "type": "string" } }, "additionalProperties": true, "required": [ "items", "next_cursor", "request_id" ] }, "example": { "items": [], "next_cursor": null, "request_id": "req_example" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Tenant suspended or insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Missing resource or deployment disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Body read timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict or recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Stale resource version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Missing If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Management concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Central service, storage or operation recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Get audit", "tags": [ "History" ], "description": "Tenant management events, including actor, resource, result and created_at in Unix seconds. Only limit/cursor are supported; no app/key/time filters.", "x-scopes": [ "read" ] } }, "/llmgateway/management/v1/operations/{operation_id}": { "get": { "operationId": "Get_operation", "security": [ { "ManagementKey": [] } ], "parameters": [ { "name": "operation_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "operation_example" } ], "responses": { "200": { "description": "Success", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "no-store" }, "X-Request-ID": { "schema": { "type": "string" }, "description": "Request correlation ID." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "operation_id": { "type": "string" }, "state": { "type": "string" }, "created_at": { "type": "number", "description": "Unix epoch seconds, potentially fractional." }, "request_id": { "type": "string" } }, "additionalProperties": true, "required": [ "operation_id", "state", "created_at", "request_id" ] }, "example": { "operation_id": "operation_example", "state": "complete", "created_at": 1790251200.0, "request_id": "req_example" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Tenant suspended or insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Missing resource or deployment disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Body read timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict or recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Stale resource version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Missing If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Management concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Central service, storage or operation recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Get operation", "tags": [ "History" ], "description": "Status is visible only to the same management key that initiated the operation.", "x-scopes": [ "read" ] } }, "/llmgateway/management/v1/operations/{operation_id}/recover": { "post": { "operationId": "Post_recover", "security": [ { "ManagementKey": [] } ], "parameters": [ { "name": "operation_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "operation_example" } ], "responses": { "200": { "description": "Success", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "no-store" }, "X-Request-ID": { "schema": { "type": "string" }, "description": "Request correlation ID." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "app": { "$ref": "#/components/schemas/AppView" }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/Warning" } }, "request_id": { "type": "string" }, "operation_id": { "type": "string" }, "state": { "type": "string" } }, "additionalProperties": true, "required": [ "operation_id", "state", "request_id" ] }, "example": { "app": { "name": "Support Bot", "enabled": true, "mode": "gateway", "provider_labels": [ "Production OpenAI" ], "provider_mode": "shared", "version": "app-v1", "policy_authority": { "enabled": false, "active_revision": null, "active_checksum": null }, "tags": [ "production" ], "detection": { "enabled_categories": {}, "custom_definitions": [] }, "limits": {}, "routing": { "routing_groups": [], "token_based_routing_groups": [], "custom_routing": [] }, "access": {}, "transformations": {}, "self_service": {}, "prompts": {} }, "warnings": [], "operation_id": "operation_example", "state": "complete", "request_id": "req_example" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Tenant suspended or insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Missing resource or deployment disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Body read timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict or recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Stale resource version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Missing If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Management concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Central service, storage or operation recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" }, "example": {} } } }, "summary": "Post recover", "tags": [ "History" ], "description": "Retry a saved configuration write using the initiating key. Requires config:write. Creation must instead retry the original POST with its original Idempotency-Key.", "x-scopes": [ "config:write" ] } }, "/llmgateway/management/v1/app": { "get": { "operationId": "Read_an_app_query", "security": [ { "ManagementKey": [] } ], "parameters": [ { "name": "app_name", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Exact display name; encode with standard query URL encoding.", "example": "Support Bot" } ], "responses": { "200": { "description": "Success", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "no-store" }, "X-Request-ID": { "schema": { "type": "string" }, "description": "Request correlation ID." }, "ETag": { "schema": { "type": "string" }, "description": "Quoted resource version. Lists expose per-resource versions in their metadata." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "app": { "$ref": "#/components/schemas/AppView" }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/Warning" } }, "request_id": { "type": "string" } }, "additionalProperties": true, "required": [ "app", "warnings", "request_id" ] }, "example": { "app": { "name": "Support Bot", "enabled": true, "mode": "gateway", "provider_labels": [ "Production OpenAI" ], "provider_mode": "shared", "version": "app-v1", "policy_authority": { "enabled": false, "active_revision": null, "active_checksum": null }, "tags": [ "production" ], "detection": { "enabled_categories": {}, "custom_definitions": [] }, "limits": {}, "routing": { "routing_groups": [], "token_based_routing_groups": [], "custom_routing": [] }, "access": {}, "transformations": {}, "self_service": {}, "prompts": {} }, "warnings": [], "request_id": "req_example" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Tenant suspended or insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Missing resource or deployment disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Body read timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict or recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Stale resource version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Missing If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Management concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Central service, storage or operation recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Read an app (query locator)", "tags": [ "Apps" ], "description": "Read or update stored settings. App enablement is enforced independently of QuilrQL. Use app_name in the query for names containing slashes or literal percent signs; URL-encode the query value once.", "x-scopes": [ "read" ] }, "patch": { "operationId": "Update_or_disable_an_app_query", "security": [ { "ManagementKey": [] } ], "parameters": [ { "name": "app_name", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Exact display name; encode with standard query URL encoding.", "example": "Support Bot" }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Quoted ETag returned by the latest resource read. Prompt/attachment/rollback writes use the app ETag.", "example": "\"resource-version-from-read\"" } ], "responses": { "200": { "description": "Success", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "no-store" }, "X-Request-ID": { "schema": { "type": "string" }, "description": "Request correlation ID." }, "ETag": { "schema": { "type": "string" }, "description": "Quoted resource version. Lists expose per-resource versions in their metadata." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "app": { "$ref": "#/components/schemas/AppView" }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/Warning" } }, "request_id": { "type": "string" } }, "additionalProperties": true, "required": [ "app", "warnings", "request_id" ] }, "example": { "app": { "name": "Support Bot", "enabled": true, "mode": "gateway", "provider_labels": [ "Production OpenAI" ], "provider_mode": "shared", "version": "app-v1", "policy_authority": { "enabled": false, "active_revision": null, "active_checksum": null }, "tags": [ "production" ], "detection": { "enabled_categories": {}, "custom_definitions": [] }, "limits": {}, "routing": { "routing_groups": [], "token_based_routing_groups": [], "custom_routing": [] }, "access": {}, "transformations": {}, "self_service": {}, "prompts": {} }, "warnings": [], "request_id": "req_example" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Tenant suspended or insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Missing resource or deployment disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Body read timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict or recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Stale resource version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Missing If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Management concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Central service, storage or operation recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppPatch" }, "example": { "detection": { "data_risk_action": "redact" }, "limits": { "timeout": 30 } } } } }, "summary": "Update or disable an app (query locator)", "tags": [ "Apps" ], "description": "Read or update stored settings. App enablement is enforced independently of QuilrQL. Use app_name in the query for names containing slashes or literal percent signs; URL-encode the query value once.", "x-scopes": [ "config:write" ] } }, "/llmgateway/management/v1/app/providers": { "get": { "operationId": "List_app_providers_query", "security": [ { "ManagementKey": [] } ], "parameters": [ { "name": "app_name", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Exact display name; encode with standard query URL encoding.", "example": "Support Bot" } ], "responses": { "200": { "description": "Success", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "no-store" }, "X-Request-ID": { "schema": { "type": "string" }, "description": "Request correlation ID." }, "ETag": { "schema": { "type": "string" }, "description": "Quoted resource version. Lists expose per-resource versions in their metadata." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "provider_labels": { "type": "array", "items": { "type": "string" } }, "version": { "type": "string", "description": "Opaque resource version. Send its quoted value in If-Match." }, "request_id": { "type": "string" } }, "additionalProperties": true, "required": [ "provider_labels", "version", "request_id" ] }, "example": { "provider_labels": [ "Production OpenAI" ], "version": "app-v1", "request_id": "req_example" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Tenant suspended or insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Missing resource or deployment disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Body read timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict or recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Stale resource version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Missing If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Management concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Central service, storage or operation recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "List app providers (query locator)", "tags": [ "Apps" ], "description": "Returns ordered provider_labels and the app version, not a paginated provider collection. Use app_name in the query for names containing slashes or literal percent signs; URL-encode the query value once.", "x-scopes": [ "read" ] } }, "/llmgateway/management/v1/app/providers/{label}": { "put": { "operationId": "Attach_a_shared_provider_query", "security": [ { "ManagementKey": [] } ], "parameters": [ { "name": "label", "in": "path", "required": true, "schema": { "type": "string" }, "example": "Production OpenAI" }, { "name": "app_name", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Exact display name; encode with standard query URL encoding.", "example": "Support Bot" }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Quoted ETag returned by the latest resource read. Prompt/attachment/rollback writes use the app ETag.", "example": "\"resource-version-from-read\"" } ], "responses": { "200": { "description": "Success", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "no-store" }, "X-Request-ID": { "schema": { "type": "string" }, "description": "Request correlation ID." }, "ETag": { "schema": { "type": "string" }, "description": "Quoted resource version. Lists expose per-resource versions in their metadata." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "app": { "$ref": "#/components/schemas/AppView" }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/Warning" } }, "request_id": { "type": "string" } }, "additionalProperties": true, "required": [ "app", "warnings", "request_id" ] }, "example": { "app": { "name": "Support Bot", "enabled": true, "mode": "gateway", "provider_labels": [ "Production OpenAI" ], "provider_mode": "shared", "version": "app-v1", "policy_authority": { "enabled": false, "active_revision": null, "active_checksum": null }, "tags": [ "production" ], "detection": { "enabled_categories": {}, "custom_definitions": [] }, "limits": {}, "routing": { "routing_groups": [], "token_based_routing_groups": [], "custom_routing": [] }, "access": {}, "transformations": {}, "self_service": {}, "prompts": {} }, "warnings": [], "request_id": "req_example" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Tenant suspended or insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Missing resource or deployment disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Body read timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict or recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Stale resource version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Missing If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Management concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Central service, storage or operation recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Attachment" }, "example": { "primary": false } } } }, "summary": "Attach a shared provider (query locator)", "tags": [ "Apps" ], "description": "Use the current app ETag. PUT preserves unrelated attachments; DELETE validates remaining routes. Provider removal while QuilrQL is enabled returns policy_dependency. Use app_name in the query for names containing slashes or literal percent signs; URL-encode the query value once.", "x-scopes": [ "config:write" ] }, "delete": { "operationId": "Detach_an_app_provider_query", "security": [ { "ManagementKey": [] } ], "parameters": [ { "name": "label", "in": "path", "required": true, "schema": { "type": "string" }, "example": "Production OpenAI" }, { "name": "app_name", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Exact display name; encode with standard query URL encoding.", "example": "Support Bot" }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Quoted ETag returned by the latest resource read. Prompt/attachment/rollback writes use the app ETag.", "example": "\"resource-version-from-read\"" } ], "responses": { "200": { "description": "Success", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "no-store" }, "X-Request-ID": { "schema": { "type": "string" }, "description": "Request correlation ID." }, "ETag": { "schema": { "type": "string" }, "description": "Quoted resource version. Lists expose per-resource versions in their metadata." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "app": { "$ref": "#/components/schemas/AppView" }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/Warning" } }, "request_id": { "type": "string" } }, "additionalProperties": true, "required": [ "app", "warnings", "request_id" ] }, "example": { "app": { "name": "Support Bot", "enabled": true, "mode": "gateway", "provider_labels": [ "Production OpenAI" ], "provider_mode": "shared", "version": "app-v1", "policy_authority": { "enabled": false, "active_revision": null, "active_checksum": null }, "tags": [ "production" ], "detection": { "enabled_categories": {}, "custom_definitions": [] }, "limits": {}, "routing": { "routing_groups": [], "token_based_routing_groups": [], "custom_routing": [] }, "access": {}, "transformations": {}, "self_service": {}, "prompts": {} }, "warnings": [], "request_id": "req_example" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Tenant suspended or insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Missing resource or deployment disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Body read timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict or recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Stale resource version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Missing If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Management concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Central service, storage or operation recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" }, "example": {} } } }, "summary": "Detach an app provider (query locator)", "tags": [ "Apps" ], "description": "Use the current app ETag. PUT preserves unrelated attachments; DELETE validates remaining routes. Provider removal while QuilrQL is enabled returns policy_dependency. Use app_name in the query for names containing slashes or literal percent signs; URL-encode the query value once.", "x-scopes": [ "config:write" ] } }, "/llmgateway/management/v1/app/provider-conversion": { "post": { "operationId": "Convert_inline_providers_query", "security": [ { "ManagementKey": [] } ], "parameters": [ { "name": "app_name", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Exact display name; encode with standard query URL encoding.", "example": "Support Bot" }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Quoted ETag returned by the latest resource read. Prompt/attachment/rollback writes use the app ETag.", "example": "\"resource-version-from-read\"" } ], "responses": { "200": { "description": "Success", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "no-store" }, "X-Request-ID": { "schema": { "type": "string" }, "description": "Request correlation ID." }, "ETag": { "schema": { "type": "string" }, "description": "Quoted resource version. Lists expose per-resource versions in their metadata." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "app": { "$ref": "#/components/schemas/AppView" }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/Warning" } }, "request_id": { "type": "string" } }, "additionalProperties": true, "required": [ "app", "warnings", "request_id" ] }, "example": { "app": { "name": "Support Bot", "enabled": true, "mode": "gateway", "provider_labels": [ "Production OpenAI" ], "provider_mode": "shared", "version": "app-v1", "policy_authority": { "enabled": false, "active_revision": null, "active_checksum": null }, "tags": [ "production" ], "detection": { "enabled_categories": {}, "custom_definitions": [] }, "limits": {}, "routing": { "routing_groups": [], "token_based_routing_groups": [], "custom_routing": [] }, "access": {}, "transformations": {}, "self_service": {}, "prompts": {} }, "warnings": [], "request_id": "req_example" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Tenant suspended or insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Missing resource or deployment disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Body read timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict or recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Stale resource version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Missing If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Management concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Central service, storage or operation recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conversion" }, "example": { "provider_labels": [ "Production OpenAI" ] } } } }, "summary": "Convert inline providers (query locator)", "tags": [ "Apps" ], "description": "Convert an inline app using a complete shared-provider selection. Uses the app ETag; no idempotency replay contract. Use app_name in the query for names containing slashes or literal percent signs; URL-encode the query value once.", "x-scopes": [ "config:write" ] } }, "/llmgateway/management/v1/app/keys": { "get": { "operationId": "List_gateway_credentials_query", "security": [ { "ManagementKey": [] } ], "parameters": [ { "name": "app_name", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Exact display name; encode with standard query URL encoding.", "example": "Support Bot" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "example": 50 }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "example": "cursor-from-previous-page" } ], "responses": { "200": { "description": "Success", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "no-store" }, "X-Request-ID": { "schema": { "type": "string" }, "description": "Request correlation ID." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/GatewayKey" } }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "request_id": { "type": "string" } }, "additionalProperties": true, "required": [ "items", "next_cursor", "request_id" ] }, "example": { "items": [ { "key_id": "key_example", "name": "Default", "created_at": "2026-09-24T12:00:00Z", "expires_at": null, "status": "active", "fingerprint": "0123456789ab" } ], "next_cursor": null, "request_id": "req_example" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Tenant suspended or insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Missing resource or deployment disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Body read timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict or recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Stale resource version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Missing If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Management concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Central service, storage or operation recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "List gateway credentials (query locator)", "tags": [ "Credentials" ], "description": "Tenant-scoped operation. Resource reads return redacted metadata; writes use the permissions and preconditions shown below. Use app_name in the query for names containing slashes or literal percent signs; URL-encode the query value once.", "x-scopes": [ "read" ] }, "post": { "operationId": "Issue_a_gateway_credential_query", "security": [ { "ManagementKey": [] } ], "parameters": [ { "name": "app_name", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Exact display name; encode with standard query URL encoding.", "example": "Support Bot" }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "example": "unique-operation-001" } ], "responses": { "201": { "description": "Created", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "no-store" }, "X-Request-ID": { "schema": { "type": "string" }, "description": "Request correlation ID." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "$ref": "#/components/schemas/GatewayKey" }, "request_id": { "type": "string" }, "operation_id": { "type": "string" } }, "additionalProperties": true, "required": [ "key", "request_id" ] }, "example": { "key": { "key_id": "key_example", "name": "Default", "created_at": "2026-09-24T12:00:00Z", "expires_at": null, "status": "active", "fingerprint": "0123456789ab", "secret": "" }, "operation_id": "operation_example", "request_id": "req_example" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Tenant suspended or insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Missing resource or deployment disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Body read timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict or recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Stale resource version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Missing If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Management concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Central service, storage or operation recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayKeyCreate" }, "example": { "name": "Deployment", "expires_at": null } } } }, "summary": "Issue a gateway credential (query locator)", "tags": [ "Credentials" ], "description": "Tenant-scoped operation. Resource reads return redacted metadata; writes use the permissions and preconditions shown below. Use app_name in the query for names containing slashes or literal percent signs; URL-encode the query value once.", "x-scopes": [ "credentials:write" ] } }, "/llmgateway/management/v1/app/keys/{key_id}": { "get": { "operationId": "Get_key_query", "security": [ { "ManagementKey": [] } ], "parameters": [ { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "key_example" }, { "name": "app_name", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Exact display name; encode with standard query URL encoding.", "example": "Support Bot" } ], "responses": { "200": { "description": "Success", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "no-store" }, "X-Request-ID": { "schema": { "type": "string" }, "description": "Request correlation ID." }, "ETag": { "schema": { "type": "string" }, "description": "Quoted resource version. Lists expose per-resource versions in their metadata." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "$ref": "#/components/schemas/GatewayKey" }, "request_id": { "type": "string" }, "version": { "type": "string", "description": "Opaque resource version. Send its quoted value in If-Match." } }, "additionalProperties": true, "required": [ "key", "request_id" ] }, "example": { "key": { "key_id": "key_example", "name": "Default", "created_at": "2026-09-24T12:00:00Z", "expires_at": null, "status": "active", "fingerprint": "0123456789ab" }, "version": "key-v1", "request_id": "req_example" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Tenant suspended or insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Missing resource or deployment disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Body read timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict or recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Stale resource version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Missing If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Management concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Central service, storage or operation recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Get key (query locator)", "tags": [ "Credentials" ], "description": "Tenant-scoped operation. Resource reads return redacted metadata; writes use the permissions and preconditions shown below. Use app_name in the query for names containing slashes or literal percent signs; URL-encode the query value once.", "x-scopes": [ "read" ] }, "patch": { "operationId": "Change_gateway_key_expiry_query", "security": [ { "ManagementKey": [] } ], "parameters": [ { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "key_example" }, { "name": "app_name", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Exact display name; encode with standard query URL encoding.", "example": "Support Bot" }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Quoted ETag returned by the latest resource read. Prompt/attachment/rollback writes use the app ETag.", "example": "\"resource-version-from-read\"" } ], "responses": { "200": { "description": "Success", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "no-store" }, "X-Request-ID": { "schema": { "type": "string" }, "description": "Request correlation ID." }, "ETag": { "schema": { "type": "string" }, "description": "Quoted resource version. Lists expose per-resource versions in their metadata." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "$ref": "#/components/schemas/GatewayKey" }, "request_id": { "type": "string" }, "version": { "type": "string", "description": "Opaque resource version. Send its quoted value in If-Match." } }, "additionalProperties": true, "required": [ "key", "request_id" ] }, "example": { "key": { "key_id": "key_example", "name": "Default", "created_at": "2026-09-24T12:00:00Z", "expires_at": null, "status": "active", "fingerprint": "0123456789ab" }, "version": "key-v1", "request_id": "req_example" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Tenant suspended or insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Missing resource or deployment disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Body read timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict or recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Stale resource version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Missing If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Management concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Central service, storage or operation recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayKeyPatch" }, "example": { "expires_at": null } } } }, "summary": "Change gateway key expiry (query locator)", "tags": [ "Credentials" ], "description": "Tenant-scoped operation. Resource reads return redacted metadata; writes use the permissions and preconditions shown below. Use app_name in the query for names containing slashes or literal percent signs; URL-encode the query value once.", "x-scopes": [ "credentials:write" ] }, "delete": { "operationId": "Revoke_a_gateway_credential_query", "security": [ { "ManagementKey": [] } ], "parameters": [ { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "key_example" }, { "name": "app_name", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Exact display name; encode with standard query URL encoding.", "example": "Support Bot" }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Quoted ETag returned by the latest resource read. Prompt/attachment/rollback writes use the app ETag.", "example": "\"resource-version-from-read\"" } ], "responses": { "200": { "description": "Success", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "no-store" }, "X-Request-ID": { "schema": { "type": "string" }, "description": "Request correlation ID." }, "ETag": { "schema": { "type": "string" }, "description": "Quoted resource version. Lists expose per-resource versions in their metadata." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "$ref": "#/components/schemas/GatewayKey" }, "request_id": { "type": "string" }, "version": { "type": "string", "description": "Opaque resource version. Send its quoted value in If-Match." } }, "additionalProperties": true, "required": [ "key", "request_id" ] }, "example": { "key": { "key_id": "key_example", "name": "Default", "created_at": "2026-09-24T12:00:00Z", "expires_at": null, "status": "revoked", "fingerprint": "0123456789ab" }, "version": "key-v1", "request_id": "req_example" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Tenant suspended or insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Missing resource or deployment disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Body read timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict or recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Stale resource version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Missing If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Management concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Central service, storage or operation recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" }, "example": {} } } }, "summary": "Revoke a gateway credential (query locator)", "tags": [ "Credentials" ], "description": "Tenant-scoped operation. Resource reads return redacted metadata; writes use the permissions and preconditions shown below. Use app_name in the query for names containing slashes or literal percent signs; URL-encode the query value once.", "x-scopes": [ "credentials:write" ] } }, "/llmgateway/management/v1/app/keys/{key_id}/reveal": { "post": { "operationId": "Reveal_a_gateway_credential_query", "security": [ { "ManagementKey": [] } ], "parameters": [ { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "key_example" }, { "name": "app_name", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Exact display name; encode with standard query URL encoding.", "example": "Support Bot" } ], "responses": { "200": { "description": "Success", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "no-store" }, "X-Request-ID": { "schema": { "type": "string" }, "description": "Request correlation ID." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "$ref": "#/components/schemas/GatewayKey" }, "request_id": { "type": "string" } }, "additionalProperties": true, "required": [ "key", "request_id" ] }, "example": { "key": { "key_id": "key_example", "name": "Default", "created_at": "2026-09-24T12:00:00Z", "expires_at": null, "status": "active", "fingerprint": "0123456789ab", "secret": "" }, "request_id": "req_example" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Tenant suspended or insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Missing resource or deployment disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Body read timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict or recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Stale resource version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Missing If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Management concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Central service, storage or operation recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" }, "example": {} } } }, "summary": "Reveal a gateway credential (query locator)", "tags": [ "Credentials" ], "description": "Explicitly reveal an active gateway credential. Expired/revoked credentials return terminal_key_state. Use app_name in the query for names containing slashes or literal percent signs; URL-encode the query value once.", "x-scopes": [ "credentials:read" ] } }, "/llmgateway/management/v1/app/prompts": { "get": { "operationId": "List_prompts_query", "security": [ { "ManagementKey": [] } ], "parameters": [ { "name": "app_name", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Exact display name; encode with standard query URL encoding.", "example": "Support Bot" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "example": 50 }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "example": "cursor-from-previous-page" } ], "responses": { "200": { "description": "Success", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "no-store" }, "X-Request-ID": { "schema": { "type": "string" }, "description": "Request correlation ID." }, "ETag": { "schema": { "type": "string" }, "description": "Quoted resource version. Lists expose per-resource versions in their metadata." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "prompt_id": { "type": "string" }, "content": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "additionalProperties": true } }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "request_id": { "type": "string" }, "version": { "type": "string", "description": "Opaque resource version. Send its quoted value in If-Match." } }, "additionalProperties": true, "required": [ "items", "next_cursor", "request_id" ] }, "example": { "items": [], "next_cursor": null, "version": "app-v1", "request_id": "req_example" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Tenant suspended or insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Missing resource or deployment disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Body read timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict or recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Stale resource version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Missing If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Management concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Central service, storage or operation recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "List prompts (query locator)", "tags": [ "Prompts" ], "description": "Tenant-scoped operation. Resource reads return redacted metadata; writes use the permissions and preconditions shown below. Use app_name in the query for names containing slashes or literal percent signs; URL-encode the query value once.", "x-scopes": [ "read" ] } }, "/llmgateway/management/v1/app/prompts/{prompt_id}": { "get": { "operationId": "Read_a_prompt_query", "security": [ { "ManagementKey": [] } ], "parameters": [ { "name": "prompt_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "support" }, { "name": "app_name", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Exact display name; encode with standard query URL encoding.", "example": "Support Bot" } ], "responses": { "200": { "description": "Success", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "no-store" }, "X-Request-ID": { "schema": { "type": "string" }, "description": "Request correlation ID." }, "ETag": { "schema": { "type": "string" }, "description": "Quoted resource version. Lists expose per-resource versions in their metadata." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt_id": { "type": "string" }, "prompt": { "anyOf": [ { "type": "object" }, { "type": "null" } ] }, "version": { "type": "string", "description": "Opaque resource version. Send its quoted value in If-Match." }, "request_id": { "type": "string" } }, "additionalProperties": true, "required": [ "prompt_id", "prompt", "version", "request_id" ] }, "example": { "prompt_id": "support", "prompt": { "content": "You help customers with support questions.", "created_at": "2026-09-24T12:00:00+00:00", "updated_at": "2026-09-24T12:00:00+00:00" }, "version": "app-v1", "request_id": "req_example" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Tenant suspended or insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Missing resource or deployment disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Body read timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict or recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Stale resource version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Missing If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Management concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Central service, storage or operation recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Read a prompt (query locator)", "tags": [ "Prompts" ], "description": "Use the current app ETag for every mutation, including creation. PUT creates or replaces; If-None-Match is not a create-only guard. Use app_name in the query for names containing slashes or literal percent signs; URL-encode the query value once.", "x-scopes": [ "read" ] }, "put": { "operationId": "Create_or_replace_a_prompt_query", "security": [ { "ManagementKey": [] } ], "parameters": [ { "name": "prompt_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "support" }, { "name": "app_name", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Exact display name; encode with standard query URL encoding.", "example": "Support Bot" }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Quoted ETag returned by the latest resource read. Prompt/attachment/rollback writes use the app ETag.", "example": "\"resource-version-from-read\"" } ], "responses": { "200": { "description": "Success", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "no-store" }, "X-Request-ID": { "schema": { "type": "string" }, "description": "Request correlation ID." }, "ETag": { "schema": { "type": "string" }, "description": "Quoted resource version. Lists expose per-resource versions in their metadata." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt_id": { "type": "string" }, "prompt": { "anyOf": [ { "type": "object" }, { "type": "null" } ] }, "version": { "type": "string", "description": "Opaque resource version. Send its quoted value in If-Match." }, "request_id": { "type": "string" } }, "additionalProperties": true, "required": [ "prompt_id", "prompt", "version", "request_id" ] }, "example": { "prompt_id": "support", "prompt": { "content": "You help customers with support questions.", "created_at": "2026-09-24T12:00:00+00:00", "updated_at": "2026-09-24T12:00:00+00:00" }, "version": "app-v1", "request_id": "req_example" } } } }, "201": { "description": "Prompt created; 200 means replaced.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "no-store" }, "X-Request-ID": { "schema": { "type": "string" }, "description": "Request correlation ID." }, "ETag": { "schema": { "type": "string" }, "description": "Quoted resource version. Lists expose per-resource versions in their metadata." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt_id": { "type": "string" }, "prompt": { "anyOf": [ { "type": "object" }, { "type": "null" } ] }, "version": { "type": "string", "description": "Opaque resource version. Send its quoted value in If-Match." }, "request_id": { "type": "string" } }, "additionalProperties": true, "required": [ "prompt_id", "prompt", "version", "request_id" ] }, "example": { "prompt_id": "support", "prompt": { "content": "You help customers with support questions.", "created_at": "2026-09-24T12:00:00+00:00", "updated_at": "2026-09-24T12:00:00+00:00" }, "version": "app-v1", "request_id": "req_example" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Tenant suspended or insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Missing resource or deployment disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Body read timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict or recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Stale resource version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Missing If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Management concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Central service, storage or operation recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Prompt" }, "example": { "content": "You help customers with support questions." } } } }, "summary": "Create or replace a prompt (query locator)", "tags": [ "Prompts" ], "description": "Use the current app ETag for every mutation, including creation. PUT creates or replaces; If-None-Match is not a create-only guard. Use app_name in the query for names containing slashes or literal percent signs; URL-encode the query value once.", "x-scopes": [ "config:write" ] }, "delete": { "operationId": "Delete_a_prompt_query", "security": [ { "ManagementKey": [] } ], "parameters": [ { "name": "prompt_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "support" }, { "name": "app_name", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Exact display name; encode with standard query URL encoding.", "example": "Support Bot" }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Quoted ETag returned by the latest resource read. Prompt/attachment/rollback writes use the app ETag.", "example": "\"resource-version-from-read\"" } ], "responses": { "200": { "description": "Success", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "no-store" }, "X-Request-ID": { "schema": { "type": "string" }, "description": "Request correlation ID." }, "ETag": { "schema": { "type": "string" }, "description": "Quoted resource version. Lists expose per-resource versions in their metadata." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt_id": { "type": "string" }, "prompt": { "anyOf": [ { "type": "object" }, { "type": "null" } ] }, "version": { "type": "string", "description": "Opaque resource version. Send its quoted value in If-Match." }, "request_id": { "type": "string" } }, "additionalProperties": true, "required": [ "prompt_id", "prompt", "version", "request_id" ] }, "example": { "prompt_id": "support", "prompt": null, "version": "app-v1", "request_id": "req_example" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Tenant suspended or insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Missing resource or deployment disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Body read timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict or recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Stale resource version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Missing If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Management concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Central service, storage or operation recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" }, "example": {} } } }, "summary": "Delete a prompt (query locator)", "tags": [ "Prompts" ], "description": "Use the current app ETag for every mutation, including creation. PUT creates or replaces; If-None-Match is not a create-only guard. Use app_name in the query for names containing slashes or literal percent signs; URL-encode the query value once.", "x-scopes": [ "config:write" ] } }, "/llmgateway/management/v1/app/versions": { "get": { "operationId": "List_app_configuration_versions_query", "security": [ { "ManagementKey": [] } ], "parameters": [ { "name": "app_name", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Exact display name; encode with standard query URL encoding.", "example": "Support Bot" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "example": 50 }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "example": "cursor-from-previous-page" } ], "responses": { "200": { "description": "Success", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "no-store" }, "X-Request-ID": { "schema": { "type": "string" }, "description": "Request correlation ID." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/VersionRecord" } }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "request_id": { "type": "string" } }, "additionalProperties": true, "required": [ "items", "next_cursor", "request_id" ] }, "example": { "items": [], "next_cursor": null, "request_id": "req_example" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Tenant suspended or insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Missing resource or deployment disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Body read timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict or recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Stale resource version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Missing If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Management concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Central service, storage or operation recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "List app configuration versions (query locator)", "tags": [ "History" ], "description": "Tenant-scoped operation. Resource reads return redacted metadata; writes use the permissions and preconditions shown below. Use app_name in the query for names containing slashes or literal percent signs; URL-encode the query value once.", "x-scopes": [ "read" ] } }, "/llmgateway/management/v1/app/versions/{version_id}": { "get": { "operationId": "Read_a_configuration_version_query", "security": [ { "ManagementKey": [] } ], "parameters": [ { "name": "version_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "version_example" }, { "name": "app_name", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Exact display name; encode with standard query URL encoding.", "example": "Support Bot" } ], "responses": { "200": { "description": "Success", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "no-store" }, "X-Request-ID": { "schema": { "type": "string" }, "description": "Request correlation ID." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "version_record": { "$ref": "#/components/schemas/VersionRecord" }, "request_id": { "type": "string" } }, "additionalProperties": true, "required": [ "version_record", "request_id" ] }, "example": { "version_record": { "version_id": "version_example", "version": 1, "changed_at": "2026-09-24T12:00:00Z", "operation": "management_update", "actor_type": "management_key", "actor_user_id": "management_key_example", "actor_email": null, "previous_config": {}, "new_config": {} }, "request_id": "req_example" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Tenant suspended or insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Missing resource or deployment disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Body read timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict or recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Stale resource version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Missing If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Management concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Central service, storage or operation recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Read a configuration version (query locator)", "tags": [ "History" ], "description": "Tenant-scoped operation. Resource reads return redacted metadata; writes use the permissions and preconditions shown below. Use app_name in the query for names containing slashes or literal percent signs; URL-encode the query value once.", "x-scopes": [ "read" ] } }, "/llmgateway/management/v1/app/versions/{version_id}/rollback": { "post": { "operationId": "Roll_back_app_configuration_query", "security": [ { "ManagementKey": [] } ], "parameters": [ { "name": "version_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "version_example" }, { "name": "app_name", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Exact display name; encode with standard query URL encoding.", "example": "Support Bot" }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Quoted ETag returned by the latest resource read. Prompt/attachment/rollback writes use the app ETag.", "example": "\"resource-version-from-read\"" }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "example": "unique-operation-001" } ], "responses": { "200": { "description": "Success", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "no-store" }, "X-Request-ID": { "schema": { "type": "string" }, "description": "Request correlation ID." }, "ETag": { "schema": { "type": "string" }, "description": "Quoted resource version. Lists expose per-resource versions in their metadata." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "app": { "$ref": "#/components/schemas/AppView" }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/Warning" } }, "request_id": { "type": "string" } }, "additionalProperties": true, "required": [ "app", "warnings", "request_id" ] }, "example": { "app": { "name": "Support Bot", "enabled": true, "mode": "gateway", "provider_labels": [ "Production OpenAI" ], "provider_mode": "shared", "version": "app-v1", "policy_authority": { "enabled": false, "active_revision": null, "active_checksum": null }, "tags": [ "production" ], "detection": { "enabled_categories": {}, "custom_definitions": [] }, "limits": {}, "routing": { "routing_groups": [], "token_based_routing_groups": [], "custom_routing": [] }, "access": {}, "transformations": {}, "self_service": {}, "prompts": {} }, "warnings": [], "request_id": "req_example" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Tenant suspended or insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Missing resource or deployment disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Body read timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict or recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Stale resource version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Missing If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Management concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Central service, storage or operation recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" }, "example": {} } } }, "summary": "Roll back app configuration (query locator)", "tags": [ "History" ], "description": "Restricted app configuration rollback; no policy rollback. Requires the current app ETag and Idempotency-Key. Use app_name in the query for names containing slashes or literal percent signs; URL-encode the query value once.", "x-scopes": [ "config:write" ] } }, "/llmgateway/management-admin/v1/tenants/{tenant_id}/settings": { "get": { "operationId": "Read_tenant_management_settings", "security": [ { "TenantAdminJWT": [] } ], "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "tenant_example" } ], "responses": { "200": { "description": "Success", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "no-store" }, "X-Request-ID": { "schema": { "type": "string" }, "description": "Request correlation ID." }, "ETag": { "schema": { "type": "string" }, "description": "Quoted resource version. Lists expose per-resource versions in their metadata." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "version": { "type": "string", "description": "Opaque resource version. Send its quoted value in If-Match." }, "request_id": { "type": "string" } }, "additionalProperties": true, "required": [ "enabled", "version", "request_id" ] }, "example": { "enabled": true, "version": "settings-v1", "request_id": "req_example" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Tenant suspended or insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Missing resource or deployment disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Body read timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict or recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Stale resource version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Missing If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Management concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Central service, storage or operation recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Read tenant management settings", "tags": [ "Administration" ], "description": "Tenant-admin JWT. PATCH requires the settings ETag. Suspending management preserves keys; unexpired/unrevoked keys resume on re-enablement.", "x-scopes": [] }, "patch": { "operationId": "Enable_or_suspend_tenant_management", "security": [ { "TenantAdminJWT": [] } ], "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "tenant_example" }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Quoted ETag returned by the latest resource read. Prompt/attachment/rollback writes use the app ETag.", "example": "\"resource-version-from-read\"" } ], "responses": { "200": { "description": "Success", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "no-store" }, "X-Request-ID": { "schema": { "type": "string" }, "description": "Request correlation ID." }, "ETag": { "schema": { "type": "string" }, "description": "Quoted resource version. Lists expose per-resource versions in their metadata." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "version": { "type": "string", "description": "Opaque resource version. Send its quoted value in If-Match." }, "request_id": { "type": "string" } }, "additionalProperties": true, "required": [ "enabled", "version", "request_id" ] }, "example": { "enabled": true, "version": "settings-v1", "request_id": "req_example" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Tenant suspended or insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Missing resource or deployment disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Body read timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict or recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Stale resource version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Missing If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Management concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Central service, storage or operation recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantSettings" }, "example": { "enabled": true } } } }, "summary": "Enable or suspend tenant management", "tags": [ "Administration" ], "description": "Tenant-admin JWT. PATCH requires the settings ETag. Suspending management preserves keys; unexpired/unrevoked keys resume on re-enablement.", "x-scopes": [] } }, "/llmgateway/management-admin/v1/tenants/{tenant_id}/keys": { "get": { "operationId": "List_management_keys", "security": [ { "TenantAdminJWT": [] } ], "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "tenant_example" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "example": 50 }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "example": "cursor-from-previous-page" } ], "responses": { "200": { "description": "Success", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "no-store" }, "X-Request-ID": { "schema": { "type": "string" }, "description": "Request correlation ID." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ManagementKey" } }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "request_id": { "type": "string" } }, "additionalProperties": true, "required": [ "items", "next_cursor", "request_id" ] }, "example": { "items": [ { "key_id": "management_key_example", "tenant": "tenant_example", "name": "Deployment automation", "scopes": [ "read", "config:write", "providers:write", "credentials:write" ], "created_at": 1790251200.0, "expires_at": null, "revoked_at": null, "created_by": "tenant_admin:admin_example", "last_used_at": null, "status": "active", "version": "key-v1" } ], "next_cursor": null, "request_id": "req_example" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Tenant suspended or insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Missing resource or deployment disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Body read timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict or recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Stale resource version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Missing If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Management concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Central service, storage or operation recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "List management keys", "tags": [ "Administration" ], "description": "Tenant-admin JWT. Creation requires tenant opt-in and returns the secret; lists return metadata including version. Issuance replay is available for 24 hours to the same admin and idempotency key.", "x-scopes": [] }, "post": { "operationId": "Issue_a_management_key", "security": [ { "TenantAdminJWT": [] } ], "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "tenant_example" }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "example": "unique-operation-001" } ], "responses": { "201": { "description": "Created", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "no-store" }, "X-Request-ID": { "schema": { "type": "string" }, "description": "Request correlation ID." }, "ETag": { "schema": { "type": "string" }, "description": "Quoted resource version. Lists expose per-resource versions in their metadata." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "$ref": "#/components/schemas/ManagementKey" }, "request_id": { "type": "string" }, "operation_id": { "type": "string" } }, "additionalProperties": true, "required": [ "key", "request_id" ] }, "example": { "key": { "key_id": "management_key_example", "tenant": "tenant_example", "name": "Deployment automation", "scopes": [ "read", "config:write", "providers:write", "credentials:write" ], "created_at": 1790251200.0, "expires_at": null, "revoked_at": null, "created_by": "tenant_admin:admin_example", "last_used_at": null, "status": "active", "version": "key-v1", "secret": "" }, "operation_id": "operation_example", "request_id": "req_example" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Tenant suspended or insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Missing resource or deployment disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Body read timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict or recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Stale resource version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Missing If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Management concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Central service, storage or operation recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementKeyCreate" }, "example": { "name": "Deployment automation", "scopes": [ "read", "config:write", "providers:write", "credentials:write" ], "expires_at": null } } } }, "summary": "Issue a management key", "tags": [ "Administration" ], "description": "Tenant-admin JWT. Creation requires tenant opt-in and returns the secret; lists return metadata including version. Issuance replay is available for 24 hours to the same admin and idempotency key.", "x-scopes": [] } }, "/llmgateway/management-admin/v1/tenants/{tenant_id}/keys/{key_id}": { "patch": { "operationId": "Update_a_management_key", "security": [ { "TenantAdminJWT": [] } ], "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "tenant_example" }, { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "key_example" }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Quoted ETag returned by the latest resource read. Prompt/attachment/rollback writes use the app ETag.", "example": "\"resource-version-from-read\"" } ], "responses": { "200": { "description": "Success", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "no-store" }, "X-Request-ID": { "schema": { "type": "string" }, "description": "Request correlation ID." }, "ETag": { "schema": { "type": "string" }, "description": "Quoted resource version. Lists expose per-resource versions in their metadata." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "$ref": "#/components/schemas/ManagementKey" }, "request_id": { "type": "string" } }, "additionalProperties": true, "required": [ "key", "request_id" ] }, "example": { "key": { "key_id": "management_key_example", "tenant": "tenant_example", "name": "Deployment automation", "scopes": [ "read", "config:write", "providers:write", "credentials:write" ], "created_at": 1790251200.0, "expires_at": null, "revoked_at": null, "created_by": "tenant_admin:admin_example", "last_used_at": null, "status": "active", "version": "key-v1" }, "request_id": "req_example" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Tenant suspended or insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Missing resource or deployment disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Body read timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict or recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Stale resource version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Missing If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Management concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Central service, storage or operation recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementKeyPatch" }, "example": { "name": "Production automation", "scopes": [ "read", "config:write" ] } } } }, "summary": "Update a management key", "tags": [ "Administration" ], "description": "Use key.version from the list as a quoted If-Match. PATCH changes name/scopes/expiry. DELETE revokes and returns key metadata. Expired/revoked keys cannot be edited.", "x-scopes": [] }, "delete": { "operationId": "Revoke_a_management_key", "security": [ { "TenantAdminJWT": [] } ], "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "tenant_example" }, { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "key_example" }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Quoted ETag returned by the latest resource read. Prompt/attachment/rollback writes use the app ETag.", "example": "\"resource-version-from-read\"" } ], "responses": { "200": { "description": "Success", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "no-store" }, "X-Request-ID": { "schema": { "type": "string" }, "description": "Request correlation ID." }, "ETag": { "schema": { "type": "string" }, "description": "Quoted resource version. Lists expose per-resource versions in their metadata." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "$ref": "#/components/schemas/ManagementKey" }, "request_id": { "type": "string" } }, "additionalProperties": true, "required": [ "key", "request_id" ] }, "example": { "key": { "key_id": "management_key_example", "tenant": "tenant_example", "name": "Deployment automation", "scopes": [ "read", "config:write", "providers:write", "credentials:write" ], "created_at": 1790251200.0, "expires_at": null, "revoked_at": 1790251300.0, "created_by": "tenant_admin:admin_example", "last_used_at": null, "status": "revoked", "version": "key-v1" }, "request_id": "req_example" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Tenant suspended or insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Missing resource or deployment disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Body read timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict or recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Stale resource version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 1 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Missing If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Management concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Central service, storage or operation recovery required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" }, "example": {} } } }, "summary": "Revoke a management key", "tags": [ "Administration" ], "description": "Use key.version from the list as a quoted If-Match. PATCH changes name/scopes/expiry. DELETE revokes and returns key metadata. Expired/revoked keys cannot be edited.", "x-scopes": [] } } }, "components": { "schemas": { "AppCreate": { "type": "object", "properties": { "detection": { "type": "object", "properties": { "category_actions": { "type": "object", "additionalProperties": { "type": "string", "description": "Adversarial detections do not expose redactable spans; incompatible actions are rejected by catalog validation.", "enum": [ "monitor", "partial-redact", "redact", "block" ] }, "description": "Category ID to action." }, "category_scopes": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "request", "response", "both" ] }, "description": "" }, "category_sensitivities": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string", "enum": [ "low", "medium", "high" ] }, "description": "" }, "description": "" }, "custom_definitions": { "type": "array", "items": { "$ref": "#/components/schemas/CustomSelection" }, "description": "Full replacement of definition selections; [] removes selections. Does not delete definitions.", "maxItems": 1000 }, "data_risk_action": { "type": "string", "description": "Adversarial detections do not expose redactable spans; incompatible actions are rejected by catalog validation.", "enum": [ "monitor", "partial-redact", "redact", "block" ] }, "edm_pattern_sensitivities": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "low", "medium", "high" ] }, "description": "" }, "enabled_categories": { "type": "object", "additionalProperties": { "type": "boolean", "description": "" }, "description": "Catalog category/subcategory IDs mapped to enabled state. Unknown selectors are rejected." }, "guardian_agent": { "$ref": "#/components/schemas/Guardian" }, "hallucination_check_action": { "type": "string", "enum": [ "block", "monitor" ] }, "hallucination_check_risk_level": { "type": "string" }, "hallucination_check_score_threshold": { "type": "number", "minimum": 0, "maximum": 1 }, "is_hallucination_check_enabled": { "type": "boolean" }, "scan_encoded_images": { "type": "boolean" }, "scan_encoded_images_scope": { "type": "string", "enum": [ "request", "response", "both" ] }, "scan_images": { "type": "boolean" }, "scan_images_scope": { "type": "string", "enum": [ "request", "response", "both" ] }, "sub_category_actions": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "string", "description": "Adversarial detections do not expose redactable spans; incompatible actions are rejected by catalog validation.", "enum": [ "monitor", "partial-redact", "redact", "block" ] }, "description": "" }, "description": "Category ID to subcategory name to action." }, "sub_category_sensitivities": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "low", "medium", "high" ] } } } }, "additionalProperties": false }, "limits": { "type": "object", "properties": { "concurrency_per_minute": { "type": [ "integer", "null" ], "minimum": 0 }, "model_rate_limits": { "type": "array", "items": { "$ref": "#/components/schemas/ModelLimit" } }, "rate_limit": { "anyOf": [ { "$ref": "#/components/schemas/RateLimit" }, { "type": "null" } ] }, "rate_limit_per_minute": { "type": "integer", "minimum": 0 }, "timeout": { "type": [ "integer", "null" ], "minimum": 0 }, "token_limits": { "$ref": "#/components/schemas/TokenLimits" } }, "additionalProperties": false }, "routing": { "type": "object", "properties": { "custom_routing": { "type": "array", "items": { "$ref": "#/components/schemas/ContextRoute" } }, "routing_groups": { "type": "array", "items": { "$ref": "#/components/schemas/RoutingGroup" } }, "routing_thresholds": { "type": "object", "properties": { "low_max_words": { "type": "integer", "minimum": 0 }, "medium_max_words": { "type": "integer", "minimum": 0 } }, "additionalProperties": false, "required": [ "low_max_words", "medium_max_words" ], "description": "0 <= low_max_words <= medium_max_words." }, "token_based_routing_groups": { "type": "array", "items": { "$ref": "#/components/schemas/RoutingGroup" } } }, "additionalProperties": false }, "access": { "type": "object", "properties": { "allowed_source_ips": { "oneOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "object", "properties": { "enabled": { "type": "boolean" }, "ips": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, { "type": "null" } ] }, "allowed_user_domains": { "type": "array", "items": { "type": "string" }, "maxItems": 1000 }, "allowed_user_emails": { "type": "array", "items": { "type": "string" }, "maxItems": 1000 }, "enforce_conversation_id": { "type": "boolean" }, "enforce_identity": { "type": "boolean" }, "identity_header_mode": { "type": "boolean" }, "identity_token_headers": { "type": "array", "items": { "type": "string" }, "maxItems": 1000 }, "identity_token_oid_fallback": { "type": "boolean" }, "jwt_auth": { "anyOf": [ { "$ref": "#/components/schemas/JwtAuth" }, { "type": "null" } ] } }, "additionalProperties": false }, "transformations": { "type": "object", "properties": { "token_saving": { "$ref": "#/components/schemas/TokenSaving" } }, "additionalProperties": false }, "self_service": { "type": "object", "properties": { "enable_self_service": { "type": "boolean" }, "self_service": { "type": "object", "properties": { "access_control": { "anyOf": [ { "type": "object", "properties": { "version": { "type": "integer", "const": 1 }, "self_service_viewer": { "$ref": "#/components/schemas/AccessRule" }, "settings_update_requester": { "$ref": "#/components/schemas/AccessRule" }, "settings_update_direct": { "$ref": "#/components/schemas/AccessRule" }, "show_api_key": { "$ref": "#/components/schemas/AccessRule" }, "show_logs_for_all_users": { "$ref": "#/components/schemas/AccessRule" } }, "additionalProperties": true, "description": "" }, { "type": "null" } ] } }, "additionalProperties": true, "description": "Stored self-service configuration. Access-control roles live inside this object. Omit to preserve; the section itself does not accept null." } }, "additionalProperties": false }, "prompts": { "type": "object", "properties": { "require_system_from_store": { "type": "boolean" } }, "additionalProperties": false }, "enabled": { "type": "boolean" }, "smart_group_policies": { "type": "array", "items": { "$ref": "#/components/schemas/GroupPolicy" } }, "alerting": { "anyOf": [ { "$ref": "#/components/schemas/Alerting" }, { "type": "null" } ] }, "provider_labels": { "type": "array", "items": { "type": "string" }, "maxItems": 1000 }, "tags": { "type": "array", "items": { "type": "string" }, "maxItems": 1000 }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "mode": { "type": "string", "enum": [ "gateway", "sdk", "copilot_studio" ], "default": "gateway" }, "initial_key": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": false } }, "additionalProperties": false, "required": [ "name" ], "description": "Create an app and one gateway credential. Gateway mode requires a nonempty ordered provider_labels list; SDK/Copilot Studio omit it. initial_key defaults to a key named Default. Existing QuilrQL authority can publish the new app allowed-models default." }, "AppPatch": { "type": "object", "properties": { "detection": { "type": "object", "properties": { "category_actions": { "type": "object", "additionalProperties": { "type": "string", "description": "Adversarial detections do not expose redactable spans; incompatible actions are rejected by catalog validation.", "enum": [ "monitor", "partial-redact", "redact", "block" ] }, "description": "Category ID to action." }, "category_scopes": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "request", "response", "both" ] }, "description": "" }, "category_sensitivities": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string", "enum": [ "low", "medium", "high" ] }, "description": "" }, "description": "" }, "custom_definitions": { "type": "array", "items": { "$ref": "#/components/schemas/CustomSelection" }, "description": "Full replacement of definition selections; [] removes selections. Does not delete definitions.", "maxItems": 1000 }, "data_risk_action": { "type": "string", "description": "Adversarial detections do not expose redactable spans; incompatible actions are rejected by catalog validation.", "enum": [ "monitor", "partial-redact", "redact", "block" ] }, "edm_pattern_sensitivities": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "low", "medium", "high" ] }, "description": "" }, "enabled_categories": { "type": "object", "additionalProperties": { "type": "boolean", "description": "" }, "description": "Catalog category/subcategory IDs mapped to enabled state. Unknown selectors are rejected." }, "guardian_agent": { "$ref": "#/components/schemas/Guardian" }, "hallucination_check_action": { "type": "string", "enum": [ "block", "monitor" ] }, "hallucination_check_risk_level": { "type": "string" }, "hallucination_check_score_threshold": { "type": "number", "minimum": 0, "maximum": 1 }, "is_hallucination_check_enabled": { "type": "boolean" }, "scan_encoded_images": { "type": "boolean" }, "scan_encoded_images_scope": { "type": "string", "enum": [ "request", "response", "both" ] }, "scan_images": { "type": "boolean" }, "scan_images_scope": { "type": "string", "enum": [ "request", "response", "both" ] }, "sub_category_actions": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "string", "description": "Adversarial detections do not expose redactable spans; incompatible actions are rejected by catalog validation.", "enum": [ "monitor", "partial-redact", "redact", "block" ] }, "description": "" }, "description": "Category ID to subcategory name to action." }, "sub_category_sensitivities": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "low", "medium", "high" ] } } } }, "additionalProperties": false }, "limits": { "type": "object", "properties": { "concurrency_per_minute": { "type": [ "integer", "null" ], "minimum": 0 }, "model_rate_limits": { "type": "array", "items": { "$ref": "#/components/schemas/ModelLimit" } }, "rate_limit": { "anyOf": [ { "$ref": "#/components/schemas/RateLimit" }, { "type": "null" } ] }, "rate_limit_per_minute": { "type": "integer", "minimum": 0 }, "timeout": { "type": [ "integer", "null" ], "minimum": 0 }, "token_limits": { "$ref": "#/components/schemas/TokenLimits" } }, "additionalProperties": false }, "routing": { "type": "object", "properties": { "custom_routing": { "type": "array", "items": { "$ref": "#/components/schemas/ContextRoute" } }, "routing_groups": { "type": "array", "items": { "$ref": "#/components/schemas/RoutingGroup" } }, "routing_thresholds": { "type": "object", "properties": { "low_max_words": { "type": "integer", "minimum": 0 }, "medium_max_words": { "type": "integer", "minimum": 0 } }, "additionalProperties": false, "required": [ "low_max_words", "medium_max_words" ], "description": "0 <= low_max_words <= medium_max_words." }, "token_based_routing_groups": { "type": "array", "items": { "$ref": "#/components/schemas/RoutingGroup" } } }, "additionalProperties": false }, "access": { "type": "object", "properties": { "allowed_source_ips": { "oneOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "object", "properties": { "enabled": { "type": "boolean" }, "ips": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, { "type": "null" } ] }, "allowed_user_domains": { "type": "array", "items": { "type": "string" }, "maxItems": 1000 }, "allowed_user_emails": { "type": "array", "items": { "type": "string" }, "maxItems": 1000 }, "enforce_conversation_id": { "type": "boolean" }, "enforce_identity": { "type": "boolean" }, "identity_header_mode": { "type": "boolean" }, "identity_token_headers": { "type": "array", "items": { "type": "string" }, "maxItems": 1000 }, "identity_token_oid_fallback": { "type": "boolean" }, "jwt_auth": { "anyOf": [ { "$ref": "#/components/schemas/JwtAuth" }, { "type": "null" } ] } }, "additionalProperties": false }, "transformations": { "type": "object", "properties": { "token_saving": { "$ref": "#/components/schemas/TokenSaving" } }, "additionalProperties": false }, "self_service": { "type": "object", "properties": { "enable_self_service": { "type": "boolean" }, "self_service": { "type": "object", "properties": { "access_control": { "anyOf": [ { "type": "object", "properties": { "version": { "type": "integer", "const": 1 }, "self_service_viewer": { "$ref": "#/components/schemas/AccessRule" }, "settings_update_requester": { "$ref": "#/components/schemas/AccessRule" }, "settings_update_direct": { "$ref": "#/components/schemas/AccessRule" }, "show_api_key": { "$ref": "#/components/schemas/AccessRule" }, "show_logs_for_all_users": { "$ref": "#/components/schemas/AccessRule" } }, "additionalProperties": true, "description": "" }, { "type": "null" } ] } }, "additionalProperties": true, "description": "Stored self-service configuration. Access-control roles live inside this object. Omit to preserve; the section itself does not accept null." } }, "additionalProperties": false }, "prompts": { "type": "object", "properties": { "require_system_from_store": { "type": "boolean" } }, "additionalProperties": false }, "enabled": { "type": "boolean" }, "smart_group_policies": { "type": "array", "items": { "$ref": "#/components/schemas/GroupPolicy" } }, "alerting": { "anyOf": [ { "$ref": "#/components/schemas/Alerting" }, { "type": "null" } ] }, "provider_labels": { "type": "array", "items": { "type": "string" }, "maxItems": 1000 }, "tags": { "type": "array", "items": { "type": "string" }, "maxItems": 1000 } }, "additionalProperties": false, "description": "Stored app settings. Omitted fields are preserved. Unknown top-level and section fields are rejected. Nested controls follow the existing gateway validators. Responses report settings that are inactive under QuilrQL." }, "GatewayKeyCreate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": false, "required": [ "name" ] }, "GatewayKeyPatch": { "type": "object", "properties": { "expires_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": false, "required": [ "expires_at" ] }, "ManagementKeyCreate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "scopes": { "type": "array", "items": { "enum": [ "config:write", "credentials:read", "credentials:write", "providers:write", "read" ], "type": "string" }, "minItems": 1 } }, "additionalProperties": false, "required": [ "name", "scopes" ] }, "Provider": { "type": "object", "properties": { "label": { "type": "string" }, "provider_name": { "type": "string", "enum": [ "openai", "azureopenai", "general", "quilr_ai", "anthropic", "anthropic_messages", "anthropic_messages_bedrock", "anthropic_messages_azure", "deepseek", "vertex_ai", "gemini_chatcompletions", "oracle", "openai_responses", "openai_responses_azure", "oracle_responses", "openai_assistants", "openai_assistants_azure", "openai_realtime", "openai_realtime_azure", "bedrock", "bedrock_embeddings", "cohere_rerank", "bedrock_rerank", "jina_rerank", "voyage_rerank", "general_rerank", "sarvam" ] }, "provider_settings": { "$ref": "#/components/schemas/ProviderSettings" }, "selected_models": { "type": "array", "items": { "type": "string" }, "maxItems": 1000 }, "model_costs": { "type": "object", "additionalProperties": { "anyOf": [ { "$ref": "#/components/schemas/ModelCost" }, { "type": "null" } ] } }, "enabled": { "type": "boolean" } }, "additionalProperties": false, "description": "Shared-provider configuration. Creation requires label and provider_name plus credentials for that type. Label and provider type are immutable. Saves never probe upstream." }, "Prompt": { "type": "object", "properties": { "content": { "type": "string", "minLength": 1 } }, "additionalProperties": false, "required": [ "content" ], "description": "Nonempty prompt content. The complete JSON request is limited to 1 MiB. Creation, replacement and deletion use the current app ETag." }, "Attachment": { "type": "object", "properties": { "primary": { "type": "boolean", "default": false } }, "additionalProperties": false }, "Conversion": { "type": "object", "properties": { "provider_labels": { "type": "array", "items": { "type": "string" }, "maxItems": 1000 }, "routing": { "type": "object", "properties": { "custom_routing": { "type": "array", "items": { "$ref": "#/components/schemas/ContextRoute" } }, "routing_groups": { "type": "array", "items": { "$ref": "#/components/schemas/RoutingGroup" } }, "routing_thresholds": { "type": "object", "properties": { "low_max_words": { "type": "integer", "minimum": 0 }, "medium_max_words": { "type": "integer", "minimum": 0 } }, "additionalProperties": false, "required": [ "low_max_words", "medium_max_words" ], "description": "0 <= low_max_words <= medium_max_words." }, "token_based_routing_groups": { "type": "array", "items": { "$ref": "#/components/schemas/RoutingGroup" } } }, "additionalProperties": false } }, "additionalProperties": false, "required": [ "provider_labels" ] }, "TenantSettings": { "type": "object", "properties": { "enabled": { "type": "boolean" } }, "additionalProperties": false, "required": [ "enabled" ] }, "ProviderTest": { "type": "object", "properties": { "kind": { "enum": [ "connection", "model" ], "type": "string", "description": "Model tests support the provider types advertised by capabilities. Connection-only tests are Not Generally Available and return unsupported_test_kind." }, "model": { "type": "string" } }, "additionalProperties": false, "required": [ "kind" ] }, "Empty": { "type": "object", "properties": {}, "additionalProperties": false }, "ManagementKeyPatch": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "scopes": { "type": "array", "items": { "enum": [ "config:write", "credentials:read", "credentials:write", "providers:write", "read" ], "type": "string" }, "minItems": 1 } }, "additionalProperties": false }, "RateLimit": { "type": "object", "properties": { "value": { "type": "integer", "description": "Maximum events in the window; zero disables this limit.", "minimum": 0 }, "duration": { "type": "string", "enum": [ "minute", "hour", "day" ] } }, "additionalProperties": true, "description": "App request rate: value and duration are required; zero disables this limit.", "required": [ "value", "duration" ] }, "TokenLimits": { "type": "object", "properties": { "max_per_request": { "anyOf": [ { "type": "integer", "description": "Maximum input tokens per request; zero disables.", "minimum": 0 }, { "type": "null" } ], "description": "Maximum input tokens per request; zero disables." }, "input": { "anyOf": [ { "$ref": "#/components/schemas/RateLimit" }, { "type": "null" } ], "description": "" }, "output": { "anyOf": [ { "$ref": "#/components/schemas/RateLimit" }, { "type": "null" } ], "description": "" } }, "additionalProperties": true, "description": "" }, "ModelLimit": { "type": "object", "properties": { "provider_label": { "type": "string", "description": "Exact, trimmed tenant-wide provider label. Immutable after creation.", "minLength": 1, "maxLength": 200 }, "model": { "type": "string", "description": "Exact configured model identifier; availability depends on the provider and deployment.", "minLength": 1, "maxLength": 512 }, "timeout": { "anyOf": [ { "type": "number", "description": "Seconds.", "minimum": 0 }, { "type": "null" } ], "description": "Seconds." }, "concurrency_per_minute": { "anyOf": [ { "type": "integer", "description": "Request admissions per 60 seconds, following existing gateway semantics.", "minimum": 0 }, { "type": "null" } ], "description": "Request admissions per 60 seconds, following existing gateway semantics." }, "rate_limit": { "anyOf": [ { "$ref": "#/components/schemas/RateLimit" }, { "type": "null" } ], "description": "" }, "token_limits": { "anyOf": [ { "$ref": "#/components/schemas/TokenLimits" }, { "type": "null" } ], "description": "" } }, "additionalProperties": true, "description": "", "required": [ "provider_label", "model" ] }, "CustomSelection": { "type": "object", "properties": { "definition_id": { "type": "string", "description": "Stable ID from GET /custom-definitions.", "minLength": 1, "maxLength": 200 }, "enabled": { "type": "boolean", "description": "", "default": true }, "action": { "type": "string", "description": "Adversarial detections do not expose redactable spans; incompatible actions are rejected by catalog validation.", "enum": [ "monitor", "partial-redact", "redact", "block" ] }, "scope": { "type": "string", "enum": [ "request", "response", "both" ] }, "sensitivity": { "type": "string", "enum": [ "low", "medium", "high" ] } }, "additionalProperties": false, "description": "Select or configure an existing definition. Regex, EDM rows, semantic examples and intent definitions are not accepted.", "required": [ "definition_id" ] }, "Guardian": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "" }, "coding_helpers": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "" }, "dependency_security_check": { "type": "boolean", "description": "" }, "latest_version_suggestions": { "type": "boolean", "description": "" } }, "additionalProperties": true, "description": "" }, "task_adherence": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "" }, "action": { "type": "string", "enum": [ "nudge", "block" ] }, "sensitivity": { "type": "string", "enum": [ "low", "medium", "high" ] }, "agent_purpose": { "type": "string" }, "guardian_agent_prompt": { "type": "string" } }, "additionalProperties": true, "description": "" } }, "additionalProperties": true, "description": "Partial update of Guardian branches. Set a branch enabled:false to disable it. Model-backed checks follow deployment capability." }, "AccessRule": { "type": "object", "properties": { "allow_all": { "type": "boolean", "description": "", "default": false }, "allow_emails": { "type": "array", "items": { "type": "string", "format": "email" }, "description": "", "uniqueItems": true }, "deny_emails": { "type": "array", "items": { "type": "string", "format": "email" }, "description": "", "uniqueItems": true }, "allow_smart_groups": { "type": "array", "items": { "type": "string", "description": "Existing gateway smart-group name.", "minLength": 1 }, "description": "", "uniqueItems": true }, "deny_smart_groups": { "type": "array", "items": { "type": "string", "description": "Existing gateway smart-group name.", "minLength": 1 }, "description": "", "uniqueItems": true } }, "additionalProperties": true, "description": "Deny rules win. A group reference never changes group membership." }, "TokenSaving": { "type": "object", "properties": { "smart_json_compression": { "type": "boolean", "description": "" }, "html_to_text": { "type": "boolean", "description": "" }, "markdown_to_text": { "type": "boolean", "description": "" }, "text_compression": { "type": "boolean", "description": "" } }, "additionalProperties": false, "description": "" }, "AlertRule": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "", "default": false }, "window_minutes": { "type": "integer", "description": "", "minimum": 5, "maximum": 1440, "default": 15 }, "failure_rate_threshold": { "type": "number", "description": "Percentage.", "minimum": 0, "maximum": 100, "default": 10 }, "minimum_requests": { "type": "integer", "description": "", "minimum": 0, "default": 20 }, "cooldown_minutes": { "type": "integer", "description": "", "minimum": 1, "default": 10 }, "notify_on_recovery": { "type": "boolean", "description": "", "default": true } }, "additionalProperties": true, "description": "" }, "Alerting": { "type": "object", "properties": { "app_level": { "$ref": "#/components/schemas/AlertRule" }, "provider_level": { "$ref": "#/components/schemas/AlertRule" }, "channels": { "type": "object", "properties": { "emails": { "type": "array", "items": { "type": "string", "format": "email" }, "description": "", "uniqueItems": true }, "webhooks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "slack", "generic" ], "default": "generic" }, "label": { "type": "string" }, "url": { "type": "string", "description": "HTTPS webhook URL, required for each submitted webhook. Omit the whole alerting field to preserve stored configuration.", "format": "uri", "writeOnly": true } }, "additionalProperties": true, "description": "", "required": [ "url" ] }, "description": "" } }, "additionalProperties": true, "description": "" } }, "additionalProperties": true, "description": "Submitted alerting configuration is normalized as a complete configuration, not merged with stored webhook secrets. Include each webhook URL when updating alerting; null clears alerting." }, "ModelCost": { "type": "object", "properties": { "input_per_1m": { "anyOf": [ { "type": "number", "description": "USD per million tokens; null removes this override.", "minimum": 0 }, { "type": "null" } ], "description": "USD per million tokens; null removes this override." }, "output_per_1m": { "anyOf": [ { "type": "number", "description": "USD per million tokens; null removes this override.", "minimum": 0 }, { "type": "null" } ], "description": "USD per million tokens; null removes this override." }, "cache_per_1m": { "anyOf": [ { "type": "number", "description": "USD per million tokens; null removes this override.", "minimum": 0 }, { "type": "null" } ], "description": "USD per million tokens; null removes this override." } }, "additionalProperties": false, "description": "" }, "JwtAuth": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "allowed_issuers": { "type": "array", "items": { "type": "string" } }, "allowed_client_ids": { "type": "array", "items": { "type": "string" } }, "public_key_pem": { "type": "string", "description": "RSA public key in PEM format. Required for an enabled configuration; saves do not fetch JWKS URLs." }, "kid": { "type": "string" } }, "additionalProperties": false, "description": "null, {}, or enabled:false disables JWT authentication. Enabling requires nonempty issuer/client-ID lists and an RSA public_key_pem." }, "GroupPolicy": { "type": "object", "properties": { "enabled_categories": { "type": "object", "additionalProperties": { "type": "boolean", "description": "" }, "description": "Catalog category/subcategory IDs mapped to enabled state. Unknown selectors are rejected." }, "category_actions": { "type": "object", "additionalProperties": { "type": "string", "description": "Adversarial detections do not expose redactable spans; incompatible actions are rejected by catalog validation.", "enum": [ "monitor", "partial-redact", "redact", "block" ] }, "description": "Category ID to action." }, "sub_category_actions": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "string", "description": "Adversarial detections do not expose redactable spans; incompatible actions are rejected by catalog validation.", "enum": [ "monitor", "partial-redact", "redact", "block" ] }, "description": "" }, "description": "Category ID to subcategory name to action." }, "category_scopes": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "request", "response", "both" ] }, "description": "" }, "category_sensitivities": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string", "enum": [ "low", "medium", "high" ] }, "description": "" }, "description": "" }, "group_name": { "type": "string" }, "enabled": { "type": "boolean" }, "actions": { "type": "object", "properties": { "data_risk_action": { "type": "string", "description": "Adversarial detections do not expose redactable spans; incompatible actions are rejected by catalog validation.", "enum": [ "monitor", "partial-redact", "redact", "block" ] }, "hallucination_check_action": { "type": "string", "enum": [ "block", "monitor" ] } }, "additionalProperties": true }, "sub_category_sensitivities": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "low", "medium", "high" ] } } } }, "additionalProperties": false, "required": [ "group_name" ] }, "RoutingModel": { "type": "object", "properties": { "provider_name": { "type": "string" }, "model_name": { "type": "string" }, "credential_source": { "type": "string", "description": "Attached shared-provider label; no inline credentials." }, "weight": { "type": "number", "exclusiveMinimum": 0 } }, "additionalProperties": true, "required": [ "provider_name", "model_name", "weight" ] }, "RoutingGroup": { "type": "object", "properties": { "group_name": { "type": "string" }, "group_kind": { "type": "string", "enum": [ "chat_completion", "anthropic_messages", "vertex_ai", "responses", "realtime", "bedrock_runtime" ] }, "models": { "type": "array", "items": { "$ref": "#/components/schemas/RoutingModel" }, "minItems": 1 } }, "additionalProperties": true, "required": [ "group_name", "models" ], "description": "Model weights sum to 100. Models and provider types must support the group protocol. Request and token groups use separate lists." }, "ContextRoute": { "type": "object", "properties": { "group": { "type": "string", "enum": [ "chat_completion", "anthropic_messages", "vertex_ai", "responses", "bedrock_runtime" ] }, "type": { "type": "string", "enum": [ "Low_Context_Request", "Medium_Context_Request", "High_Context_Request" ] }, "is_published": { "type": "boolean" }, "models": { "type": "array", "items": { "type": "object", "properties": { "provider_name": { "type": "string" }, "model": { "type": "string" }, "label": { "type": "string" }, "credential_source": { "type": "string" } }, "additionalProperties": true, "required": [ "provider_name", "model" ] } } }, "additionalProperties": true, "required": [ "type", "is_published", "models" ], "description": "A context route uses the existing gateway routing format. Published routes require at least one configured model. Omitted group defaults to chat_completion." }, "ProviderSettings": { "type": "object", "properties": { "anthropic_version": { "type": "string", "description": "Optional Anthropic API version header." }, "api_key": { "type": "string", "description": "Write-only secret. Omission preserves an existing secret on PATCH. Never echo redacted placeholders.", "minLength": 1, "writeOnly": true }, "auth_type": { "type": "string", "enum": [ "api_key", "express", "service_account", "adc", "gateway_user_principal", "user_principal", "session_principal", "instance_principal", "resource_principal" ] }, "aws_access_key": { "type": "string", "description": "Write-only secret. Omission preserves an existing secret on PATCH. Never echo redacted placeholders.", "minLength": 1, "writeOnly": true }, "aws_auth_mode": { "type": "string", "enum": [ "static", "assume_role" ] }, "aws_external_id": { "type": "string", "description": "Write-only secret. Omission preserves an existing secret on PATCH. Never echo redacted placeholders.", "minLength": 1, "writeOnly": true }, "aws_region": { "type": "string", "minLength": 1 }, "aws_role_arn": { "type": "string", "minLength": 1 }, "aws_role_session_name": { "type": "string", "minLength": 2, "maxLength": 64 }, "aws_secret_key": { "type": "string", "description": "Write-only secret. Omission preserves an existing secret on PATCH. Never echo redacted placeholders.", "minLength": 1, "writeOnly": true }, "aws_session_duration_seconds": { "type": "integer", "description": "", "minimum": 900, "maximum": 43200 }, "aws_session_token": { "type": "string", "description": "Write-only secret. Omission preserves an existing secret on PATCH. Never echo redacted placeholders.", "minLength": 1, "writeOnly": true }, "azure_api_version": { "type": "string", "description": "Azure API version." }, "azure_endpoint": { "type": "string", "format": "uri" }, "base_url": { "type": "string", "format": "uri" }, "gcp_project_id": { "type": "string", "minLength": 1 }, "gcp_region": { "type": "string" }, "oci_compartment_id": { "type": "string", "minLength": 1 }, "oci_fingerprint": { "type": "string", "minLength": 1 }, "oci_private_key": { "type": "string", "description": "Write-only secret. Omission preserves an existing secret on PATCH. Never echo redacted placeholders.", "minLength": 1, "writeOnly": true }, "oci_private_key_passphrase": { "type": "string", "description": "Write-only secret. Omission preserves an existing secret on PATCH. Never echo redacted placeholders.", "minLength": 1, "writeOnly": true }, "oci_project_id": { "type": "string", "minLength": 1 }, "oci_region": { "type": "string", "minLength": 1 }, "oci_session_token": { "type": "string", "description": "Write-only secret. Omission preserves an existing secret on PATCH. Never echo redacted placeholders.", "minLength": 1, "writeOnly": true }, "oci_tenancy_id": { "type": "string", "minLength": 1 }, "oci_user_id": { "type": "string", "minLength": 1 }, "service_account_json": { "type": "string", "description": "JSON-encoded Google service account document.", "minLength": 1, "writeOnly": true } }, "additionalProperties": false, "description": "Supply fields for the chosen provider type. Omitted PATCH credentials are preserved. Azure uses azure_api_version. Provider-specific required credentials are validated against the merged configuration." }, "ProviderCreate": { "type": "object", "properties": { "label": { "type": "string" }, "provider_name": { "type": "string", "enum": [ "openai", "azureopenai", "general", "quilr_ai", "anthropic", "anthropic_messages", "anthropic_messages_bedrock", "anthropic_messages_azure", "deepseek", "vertex_ai", "gemini_chatcompletions", "oracle", "openai_responses", "openai_responses_azure", "oracle_responses", "openai_assistants", "openai_assistants_azure", "openai_realtime", "openai_realtime_azure", "bedrock", "bedrock_embeddings", "cohere_rerank", "bedrock_rerank", "jina_rerank", "voyage_rerank", "general_rerank", "sarvam" ] }, "provider_settings": { "$ref": "#/components/schemas/ProviderSettings" }, "selected_models": { "type": "array", "items": { "type": "string" }, "maxItems": 1000 }, "model_costs": { "type": "object", "additionalProperties": { "anyOf": [ { "$ref": "#/components/schemas/ModelCost" }, { "type": "null" } ] } }, "enabled": { "type": "boolean" } }, "additionalProperties": false, "description": "Shared-provider configuration. Creation requires label and provider_name plus credentials for that type. Label and provider type are immutable. Saves never probe upstream.", "required": [ "label", "provider_name" ] }, "ProviderPatch": { "type": "object", "properties": { "label": { "type": "string" }, "provider_name": { "type": "string", "enum": [ "openai", "azureopenai", "general", "quilr_ai", "anthropic", "anthropic_messages", "anthropic_messages_bedrock", "anthropic_messages_azure", "deepseek", "vertex_ai", "gemini_chatcompletions", "oracle", "openai_responses", "openai_responses_azure", "oracle_responses", "openai_assistants", "openai_assistants_azure", "openai_realtime", "openai_realtime_azure", "bedrock", "bedrock_embeddings", "cohere_rerank", "bedrock_rerank", "jina_rerank", "voyage_rerank", "general_rerank", "sarvam" ] }, "provider_settings": { "$ref": "#/components/schemas/ProviderSettings" }, "selected_models": { "type": "array", "items": { "type": "string" }, "maxItems": 1000 }, "model_costs": { "type": "object", "additionalProperties": { "anyOf": [ { "$ref": "#/components/schemas/ModelCost" }, { "type": "null" } ] } }, "enabled": { "type": "boolean" } }, "additionalProperties": false, "description": "Shared-provider configuration. Creation requires label and provider_name plus credentials for that type. Label and provider type are immutable. Saves never probe upstream." }, "PolicyAuthority": { "type": "object", "properties": { "enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "active_revision": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "active_checksum": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": true }, "AppView": { "type": "object", "properties": { "detection": { "type": "object", "description": "Stored controls; secret fields are redacted." }, "limits": { "type": "object", "description": "Stored controls; secret fields are redacted." }, "routing": { "type": "object", "description": "Stored controls; secret fields are redacted." }, "access": { "type": "object", "description": "Stored controls; secret fields are redacted." }, "transformations": { "type": "object", "description": "Stored controls; secret fields are redacted." }, "self_service": { "type": "object", "description": "Stored controls; secret fields are redacted." }, "prompts": { "type": "object", "description": "Stored controls; secret fields are redacted." }, "name": { "type": "string" }, "mode": { "type": "string", "enum": [ "gateway", "sdk", "copilot_studio" ] }, "enabled": { "type": "boolean" }, "provider_labels": { "type": "array", "items": { "type": "string" } }, "provider_mode": { "type": "string", "enum": [ "shared", "inline" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "version": { "type": "string", "description": "Opaque resource version. Send its quoted value in If-Match." }, "policy_authority": { "$ref": "#/components/schemas/PolicyAuthority" }, "alerting": { "type": "object" }, "smart_group_policies": { "type": "array", "items": { "type": "object" } } }, "additionalProperties": true, "required": [ "name", "mode", "enabled", "version" ] }, "Warning": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "fields": { "type": "array", "items": { "type": "string" } }, "active_revision": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, "additionalProperties": true, "required": [ "code", "message" ] }, "GatewayKey": { "type": "object", "properties": { "key_id": { "type": "string" }, "name": { "type": "string" }, "created_at": { "type": "string" }, "expires_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "active", "expired", "revoked" ] }, "fingerprint": { "type": "string" }, "secret": { "type": "string", "description": "Present only on issuance and explicit active-key reveal." } }, "additionalProperties": true, "required": [ "key_id", "name", "status", "expires_at", "fingerprint" ] }, "ManagementKey": { "type": "object", "properties": { "key_id": { "type": "string" }, "tenant": { "type": "string" }, "name": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "config:write", "credentials:read", "credentials:write", "providers:write", "read" ] } }, "created_at": { "type": "number", "description": "Unix epoch seconds, potentially fractional." }, "expires_at": { "anyOf": [ { "type": "number", "description": "Unix epoch seconds, potentially fractional." }, { "type": "null" } ] }, "revoked_at": { "anyOf": [ { "type": "number", "description": "Unix epoch seconds, potentially fractional." }, { "type": "null" } ] }, "created_by": { "type": "string" }, "last_used_at": { "anyOf": [ { "type": "number", "description": "Unix epoch seconds, potentially fractional." }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "active", "expired", "revoked" ] }, "version": { "type": "string", "description": "Opaque resource version. Send its quoted value in If-Match." }, "secret": { "type": "string", "description": "Issuance response only, including its authorized idempotent replay." } }, "additionalProperties": true, "required": [ "key_id", "tenant", "name", "scopes", "status", "version" ] }, "ProviderView": { "type": "object", "properties": { "provider_id": { "type": "string" }, "label": { "type": "string" }, "provider_name": { "type": "string" }, "selected_models": { "type": "array", "items": { "type": "string" } }, "model_costs": { "type": "object" }, "enabled": { "type": "boolean" }, "is_active": { "type": "boolean" }, "version": { "type": "string", "description": "Opaque resource version. Send its quoted value in If-Match." }, "credential_configured": { "type": "boolean" }, "connection": { "type": "object", "description": "Allowlisted connection metadata. Provider secrets are omitted." } }, "additionalProperties": true, "required": [ "label", "provider_name", "version", "credential_configured" ] }, "VersionRecord": { "type": "object", "properties": { "version_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "version": {}, "changed_at": {}, "operation": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "actor_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "actor_user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "actor_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "previous_config": { "type": "object" }, "new_config": { "type": "object" } }, "additionalProperties": true }, "AuditEvent": { "type": "object", "properties": { "event_id": { "type": "string" }, "actor": { "type": "string" }, "operation": { "type": "string" }, "resource": { "type": "string" }, "request_id": { "type": "string" }, "result": { "type": "string" }, "created_at": { "type": "number", "description": "Unix epoch seconds, potentially fractional." }, "changes": { "type": "object" } }, "additionalProperties": true }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "operation_id": { "type": "string" }, "fields": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": true, "required": [ "code", "message" ] }, "request_id": { "type": "string" } }, "additionalProperties": true, "required": [ "error", "request_id" ] } }, "securitySchemes": { "ManagementKey": { "type": "http", "scheme": "bearer", "bearerFormat": "qlmgmt_" }, "TenantAdminJWT": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Verified Quilr JWT with the selected tenant in tenantIds, an Admin or Super Admin role, and an identifying sub, userId or email." } } }, "tags": [ { "name": "Apps" }, { "name": "Providers" }, { "name": "Credentials" }, { "name": "Administration" }, { "name": "Prompts" }, { "name": "Catalogs" }, { "name": "History" }, { "name": "Reference" } ], "x-not-generally-available": [ "Policy authoring schema/catalog/search, suggested policies, validation/simulation and conversion preview", "Policy draft/revision lifecycle, publishing, rollback and authority changes", "policy:write and policy:publish management scopes", "App rename/deletion and shared-provider deletion", "Custom-definition authoring and smart-group/membership writes", "Dedicated key rotation and per-management-key pause/resume", "Later management-key secret retrieval and expired/revoked gateway-key reveal", "Connection-only provider tests", "Create-only prompt preconditions", "Provider filters, catalog search and audit app/key/operation/time filters", "App-restricted management keys and management traffic/usage/health/red-team APIs" ], "servers": [ { "url": "https://management.example.com", "description": "Replace with your central management origin." } ] }