{ "openapi": "3.1.2", "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema", "info": { "title": "Agent Platform Control Plane API", "version": "1.0-r2", "description": "First supported Control Plane management API. R2 is the product release; v1 is the independent API major. The stable public component mount is /control-plane. Agent catalog and A2A invocation are separate APIs.", "x-contract-status": "r2-target-accepted-by-ADR-0002-ADR-0003-ADR-0004" }, "servers": [{"url": "/control-plane"}], "security": [{"bearerAuth": []}], "x-authorization-projection-policy": { "operationRequesterGate": "Every newly created Operation is hidden, cannot start its Workflow, and cannot produce a 2xx/202 response until operation:{operationId}#requester is confirmed by SpiceDB and its consistency token is persisted.", "apiKeyOwnerGate": "New keys additionally require confirmed api_key:{keyId}#owner before apply or any 2xx/oneTimeSecret response.", "retry": "The durable PostgreSQL Operation intent and allocated IDs are reused by an exact Idempotency-Key replay.", "failureMode": "Authorization projection timeout or outage fails closed without worker apply, partial data, or secret disclosure." }, "paths": { "/api/v1/activity/llm/requests": {"get":{"operationId":"getActivityLlmRequestsV1","summary":"Read authorized Activity requests","description":"Metadata only. Current permissions and retention are rechecked on each page. Cursor binds the query and observation; page size may change. Options omit their target dimension filter and return observed values without counts; q is a literal substring of safe label or identity.","x-authorization-resource":"activity:current-authorized-resources","x-authorization-permission":"control_plane#administer OR api_key#activity_read OR agent#activity_diagnose","parameters":[{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Optional pair with to; UTC start-inclusive. Defaults to the last 24 hours at the observation cutoff."},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"End-exclusive, no later than server time. Both from and to are required when either is supplied."},{"name":"observation","in":"query","required":false,"schema":{"type":"string","maxLength":2048},"description":"Caller-bound ingestion cutoff, expires after 1 hour; rights and retention are checked again."},{"name":"agentId","in":"query","required":false,"schema":{"type":"array","items":{"type":"string","format":"uuid","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"maxItems":50},"style":"form","explode":true},{"name":"agentVersionId","in":"query","required":false,"schema":{"type":"array","items":{"type":"string","format":"uuid","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"maxItems":50},"style":"form","explode":true},{"name":"ownership","in":"query","required":false,"schema":{"enum":["all","mine"],"default":"all"},"description":"Mine means direct key ownership, never the caller of an opaque Agent."},{"name":"keyId","in":"query","required":false,"schema":{"type":"array","items":{"type":"string","format":"uuid","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"maxItems":50},"style":"form","explode":true},{"name":"modelId","in":"query","required":false,"schema":{"type":"array","items":{"type":"string","format":"uuid","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"maxItems":50},"style":"form","explode":true},{"name":"finalProviderId","in":"query","required":false,"schema":{"type":"array","items":{"type":"string","format":"uuid","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"maxItems":50},"style":"form","explode":true},{"name":"attemptProviderId","in":"query","required":false,"schema":{"type":"array","items":{"type":"string","format":"uuid","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"maxItems":50},"style":"form","explode":true},{"name":"outcome","in":"query","required":false,"schema":{"type":"array","items":{"enum":["success","rejected","error","cancelled","unknown"]},"maxItems":50},"style":"form","explode":true},{"name":"reasonCode","in":"query","required":false,"schema":{"type":"array","items":{"enum":["none","invalid_key","unauthenticated","forbidden","rate_limited","model_not_found","gateway_dependency_unavailable","upstream_error","upstream_timeout","transport_error","client_cancelled","termination_unknown"]},"maxItems":50},"style":"form","explode":true},{"name":"ownerType","in":"query","required":false,"schema":{"enum":["principal","service","agent"]},"description":"Exact typed owner in diagnostic/mine scope; supply its complete identity tuple."},{"name":"ownerIssuer","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":2048}},{"name":"ownerSubject","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":512}},{"name":"ownerAgentId","in":"query","required":false,"schema":{"type":"string","format":"uuid","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"}},{"name":"requestId","in":"query","required":false,"schema":{"type":"string","pattern":"^[0-9a-f]{64}$"},"description":"Diagnostic/mine scope only."},{"name":"traceId","in":"query","required":false,"schema":{"type":"string","pattern":"^[0-9a-f]{32}$"},"description":"Diagnostic/mine scope only."},{"name":"unknown","in":"query","required":false,"schema":{"type":"array","items":{"enum":["keyId","keyOwner","agentId","agentVersionId","modelId","finalProviderId","attemptProviderId"]},"maxItems":50},"style":"form","explode":true,"description":"OR with explicit values of the same nullable dimension."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","maxLength":2048},"description":"Opaque authenticated keyset cursor; repeats the original query, retains the original cutoff and never preserves revoked access."},{"name":"sort","in":"query","required":false,"schema":{"enum":["startedAt","-startedAt","durationMs","-durationMs"],"default":"-startedAt"},"description":"Request ID breaks ties in the same direction. Unknown durations sort last."}],"responses":{"200":{"description":"Authorized metadata collection and opaque next cursor; null marks the end.","headers":{"Cache-Control":{"schema":{"const":"private, no-store"}}},"content":{"application/json":{"schema":{"$ref":"../schemas/activity-collections-v1.schema.json#/$defs/LlmRequests"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"503":{"$ref":"#/components/responses/AuthorizationUnavailable"},"422":{"description":"Requested history expired, or query/current authority scope is too large.","content":{"application/json":{"schema":{"$ref":"../schemas/error-v1.schema.json"}}}},"429":{"description":"Management request limit reached; retry after the indicated interval.","content":{"application/json":{"schema":{"$ref":"../schemas/error-v1.schema.json"}}},"headers":{"Retry-After":{"schema":{"type":"integer","minimum":1}}}}}}}, "/api/v1/activity/llm/filter-options": {"get":{"operationId":"getActivityLlmFilterOptionsV1","summary":"Read authorized Activity filter-options","description":"Metadata only. Current permissions and retention are rechecked on each page. Cursor binds the query and observation; page size may change. Options omit their target dimension filter and return observed values without counts; q is a literal substring of safe label or identity.","x-authorization-resource":"activity:current-authorized-resources","x-authorization-permission":"control_plane#administer OR agent#activity_aggregate OR api_key#activity_read OR agent#activity_diagnose","parameters":[{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Optional pair with to; UTC start-inclusive. Defaults to the last 24 hours at the observation cutoff."},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"End-exclusive, no later than server time. Both from and to are required when either is supplied."},{"name":"observation","in":"query","required":false,"schema":{"type":"string","maxLength":2048},"description":"Caller-bound ingestion cutoff, expires after 1 hour; rights and retention are checked again."},{"name":"agentId","in":"query","required":false,"schema":{"type":"array","items":{"type":"string","format":"uuid","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"maxItems":50},"style":"form","explode":true},{"name":"agentVersionId","in":"query","required":false,"schema":{"type":"array","items":{"type":"string","format":"uuid","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"maxItems":50},"style":"form","explode":true},{"name":"access","in":"query","required":false,"schema":{"enum":["aggregate","diagnostic"],"default":"aggregate"}},{"name":"ownership","in":"query","required":false,"schema":{"enum":["all","mine"],"default":"all"},"description":"Mine means direct key ownership, never the caller of an opaque Agent."},{"name":"keyId","in":"query","required":false,"schema":{"type":"array","items":{"type":"string","format":"uuid","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"maxItems":50},"style":"form","explode":true},{"name":"modelId","in":"query","required":false,"schema":{"type":"array","items":{"type":"string","format":"uuid","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"maxItems":50},"style":"form","explode":true},{"name":"finalProviderId","in":"query","required":false,"schema":{"type":"array","items":{"type":"string","format":"uuid","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"maxItems":50},"style":"form","explode":true},{"name":"attemptProviderId","in":"query","required":false,"schema":{"type":"array","items":{"type":"string","format":"uuid","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"maxItems":50},"style":"form","explode":true},{"name":"outcome","in":"query","required":false,"schema":{"type":"array","items":{"enum":["success","rejected","error","cancelled","unknown"]},"maxItems":50},"style":"form","explode":true},{"name":"reasonCode","in":"query","required":false,"schema":{"type":"array","items":{"enum":["none","invalid_key","unauthenticated","forbidden","rate_limited","model_not_found","gateway_dependency_unavailable","upstream_error","upstream_timeout","transport_error","client_cancelled","termination_unknown"]},"maxItems":50},"style":"form","explode":true},{"name":"ownerType","in":"query","required":false,"schema":{"enum":["principal","service","agent"]},"description":"Exact typed owner in diagnostic/mine scope; supply its complete identity tuple."},{"name":"ownerIssuer","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":2048}},{"name":"ownerSubject","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":512}},{"name":"ownerAgentId","in":"query","required":false,"schema":{"type":"string","format":"uuid","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"}},{"name":"requestId","in":"query","required":false,"schema":{"type":"string","pattern":"^[0-9a-f]{64}$"},"description":"Diagnostic/mine scope only."},{"name":"traceId","in":"query","required":false,"schema":{"type":"string","pattern":"^[0-9a-f]{32}$"},"description":"Diagnostic/mine scope only."},{"name":"unknown","in":"query","required":false,"schema":{"type":"array","items":{"enum":["keyId","keyOwner","agentId","agentVersionId","modelId","finalProviderId","attemptProviderId"]},"maxItems":50},"style":"form","explode":true,"description":"OR with explicit values of the same nullable dimension."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","maxLength":2048},"description":"Opaque authenticated keyset cursor; repeats the original query, retains the original cutoff and never preserves revoked access."},{"name":"dimension","in":"query","required":true,"schema":{"enum":["keyId","keyOwner","agentId","agentVersionId","modelId","finalProviderId","attemptProviderId"]}},{"name":"q","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":256},"description":"Trimmed literal case-insensitive substring of an observed safe label or identifier; no wildcard syntax."}],"responses":{"200":{"description":"Authorized metadata collection and opaque next cursor; null marks the end.","headers":{"Cache-Control":{"schema":{"const":"private, no-store"}}},"content":{"application/json":{"schema":{"$ref":"../schemas/activity-collections-v1.schema.json#/$defs/LlmOptions"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"503":{"$ref":"#/components/responses/AuthorizationUnavailable"},"422":{"description":"Requested history expired, or query/current authority scope is too large.","content":{"application/json":{"schema":{"$ref":"../schemas/error-v1.schema.json"}}}},"429":{"description":"Management request limit reached; retry after the indicated interval.","content":{"application/json":{"schema":{"$ref":"../schemas/error-v1.schema.json"}}},"headers":{"Retry-After":{"schema":{"type":"integer","minimum":1}}}}}}}, "/api/v1/activity/agents/filter-options": {"get":{"operationId":"getActivityAgentsFilterOptionsV1","summary":"Read authorized Activity filter-options","description":"Metadata only. Current permissions and retention are rechecked on each page. Cursor binds the query and observation; page size may change. Options omit their target dimension filter and return observed values without counts; q is a literal substring of safe label or identity.","x-authorization-resource":"activity:current-authorized-resources","x-authorization-permission":"control_plane#administer OR agent#activity_aggregate","parameters":[{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Optional pair with to; UTC start-inclusive. Defaults to the last 24 hours at the observation cutoff."},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"End-exclusive, no later than server time. Both from and to are required when either is supplied."},{"name":"observation","in":"query","required":false,"schema":{"type":"string","maxLength":2048},"description":"Caller-bound ingestion cutoff, expires after 1 hour; rights and retention are checked again."},{"name":"agentId","in":"query","required":false,"schema":{"type":"array","items":{"type":"string","format":"uuid","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"maxItems":50},"style":"form","explode":true},{"name":"agentVersionId","in":"query","required":false,"schema":{"type":"array","items":{"type":"string","format":"uuid","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"maxItems":50},"style":"form","explode":true},{"name":"unknown","in":"query","required":false,"schema":{"type":"array","items":{"enum":["agentId","agentVersionId"]},"maxItems":50},"style":"form","explode":true,"description":"OR with explicit values of the same nullable dimension."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","maxLength":2048},"description":"Opaque authenticated keyset cursor; repeats the original query, retains the original cutoff and never preserves revoked access."},{"name":"dimension","in":"query","required":true,"schema":{"enum":["agentId","agentVersionId"]}},{"name":"q","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":256},"description":"Trimmed literal case-insensitive substring of an observed safe label or identifier; no wildcard syntax."}],"responses":{"200":{"description":"Authorized metadata collection and opaque next cursor; null marks the end.","headers":{"Cache-Control":{"schema":{"const":"private, no-store"}}},"content":{"application/json":{"schema":{"$ref":"../schemas/activity-collections-v1.schema.json#/$defs/AgentsOptions"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"503":{"$ref":"#/components/responses/AuthorizationUnavailable"},"422":{"description":"Requested history expired, or query/current authority scope is too large.","content":{"application/json":{"schema":{"$ref":"../schemas/error-v1.schema.json"}}}},"429":{"description":"Management request limit reached; retry after the indicated interval.","content":{"application/json":{"schema":{"$ref":"../schemas/error-v1.schema.json"}}},"headers":{"Retry-After":{"schema":{"type":"integer","minimum":1}}}}}}}, "/api/v1/activity/llm/summary": {"get": {"operationId": "getActivityLlmSummaryV1", "summary": "Read authorized llm Activity summary", "description": "Metadata only. Current permissions are applied before aggregation and ranking; unknown and partial usage are explicit. No client SQL, monetary costs or Agent-run success claims.", "x-authorization-resource": "activity:current-authorized-resources", "x-authorization-permission": "control_plane#administer OR agent#activity_aggregate OR api_key#activity_read OR agent#activity_diagnose", "parameters": [{"name": "from", "in": "query", "required": false, "schema": {"type": "string", "format": "date-time"}, "description": "Optional pair with to; UTC start-inclusive. Defaults to the last 24 hours at the observation cutoff."}, {"name": "to", "in": "query", "required": false, "schema": {"type": "string", "format": "date-time"}, "description": "End-exclusive, no later than server time. Both from and to are required when either is supplied."}, {"name": "observation", "in": "query", "required": false, "schema": {"type": "string", "maxLength": 2048}, "description": "Caller-bound ingestion cutoff, expires after 1 hour; rights and retention are checked again."}, {"name": "agentId", "in": "query", "required": false, "schema": {"type": "array", "items": {"type": "string", "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"}, "maxItems": 50}, "style": "form", "explode": true}, {"name": "agentVersionId", "in": "query", "required": false, "schema": {"type": "array", "items": {"type": "string", "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"}, "maxItems": 50}, "style": "form", "explode": true}, {"name": "access", "in": "query", "required": false, "schema": {"enum": ["aggregate", "diagnostic"], "default": "aggregate"}}, {"name": "ownership", "in": "query", "required": false, "schema": {"enum": ["all", "mine"], "default": "all"}, "description": "Mine means direct key ownership, never the caller of an opaque Agent."}, {"name": "keyId", "in": "query", "required": false, "schema": {"type": "array", "items": {"type": "string", "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"}, "maxItems": 50}, "style": "form", "explode": true}, {"name": "modelId", "in": "query", "required": false, "schema": {"type": "array", "items": {"type": "string", "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"}, "maxItems": 50}, "style": "form", "explode": true}, {"name": "finalProviderId", "in": "query", "required": false, "schema": {"type": "array", "items": {"type": "string", "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"}, "maxItems": 50}, "style": "form", "explode": true}, {"name": "attemptProviderId", "in": "query", "required": false, "schema": {"type": "array", "items": {"type": "string", "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"}, "maxItems": 50}, "style": "form", "explode": true}, {"name": "outcome", "in": "query", "required": false, "schema": {"type": "array", "items": {"enum": ["success", "rejected", "error", "cancelled", "unknown"]}, "maxItems": 50}, "style": "form", "explode": true}, {"name": "reasonCode", "in": "query", "required": false, "schema": {"type": "array", "items": {"enum": ["none", "invalid_key", "unauthenticated", "forbidden", "rate_limited", "model_not_found", "gateway_dependency_unavailable", "upstream_error", "upstream_timeout", "transport_error", "client_cancelled", "termination_unknown"]}, "maxItems": 50}, "style": "form", "explode": true}, {"name": "ownerType", "in": "query", "required": false, "schema": {"enum": ["principal", "service", "agent"]}, "description": "Exact typed owner in diagnostic/mine scope; supply its complete identity tuple."}, {"name": "ownerIssuer", "in": "query", "required": false, "schema": {"type": "string", "minLength": 1, "maxLength": 2048}}, {"name": "ownerSubject", "in": "query", "required": false, "schema": {"type": "string", "minLength": 1, "maxLength": 512}}, {"name": "ownerAgentId", "in": "query", "required": false, "schema": {"type": "string", "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"}}, {"name": "requestId", "in": "query", "required": false, "schema": {"type": "string", "pattern": "^[0-9a-f]{64}$"}, "description": "Diagnostic/mine scope only."}, {"name": "traceId", "in": "query", "required": false, "schema": {"type": "string", "pattern": "^[0-9a-f]{32}$"}, "description": "Diagnostic/mine scope only."}, {"name": "unknown", "in": "query", "required": false, "schema": {"type": "array", "items": {"enum": ["keyId", "keyOwner", "agentId", "agentVersionId", "modelId", "finalProviderId", "attemptProviderId"]}, "maxItems": 50}, "style": "form", "explode": true, "description": "OR with explicit values of the same nullable dimension."}, {"name": "metric", "in": "query", "required": false, "schema": {"type": "array", "items": {"enum": ["requests", "errorRate", "rejectionRate", "inputTokens", "outputTokens", "totalTokens", "cachedInputTokens", "reasoningTokens", "durationMs", "ttftMs"]}, "maxItems": 50}, "style": "form", "explode": true, "description": "Final Provider supports request metrics; attempt Provider supports token metrics. Series requires one distinct metric."}], "responses": {"200": {"description": "Authorized observed metrics with explicit coverage and delivery quality.", "headers": {"Cache-Control": {"schema": {"const": "private, no-store"}}}, "content": {"application/json": {"schema": {"$ref": "../schemas/activity-aggregates-v1.schema.json#/$defs/LlmSummary"}}}}, "400": {"$ref": "#/components/responses/InvalidRequest"}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "503": {"$ref": "#/components/responses/AuthorizationUnavailable"}, "422": {"description": "Requested history expired, or query/current authority scope is too large.", "content": {"application/json": {"schema": {"$ref": "../schemas/error-v1.schema.json"}}}}, "429": {"description": "Management request limit reached; retry after the indicated interval.", "content": {"application/json": {"schema": {"$ref": "../schemas/error-v1.schema.json"}}}, "headers": {"Retry-After": {"schema": {"type": "integer", "minimum": 1}}}}}}}, "/api/v1/activity/llm/series": {"get": {"operationId": "getActivityLlmSeriesV1", "summary": "Read authorized llm Activity series", "description": "Metadata only. Current permissions are applied before aggregation and ranking; unknown and partial usage are explicit. No client SQL, monetary costs or Agent-run success claims.", "x-authorization-resource": "activity:current-authorized-resources", "x-authorization-permission": "control_plane#administer OR agent#activity_aggregate OR api_key#activity_read OR agent#activity_diagnose", "parameters": [{"name": "from", "in": "query", "required": false, "schema": {"type": "string", "format": "date-time"}, "description": "Optional pair with to; UTC start-inclusive. Defaults to the last 24 hours at the observation cutoff."}, {"name": "to", "in": "query", "required": false, "schema": {"type": "string", "format": "date-time"}, "description": "End-exclusive, no later than server time. Both from and to are required when either is supplied."}, {"name": "observation", "in": "query", "required": false, "schema": {"type": "string", "maxLength": 2048}, "description": "Caller-bound ingestion cutoff, expires after 1 hour; rights and retention are checked again."}, {"name": "agentId", "in": "query", "required": false, "schema": {"type": "array", "items": {"type": "string", "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"}, "maxItems": 50}, "style": "form", "explode": true}, {"name": "agentVersionId", "in": "query", "required": false, "schema": {"type": "array", "items": {"type": "string", "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"}, "maxItems": 50}, "style": "form", "explode": true}, {"name": "access", "in": "query", "required": false, "schema": {"enum": ["aggregate", "diagnostic"], "default": "aggregate"}}, {"name": "ownership", "in": "query", "required": false, "schema": {"enum": ["all", "mine"], "default": "all"}, "description": "Mine means direct key ownership, never the caller of an opaque Agent."}, {"name": "keyId", "in": "query", "required": false, "schema": {"type": "array", "items": {"type": "string", "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"}, "maxItems": 50}, "style": "form", "explode": true}, {"name": "modelId", "in": "query", "required": false, "schema": {"type": "array", "items": {"type": "string", "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"}, "maxItems": 50}, "style": "form", "explode": true}, {"name": "finalProviderId", "in": "query", "required": false, "schema": {"type": "array", "items": {"type": "string", "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"}, "maxItems": 50}, "style": "form", "explode": true}, {"name": "attemptProviderId", "in": "query", "required": false, "schema": {"type": "array", "items": {"type": "string", "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"}, "maxItems": 50}, "style": "form", "explode": true}, {"name": "outcome", "in": "query", "required": false, "schema": {"type": "array", "items": {"enum": ["success", "rejected", "error", "cancelled", "unknown"]}, "maxItems": 50}, "style": "form", "explode": true}, {"name": "reasonCode", "in": "query", "required": false, "schema": {"type": "array", "items": {"enum": ["none", "invalid_key", "unauthenticated", "forbidden", "rate_limited", "model_not_found", "gateway_dependency_unavailable", "upstream_error", "upstream_timeout", "transport_error", "client_cancelled", "termination_unknown"]}, "maxItems": 50}, "style": "form", "explode": true}, {"name": "ownerType", "in": "query", "required": false, "schema": {"enum": ["principal", "service", "agent"]}, "description": "Exact typed owner in diagnostic/mine scope; supply its complete identity tuple."}, {"name": "ownerIssuer", "in": "query", "required": false, "schema": {"type": "string", "minLength": 1, "maxLength": 2048}}, {"name": "ownerSubject", "in": "query", "required": false, "schema": {"type": "string", "minLength": 1, "maxLength": 512}}, {"name": "ownerAgentId", "in": "query", "required": false, "schema": {"type": "string", "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"}}, {"name": "requestId", "in": "query", "required": false, "schema": {"type": "string", "pattern": "^[0-9a-f]{64}$"}, "description": "Diagnostic/mine scope only."}, {"name": "traceId", "in": "query", "required": false, "schema": {"type": "string", "pattern": "^[0-9a-f]{32}$"}, "description": "Diagnostic/mine scope only."}, {"name": "unknown", "in": "query", "required": false, "schema": {"type": "array", "items": {"enum": ["keyId", "keyOwner", "agentId", "agentVersionId", "modelId", "finalProviderId", "attemptProviderId"]}, "maxItems": 50}, "style": "form", "explode": true, "description": "OR with explicit values of the same nullable dimension."}, {"name": "metric", "in": "query", "required": true, "schema": {"type": "array", "items": {"enum": ["requests", "errorRate", "rejectionRate", "inputTokens", "outputTokens", "totalTokens", "cachedInputTokens", "reasoningTokens", "durationMs", "ttftMs"]}, "maxItems": 50}, "style": "form", "explode": true, "description": "Final Provider supports request metrics; attempt Provider supports token metrics. Series requires one distinct metric."}, {"name": "groupBy", "in": "query", "required": false, "schema": {"type": "array", "items": {"enum": ["keyId", "keyOwner", "agentId", "agentVersionId", "modelId", "finalProviderId", "attemptProviderId", "outcome", "reasonCode"]}, "maxItems": 2, "uniqueItems": true}, "style": "form", "explode": true, "description": "Ordered 0–2 distinct dimensions; breakdown requires 1–2."}, {"name": "top", "in": "query", "required": false, "schema": {"type": "integer", "minimum": 1, "maximum": 20, "default": 10}, "description": "Rank groups across the whole interval, then recompute Others from remaining facts."}, {"name": "rankBy", "in": "query", "required": false, "schema": {"enum": ["requests", "errorRate", "rejectionRate", "inputTokens", "outputTokens", "totalTokens", "cachedInputTokens", "reasoningTokens", "durationMs.mean", "durationMs.p50", "durationMs.p95", "ttftMs.p50", "ttftMs.p95"]}, "description": "Must select a returned metric; defaults to the first scalar, otherwise p95."}, {"name": "granularity", "in": "query", "required": false, "schema": {"enum": ["auto", "minute", "hour", "day"], "default": "auto"}, "description": "UTC buckets clipped to the range; auto uses minutes through 24h, hours thereafter. Minute maximum is 24h."}], "responses": {"200": {"description": "Authorized observed metrics with explicit coverage and delivery quality.", "headers": {"Cache-Control": {"schema": {"const": "private, no-store"}}}, "content": {"application/json": {"schema": {"$ref": "../schemas/activity-aggregates-v1.schema.json#/$defs/LlmSeries"}}}}, "400": {"$ref": "#/components/responses/InvalidRequest"}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "503": {"$ref": "#/components/responses/AuthorizationUnavailable"}, "422": {"description": "Requested history expired, or query/current authority scope is too large.", "content": {"application/json": {"schema": {"$ref": "../schemas/error-v1.schema.json"}}}}, "429": {"description": "Management request limit reached; retry after the indicated interval.", "content": {"application/json": {"schema": {"$ref": "../schemas/error-v1.schema.json"}}}, "headers": {"Retry-After": {"schema": {"type": "integer", "minimum": 1}}}}}}}, "/api/v1/activity/llm/breakdown": {"get": {"operationId": "getActivityLlmBreakdownV1", "summary": "Read authorized llm Activity breakdown", "description": "Metadata only. Current permissions are applied before aggregation and ranking; unknown and partial usage are explicit. No client SQL, monetary costs or Agent-run success claims.", "x-authorization-resource": "activity:current-authorized-resources", "x-authorization-permission": "control_plane#administer OR agent#activity_aggregate OR api_key#activity_read OR agent#activity_diagnose", "parameters": [{"name": "from", "in": "query", "required": false, "schema": {"type": "string", "format": "date-time"}, "description": "Optional pair with to; UTC start-inclusive. Defaults to the last 24 hours at the observation cutoff."}, {"name": "to", "in": "query", "required": false, "schema": {"type": "string", "format": "date-time"}, "description": "End-exclusive, no later than server time. Both from and to are required when either is supplied."}, {"name": "observation", "in": "query", "required": false, "schema": {"type": "string", "maxLength": 2048}, "description": "Caller-bound ingestion cutoff, expires after 1 hour; rights and retention are checked again."}, {"name": "agentId", "in": "query", "required": false, "schema": {"type": "array", "items": {"type": "string", "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"}, "maxItems": 50}, "style": "form", "explode": true}, {"name": "agentVersionId", "in": "query", "required": false, "schema": {"type": "array", "items": {"type": "string", "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"}, "maxItems": 50}, "style": "form", "explode": true}, {"name": "access", "in": "query", "required": false, "schema": {"enum": ["aggregate", "diagnostic"], "default": "aggregate"}}, {"name": "ownership", "in": "query", "required": false, "schema": {"enum": ["all", "mine"], "default": "all"}, "description": "Mine means direct key ownership, never the caller of an opaque Agent."}, {"name": "keyId", "in": "query", "required": false, "schema": {"type": "array", "items": {"type": "string", "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"}, "maxItems": 50}, "style": "form", "explode": true}, {"name": "modelId", "in": "query", "required": false, "schema": {"type": "array", "items": {"type": "string", "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"}, "maxItems": 50}, "style": "form", "explode": true}, {"name": "finalProviderId", "in": "query", "required": false, "schema": {"type": "array", "items": {"type": "string", "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"}, "maxItems": 50}, "style": "form", "explode": true}, {"name": "attemptProviderId", "in": "query", "required": false, "schema": {"type": "array", "items": {"type": "string", "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"}, "maxItems": 50}, "style": "form", "explode": true}, {"name": "outcome", "in": "query", "required": false, "schema": {"type": "array", "items": {"enum": ["success", "rejected", "error", "cancelled", "unknown"]}, "maxItems": 50}, "style": "form", "explode": true}, {"name": "reasonCode", "in": "query", "required": false, "schema": {"type": "array", "items": {"enum": ["none", "invalid_key", "unauthenticated", "forbidden", "rate_limited", "model_not_found", "gateway_dependency_unavailable", "upstream_error", "upstream_timeout", "transport_error", "client_cancelled", "termination_unknown"]}, "maxItems": 50}, "style": "form", "explode": true}, {"name": "ownerType", "in": "query", "required": false, "schema": {"enum": ["principal", "service", "agent"]}, "description": "Exact typed owner in diagnostic/mine scope; supply its complete identity tuple."}, {"name": "ownerIssuer", "in": "query", "required": false, "schema": {"type": "string", "minLength": 1, "maxLength": 2048}}, {"name": "ownerSubject", "in": "query", "required": false, "schema": {"type": "string", "minLength": 1, "maxLength": 512}}, {"name": "ownerAgentId", "in": "query", "required": false, "schema": {"type": "string", "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"}}, {"name": "requestId", "in": "query", "required": false, "schema": {"type": "string", "pattern": "^[0-9a-f]{64}$"}, "description": "Diagnostic/mine scope only."}, {"name": "traceId", "in": "query", "required": false, "schema": {"type": "string", "pattern": "^[0-9a-f]{32}$"}, "description": "Diagnostic/mine scope only."}, {"name": "unknown", "in": "query", "required": false, "schema": {"type": "array", "items": {"enum": ["keyId", "keyOwner", "agentId", "agentVersionId", "modelId", "finalProviderId", "attemptProviderId"]}, "maxItems": 50}, "style": "form", "explode": true, "description": "OR with explicit values of the same nullable dimension."}, {"name": "metric", "in": "query", "required": true, "schema": {"type": "array", "items": {"enum": ["requests", "errorRate", "rejectionRate", "inputTokens", "outputTokens", "totalTokens", "cachedInputTokens", "reasoningTokens", "durationMs", "ttftMs"]}, "maxItems": 50}, "style": "form", "explode": true, "description": "Final Provider supports request metrics; attempt Provider supports token metrics. Series requires one distinct metric."}, {"name": "groupBy", "in": "query", "required": true, "schema": {"type": "array", "items": {"enum": ["keyId", "keyOwner", "agentId", "agentVersionId", "modelId", "finalProviderId", "attemptProviderId", "outcome", "reasonCode"]}, "maxItems": 2, "uniqueItems": true}, "style": "form", "explode": true, "description": "Ordered 0–2 distinct dimensions; breakdown requires 1–2."}, {"name": "top", "in": "query", "required": false, "schema": {"type": "integer", "minimum": 1, "maximum": 20, "default": 10}, "description": "Rank groups across the whole interval, then recompute Others from remaining facts."}, {"name": "rankBy", "in": "query", "required": false, "schema": {"enum": ["requests", "errorRate", "rejectionRate", "inputTokens", "outputTokens", "totalTokens", "cachedInputTokens", "reasoningTokens", "durationMs.mean", "durationMs.p50", "durationMs.p95", "ttftMs.p50", "ttftMs.p95"]}, "description": "Must select a returned metric; defaults to the first scalar, otherwise p95."}, {"name": "sort", "in": "query", "required": false, "schema": {"enum": ["rank", "-rank"], "default": "-rank"}, "description": "Null ranks last; canonical group tuple is the stable tie-breaker."}], "responses": {"200": {"description": "Authorized observed metrics with explicit coverage and delivery quality.", "headers": {"Cache-Control": {"schema": {"const": "private, no-store"}}}, "content": {"application/json": {"schema": {"$ref": "../schemas/activity-aggregates-v1.schema.json#/$defs/LlmBreakdown"}}}}, "400": {"$ref": "#/components/responses/InvalidRequest"}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "503": {"$ref": "#/components/responses/AuthorizationUnavailable"}, "422": {"description": "Requested history expired, or query/current authority scope is too large.", "content": {"application/json": {"schema": {"$ref": "../schemas/error-v1.schema.json"}}}}, "429": {"description": "Management request limit reached; retry after the indicated interval.", "content": {"application/json": {"schema": {"$ref": "../schemas/error-v1.schema.json"}}}, "headers": {"Retry-After": {"schema": {"type": "integer", "minimum": 1}}}}}}}, "/api/v1/activity/agents/summary": {"get": {"operationId": "getActivityAgentsSummaryV1", "summary": "Read authorized agents Activity summary", "description": "Metadata only. Current permissions are applied before aggregation and ranking; unknown and partial usage are explicit. No client SQL, monetary costs or Agent-run success claims.", "x-authorization-resource": "activity:current-authorized-resources", "x-authorization-permission": "control_plane#administer OR agent#activity_aggregate", "parameters": [{"name": "from", "in": "query", "required": false, "schema": {"type": "string", "format": "date-time"}, "description": "Optional pair with to; UTC start-inclusive. Defaults to the last 24 hours at the observation cutoff."}, {"name": "to", "in": "query", "required": false, "schema": {"type": "string", "format": "date-time"}, "description": "End-exclusive, no later than server time. Both from and to are required when either is supplied."}, {"name": "observation", "in": "query", "required": false, "schema": {"type": "string", "maxLength": 2048}, "description": "Caller-bound ingestion cutoff, expires after 1 hour; rights and retention are checked again."}, {"name": "agentId", "in": "query", "required": false, "schema": {"type": "array", "items": {"type": "string", "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"}, "maxItems": 50}, "style": "form", "explode": true}, {"name": "agentVersionId", "in": "query", "required": false, "schema": {"type": "array", "items": {"type": "string", "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"}, "maxItems": 50}, "style": "form", "explode": true}, {"name": "unknown", "in": "query", "required": false, "schema": {"type": "array", "items": {"enum": ["agentId", "agentVersionId"]}, "maxItems": 50}, "style": "form", "explode": true, "description": "OR with explicit values of the same nullable dimension."}, {"name": "metric", "in": "query", "required": false, "schema": {"type": "array", "items": {"enum": ["agentRequests", "httpErrors", "gatewayRejections", "durationMs"]}, "maxItems": 50}, "style": "form", "explode": true, "description": "Final Provider supports request metrics; attempt Provider supports token metrics. Series requires one distinct metric."}], "responses": {"200": {"description": "Authorized observed metrics with explicit coverage and delivery quality.", "headers": {"Cache-Control": {"schema": {"const": "private, no-store"}}}, "content": {"application/json": {"schema": {"$ref": "../schemas/activity-aggregates-v1.schema.json#/$defs/AgentsSummary"}}}}, "400": {"$ref": "#/components/responses/InvalidRequest"}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "503": {"$ref": "#/components/responses/AuthorizationUnavailable"}, "422": {"description": "Requested history expired, or query/current authority scope is too large.", "content": {"application/json": {"schema": {"$ref": "../schemas/error-v1.schema.json"}}}}, "429": {"description": "Management request limit reached; retry after the indicated interval.", "content": {"application/json": {"schema": {"$ref": "../schemas/error-v1.schema.json"}}}, "headers": {"Retry-After": {"schema": {"type": "integer", "minimum": 1}}}}}}}, "/api/v1/activity/agents/series": {"get": {"operationId": "getActivityAgentsSeriesV1", "summary": "Read authorized agents Activity series", "description": "Metadata only. Current permissions are applied before aggregation and ranking; unknown and partial usage are explicit. No client SQL, monetary costs or Agent-run success claims.", "x-authorization-resource": "activity:current-authorized-resources", "x-authorization-permission": "control_plane#administer OR agent#activity_aggregate", "parameters": [{"name": "from", "in": "query", "required": false, "schema": {"type": "string", "format": "date-time"}, "description": "Optional pair with to; UTC start-inclusive. Defaults to the last 24 hours at the observation cutoff."}, {"name": "to", "in": "query", "required": false, "schema": {"type": "string", "format": "date-time"}, "description": "End-exclusive, no later than server time. Both from and to are required when either is supplied."}, {"name": "observation", "in": "query", "required": false, "schema": {"type": "string", "maxLength": 2048}, "description": "Caller-bound ingestion cutoff, expires after 1 hour; rights and retention are checked again."}, {"name": "agentId", "in": "query", "required": false, "schema": {"type": "array", "items": {"type": "string", "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"}, "maxItems": 50}, "style": "form", "explode": true}, {"name": "agentVersionId", "in": "query", "required": false, "schema": {"type": "array", "items": {"type": "string", "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"}, "maxItems": 50}, "style": "form", "explode": true}, {"name": "unknown", "in": "query", "required": false, "schema": {"type": "array", "items": {"enum": ["agentId", "agentVersionId"]}, "maxItems": 50}, "style": "form", "explode": true, "description": "OR with explicit values of the same nullable dimension."}, {"name": "metric", "in": "query", "required": true, "schema": {"type": "array", "items": {"enum": ["agentRequests", "httpErrors", "gatewayRejections", "durationMs"]}, "maxItems": 50}, "style": "form", "explode": true, "description": "Final Provider supports request metrics; attempt Provider supports token metrics. Series requires one distinct metric."}, {"name": "groupBy", "in": "query", "required": false, "schema": {"type": "array", "items": {"enum": ["agentId", "agentVersionId"]}, "maxItems": 2, "uniqueItems": true}, "style": "form", "explode": true, "description": "Ordered 0–2 distinct dimensions; breakdown requires 1–2."}, {"name": "top", "in": "query", "required": false, "schema": {"type": "integer", "minimum": 1, "maximum": 20, "default": 10}, "description": "Rank groups across the whole interval, then recompute Others from remaining facts."}, {"name": "rankBy", "in": "query", "required": false, "schema": {"enum": ["agentRequests", "httpErrors", "gatewayRejections", "durationMs.mean", "durationMs.p50", "durationMs.p95"]}, "description": "Must select a returned metric; defaults to the first scalar, otherwise p95."}, {"name": "granularity", "in": "query", "required": false, "schema": {"enum": ["auto", "minute", "hour", "day"], "default": "auto"}, "description": "UTC buckets clipped to the range; auto uses minutes through 24h, hours thereafter. Minute maximum is 24h."}], "responses": {"200": {"description": "Authorized observed metrics with explicit coverage and delivery quality.", "headers": {"Cache-Control": {"schema": {"const": "private, no-store"}}}, "content": {"application/json": {"schema": {"$ref": "../schemas/activity-aggregates-v1.schema.json#/$defs/AgentsSeries"}}}}, "400": {"$ref": "#/components/responses/InvalidRequest"}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "503": {"$ref": "#/components/responses/AuthorizationUnavailable"}, "422": {"description": "Requested history expired, or query/current authority scope is too large.", "content": {"application/json": {"schema": {"$ref": "../schemas/error-v1.schema.json"}}}}, "429": {"description": "Management request limit reached; retry after the indicated interval.", "content": {"application/json": {"schema": {"$ref": "../schemas/error-v1.schema.json"}}}, "headers": {"Retry-After": {"schema": {"type": "integer", "minimum": 1}}}}}}}, "/api/v1/activity/agents/breakdown": {"get": {"operationId": "getActivityAgentsBreakdownV1", "summary": "Read authorized agents Activity breakdown", "description": "Metadata only. Current permissions are applied before aggregation and ranking; unknown and partial usage are explicit. No client SQL, monetary costs or Agent-run success claims.", "x-authorization-resource": "activity:current-authorized-resources", "x-authorization-permission": "control_plane#administer OR agent#activity_aggregate", "parameters": [{"name": "from", "in": "query", "required": false, "schema": {"type": "string", "format": "date-time"}, "description": "Optional pair with to; UTC start-inclusive. Defaults to the last 24 hours at the observation cutoff."}, {"name": "to", "in": "query", "required": false, "schema": {"type": "string", "format": "date-time"}, "description": "End-exclusive, no later than server time. Both from and to are required when either is supplied."}, {"name": "observation", "in": "query", "required": false, "schema": {"type": "string", "maxLength": 2048}, "description": "Caller-bound ingestion cutoff, expires after 1 hour; rights and retention are checked again."}, {"name": "agentId", "in": "query", "required": false, "schema": {"type": "array", "items": {"type": "string", "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"}, "maxItems": 50}, "style": "form", "explode": true}, {"name": "agentVersionId", "in": "query", "required": false, "schema": {"type": "array", "items": {"type": "string", "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"}, "maxItems": 50}, "style": "form", "explode": true}, {"name": "unknown", "in": "query", "required": false, "schema": {"type": "array", "items": {"enum": ["agentId", "agentVersionId"]}, "maxItems": 50}, "style": "form", "explode": true, "description": "OR with explicit values of the same nullable dimension."}, {"name": "metric", "in": "query", "required": true, "schema": {"type": "array", "items": {"enum": ["agentRequests", "httpErrors", "gatewayRejections", "durationMs"]}, "maxItems": 50}, "style": "form", "explode": true, "description": "Final Provider supports request metrics; attempt Provider supports token metrics. Series requires one distinct metric."}, {"name": "groupBy", "in": "query", "required": true, "schema": {"type": "array", "items": {"enum": ["agentId", "agentVersionId"]}, "maxItems": 2, "uniqueItems": true}, "style": "form", "explode": true, "description": "Ordered 0–2 distinct dimensions; breakdown requires 1–2."}, {"name": "top", "in": "query", "required": false, "schema": {"type": "integer", "minimum": 1, "maximum": 20, "default": 10}, "description": "Rank groups across the whole interval, then recompute Others from remaining facts."}, {"name": "rankBy", "in": "query", "required": false, "schema": {"enum": ["agentRequests", "httpErrors", "gatewayRejections", "durationMs.mean", "durationMs.p50", "durationMs.p95"]}, "description": "Must select a returned metric; defaults to the first scalar, otherwise p95."}, {"name": "sort", "in": "query", "required": false, "schema": {"enum": ["rank", "-rank"], "default": "-rank"}, "description": "Null ranks last; canonical group tuple is the stable tie-breaker."}], "responses": {"200": {"description": "Authorized observed metrics with explicit coverage and delivery quality.", "headers": {"Cache-Control": {"schema": {"const": "private, no-store"}}}, "content": {"application/json": {"schema": {"$ref": "../schemas/activity-aggregates-v1.schema.json#/$defs/AgentsBreakdown"}}}}, "400": {"$ref": "#/components/responses/InvalidRequest"}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "503": {"$ref": "#/components/responses/AuthorizationUnavailable"}, "422": {"description": "Requested history expired, or query/current authority scope is too large.", "content": {"application/json": {"schema": {"$ref": "../schemas/error-v1.schema.json"}}}}, "429": {"description": "Management request limit reached; retry after the indicated interval.", "content": {"application/json": {"schema": {"$ref": "../schemas/error-v1.schema.json"}}}, "headers": {"Retry-After": {"schema": {"type": "integer", "minimum": 1}}}}}}}, "/api/v1/activity/llm/requests/{requestId}": {"get": {"operationId": "getActivityLlmRequestV1", "summary": "Read authorized metadata of one observed LLM request", "x-authorization-resource": "api_key:{keyId}", "x-authorization-permission": "api_key#activity_read OR agent#activity_diagnose OR control_plane#administer", "parameters": [{"name": "requestId", "in": "path", "required": true, "schema": {"type": "string", "pattern": "^[0-9a-f]{64}$"}}, {"name": "observation", "in": "query", "schema": {"type": "string", "maxLength": 2048}}], "responses": {"200": {"description": "Metadata only; last-attempt source can be incomplete", "headers": {"Cache-Control": {"schema": {"const": "private, no-store"}}}, "content": {"application/json": {"schema": {"$ref": "../schemas/activity-request-v1.schema.json"}}}}, "400": {"$ref": "#/components/responses/InvalidRequest"}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "404": {"$ref": "#/components/responses/NotFound"}, "503": {"$ref": "#/components/responses/AuthorizationUnavailable"}}}}, "/api/v1/guardrail-policies": {"get": {"operationId": "listGuardrailPoliciesV1", "x-authorization-resource": "control_plane:control-plane", "x-authorization-permission": "control_plane#administer", "parameters": [{"$ref": "#/components/parameters/Cursor"}, {"name": "limit", "in": "query", "schema": {"type": "integer", "minimum": 1, "maximum": 50, "default": 20}}], "responses": {"200": {"description": "Guardrail authoring data; not runtime activation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/GuardrailPolicyList"}}}}, "400": {"$ref": "#/components/responses/InvalidRequest"}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "503": {"$ref": "#/components/responses/AuthorizationUnavailable"}}}, "post": {"operationId": "createGuardrailPolicyV1", "summary": "Save an immutable draft policy revision", "x-authorization-resource": "control_plane:control-plane", "x-authorization-permission": "control_plane#administer", "parameters": [{"$ref": "#/components/parameters/IdempotencyKey"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/GuardrailPolicyCreate"}}}}, "responses": {"202": {"$ref": "#/components/responses/OperationAccepted"}, "400": {"$ref": "#/components/responses/InvalidRequest"}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "409": {"$ref": "#/components/responses/Conflict"}, "503": {"$ref": "#/components/responses/AuthorizationUnavailable"}, "412": {"$ref": "#/components/responses/PreconditionFailed"}}}}, "/api/v1/guardrail-policies/{policyId}": {"get": {"operationId": "getGuardrailPolicyV1", "x-authorization-resource": "control_plane:control-plane", "x-authorization-permission": "control_plane#administer", "parameters": [{"name": "policyId", "in": "path", "required": true, "schema": {"$ref": "#/components/schemas/UuidV7"}}], "responses": {"200": {"description": "Guardrail authoring data; not runtime activation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/GuardrailPolicyDetail"}}}, "headers": {"ETag": {"required": true, "schema": {"type": "string"}}}}, "400": {"$ref": "#/components/responses/InvalidRequest"}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "503": {"$ref": "#/components/responses/AuthorizationUnavailable"}}}, "put": {"operationId": "replaceGuardrailPolicyV1", "summary": "Save an immutable draft policy revision", "x-authorization-resource": "control_plane:control-plane", "x-authorization-permission": "control_plane#administer", "parameters": [{"name": "policyId", "in": "path", "required": true, "schema": {"$ref": "#/components/schemas/UuidV7"}}, {"$ref": "#/components/parameters/IfMatch"}, {"$ref": "#/components/parameters/IdempotencyKey"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/GuardrailPolicyReplace"}}}}, "responses": {"202": {"$ref": "#/components/responses/OperationAccepted"}, "400": {"$ref": "#/components/responses/InvalidRequest"}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "409": {"$ref": "#/components/responses/Conflict"}, "503": {"$ref": "#/components/responses/AuthorizationUnavailable"}, "412": {"$ref": "#/components/responses/PreconditionFailed"}}}}, "/api/v1/guardrail-policies/{policyId}/revisions": {"get": {"operationId": "listGuardrailPolicyRevisionsV1", "x-authorization-resource": "control_plane:control-plane", "x-authorization-permission": "control_plane#administer", "parameters": [{"name": "policyId", "in": "path", "required": true, "schema": {"$ref": "#/components/schemas/UuidV7"}}, {"name": "limit", "in": "query", "schema": {"type": "integer", "minimum": 1, "maximum": 50, "default": 20}}, {"name": "beforeRevision", "in": "query", "schema": {"type": "integer", "minimum": 1}}], "responses": {"200": {"description": "Guardrail authoring data; not runtime activation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/GuardrailPolicyRevisions"}}}}, "400": {"$ref": "#/components/responses/InvalidRequest"}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "503": {"$ref": "#/components/responses/AuthorizationUnavailable"}}}}, "/api/v1/guardrail-policies/{policyId}/revisions/{revision}": {"get": {"operationId": "getGuardrailPolicyRevisionV1", "x-authorization-resource": "control_plane:control-plane", "x-authorization-permission": "control_plane#administer", "parameters": [{"name": "policyId", "in": "path", "required": true, "schema": {"$ref": "#/components/schemas/UuidV7"}}, {"name": "revision", "in": "path", "required": true, "schema": {"type": "integer", "minimum": 1}}], "responses": {"200": {"description": "Guardrail authoring data; not runtime activation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/GuardrailPolicyDetail"}}}, "headers": {"ETag": {"required": true, "schema": {"type": "string"}}}}, "400": {"$ref": "#/components/responses/InvalidRequest"}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "503": {"$ref": "#/components/responses/AuthorizationUnavailable"}}}}, "/api/v1/system/status": { "get": { "operationId": "getControlPlaneStatusV1", "summary": "Read safe desired/observed status for Control Plane domains", "x-authorization-resource": "control_plane:control-plane", "x-authorization-permission": "control_plane#observe", "responses": { "200": {"description": "Safe domain status", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/SystemStatus"}}}}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "503": {"$ref": "#/components/responses/AuthorizationUnavailable"} } } }, "/api/v1/key-issuance-policy": { "get": { "operationId": "getKeyIssuancePolicyV1", "summary": "Get the installation human self-issuance envelope", "x-authorization-resource": "control_plane:control-plane", "x-authorization-permission": "control_plane#administer", "responses": { "200": {"description": "Installation KeyIssuancePolicy", "headers": {"ETag": {"$ref": "#/components/headers/ETag"}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/KeyIssuancePolicy"}}}}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "503": {"$ref": "#/components/responses/AuthorizationUnavailable"} } }, "patch": { "operationId": "updateKeyIssuancePolicyV1", "summary": "Update the envelope for future human key issue without rewriting existing keys", "x-authorization-resource": "control_plane:control-plane", "x-authorization-permission": "control_plane#administer", "parameters": [{"$ref": "#/components/parameters/IfMatch"}, {"$ref": "#/components/parameters/IdempotencyKey"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/KeyIssuancePolicyUpdateRequest"}}}}, "responses": { "202": {"$ref": "#/components/responses/OperationAccepted"}, "400": {"$ref": "#/components/responses/InvalidRequest"}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "409": {"$ref": "#/components/responses/Conflict"}, "412": {"$ref": "#/components/responses/PreconditionFailed"}, "503": {"$ref": "#/components/responses/AuthorizationUnavailable"} } } }, "/api/v1/agent-publication-policy": { "get": { "operationId": "getAgentPublicationPolicyV1", "summary": "Get the installation Agent publication envelope", "x-authorization-resource": "control_plane:control-plane", "x-authorization-permission": "control_plane#administer", "responses": { "200": {"description": "Installation AgentPublicationPolicy", "headers": {"ETag": {"$ref": "#/components/headers/ETag"}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/AgentPublicationPolicy"}}}}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "503": {"$ref": "#/components/responses/AuthorizationUnavailable"} } }, "patch": { "operationId": "updateAgentPublicationPolicyV1", "summary": "Update the envelope for future AgentVersion creation without rewriting frozen versions", "x-authorization-resource": "control_plane:control-plane", "x-authorization-permission": "control_plane#administer", "parameters": [{"$ref": "#/components/parameters/IfMatch"}, {"$ref": "#/components/parameters/IdempotencyKey"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/AgentPublicationPolicyUpdateRequest"}}}}, "responses": { "202": {"$ref": "#/components/responses/OperationAccepted"}, "400": {"$ref": "#/components/responses/InvalidRequest"}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "409": {"$ref": "#/components/responses/Conflict"}, "412": {"$ref": "#/components/responses/PreconditionFailed"}, "503": {"$ref": "#/components/responses/AuthorizationUnavailable"} } } }, "/api/v1/tiers": { "get": { "operationId": "listTiersV1", "summary": "List technical rate and quota tiers", "x-authorization-resource": "control_plane:control-plane", "x-authorization-permission": "control_plane#administer", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 2048 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 20 } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 256 } }, { "name": "sort", "in": "query", "required": false, "schema": { "enum": [ "name", "-name", "createdAt", "-createdAt" ], "type": "string" } }, { "name": "desiredState", "in": "query", "required": false, "schema": { "enum": [ "enabled", "disabled" ], "type": "string" } }, { "name": "verifiedState", "in": "query", "required": false, "schema": { "enum": [ "pending", "enabled", "disabled", "degraded" ], "type": "string" } } ], "responses": { "200": {"description": "Tier page", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/TierList"}}}}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "503": {"$ref": "#/components/responses/AuthorizationUnavailable"} } }, "post": { "operationId": "createTierV1", "summary": "Create a technical tier through a verified durable operation", "x-authorization-resource": "control_plane:control-plane", "x-authorization-permission": "control_plane#administer", "parameters": [{"$ref": "#/components/parameters/IdempotencyKey"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/TierCreateRequest"}}}}, "responses": { "202": {"$ref": "#/components/responses/OperationAccepted"}, "400": {"$ref": "#/components/responses/InvalidRequest"}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "409": {"$ref": "#/components/responses/Conflict"}, "503": {"$ref": "#/components/responses/AuthorizationUnavailable"} } } }, "/api/v1/tiers/{tierId}": { "get": { "operationId": "getTierV1", "summary": "Get a tier", "x-authorization-resource": "control_plane:control-plane", "x-authorization-permission": "control_plane#administer", "parameters": [{"$ref": "#/components/parameters/TierId"}], "responses": { "200": {"description": "Tier", "headers": {"ETag": {"$ref": "#/components/headers/ETag"}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Tier"}}}}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "503": {"$ref": "#/components/responses/AuthorizationUnavailable"} } }, "patch": { "operationId": "updateTierV1", "summary": "Update a tier under an exact revision precondition", "x-authorization-resource": "control_plane:control-plane", "x-authorization-permission": "control_plane#administer", "parameters": [{"$ref": "#/components/parameters/TierId"}, {"$ref": "#/components/parameters/IfMatch"}, {"$ref": "#/components/parameters/IdempotencyKey"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/TierUpdateRequest"}}}}, "responses": { "202": {"$ref": "#/components/responses/OperationAccepted"}, "400": {"$ref": "#/components/responses/InvalidRequest"}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "409": {"$ref": "#/components/responses/Conflict"}, "412": {"$ref": "#/components/responses/PreconditionFailed"}, "503": {"$ref": "#/components/responses/AuthorizationUnavailable"} } }, "delete": { "operationId": "deleteTierV1", "summary": "Delete an unused tier after dependency verification", "x-authorization-resource": "control_plane:control-plane", "x-authorization-permission": "control_plane#administer", "parameters": [{"$ref": "#/components/parameters/TierId"}, {"$ref": "#/components/parameters/IfMatch"}, {"$ref": "#/components/parameters/IdempotencyKey"}], "responses": { "202": {"$ref": "#/components/responses/OperationAccepted"}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "409": {"$ref": "#/components/responses/Conflict"}, "412": {"$ref": "#/components/responses/PreconditionFailed"}, "503": {"$ref": "#/components/responses/AuthorizationUnavailable"} } } }, "/api/v1/providers": { "get": { "operationId": "listProvidersV1", "summary": "List provider metadata and credential status without credential material", "x-authorization-resource": "control_plane:control-plane", "x-authorization-permission": "control_plane#administer", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 2048 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 20 } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 256 } }, { "name": "sort", "in": "query", "required": false, "schema": { "enum": [ "name", "-name", "createdAt", "-createdAt" ], "type": "string" } }, { "name": "desiredState", "in": "query", "required": false, "schema": { "enum": [ "enabled", "disabled" ], "type": "string" } }, { "name": "verifiedState", "in": "query", "required": false, "schema": { "enum": [ "pending", "enabled", "disabled", "degraded" ], "type": "string" } } ], "responses": { "200": {"description": "Provider page", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ProviderList"}}}}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "503": {"$ref": "#/components/responses/AuthorizationUnavailable"} } }, "post": { "operationId": "createProviderV1", "summary": "Create disabled non-secret provider configuration", "x-authorization-resource": "control_plane:control-plane", "x-authorization-permission": "control_plane#administer", "parameters": [{"$ref": "#/components/parameters/IdempotencyKey"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ProviderCreateRequest"}}}}, "responses": { "202": {"$ref": "#/components/responses/OperationAccepted"}, "400": {"$ref": "#/components/responses/InvalidRequest"}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "409": {"$ref": "#/components/responses/Conflict"}, "503": {"$ref": "#/components/responses/AuthorizationUnavailable"} } } }, "/api/v1/providers/{providerId}": { "get": { "operationId": "getProviderV1", "summary": "Get provider metadata without credential material", "x-authorization-resource": "control_plane:control-plane", "x-authorization-permission": "control_plane#administer", "parameters": [{"$ref": "#/components/parameters/ProviderId"}], "responses": { "200": {"description": "Provider", "headers": {"ETag": {"$ref": "#/components/headers/ETag"}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Provider"}}}}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "503": {"$ref": "#/components/responses/AuthorizationUnavailable"} } }, "patch": { "operationId": "updateProviderV1", "summary": "Update non-secret provider configuration", "x-authorization-resource": "control_plane:control-plane", "x-authorization-permission": "control_plane#administer", "parameters": [{"$ref": "#/components/parameters/ProviderId"}, {"$ref": "#/components/parameters/IfMatch"}, {"$ref": "#/components/parameters/IdempotencyKey"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ProviderUpdateRequest"}}}}, "responses": { "202": {"$ref": "#/components/responses/OperationAccepted"}, "400": {"$ref": "#/components/responses/InvalidRequest"}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "409": {"$ref": "#/components/responses/Conflict"}, "412": {"$ref": "#/components/responses/PreconditionFailed"}, "503": {"$ref": "#/components/responses/AuthorizationUnavailable"} } }, "delete": { "operationId": "deleteProviderV1", "summary": "Delete a provider only when no Model references it", "x-authorization-resource": "control_plane:control-plane", "x-authorization-permission": "control_plane#administer", "parameters": [{"$ref": "#/components/parameters/ProviderId"}, {"$ref": "#/components/parameters/IfMatch"}, {"$ref": "#/components/parameters/IdempotencyKey"}], "responses": { "202": {"$ref": "#/components/responses/OperationAccepted"}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "409": {"$ref": "#/components/responses/Conflict"}, "412": {"$ref": "#/components/responses/PreconditionFailed"}, "503": {"$ref": "#/components/responses/AuthorizationUnavailable"} } } }, "/api/v1/providers/{providerId}/credential": { "put": { "operationId": "putProviderCredentialV1", "summary": "Set or replace and verify a provider credential without returning it", "x-authorization-resource": "control_plane:control-plane", "x-authorization-permission": "control_plane#administer", "x-secret-input": true, "parameters": [{"$ref": "#/components/parameters/ProviderId"}, {"$ref": "#/components/parameters/IfMatch"}, {"$ref": "#/components/parameters/IdempotencyKey"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ProviderCredentialWriteRequest"}}}}, "responses": { "202": {"$ref": "#/components/responses/OperationAccepted"}, "400": {"$ref": "#/components/responses/InvalidRequest"}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "409": {"$ref": "#/components/responses/Conflict"}, "412": {"$ref": "#/components/responses/PreconditionFailed"}, "503": {"$ref": "#/components/responses/AuthorizationUnavailable"} } } }, "/api/v1/models": { "get": { "operationId": "listModelsV1", "summary": "List model desired and verified state", "x-authorization-resource": "control_plane:control-plane", "x-authorization-permission": "control_plane#administer", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 2048 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 20 } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 256 } }, { "name": "sort", "in": "query", "required": false, "schema": { "enum": [ "name", "-name", "createdAt", "-createdAt" ], "type": "string" } }, { "name": "desiredState", "in": "query", "required": false, "schema": { "enum": [ "enabled", "disabled" ], "type": "string" } }, { "name": "verifiedState", "in": "query", "required": false, "schema": { "enum": [ "pending", "enabled", "disabled", "degraded" ], "type": "string" } }, { "name": "providerId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": {"description": "Model page", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ModelList"}}}}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "503": {"$ref": "#/components/responses/AuthorizationUnavailable"} } }, "post": { "operationId": "createModelV1", "summary": "Create and verify a provider-bound model", "x-authorization-resource": "control_plane:control-plane", "x-authorization-permission": "control_plane#administer", "parameters": [{"$ref": "#/components/parameters/IdempotencyKey"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ModelCreateRequest"}}}}, "responses": { "202": {"$ref": "#/components/responses/OperationAccepted"}, "400": {"$ref": "#/components/responses/InvalidRequest"}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "409": {"$ref": "#/components/responses/Conflict"}, "503": {"$ref": "#/components/responses/AuthorizationUnavailable"} } } }, "/api/v1/models/{modelId}": { "get": { "operationId": "getModelV1", "summary": "Get a model", "x-authorization-resource": "control_plane:control-plane", "x-authorization-permission": "control_plane#administer", "parameters": [{"$ref": "#/components/parameters/ModelId"}], "responses": { "200": {"description": "Model", "headers": {"ETag": {"$ref": "#/components/headers/ETag"}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Model"}}}}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "503": {"$ref": "#/components/responses/AuthorizationUnavailable"} } }, "patch": { "operationId": "updateModelV1", "summary": "Update and verify a model", "x-authorization-resource": "control_plane:control-plane", "x-authorization-permission": "control_plane#administer", "parameters": [{"$ref": "#/components/parameters/ModelId"}, {"$ref": "#/components/parameters/IfMatch"}, {"$ref": "#/components/parameters/IdempotencyKey"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ModelUpdateRequest"}}}}, "responses": { "202": {"$ref": "#/components/responses/OperationAccepted"}, "400": {"$ref": "#/components/responses/InvalidRequest"}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "409": {"$ref": "#/components/responses/Conflict"}, "412": {"$ref": "#/components/responses/PreconditionFailed"}, "503": {"$ref": "#/components/responses/AuthorizationUnavailable"} } }, "delete": { "operationId": "deleteModelV1", "summary": "Delete a model only when no active key or route requires it", "x-authorization-resource": "control_plane:control-plane", "x-authorization-permission": "control_plane#administer", "parameters": [{"$ref": "#/components/parameters/ModelId"}, {"$ref": "#/components/parameters/IfMatch"}, {"$ref": "#/components/parameters/IdempotencyKey"}], "responses": { "202": {"$ref": "#/components/responses/OperationAccepted"}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "409": {"$ref": "#/components/responses/Conflict"}, "412": {"$ref": "#/components/responses/PreconditionFailed"}, "503": {"$ref": "#/components/responses/AuthorizationUnavailable"} } } }, "/api/v1/keys": { "get": { "operationId": "listKeysV1", "summary": "List key metadata for direct administration without raw material", "x-authorization-resource": "control_plane:control-plane", "x-authorization-permission": "control_plane#administer", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 2048 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 20 } }, { "name": "ownerType", "in": "query", "required": false, "schema": { "enum": [ "principal", "service", "agent" ], "type": "string" } }, { "name": "ownerIssuer", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 1024 } }, { "name": "ownerSubject", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^[^\\x00-\\x1f\\x7f]+$" } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 256 } }, { "name": "sort", "in": "query", "required": false, "schema": { "enum": [ "name", "-name", "createdAt", "-createdAt" ], "type": "string" } }, { "name": "status", "in": "query", "required": false, "schema": { "enum": [ "pending", "active", "revoking", "revoked", "degraded" ], "type": "string" } } ], "responses": { "200": {"description": "Key metadata page", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/KeyList"}}}}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "503": {"$ref": "#/components/responses/AuthorizationUnavailable"} } }, "post": { "operationId": "issueAdminKeyV1", "summary": "Issue a verified human or service key and return its secret once", "description": "Never returns 202. Initial verified success is 201 with oneTimeSecret; exact idempotent replay is 200 metadata-only.", "x-authorization-resource": "control_plane:control-plane", "x-authorization-permission": "control_plane#administer", "x-authorization-projection-gates": ["operation:{allocatedOperationId}#requester", "api_key:{allocatedKeyId}#owner"], "x-secret-response-once": true, "parameters": [{"$ref": "#/components/parameters/IdempotencyKey"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/AdminKeyIssueRequest"}}}}, "responses": { "201": {"description": "New key verified by Gateway; secret returned once", "headers": {"Idempotency-Replayed": {"$ref": "#/components/headers/NotReplayed"}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/KeySecretResponse"}}}}, "200": {"description": "Exact idempotent replay; metadata only", "headers": {"Idempotency-Replayed": {"$ref": "#/components/headers/Replayed"}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Key"}}}}, "400": {"$ref": "#/components/responses/InvalidRequest"}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "409": {"$ref": "#/components/responses/Conflict"}, "503": {"$ref": "#/components/responses/AuthorizationUnavailable"}, "504": {"$ref": "#/components/responses/VerificationTimeout"} } } }, "/api/v1/keys/{keyId}": { "get": { "operationId": "getKeyV1", "summary": "Get key metadata without raw material", "x-authorization-resource": "control_plane:control-plane", "x-authorization-permission": "control_plane#administer", "parameters": [{"$ref": "#/components/parameters/KeyId"}], "responses": { "200": {"description": "Key metadata", "headers": {"ETag": {"$ref": "#/components/headers/ETag"}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Key"}}}}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "503": {"$ref": "#/components/responses/AuthorizationUnavailable"} } }, "patch": { "operationId": "updateKeyPolicyV1", "summary": "Update explicit Tier and Model grants without changing owner", "description": "Rejects Agent-owned keys with 409 agent_key_lifecycle_owned_by_publication; their lifecycle is internal to Agent Publication.", "x-rejected-owner-types": ["agent"], "x-owner-conflict-code": "agent_key_lifecycle_owned_by_publication", "x-authorization-resource": "control_plane:control-plane", "x-authorization-permission": "control_plane#administer", "parameters": [{"$ref": "#/components/parameters/KeyId"}, {"$ref": "#/components/parameters/IfMatch"}, {"$ref": "#/components/parameters/IdempotencyKey"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/KeyPolicyUpdateRequest"}}}}, "responses": { "202": {"$ref": "#/components/responses/OperationAccepted"}, "400": {"$ref": "#/components/responses/InvalidRequest"}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "409": {"$ref": "#/components/responses/Conflict"}, "412": {"$ref": "#/components/responses/PreconditionFailed"}, "503": {"$ref": "#/components/responses/AuthorizationUnavailable"} } } }, "/api/v1/keys/{keyId}:rotate": { "post": { "operationId": "rotateAdminKeyV1", "summary": "Rotate a human or service key and return the verified secret once", "description": "Never returns 202. Exact idempotent replay returns Key metadata without oneTimeSecret. Agent-owned targets fail with 409 agent_key_lifecycle_owned_by_publication.", "x-rejected-owner-types": ["agent"], "x-owner-conflict-code": "agent_key_lifecycle_owned_by_publication", "x-authorization-resource": "control_plane:control-plane", "x-authorization-permission": "control_plane#administer", "x-authorization-projection-gates": ["operation:{allocatedOperationId}#requester"], "x-secret-response-once": true, "parameters": [{"$ref": "#/components/parameters/KeyId"}, {"$ref": "#/components/parameters/IfMatch"}, {"$ref": "#/components/parameters/IdempotencyKey"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/KeyRotateRequest"}}}}, "responses": { "200": {"description": "Initial verified rotation returns KeySecretResponse; replay returns Key metadata", "headers": {"Idempotency-Replayed": {"$ref": "#/components/headers/ReplayState"}}, "content": {"application/json": {"schema": {"oneOf": [{"$ref": "#/components/schemas/KeySecretResponse"}, {"$ref": "#/components/schemas/Key"}]}}}}, "400": {"$ref": "#/components/responses/InvalidRequest"}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "409": {"$ref": "#/components/responses/Conflict"}, "412": {"$ref": "#/components/responses/PreconditionFailed"}, "503": {"$ref": "#/components/responses/AuthorizationUnavailable"}, "504": {"$ref": "#/components/responses/VerificationTimeout"} } } }, "/api/v1/keys/{keyId}:revoke": { "post": { "operationId": "revokeAdminKeyV1", "summary": "Revoke a key and verify Gateway rejection", "description": "Agent-owned targets fail with 409 agent_key_lifecycle_owned_by_publication; use typed Agent unpublish or suspension.", "x-rejected-owner-types": ["agent"], "x-owner-conflict-code": "agent_key_lifecycle_owned_by_publication", "x-authorization-resource": "control_plane:control-plane", "x-authorization-permission": "control_plane#administer", "parameters": [{"$ref": "#/components/parameters/KeyId"}, {"$ref": "#/components/parameters/IfMatch"}, {"$ref": "#/components/parameters/IdempotencyKey"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/RevokeRequest"}}}}, "responses": { "202": {"$ref": "#/components/responses/OperationAccepted"}, "400": {"$ref": "#/components/responses/InvalidRequest"}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "409": {"$ref": "#/components/responses/Conflict"}, "412": {"$ref": "#/components/responses/PreconditionFailed"}, "503": {"$ref": "#/components/responses/AuthorizationUnavailable"} } } }, "/api/v1/me/key-issuance-policy": { "get": { "operationId": "getMyKeyIssuancePolicyV1", "summary": "Read the safe self-service key envelope for the authenticated human", "x-authorization-mode": "authenticated_human_self_service_policy", "x-authorization-caller-type": "principal", "responses": { "200": {"description": "Redacted verified self-service envelope and caller-specific remaining key count", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/SelfKeyIssuancePolicy"}}}}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "503": {"$ref": "#/components/responses/AuthorizationUnavailable"} } } }, "/api/v1/me/keys": { "get": { "operationId": "listMyKeysV1", "summary": "List metadata for keys directly owned by the authenticated principal or service", "x-authorization-mode": "derived_principal_or_service_owner", "x-authorization-permission": "api_key#view", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 2048 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 20 } }, { "name": "fingerprint", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" } }, { "name": "expand", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^models$" } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 256 } }, { "name": "sort", "in": "query", "required": false, "schema": { "enum": [ "name", "-name", "createdAt", "-createdAt" ], "type": "string" } }, { "name": "status", "in": "query", "required": false, "schema": { "enum": [ "pending", "active", "revoking", "revoked", "degraded" ], "type": "string" } } ], "responses": { "200": {"description": "Caller-owned key metadata page", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/KeyList"}}}}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "503": {"$ref": "#/components/responses/AuthorizationUnavailable"} } }, "post": { "operationId": "issueMyKeyV1", "summary": "Issue a policy-bounded key for the authenticated human", "description": "Owner, Tier and Model grants are derived from identity and issuance policy. Never returns 202.", "x-authorization-mode": "authenticated_human_and_issuance_policy", "x-owner-derived-from-token": true, "x-authorization-projection-gates": ["operation:{allocatedOperationId}#requester", "api_key:{allocatedKeyId}#owner"], "x-secret-response-once": true, "parameters": [{"$ref": "#/components/parameters/IdempotencyKey"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/SelfKeyIssueRequest"}}}}, "responses": { "201": {"description": "New key verified by Gateway; secret returned once", "headers": {"Idempotency-Replayed": {"$ref": "#/components/headers/NotReplayed"}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/KeySecretResponse"}}}}, "200": {"description": "Exact idempotent replay; metadata only", "headers": {"Idempotency-Replayed": {"$ref": "#/components/headers/Replayed"}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Key"}}}}, "400": {"$ref": "#/components/responses/InvalidRequest"}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "409": {"$ref": "#/components/responses/Conflict"}, "503": {"$ref": "#/components/responses/AuthorizationUnavailable"}, "504": {"$ref": "#/components/responses/VerificationTimeout"} } } }, "/api/v1/me/keys/{keyId}": { "get": { "operationId": "getMyKeyV1", "summary": "Get metadata for a directly owned principal or service key", "x-authorization-resource": "api_key:{keyId}", "x-authorization-permission": "api_key#view", "parameters": [{"$ref": "#/components/parameters/KeyId"}], "responses": { "200": {"description": "Caller-owned key metadata", "headers": {"ETag": {"$ref": "#/components/headers/ETag"}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Key"}}}}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "404": {"$ref": "#/components/responses/HiddenOrAbsent"}, "503": {"$ref": "#/components/responses/AuthorizationUnavailable"} } } }, "/api/v1/me/keys/{keyId}:rotate": { "post": { "operationId": "rotateMyKeyV1", "summary": "Rotate a directly owned principal or service key and return the verified secret once", "x-authorization-resource": "api_key:{keyId}", "x-authorization-permission": "api_key#manage", "x-authorization-projection-gates": ["operation:{allocatedOperationId}#requester"], "x-secret-response-once": true, "parameters": [{"$ref": "#/components/parameters/KeyId"}, {"$ref": "#/components/parameters/IfMatch"}, {"$ref": "#/components/parameters/IdempotencyKey"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/KeyRotateRequest"}}}}, "responses": { "200": {"description": "Initial verified rotation returns KeySecretResponse; replay returns Key metadata", "headers": {"Idempotency-Replayed": {"$ref": "#/components/headers/ReplayState"}}, "content": {"application/json": {"schema": {"oneOf": [{"$ref": "#/components/schemas/KeySecretResponse"}, {"$ref": "#/components/schemas/Key"}]}}}}, "400": {"$ref": "#/components/responses/InvalidRequest"}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "404": {"$ref": "#/components/responses/HiddenOrAbsent"}, "409": {"$ref": "#/components/responses/Conflict"}, "412": {"$ref": "#/components/responses/PreconditionFailed"}, "503": {"$ref": "#/components/responses/AuthorizationUnavailable"}, "504": {"$ref": "#/components/responses/VerificationTimeout"} } } }, "/api/v1/me/keys/{keyId}:revoke": { "post": { "operationId": "revokeMyKeyV1", "summary": "Revoke a directly owned principal or service key", "x-authorization-resource": "api_key:{keyId}", "x-authorization-permission": "api_key#manage", "parameters": [{"$ref": "#/components/parameters/KeyId"}, {"$ref": "#/components/parameters/IfMatch"}, {"$ref": "#/components/parameters/IdempotencyKey"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/RevokeRequest"}}}}, "responses": { "202": {"$ref": "#/components/responses/OperationAccepted"}, "400": {"$ref": "#/components/responses/InvalidRequest"}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "404": {"$ref": "#/components/responses/HiddenOrAbsent"}, "409": {"$ref": "#/components/responses/Conflict"}, "412": {"$ref": "#/components/responses/PreconditionFailed"}, "503": {"$ref": "#/components/responses/AuthorizationUnavailable"} } } }, "/api/v1/bulk/previews": { "post": { "operationId": "previewBulkMutationV1", "summary": "Preview exact key revocations for owner offboarding without provider render output", "description": "Rejects the whole preview if any key target is Agent-owned with 409 agent_key_lifecycle_owned_by_publication.", "x-rejected-owner-types": ["agent"], "x-owner-conflict-code": "agent_key_lifecycle_owned_by_publication", "x-authorization-resource": "control_plane:control-plane", "x-authorization-permission": "control_plane#administer", "parameters": [{"$ref": "#/components/parameters/IdempotencyKey"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/BulkPreviewRequest"}}}}, "responses": { "200": {"description": "Bounded semantic impact preview", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/BulkPreview"}}}}, "400": {"$ref": "#/components/responses/InvalidRequest"}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "409": {"$ref": "#/components/responses/Conflict"}, "503": {"$ref": "#/components/responses/AuthorizationUnavailable"} } } }, "/api/v1/bulk/previews/{previewId}:execute": { "post": { "operationId": "executeBulkMutationV1", "summary": "Execute an unexpired exact bulk preview as one durable operation", "description": "Revalidates owner type and rejects the whole execution if any key is Agent-owned with 409 agent_key_lifecycle_owned_by_publication.", "x-rejected-owner-types": ["agent"], "x-owner-conflict-code": "agent_key_lifecycle_owned_by_publication", "x-authorization-resource": "control_plane:control-plane", "x-authorization-permission": "control_plane#administer", "parameters": [{"$ref": "#/components/parameters/PreviewId"}, {"$ref": "#/components/parameters/IdempotencyKey"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/BulkExecuteRequest"}}}}, "responses": { "202": {"$ref": "#/components/responses/OperationAccepted"}, "400": {"$ref": "#/components/responses/InvalidRequest"}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "409": {"$ref": "#/components/responses/Conflict"}, "410": {"$ref": "#/components/responses/PreviewExpired"}, "503": {"$ref": "#/components/responses/AuthorizationUnavailable"} } } }, "/api/v1/me/agent-publication-envelope": { "get": { "operationId": "getMyAgentPublicationEnvelopeV1", "summary": "Read the caller-scoped safe low-code publication envelope", "x-authorization-resource": "control_plane:control-plane", "x-authorization-permission": "control_plane#author_publication", "responses": { "200": {"description": "Safe caller-scoped publication envelope", "headers": {"ETag": {"$ref": "#/components/headers/ETag"}, "Cache-Control": {"schema": {"type": "string", "const": "private, no-store"}}}, "content": {"application/json": {"schema": {"$ref": "../schemas/agent-publication-envelope-v1.schema.json"}}}}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "503": {"$ref": "#/components/responses/AuthorizationUnavailable"} } } }, "/api/v1/low-code/artifacts": { "post": { "operationId": "uploadLowCodeArtifactV1", "summary": "Validate and durably store canonical low-code source bytes", "x-authorization-resource": "control_plane:control-plane", "x-authorization-permission": "control_plane#author_publication", "x-authorization-created-resource": "source_artifact:{sourceArtifactId}#owner@caller", "parameters": [{"$ref": "#/components/parameters/IdempotencyKey"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "../schemas/low-code-artifact-upload-request-v1.schema.json"}}}}, "responses": { "200": {"description": "Canonical source is durable and its owner relationship is confirmed", "content": {"application/json": {"schema": {"$ref": "../schemas/low-code-artifact-upload-response-v1.schema.json"}}}}, "400": {"$ref": "#/components/responses/InvalidRequest"}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "409": {"$ref": "#/components/responses/Conflict"}, "413": {"description": "Framed request or canonical source exceeds the fixed R2 limit", "content": {"application/json": {"schema": {"$ref": "../schemas/error-v1.schema.json"}}}}, "429": {"description": "Caller/global source rate, object or byte capacity is exhausted", "content": {"application/json": {"schema": {"$ref": "../schemas/error-v1.schema.json"}}}}, "503": {"$ref": "#/components/responses/AuthorizationUnavailable"} } } }, "/api/v1/agents": { "get": { "operationId": "listManagedAgentsV1", "summary": "List Control Plane publication desired state, not Registry catalog projections", "x-authorization-resource": "agent_publication:{agentId}", "x-authorization-permission": "agent_publication#manage", "x-authorization-list-filter": "permission-filtered per agent_publication object", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 2048 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 20 } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 256 } }, { "name": "sort", "in": "query", "required": false, "schema": { "enum": [ "name", "-name", "createdAt", "-createdAt" ], "type": "string" } }, { "name": "publicationState", "in": "query", "required": false, "schema": { "enum": [ "active", "degraded", "suspended", "unpublished" ], "type": "string" } } ], "responses": { "200": {"description": "Managed Agent page", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/AgentList"}}}}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "503": {"$ref": "#/components/responses/AuthorizationUnavailable"} } }, "post": { "operationId": "createAgentV1", "summary": "Create Publisher-issued Agent and initial immutable low-code version", "x-authorization-resource": "control_plane:control-plane", "x-authorization-permission": "control_plane#author_publication", "x-authorization-source": "source_artifact:{sourceArtifactId}#use", "x-owner-assignment-policy": "owner omitted, explicitly equals authenticated caller, or explicitly approved by control_plane#administer", "parameters": [{"$ref": "#/components/parameters/IdempotencyKey"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/AgentCreateRequest"}}}}, "responses": { "202": {"description": "Agent and initial immutable AgentVersion are durably allocated", "content": {"application/json": {"schema": {"$ref": "../schemas/low-code-operation-accepted-v1.schema.json"}}}}, "400": {"$ref": "#/components/responses/InvalidRequest"}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "409": {"$ref": "#/components/responses/Conflict"}, "503": {"$ref": "#/components/responses/AuthorizationUnavailable"} } } }, "/api/v1/agents/{agentId}": { "get": { "operationId": "getManagedAgentV1", "summary": "Get Control Plane Agent desired state", "x-authorization-any-of": [ {"resource": "agent_publication:{agentId}", "permission": "agent_publication#manage"} ], "parameters": [{"$ref": "#/components/parameters/AgentId"}], "responses": { "200": {"description": "Managed Agent", "headers": {"ETag": {"$ref": "#/components/headers/ETag"}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Agent"}}}}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "503": {"$ref": "#/components/responses/AuthorizationUnavailable"} } }, "patch": { "operationId": "updateManagedAgentV1", "summary": "Update Agent metadata or direct owner without changing immutable versions", "description": "name/displayName/description are mutable desired Agent metadata, but immutable AgentVersion/Card bytes do not change. Active name or owner changes complete only after an exact Registry metadata-owner projection receipt; inactive name is desired-only until the next activation. Owner changes require an active Service.", "x-authorization-resource": "agent:{agentId}", "x-authorization-permission": "agent#manage", "x-authorization-owner-transfer-gate": "When owner changes, Registry must atomically replace the old agent#owner tuple and CP must persist its consistency receipt before success.", "parameters": [{"$ref": "#/components/parameters/AgentId"}, {"$ref": "#/components/parameters/IfMatch"}, {"$ref": "#/components/parameters/IdempotencyKey"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/AgentUpdateRequest"}}}}, "responses": { "202": {"$ref": "#/components/responses/OperationAccepted"}, "400": {"$ref": "#/components/responses/InvalidRequest"}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "409": {"$ref": "#/components/responses/Conflict"}, "412": {"$ref": "#/components/responses/PreconditionFailed"}, "503": {"$ref": "#/components/responses/AuthorizationUnavailable"} } } }, "/api/v1/agents/{agentId}/versions": { "get": { "operationId": "listAgentVersionsV1", "summary": "List immutable versions for a managed Agent", "x-authorization-any-of": [ {"resource": "agent_publication:{agentId}", "permission": "agent_publication#manage"}, {"resource": "agent:{agentId}", "permission": "agent#diagnose"} ], "parameters": [{"$ref": "#/components/parameters/AgentId"}, {"$ref": "#/components/parameters/Cursor"}, {"$ref": "#/components/parameters/Limit"}], "responses": { "200": {"description": "AgentVersion page", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/AgentVersionList"}}}}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "503": {"$ref": "#/components/responses/AuthorizationUnavailable"} } }, "post": { "operationId": "createAgentVersionV1", "summary": "Create and publish an immutable low-code AgentVersion candidate", "x-authorization-resource": "agent_publication:{agentId}", "x-authorization-permission": "agent_publication#manage", "x-authorization-source": "source_artifact:{sourceArtifactId}#use", "parameters": [{"$ref": "#/components/parameters/AgentId"}, {"$ref": "#/components/parameters/IfMatch"}, {"$ref": "#/components/parameters/IdempotencyKey"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/AgentVersionCreateRequest"}}}}, "responses": { "202": {"description": "New immutable AgentVersion is durably allocated", "content": {"application/json": {"schema": {"$ref": "../schemas/low-code-operation-accepted-v1.schema.json"}}}}, "400": {"$ref": "#/components/responses/InvalidRequest"}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "409": {"$ref": "#/components/responses/Conflict"}, "412": {"$ref": "#/components/responses/PreconditionFailed"}, "503": {"$ref": "#/components/responses/AuthorizationUnavailable"} } } }, "/api/v1/agents/{agentId}/versions/{versionId}": { "get": { "operationId": "getAgentVersionV1", "summary": "Get immutable AgentVersion metadata", "x-authorization-any-of": [ {"resource": "agent_publication:{agentId}", "permission": "agent_publication#manage"}, {"resource": "agent:{agentId}", "permission": "agent#diagnose"} ], "parameters": [{"$ref": "#/components/parameters/AgentId"}, {"$ref": "#/components/parameters/VersionId"}], "responses": { "200": {"description": "AgentVersion", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/AgentVersion"}}}}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "503": {"$ref": "#/components/responses/AuthorizationUnavailable"} } } }, "/api/v1/agents/{agentId}:rollback": { "post": { "operationId": "rollbackAgentV1", "summary": "Select a previously verified immutable version", "x-authorization-resource": "agent_publication:{agentId}", "x-authorization-permission": "agent_publication#manage", "parameters": [{"$ref": "#/components/parameters/AgentId"}, {"$ref": "#/components/parameters/IfMatch"}, {"$ref": "#/components/parameters/IdempotencyKey"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/AgentRollbackRequest"}}}}, "responses": { "202": {"$ref": "#/components/responses/OperationAccepted"}, "400": {"$ref": "#/components/responses/InvalidRequest"}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "409": {"$ref": "#/components/responses/Conflict"}, "412": {"$ref": "#/components/responses/PreconditionFailed"}, "503": {"$ref": "#/components/responses/AuthorizationUnavailable"} } } }, "/api/v1/agents/{agentId}:unpublish": { "post": { "operationId": "unpublishAgentV1", "summary": "Remove reachability while preserving Agent identity and history", "x-authorization-resource": "agent_publication:{agentId}", "x-authorization-permission": "agent_publication#manage", "parameters": [{"$ref": "#/components/parameters/AgentId"}, {"$ref": "#/components/parameters/IfMatch"}, {"$ref": "#/components/parameters/IdempotencyKey"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/AgentUnpublishRequest"}}}}, "responses": { "202": {"$ref": "#/components/responses/OperationAccepted"}, "400": {"$ref": "#/components/responses/InvalidRequest"}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "409": {"$ref": "#/components/responses/Conflict"}, "412": {"$ref": "#/components/responses/PreconditionFailed"}, "503": {"$ref": "#/components/responses/AuthorizationUnavailable"} } } }, "/api/v1/agents/{agentId}:revalidate": { "post": { "operationId": "revalidateAgentV1", "summary": "Revalidate a suspended or recoverable degraded publication through all applicable gates", "x-authorization-resource": "agent_publication:{agentId}", "x-authorization-permission": "agent_publication#manage", "parameters": [{"$ref": "#/components/parameters/AgentId"}, {"$ref": "#/components/parameters/IfMatch"}, {"$ref": "#/components/parameters/IdempotencyKey"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/AgentRevalidateRequest"}}}}, "responses": { "202": {"$ref": "#/components/responses/OperationAccepted"}, "400": {"$ref": "#/components/responses/InvalidRequest"}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "409": {"$ref": "#/components/responses/Conflict"}, "412": {"$ref": "#/components/responses/PreconditionFailed"}, "503": {"$ref": "#/components/responses/AuthorizationUnavailable"} } } }, "/api/v1/agents/{agentId}/status": { "get": { "operationId": "getAgentPublicationStatusV1", "summary": "Read safe desired, applied, verified and Registry projection status", "x-authorization-any-of": [ {"resource": "agent_publication:{agentId}", "permission": "agent_publication#manage"}, {"resource": "agent:{agentId}", "permission": "agent#diagnose"} ], "parameters": [{"$ref": "#/components/parameters/AgentId"}], "responses": { "200": {"description": "Canonical detailed publication status", "content": {"application/json": {"schema": {"$ref": "../schemas/publication-status-v1.schema.json"}}}}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "503": {"$ref": "#/components/responses/AuthorizationUnavailable"} } } }, "/api/v1/operations": { "get": { "operationId": "listOperationsV1", "summary": "List durable operation status without secret material", "x-authorization-resource": "control_plane:control-plane", "x-authorization-permission": "control_plane#operate", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 2048 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 20 } }, { "name": "state", "in": "query", "required": false, "schema": { "enum": [ "accepted", "running", "retry_wait", "verifying", "compensating", "succeeded", "failed", "cancelled" ], "type": "string" } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 256 } }, { "name": "sort", "in": "query", "required": false, "schema": { "enum": [ "createdAt", "-createdAt" ], "type": "string" } }, { "name": "resourceId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "kind", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 96 } } ], "responses": { "200": {"description": "Operation page", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/OperationList"}}}}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "503": {"$ref": "#/components/responses/AuthorizationUnavailable"} } } }, "/api/v1/operations/{operationId}": { "get": { "operationId": "getOperationV1", "summary": "Get durable operation status; no operation can contain a secret", "x-authorization-any-of": [ {"resource": "control_plane:control-plane", "permission": "control_plane#operate"}, {"resource": "operation:{operationId}", "permission": "operation#view"} ], "parameters": [{"$ref": "#/components/parameters/OperationId"}], "responses": { "200": {"description": "Durable operation", "content": {"application/json": {"schema": {"$ref": "../schemas/operation-v1.schema.json"}}}}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "503": {"$ref": "#/components/responses/AuthorizationUnavailable"} } } }, "/api/v1/operations/{operationId}:cancel": { "post": { "operationId": "cancelOperationV1", "summary": "Request bounded cancellation; already applied effects use compensation", "x-authorization-any-of": [ {"resource": "control_plane:control-plane", "permission": "control_plane#operate"}, {"resource": "operation:{operationId}", "permission": "operation#cancel"} ], "x-domain-safe-boundary-required": true, "parameters": [{"$ref": "#/components/parameters/OperationId"}, {"$ref": "#/components/parameters/IdempotencyKey"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CancelRequest"}}}}, "responses": { "202": {"$ref": "#/components/responses/OperationAccepted"}, "400": {"$ref": "#/components/responses/InvalidRequest"}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "409": {"$ref": "#/components/responses/Conflict"}, "503": {"$ref": "#/components/responses/AuthorizationUnavailable"} } } }, "/api/v1/system/drift": { "get": { "operationId": "listControlPlaneDriftV1", "summary": "List safe drift classifications for Control Plane-owned domains", "x-authorization-resource": "control_plane:control-plane", "x-authorization-permission": "control_plane#observe", "parameters": [{"$ref": "#/components/parameters/Cursor"}, {"$ref": "#/components/parameters/Limit"}, {"$ref": "#/components/parameters/Domain"}], "responses": { "200": {"description": "Drift report", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/DriftReport"}}}}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "503": {"$ref": "#/components/responses/AuthorizationUnavailable"} } } }, "/api/v1/audit": { "get": { "operationId": "listControlPlaneAuditV1", "summary": "List immutable safe management audit records", "x-authorization-resource": "control_plane:control-plane", "x-authorization-permission": "control_plane#observe", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 2048 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 20 } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 256 } }, { "name": "sort", "in": "query", "required": false, "schema": { "enum": [ "occurredAt", "-occurredAt" ], "type": "string" } }, { "name": "resourceId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "actorIssuer", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 1024 } }, { "name": "actorSubject", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 1024 } }, { "name": "action", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 1024 } }, { "name": "outcome", "in": "query", "required": false, "schema": { "enum": [ "accepted", "succeeded", "failed", "denied" ], "type": "string" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": {"description": "Audit page", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/AuditList"}}}}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "503": {"$ref": "#/components/responses/AuthorizationUnavailable"} } } }, "/api/v1/system:reconcile": { "post": { "operationId": "reconcileControlPlaneV1", "summary": "Request typed reconciliation without caller-selected infrastructure", "description": "May observe blocked_recovery but cannot resolve it, adopt/prune restored state, materialize a withheld Secret or resurrect a revoked generation.", "x-authorization-resource": "control_plane:control-plane", "x-authorization-permission": "control_plane#operate", "parameters": [{"$ref": "#/components/parameters/IdempotencyKey"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ReconcileRequest"}}}}, "responses": { "202": {"$ref": "#/components/responses/OperationAccepted"}, "400": {"$ref": "#/components/responses/InvalidRequest"}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "409": {"$ref": "#/components/responses/Conflict"}, "503": {"$ref": "#/components/responses/AuthorizationUnavailable"} } } }, "/api/v1/recovery/previews": { "post": { "operationId": "createRecoveryPreviewV1", "summary": "Store an immutable observe-only recovery preview", "description": "The server binds the typed reason to the current frozen complete snapshot, inventory and scope coordinates; callers do not supply infrastructure references. Legacy inventory is classification-only and any legacy item blocks clean-slate rollout until external cleanup and a repeated complete inventory.", "x-authorization-resource": "control_plane:control-plane", "x-authorization-permission": "control_plane#operate", "x-recovery-coordinate-binding": "server-derived-exact-frozen-state", "parameters": [{"$ref": "#/components/parameters/IdempotencyKey"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/RecoveryPreviewRequest"}}}}, "responses": { "200": {"$ref": "#/components/responses/RecoveryPreviewStored"}, "400": {"$ref": "#/components/responses/InvalidRequest"}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "409": {"$ref": "#/components/responses/Conflict"}, "503": {"$ref": "#/components/responses/AuthorizationUnavailable"} } } }, "/api/v1/recovery/previews/{previewId}:execute": { "post": { "operationId": "executeRecoveryPlanV1", "summary": "Execute exact decisions from an unexpired stored recovery preview", "description": "Every decision is bound to item, observation and revision; inline destructive confirmation becomes an immutable actor-bound audit fact. Legacy decisions are quarantine/withhold no-ops and do not clear the rollout blocker.", "x-authorization-resource": "control_plane:control-plane", "x-authorization-permission": "control_plane#operate", "x-recovery-execution-guard": "exact-preview-digest-expiry-snapshot-inventory-scope-and-item-bindings", "parameters": [{"$ref": "#/components/parameters/PreviewId"}, {"$ref": "#/components/parameters/IdempotencyKey"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/RecoveryExecuteRequest"}}}}, "responses": { "202": {"$ref": "#/components/responses/OperationAccepted"}, "400": {"$ref": "#/components/responses/InvalidRequest"}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "409": {"$ref": "#/components/responses/Conflict"}, "410": {"$ref": "#/components/responses/PreviewExpired"}, "503": {"$ref": "#/components/responses/AuthorizationUnavailable"} } } }, "/api/v1/models/{modelId}/guardrail-binding": { "get": { "operationId": "getModelGuardrailBindingV1", "x-authorization-resource": "control_plane:control-plane", "x-authorization-permission": "control_plane#administer", "parameters": [ { "$ref": "#/components/parameters/ModelId" } ], "responses": { "200": { "description": "Pinned Model binding and confirmed serving state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuardrailBinding" } } }, "headers": { "ETag": { "required": true, "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "503": { "$ref": "#/components/responses/AuthorizationUnavailable" } }, "summary": "Read desired binding and last all-serving observation" }, "put": { "operationId": "replaceModelGuardrailBindingV1", "summary": "Apply, replace or detach a pinned policy through the existing Model writer", "x-authorization-resource": "control_plane:control-plane", "x-authorization-permission": "control_plane#administer", "parameters": [ { "$ref": "#/components/parameters/ModelId" }, { "$ref": "#/components/parameters/IfMatch" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuardrailBindingReplace" } } } }, "responses": { "202": { "$ref": "#/components/responses/OperationAccepted" }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "503": { "$ref": "#/components/responses/AuthorizationUnavailable" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/guardrail-providers": { "get": { "operationId": "listGuardrailProvidersV1", "x-authorization-resource": "control_plane:control-plane", "x-authorization-permission": "control_plane#administer", "parameters": [], "responses": { "200": { "description": "Approved descriptors; never credential values", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuardrailProviderCatalog" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "503": { "$ref": "#/components/responses/AuthorizationUnavailable" } }, "summary": "Read deployment-approved classifier and detector descriptors" } } }, "components": { "securitySchemes": { "bearerAuth": {"type": "http", "scheme": "bearer", "bearerFormat": "JWT"} }, "parameters": { "IdempotencyKey": {"name": "Idempotency-Key", "in": "header", "required": true, "schema": {"type": "string", "minLength": 16, "maxLength": 128, "pattern": "^[A-Za-z0-9._~-]+$"}}, "IfMatch": {"name": "If-Match", "in": "header", "required": true, "description": "Exact ETag returned by the resource read", "schema": {"type": "string", "pattern": "^\"r[1-9][0-9]*\"$"}}, "Cursor": {"name": "cursor", "in": "query", "schema": {"type": "string", "minLength": 1, "maxLength": 2048}}, "Limit": {"name": "limit", "in": "query", "schema": {"type": "integer", "minimum": 1, "maximum": 100, "default": 20}}, "TierId": {"name": "tierId", "in": "path", "required": true, "schema": {"$ref": "#/components/schemas/UuidV7"}}, "ProviderId": {"name": "providerId", "in": "path", "required": true, "schema": {"$ref": "#/components/schemas/UuidV7"}}, "ModelId": {"name": "modelId", "in": "path", "required": true, "schema": {"$ref": "#/components/schemas/UuidV7"}}, "KeyId": {"name": "keyId", "in": "path", "required": true, "schema": {"$ref": "#/components/schemas/UuidV7"}}, "AgentId": {"name": "agentId", "in": "path", "required": true, "schema": {"$ref": "#/components/schemas/UuidV7"}}, "VersionId": {"name": "versionId", "in": "path", "required": true, "schema": {"$ref": "#/components/schemas/UuidV7"}}, "OperationId": {"name": "operationId", "in": "path", "required": true, "schema": {"$ref": "#/components/schemas/UuidV7"}}, "PreviewId": {"name": "previewId", "in": "path", "required": true, "schema": {"$ref": "#/components/schemas/UuidV7"}}, "OwnerType": {"name": "ownerType", "in": "query", "schema": {"enum": ["principal", "service", "agent"]}}, "OwnerIssuer": {"name": "ownerIssuer", "in": "query", "description": "Exact issuer filter; valid only with ownerType principal or service and ownerSubject", "schema": {"type": "string", "format": "uri", "maxLength": 1024, "pattern": "^https://[^?#]+$"}}, "OwnerSubject": {"name": "ownerSubject", "in": "query", "description": "Exact immutable subject filter; valid only with ownerType principal or service and ownerIssuer", "schema": {"type": "string", "minLength": 1, "maxLength": 512, "pattern": "^[^\\u0000-\\u001f\\u007f]+$"}}, "OperationState": {"name": "state", "in": "query", "schema": {"enum": ["accepted", "running", "retry_wait", "verifying", "compensating", "succeeded", "failed", "cancelled"]}}, "Domain": {"name": "domain", "in": "query", "schema": {"$ref": "#/components/schemas/Domain"}} }, "headers": { "ETag": {"description": "Exact mutable resource revision", "schema": {"type": "string", "pattern": "^\"r[1-9][0-9]*\"$"}}, "NotReplayed": {"description": "New execution; one-time secret may be present", "required": true, "schema": {"type": "boolean", "const": false}}, "Replayed": {"description": "Exact idempotent replay; no secret is present", "required": true, "schema": {"type": "boolean", "const": true}}, "ReplayState": {"description": "False only for the initial one-time secret response; true for metadata-only replay", "required": true, "schema": {"type": "boolean"}} }, "schemas": { "GuardrailPolicy": {"type": "object", "additionalProperties": false, "required": ["id", "name", "description", "revision", "status", "definitionDigest", "createdAt", "updatedAt", "ruleCount", "ruleKinds"], "properties": {"id": {"$ref": "#/components/schemas/UuidV7"}, "name": {"type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]*$"}, "description": {"type": "string", "maxLength": 2048}, "revision": {"$ref": "#/components/schemas/Revision"}, "status": {"enum": ["draft", "archived"]}, "definitionDigest": {"type": "string", "pattern": "^sha256:[0-9a-f]{64}$"}, "createdAt": {"$ref": "#/components/schemas/Timestamp"}, "updatedAt": {"$ref": "#/components/schemas/Timestamp"}, "ruleCount": {"type": "integer", "minimum": 2}, "ruleKinds": {"type": "array", "uniqueItems": true, "items": {"enum": ["stop_list", "regex", "external_pipeline", "llm_classifier"]}}}}, "GuardrailPolicyDetail": {"type": "object", "additionalProperties": false, "required": ["id", "name", "description", "revision", "status", "definitionDigest", "createdAt", "updatedAt", "ruleCount", "ruleKinds", "definition"], "properties": {"id": {"$ref": "#/components/schemas/UuidV7"}, "name": {"type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]*$"}, "description": {"type": "string", "maxLength": 2048}, "revision": {"$ref": "#/components/schemas/Revision"}, "status": {"enum": ["draft", "archived"]}, "definitionDigest": {"type": "string", "pattern": "^sha256:[0-9a-f]{64}$"}, "createdAt": {"$ref": "#/components/schemas/Timestamp"}, "updatedAt": {"$ref": "#/components/schemas/Timestamp"}, "ruleCount": {"type": "integer", "minimum": 2}, "ruleKinds": {"type": "array", "uniqueItems": true, "items": {"enum": ["stop_list", "regex", "external_pipeline", "llm_classifier"]}}, "definition": {"$ref": "../schemas/guardrail-definition-v1.schema.json"}}}, "GuardrailPolicyCreate": {"type": "object", "additionalProperties": false, "required": ["name", "definition"], "properties": {"name": {"type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]*$"}, "description": {"type": "string", "maxLength": 2048}, "definition": {"$ref": "../schemas/guardrail-definition-v1.schema.json"}}}, "GuardrailPolicyReplace": {"type": "object", "additionalProperties": false, "required": ["name", "definition", "status"], "properties": {"name": {"type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]*$"}, "description": {"type": "string", "maxLength": 2048}, "definition": {"$ref": "../schemas/guardrail-definition-v1.schema.json"}, "status": {"enum": ["draft", "archived"]}}}, "GuardrailPolicyList": {"type": "object", "additionalProperties": false, "required": ["items", "page"], "properties": {"items": {"type": "array", "items": {"$ref": "#/components/schemas/GuardrailPolicy"}}, "page": {"type": "object", "additionalProperties": false, "properties": {"nextCursor": {"type": "string"}}}}}, "GuardrailPolicyRevisions": {"type": "object", "additionalProperties": false, "required": ["items", "page"], "properties": {"items": {"type": "array", "items": {"$ref": "#/components/schemas/GuardrailPolicy"}}, "page": {"type": "object", "additionalProperties": false, "properties": {"beforeRevision": {"type": "integer", "minimum": 1}}}}}, "Uuid": {"type": "string", "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"}, "UuidV7": {"type": "string", "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"}, "Digest": {"type": "string", "pattern": "^sha256:[0-9a-f]{64}$"}, "Revision": {"type": "integer", "minimum": 1}, "Timestamp": {"type": "string", "format": "date-time"}, "Page": {"type": "object", "additionalProperties": false, "properties": {"nextCursor": {"type": "string", "minLength": 1, "maxLength": 2048}}, "required": []}, "DirectOwner": { "oneOf": [ {"$ref": "#/components/schemas/PrincipalOwner"}, {"$ref": "#/components/schemas/ServiceOwner"} ] }, "KeyOwner": { "oneOf": [ {"$ref": "#/components/schemas/PrincipalOwner"}, {"$ref": "#/components/schemas/ServiceOwner"}, {"$ref": "#/components/schemas/AgentOwner"} ] }, "PrincipalOwner": {"type": "object", "additionalProperties": false, "required": ["type", "issuer", "subject"], "properties": {"type": {"const": "principal"}, "issuer": {"type": "string", "format": "uri", "maxLength": 1024, "pattern": "^(?:https://[^?#]+|http://(?:localhost|(?:[A-Za-z0-9-]+\\.)+localhost)(?::[0-9]{1,5})?(?:/[^?#]*)?)$", "description": "HTTPS issuer; HTTP is accepted only for the dev-local localhost profile"}, "subject": {"type": "string", "minLength": 1, "maxLength": 512, "pattern": "^[^\\u0000-\\u001f\\u007f]+$"}}}, "ServiceOwner": {"type": "object", "additionalProperties": false, "required": ["type", "issuer", "subject"], "properties": {"type": {"const": "service"}, "issuer": {"type": "string", "format": "uri", "maxLength": 1024, "pattern": "^(?:https://[^?#]+|http://(?:localhost|(?:[A-Za-z0-9-]+\\.)+localhost)(?::[0-9]{1,5})?(?:/[^?#]*)?)$", "description": "HTTPS issuer; HTTP is accepted only for the dev-local localhost profile"}, "subject": {"type": "string", "minLength": 1, "maxLength": 512, "pattern": "^[^\\u0000-\\u001f\\u007f]+$"}}}, "AgentOwner": {"type": "object", "additionalProperties": false, "required": ["type", "agentId"], "properties": {"type": {"const": "agent"}, "agentId": {"$ref": "#/components/schemas/UuidV7"}}}, "KeyIssuancePolicy": {"type": "object", "additionalProperties": false, "required": ["schemaVersion", "policyId", "enabled", "allowedTierIds", "allowedModelIds", "maxActiveKeysPerPrincipal", "verifiedState", "revision", "createdAt", "updatedAt"], "properties": {"schemaVersion": {"const": "agent-platform.control-plane.key-issuance-policy/v1"}, "policyId": {"$ref": "#/components/schemas/UuidV7"}, "enabled": {"type": "boolean"}, "allowedTierIds": {"type": "array", "minItems": 0, "maxItems": 256, "uniqueItems": true, "items": {"$ref": "#/components/schemas/UuidV7"}, "description": "One entry is fixed; multiple entries let self-issue select one member"}, "allowedModelIds": {"type": "array", "minItems": 0, "maxItems": 256, "uniqueItems": true, "items": {"$ref": "#/components/schemas/UuidV7"}, "description": "Exact set materialized into every new self-issued key"}, "maxActiveKeysPerPrincipal": {"type": "integer", "minimum": 1, "maximum": 100}, "verifiedState": {"enum": ["pending", "enabled", "disabled", "degraded"]}, "revision": {"$ref": "#/components/schemas/Revision"}, "createdAt": {"$ref": "#/components/schemas/Timestamp"}, "updatedAt": {"$ref": "#/components/schemas/Timestamp"}}, "allOf": [{"if": {"properties": {"enabled": {"const": true}}, "required": ["enabled"]}, "then": {"properties": {"allowedTierIds": {"minItems": 1}, "allowedModelIds": {"minItems": 1}}}}]}, "SelfKeyIssuancePolicy": {"type": "object", "additionalProperties": false, "required": ["schemaVersion", "enabled", "allowedTiers", "allowedModels", "maxActiveKeys", "remainingActiveKeys", "policyRevision"], "properties": {"schemaVersion": {"const": "agent-platform.control-plane.self-key-issuance-policy/v1"}, "enabled": {"type": "boolean"}, "allowedTiers": {"type": "array", "minItems": 0, "maxItems": 256, "uniqueItems": true, "items": {"$ref": "#/components/schemas/SelfServiceTierSummary"}}, "allowedModels": {"type": "array", "minItems": 0, "maxItems": 256, "uniqueItems": true, "items": {"$ref": "#/components/schemas/SelfServiceModelSummary"}}, "maxActiveKeys": {"type": "integer", "minimum": 1, "maximum": 100}, "remainingActiveKeys": {"type": "integer", "minimum": 0, "maximum": 100}, "policyRevision": {"$ref": "#/components/schemas/Revision"}}, "allOf": [{"if": {"properties": {"enabled": {"const": true}}, "required": ["enabled"]}, "then": {"properties": {"allowedTiers": {"minItems": 1}, "allowedModels": {"minItems": 1}}}}]}, "SelfServiceTierSummary": {"type": "object", "additionalProperties": false, "required": ["id", "name", "requestsPerMinute", "tokensPerMinute"], "properties": {"id": {"$ref": "#/components/schemas/UuidV7"}, "name": {"type": "string", "pattern": "^[a-z][a-z0-9._-]{0,127}$"}, "requestsPerMinute": {"type": "integer", "minimum": 1}, "tokensPerMinute": {"type": "integer", "minimum": 1}}}, "SelfServiceModelSummary": {"type": "object", "additionalProperties": false, "required": ["id", "name"], "properties": {"id": {"$ref": "#/components/schemas/UuidV7"}, "name": {"type": "string", "pattern": "^[a-z][a-z0-9._-]{0,127}$", "description": "Safe Gateway model name; no Provider identity or upstream endpoint is exposed"}}}, "KeyIssuancePolicyUpdateRequest": {"type": "object", "additionalProperties": false, "minProperties": 1, "description": "Patch is merged with the current singleton, then the effective KeyIssuancePolicy conditional is validated", "properties": {"enabled": {"type": "boolean"}, "allowedTierIds": {"type": "array", "minItems": 0, "maxItems": 256, "uniqueItems": true, "items": {"$ref": "#/components/schemas/UuidV7"}}, "allowedModelIds": {"type": "array", "minItems": 0, "maxItems": 256, "uniqueItems": true, "items": {"$ref": "#/components/schemas/UuidV7"}}, "maxActiveKeysPerPrincipal": {"type": "integer", "minimum": 1, "maximum": 100}}}, "AgentPublicationPolicy": {"type": "object", "additionalProperties": false, "required": ["schemaVersion", "policyId", "enabled", "allowedModelIds", "policyDigest", "verifiedState", "revision", "createdAt", "updatedAt"], "properties": {"schemaVersion": {"const": "agent-platform.control-plane.agent-publication-policy/v1"}, "policyId": {"$ref": "#/components/schemas/UuidV7"}, "enabled": {"type": "boolean"}, "tierId": {"$ref": "#/components/schemas/UuidV7"}, "allowedModelIds": {"type": "array", "minItems": 0, "maxItems": 256, "uniqueItems": true, "items": {"$ref": "#/components/schemas/UuidV7"}}, "policyDigest": {"$ref": "#/components/schemas/Digest"}, "verifiedState": {"enum": ["pending", "enabled", "disabled", "degraded"]}, "revision": {"$ref": "#/components/schemas/Revision"}, "createdAt": {"$ref": "#/components/schemas/Timestamp"}, "updatedAt": {"$ref": "#/components/schemas/Timestamp"}}, "allOf": [{"if": {"properties": {"enabled": {"const": true}}, "required": ["enabled"]}, "then": {"required": ["tierId"], "properties": {"allowedModelIds": {"minItems": 1}}}}]}, "AgentPublicationPolicyUpdateRequest": {"type": "object", "additionalProperties": false, "minProperties": 1, "description": "Patch is merged with the current singleton, then the effective AgentPublicationPolicy conditional is validated", "properties": {"enabled": {"type": "boolean"}, "tierId": {"description": "Set null only when the effective policy is disabled, to release the Tier reference", "oneOf": [{"$ref": "#/components/schemas/UuidV7"}, {"type": "null"}]}, "allowedModelIds": {"type": "array", "minItems": 0, "maxItems": 256, "uniqueItems": true, "items": {"$ref": "#/components/schemas/UuidV7"}}}}, "Tier": {"type": "object", "additionalProperties": false, "required": ["id", "name", "requestsPerMinute", "tokensPerMinute", "desiredState", "verifiedState", "revision", "createdAt", "updatedAt"], "properties": {"id": {"$ref": "#/components/schemas/UuidV7"}, "name": {"type": "string", "pattern": "^[a-z][a-z0-9._-]{0,127}$"}, "displayName": {"type": "string", "minLength": 1, "maxLength": 128}, "requestsPerMinute": {"type": "integer", "minimum": 1}, "tokensPerMinute": {"type": "integer", "minimum": 1}, "desiredState": {"enum": ["enabled", "disabled"]}, "verifiedState": {"enum": ["pending", "enabled", "disabled", "degraded"]}, "revision": {"$ref": "#/components/schemas/Revision"}, "createdAt": {"$ref": "#/components/schemas/Timestamp"}, "updatedAt": {"$ref": "#/components/schemas/Timestamp"}}}, "TierCreateRequest": {"type": "object", "additionalProperties": false, "required": ["name", "requestsPerMinute", "tokensPerMinute", "desiredState"], "properties": {"name": {"type": "string", "pattern": "^[a-z][a-z0-9._-]{0,127}$"}, "displayName": {"type": "string", "minLength": 1, "maxLength": 128}, "requestsPerMinute": {"type": "integer", "minimum": 1}, "tokensPerMinute": {"type": "integer", "minimum": 1}, "desiredState": {"enum": ["enabled", "disabled"]}}}, "TierUpdateRequest": {"type": "object", "additionalProperties": false, "minProperties": 1, "properties": {"displayName": {"type": "string", "minLength": 1, "maxLength": 128}, "requestsPerMinute": {"type": "integer", "minimum": 1}, "tokensPerMinute": {"type": "integer", "minimum": 1}, "desiredState": {"enum": ["enabled", "disabled"]}}}, "TierList": {"type": "object", "additionalProperties": false, "required": ["items", "page"], "properties": {"items": {"type": "array", "items": {"$ref": "#/components/schemas/Tier"}}, "page": {"$ref": "#/components/schemas/Page"}}}, "Provider": {"type": "object", "additionalProperties": false, "required": ["id", "name", "kind", "endpoint", "credentialStatus", "desiredState", "verifiedState", "revision", "createdAt", "updatedAt"], "properties": {"id": {"$ref": "#/components/schemas/UuidV7"}, "name": {"type": "string", "pattern": "^[a-z][a-z0-9._-]{0,127}$"}, "kind": {"enum": ["openai_compatible"]}, "endpoint": {"type": "string", "format": "uri", "pattern": "^https?://"}, "credentialStatus": {"enum": ["missing", "pending", "verified", "invalid"]}, "credentialFingerprint": {"type": "string", "pattern": "^sha256:[0-9a-f]{64}$"}, "desiredState": {"enum": ["enabled", "disabled"]}, "verifiedState": {"enum": ["pending", "enabled", "disabled", "degraded"]}, "revision": {"$ref": "#/components/schemas/Revision"}, "createdAt": {"$ref": "#/components/schemas/Timestamp"}, "updatedAt": {"$ref": "#/components/schemas/Timestamp"}}}, "ProviderCreateRequest": {"type": "object", "additionalProperties": false, "required": ["name", "kind", "endpoint", "desiredState"], "properties": {"name": {"type": "string", "pattern": "^[a-z][a-z0-9._-]{0,127}$"}, "kind": {"const": "openai_compatible"}, "endpoint": {"type": "string", "format": "uri", "pattern": "^https?://"}, "desiredState": {"const": "disabled", "description": "R2 create is non-secret; the credential subresource must verify a credential before PATCH enabled"}}}, "ProviderUpdateRequest": {"type": "object", "additionalProperties": false, "minProperties": 1, "properties": {"endpoint": {"type": "string", "format": "uri", "pattern": "^https?://"}, "desiredState": {"enum": ["enabled", "disabled"]}}}, "ProviderCredentialWriteRequest": {"type": "object", "additionalProperties": false, "required": ["credential", "reason"], "properties": {"credential": {"type": "string", "minLength": 16, "maxLength": 8192, "writeOnly": true, "x-sensitive": true}, "reason": {"type": "string", "minLength": 1, "maxLength": 512}}}, "ProviderList": {"type": "object", "additionalProperties": false, "required": ["items", "page"], "properties": {"items": {"type": "array", "items": {"$ref": "#/components/schemas/Provider"}}, "page": {"$ref": "#/components/schemas/Page"}}}, "Model": {"type": "object", "additionalProperties": false, "required": ["id", "gatewayName", "providerId", "upstreamModel", "profile", "desiredState", "verifiedState", "revision", "createdAt", "updatedAt"], "properties": {"id": {"$ref": "#/components/schemas/UuidV7"}, "gatewayName": {"type": "string", "pattern": "^[a-z][a-z0-9._-]{0,127}$"}, "providerId": {"$ref": "#/components/schemas/UuidV7"}, "upstreamModel": {"type": "string", "minLength": 1, "maxLength": 256}, "profile": {"enum": ["internal", "external"]}, "desiredState": {"enum": ["enabled", "disabled"]}, "verifiedState": {"enum": ["pending", "enabled", "disabled", "degraded"]}, "revision": {"$ref": "#/components/schemas/Revision"}, "createdAt": {"$ref": "#/components/schemas/Timestamp"}, "updatedAt": {"$ref": "#/components/schemas/Timestamp"}}}, "ModelCreateRequest": {"type": "object", "additionalProperties": false, "required": ["gatewayName", "providerId", "upstreamModel", "profile", "desiredState"], "properties": {"gatewayName": {"type": "string", "pattern": "^[a-z][a-z0-9._-]{0,127}$"}, "providerId": {"$ref": "#/components/schemas/UuidV7"}, "upstreamModel": {"type": "string", "minLength": 1, "maxLength": 256}, "profile": {"enum": ["internal", "external"]}, "desiredState": {"enum": ["enabled", "disabled"]}}}, "ModelUpdateRequest": {"type": "object", "additionalProperties": false, "minProperties": 1, "properties": {"upstreamModel": {"type": "string", "minLength": 1, "maxLength": 256}, "profile": {"enum": ["internal", "external"]}, "desiredState": {"enum": ["enabled", "disabled"]}}}, "ModelList": {"type": "object", "additionalProperties": false, "required": ["items", "page"], "properties": {"items": {"type": "array", "items": {"$ref": "#/components/schemas/Model"}}, "page": {"$ref": "#/components/schemas/Page"}}}, "KeyModelSummary": {"type": "object", "additionalProperties": false, "required": ["id", "name", "revision", "available"], "properties": {"id": {"$ref": "#/components/schemas/UuidV7"}, "name": {"type": "string", "pattern": "^[a-z][a-z0-9._-]{0,127}$", "description": "Stable Gateway model name; no Provider identity or upstream endpoint is exposed"}, "revision": {"$ref": "#/components/schemas/Revision"}, "available": {"type": "boolean", "description": "True only while the key, Model and Provider are all verified and enabled"}}}, "Key": {"type": "object", "additionalProperties": false, "required": ["id", "owner", "tierId", "modelIds", "status", "generation", "fingerprint", "revision", "operationId", "operationLink", "createdAt", "updatedAt"], "properties": {"id": {"$ref": "#/components/schemas/UuidV7"}, "label": {"type": "string", "minLength": 1, "maxLength": 128}, "owner": {"$ref": "#/components/schemas/KeyOwner"}, "tierId": {"$ref": "#/components/schemas/UuidV7"}, "modelIds": {"type": "array", "minItems": 1, "maxItems": 256, "uniqueItems": true, "items": {"$ref": "#/components/schemas/UuidV7"}}, "status": {"enum": ["pending", "active", "revoking", "revoked", "degraded"]}, "generation": {"type": "integer", "minimum": 1}, "fingerprint": {"type": "string", "pattern": "^sha256:[0-9a-f]{64}$"}, "revision": {"$ref": "#/components/schemas/Revision"}, "operationId": {"$ref": "#/components/schemas/UuidV7", "description": "Operation that produced the represented key revision/generation"}, "operationLink": {"type": "string", "pattern": "^/control-plane/api/v1/operations/[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"}, "createdAt": {"$ref": "#/components/schemas/Timestamp"}, "updatedAt": {"$ref": "#/components/schemas/Timestamp"}, "revokedAt": {"$ref": "#/components/schemas/Timestamp"}, "models": {"type": "array", "minItems": 1, "maxItems": 256, "uniqueItems": true, "items": {"$ref": "#/components/schemas/KeyModelSummary"}, "description": "Present only for exact direct-owner fingerprint lookup with expand=models; IDs exactly match modelIds"}, "modelsEvaluatedAt": {"$ref": "#/components/schemas/Timestamp"}}}, "AdminKeyIssueRequest": {"type": "object", "additionalProperties": false, "required": ["owner", "tierId", "modelIds"], "properties": {"label": {"type": "string", "minLength": 1, "maxLength": 128}, "owner": {"$ref": "#/components/schemas/DirectOwner"}, "tierId": {"$ref": "#/components/schemas/UuidV7"}, "modelIds": {"type": "array", "minItems": 1, "maxItems": 256, "uniqueItems": true, "items": {"$ref": "#/components/schemas/UuidV7"}}}}, "SelfKeyIssueRequest": {"type": "object", "additionalProperties": false, "properties": {"label": {"type": "string", "minLength": 1, "maxLength": 128}, "tierId": {"$ref": "#/components/schemas/UuidV7", "description": "Omit for a fixed one-Tier policy; required to choose one member when the policy allows several"}}}, "KeySecretResponse": {"type": "object", "additionalProperties": false, "required": ["key", "oneTimeSecret", "verification", "verifiedAt"], "properties": {"key": {"$ref": "#/components/schemas/Key"}, "oneTimeSecret": {"type": "string", "pattern": "^cpk_[A-Za-z0-9_-]{32,}$", "readOnly": true, "x-sensitive": true, "x-return-once": true}, "verification": {"const": "gateway_accepted"}, "verifiedAt": {"$ref": "#/components/schemas/Timestamp"}}}, "KeyPolicyUpdateRequest": {"type": "object", "additionalProperties": false, "minProperties": 1, "properties": {"tierId": {"$ref": "#/components/schemas/UuidV7"}, "modelIds": {"type": "array", "minItems": 1, "maxItems": 256, "uniqueItems": true, "items": {"$ref": "#/components/schemas/UuidV7"}}, "label": {"type": "string", "minLength": 1, "maxLength": 128}}}, "KeyRotateRequest": {"type": "object", "additionalProperties": false, "required": ["reason"], "properties": {"reason": {"type": "string", "minLength": 1, "maxLength": 512}}}, "RevokeRequest": {"type": "object", "additionalProperties": false, "required": ["reason"], "properties": {"reason": {"type": "string", "minLength": 1, "maxLength": 512}}}, "KeyList": {"type": "object", "additionalProperties": false, "required": ["items", "page"], "properties": {"items": {"type": "array", "items": {"$ref": "#/components/schemas/Key"}}, "page": {"$ref": "#/components/schemas/Page"}}}, "BulkKeyRevokeMutation": {"type": "object", "additionalProperties": false, "required": ["type", "keyId", "ifRevision"], "properties": {"type": {"const": "revoke_key"}, "keyId": {"$ref": "#/components/schemas/UuidV7"}, "ifRevision": {"$ref": "#/components/schemas/Revision"}}}, "BulkMutation": {"$ref": "#/components/schemas/BulkKeyRevokeMutation"}, "BulkPreviewRequest": {"type": "object", "additionalProperties": false, "required": ["items", "reason"], "properties": {"items": {"type": "array", "minItems": 1, "maxItems": 1000, "items": {"$ref": "#/components/schemas/BulkMutation"}}, "reason": {"type": "string", "minLength": 1, "maxLength": 512}}}, "BulkPreviewChange": {"type": "object", "additionalProperties": false, "required": ["resourceType", "resourceId", "fromRevision", "toRevision", "impact"], "properties": {"resourceType": {"const": "api_key"}, "resourceId": {"$ref": "#/components/schemas/UuidV7"}, "fromRevision": {"$ref": "#/components/schemas/Revision"}, "toRevision": {"$ref": "#/components/schemas/Revision"}, "impact": {"const": "key_revoke"}}}, "BulkImpactSummary": {"type": "object", "additionalProperties": false, "required": ["affectedItems", "affectedKeyCount", "affectedModelCount", "affectedShardIds", "destructiveItems", "reconcileCost"], "properties": {"affectedItems": {"type": "integer", "minimum": 1, "maximum": 1000}, "affectedKeyCount": {"type": "integer", "minimum": 0, "maximum": 1000}, "affectedModelCount": {"type": "integer", "minimum": 0, "maximum": 1000}, "affectedShardIds": {"type": "array", "maxItems": 1000, "uniqueItems": true, "items": {"$ref": "#/components/schemas/UuidV7"}}, "destructiveItems": {"type": "integer", "minimum": 0, "maximum": 1000}, "reconcileCost": {"type": "object", "additionalProperties": false, "required": ["shardApplies", "modelApplies"], "properties": {"shardApplies": {"type": "integer", "minimum": 0, "maximum": 1000}, "modelApplies": {"type": "integer", "minimum": 0, "maximum": 1000}}}}}, "BulkPreview": {"type": "object", "additionalProperties": false, "required": ["id", "requestDigest", "expiresAt", "changes", "impactSummary"], "properties": {"id": {"$ref": "#/components/schemas/UuidV7"}, "requestDigest": {"$ref": "#/components/schemas/Digest"}, "expiresAt": {"$ref": "#/components/schemas/Timestamp"}, "changes": {"type": "array", "minItems": 1, "maxItems": 1000, "items": {"$ref": "#/components/schemas/BulkPreviewChange"}}, "impactSummary": {"$ref": "#/components/schemas/BulkImpactSummary"}}}, "BulkExecuteRequest": {"type": "object", "additionalProperties": false, "required": ["requestDigest"], "properties": {"requestDigest": {"$ref": "#/components/schemas/Digest"}}}, "LowCodeSource": {"$ref": "../schemas/low-code-source-v2.schema.json"}, "AgentVersionInput": {"type": "object", "additionalProperties": false, "required": ["semanticVersion", "source"], "properties": {"semanticVersion": {"type": "string", "pattern": "^(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)(?:-(?:0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*)(?:\\.(?:0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*))*)?(?:\\+[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?$"}, "source": {"$ref": "#/components/schemas/LowCodeSource"}}}, "AgentCreateRequest": {"type": "object", "additionalProperties": false, "required": ["name", "displayName", "initialVersion"], "properties": {"name": {"type": "string", "pattern": "^[a-z0-9](?:[-a-z0-9]{0,61}[a-z0-9])?$"}, "displayName": {"type": "string", "minLength": 1, "maxLength": 256}, "description": {"type": "string", "maxLength": 4096}, "owner": {"$ref": "#/components/schemas/DirectOwner"}, "initialVersion": {"$ref": "#/components/schemas/AgentVersionInput"}}}, "AgentUpdateRequest": {"type": "object", "additionalProperties": false, "minProperties": 1, "properties": {"name": {"type": "string", "minLength": 1, "maxLength": 63, "pattern": "^[a-z0-9](?:[-a-z0-9]{0,61}[a-z0-9])?$", "description": "Mutable Agent-level name; does not mutate an immutable AgentVersion or Agent Card"}, "displayName": {"type": "string", "minLength": 1, "maxLength": 256, "description": "Mutable Agent-level desired metadata; does not mutate the selected immutable Card"}, "description": {"type": "string", "maxLength": 4096, "description": "Mutable Agent-level desired metadata; does not mutate the selected immutable Card"}, "owner": {"oneOf": [{"$ref": "#/components/schemas/DirectOwner"}, {"type": "null"}], "description": "Direct owner replacement/removal; requires agent#manage and an active observable Service so Registry can independently project the structural tuple."}}}, "AgentVersionCreateRequest": {"type": "object", "additionalProperties": false, "required": ["version"], "properties": {"version": {"$ref": "#/components/schemas/AgentVersionInput"}}}, "Agent": {"type": "object", "additionalProperties": false, "required": ["id", "name", "displayName", "publicationState", "publicationRevision", "revision", "createdAt", "updatedAt"], "properties": {"id": {"$ref": "#/components/schemas/UuidV7"}, "name": {"type": "string", "pattern": "^[a-z0-9](?:[-a-z0-9]{0,61}[a-z0-9])?$"}, "displayName": {"type": "string", "minLength": 1, "maxLength": 256}, "description": {"type": "string", "maxLength": 4096}, "owner": {"$ref": "#/components/schemas/DirectOwner"}, "publicationState": {"enum": ["active", "degraded", "suspended", "unpublished"]}, "selectedVersionId": {"$ref": "#/components/schemas/UuidV7"}, "publicationRevision": {"type": "integer", "minimum": 1}, "revision": {"$ref": "#/components/schemas/Revision"}, "createdAt": {"$ref": "#/components/schemas/Timestamp"}, "updatedAt": {"$ref": "#/components/schemas/Timestamp"}}}, "AgentVersion": {"type": "object", "additionalProperties": false, "required": ["id", "agentId", "semanticVersion", "protocol", "source", "llmRequired", "modelIds", "publicationPolicyRevision", "publicationPolicyDigest", "createdAt"], "properties": {"id": {"$ref": "#/components/schemas/UuidV7"}, "agentId": {"$ref": "#/components/schemas/UuidV7"}, "semanticVersion": {"type": "string", "pattern": "^(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)(?:-(?:0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*)(?:\\.(?:0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*))*)?(?:\\+[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?$"}, "protocol": {"const": "a2a"}, "source": {"$ref": "#/components/schemas/LowCodeSource"}, "artifactDigest": {"$ref": "#/components/schemas/Digest", "readOnly": true, "description": "Present after deterministic OCI packaging; absent while the candidate is only admitted"}, "llmRequired": {"type": "boolean", "readOnly": true, "description": "Derived from the validated immutable flow"}, "modelIds": {"type": "array", "minItems": 0, "maxItems": 256, "uniqueItems": true, "readOnly": true, "description": "Exact Model grants derived from the validated immutable flow; empty only when llmRequired=false", "items": {"$ref": "#/components/schemas/UuidV7"}}, "tierId": {"$ref": "#/components/schemas/UuidV7", "readOnly": true, "description": "Present only when LLM is required; derived from the administrator-managed Agent publication policy"}, "publicationPolicyRevision": {"type": "integer", "minimum": 1, "readOnly": true}, "publicationPolicyDigest": {"$ref": "#/components/schemas/Digest", "readOnly": true}, "createdAt": {"$ref": "#/components/schemas/Timestamp"}}, "allOf": [{"if": {"properties": {"llmRequired": {"const": true}}, "required": ["llmRequired"]}, "then": {"required": ["tierId"], "properties": {"modelIds": {"minItems": 1}}}, "else": {"not": {"required": ["tierId"]}, "properties": {"modelIds": {"maxItems": 0}}}}]}, "AgentRollbackRequest": {"type": "object", "additionalProperties": false, "required": ["targetAgentVersionId"], "properties": {"targetAgentVersionId": {"$ref": "#/components/schemas/UuidV7"}}}, "AgentUnpublishRequest": {"type": "object", "additionalProperties": false, "required": ["reasonCode"], "properties": {"reasonCode": {"enum": ["user_requested", "security_response", "source_retired", "operational"]}}}, "AgentRevalidateRequest": {"type": "object", "additionalProperties": false, "required": ["trigger"], "properties": {"trigger": {"enum": ["scope_restored", "operator_recovery", "provider_recovered"]}}}, "AgentList": {"type": "object", "additionalProperties": false, "required": ["items", "page"], "properties": {"items": {"type": "array", "items": {"$ref": "#/components/schemas/Agent"}}, "page": {"$ref": "#/components/schemas/Page"}}}, "AgentVersionList": {"type": "object", "additionalProperties": false, "required": ["items", "page"], "properties": {"items": {"type": "array", "items": {"$ref": "#/components/schemas/AgentVersion"}}, "page": {"$ref": "#/components/schemas/Page"}}}, "OperationList": {"type": "object", "additionalProperties": false, "required": ["items", "page"], "properties": {"items": {"type": "array", "items": {"$ref": "../schemas/operation-v1.schema.json"}}, "page": {"$ref": "#/components/schemas/Page"}}}, "CancelRequest": {"type": "object", "additionalProperties": false, "required": ["reason"], "properties": {"reason": {"type": "string", "minLength": 1, "maxLength": 512}}}, "RecoveryPreviewRequest": {"$ref": "../schemas/recovery-preview-v1.schema.json#/$defs/request"}, "RecoveryPreview": {"$ref": "../schemas/recovery-preview-v1.schema.json"}, "RecoveryExecuteRequest": {"$ref": "../schemas/recovery-execute-v1.schema.json"}, "ManagedDomain": {"enum": ["model_policy", "key_policy", "publication"]}, "Domain": {"enum": ["model_policy", "key_policy", "publication", "all"]}, "ResourceReference": {"type": "object", "additionalProperties": false, "required": ["type", "id"], "properties": {"type": {"enum": ["tier", "provider", "model", "api_key", "key_issuance_policy", "agent", "agent_version", "publication", "recovery_preview", "control_plane", "guardrail_policy"]}, "id": {"$ref": "#/components/schemas/UuidV7"}}}, "ReconcileRequest": {"type": "object", "additionalProperties": false, "required": ["domain", "mode", "reason"], "properties": {"domain": {"$ref": "#/components/schemas/Domain"}, "resource": {"$ref": "#/components/schemas/ResourceReference"}, "mode": {"enum": ["observe", "repair"]}, "reason": {"type": "string", "minLength": 1, "maxLength": 512}}}, "DriftItem": {"type": "object", "additionalProperties": false, "required": ["resource", "domain", "classification", "desiredRevision", "observedRevision", "detectedAt"], "properties": {"resource": {"$ref": "#/components/schemas/ResourceReference"}, "domain": {"$ref": "#/components/schemas/ManagedDomain"}, "classification": {"enum": ["pending_convergence", "unauthorized_external_change", "missing_object", "unsupported_provider_state", "stale_observation", "blocked_recovery"]}, "desiredRevision": {"type": "integer", "minimum": 0}, "observedRevision": {"type": "integer", "minimum": 0}, "detectedAt": {"$ref": "#/components/schemas/Timestamp"}}}, "DriftReport": {"type": "object", "additionalProperties": false, "required": ["observationComplete", "generatedAt", "items", "page"], "properties": {"observationComplete": {"type": "boolean"}, "generatedAt": {"$ref": "#/components/schemas/Timestamp"}, "items": {"type": "array", "items": {"$ref": "#/components/schemas/DriftItem"}}, "page": {"$ref": "#/components/schemas/Page"}}}, "AuditActor": {"oneOf": [{"$ref": "#/components/schemas/PrincipalOwner"}, {"$ref": "#/components/schemas/ServiceOwner"}]}, "AuditRecord": {"type": "object", "additionalProperties": false, "required": ["id", "occurredAt", "actor", "action", "resource", "outcome", "requestId"], "properties": {"id": {"$ref": "#/components/schemas/UuidV7"}, "occurredAt": {"$ref": "#/components/schemas/Timestamp"}, "actor": {"$ref": "#/components/schemas/AuditActor"}, "action": {"type": "string", "pattern": "^[a-z][a-z0-9_.]{2,127}$"}, "resource": {"$ref": "#/components/schemas/ResourceReference"}, "outcome": {"enum": ["accepted", "succeeded", "failed", "denied"]}, "requestId": {"$ref": "#/components/schemas/UuidV7"}, "operationId": {"$ref": "#/components/schemas/UuidV7"}, "reason": {"type": "string", "maxLength": 512}}}, "AuditList": {"type": "object", "additionalProperties": false, "required": ["items", "page"], "properties": {"items": {"type": "array", "items": {"$ref": "#/components/schemas/AuditRecord"}}, "page": {"$ref": "#/components/schemas/Page"}}}, "DomainStatus": {"type": "object", "additionalProperties": false, "required": ["domain", "state", "updatedAt"], "properties": {"domain": {"$ref": "#/components/schemas/ManagedDomain"}, "convergedRevision": {"type": "integer", "minimum": 0, "deprecated": true, "description": "Legacy aggregate; revision numbers of different resources are not comparable. Use observation.resources."}, "stageRevisions": {"type": "object", "additionalProperties": false, "required": ["desiredRevision", "appliedRevision", "verifiedRevision"], "properties": {"desiredRevision": {"type": "integer", "minimum": 0}, "appliedRevision": {"type": ["integer", "null"], "minimum": 0}, "verifiedRevision": {"type": ["integer", "null"], "minimum": 0}}, "deprecated": true, "description": "Legacy aggregate; revision numbers of different resources are not comparable. Use observation.resources."}, "state": {"enum": ["ready", "reconciling", "degraded", "blocked"]}, "updatedAt": {"$ref": "#/components/schemas/Timestamp"}, "observation": {"type": "object", "additionalProperties": false, "required": ["state", "checkedAt", "resources"], "properties": {"state": {"enum": ["not_checked", "incomplete", "stale", "complete"]}, "checkedAt": {"type": ["string", "null"], "format": "date-time"}, "resources": {"type": "object", "additionalProperties": false, "required": ["total", "ready", "pending", "attention", "unobserved"], "properties": {"total": {"type": "integer", "minimum": 0}, "ready": {"type": "integer", "minimum": 0}, "pending": {"type": "integer", "minimum": 0}, "attention": {"type": "integer", "minimum": 0}, "unobserved": {"type": "integer", "minimum": 0}}}}}}, "allOf": [{"if": {"properties": {"state": {"const": "ready"}}, "required": ["state"]}, "then": {"required": ["convergedRevision"], "not": {"required": ["stageRevisions"]}}}, {"if": {"properties": {"state": {"not": {"const": "ready"}}}, "required": ["state"]}, "then": {"required": ["stageRevisions"], "not": {"required": ["convergedRevision"]}}}]}, "SystemStatus": {"type": "object", "additionalProperties": false, "required": ["release", "apiVersion", "state", "domains", "generatedAt"], "properties": {"release": {"const": "R2"}, "apiVersion": {"const": "v1"}, "state": {"enum": ["ready", "degraded", "blocked"]}, "domains": {"type": "array", "minItems": 3, "maxItems": 3, "items": {"$ref": "#/components/schemas/DomainStatus"}}, "generatedAt": {"$ref": "#/components/schemas/Timestamp"}, "activeReconcileOperationId": {"$ref": "#/components/schemas/UuidV7"}}}, "GuardrailBindingReplace": { "type": "object", "additionalProperties": false, "required": [ "policyId", "policyRevision", "contentProfile" ], "properties": { "policyId": { "oneOf": [ { "$ref": "#/components/schemas/UuidV7" }, { "type": "null" } ] }, "policyRevision": { "type": [ "integer", "null" ], "minimum": 1 }, "contentProfile": { "const": "agentgateway-1.5.0-chat-webhook-v2" } }, "oneOf": [ { "properties": { "policyId": { "type": "null" }, "policyRevision": { "type": "null" } } }, { "properties": { "policyId": { "type": "string" }, "policyRevision": { "type": "integer" } } } ] }, "GuardrailBinding": { "type": "object", "additionalProperties": false, "required": [ "modelId", "gatewayName", "modelRevision", "operationId", "state", "binding", "observation" ], "properties": { "modelId": { "$ref": "#/components/schemas/UuidV7" }, "gatewayName": { "type": "string" }, "modelRevision": { "type": "integer", "minimum": 1 }, "operationId": { "$ref": "#/components/schemas/UuidV7" }, "state": { "enum": [ "failed", "disabled", "applied", "unbound", "pending" ] }, "binding": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "policyId", "policyRevision", "generationId", "bundleDigest" ], "properties": { "policyId": { "$ref": "#/components/schemas/UuidV7" }, "policyRevision": { "type": "integer", "minimum": 1 }, "generationId": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "bundleDigest": { "type": "string", "pattern": "^[0-9a-f]{64}$" } } }, { "type": "null" } ] }, "observation": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "generationId", "bundleDigest", "allServingReplicas", "pods", "observedAt" ], "properties": { "generationId": { "oneOf": [ { "type": "string", "pattern": "^[0-9a-f]{64}$" }, { "type": "null" } ] }, "bundleDigest": { "oneOf": [ { "type": "string", "pattern": "^[0-9a-f]{64}$" }, { "type": "null" } ] }, "allServingReplicas": { "const": true }, "pods": { "type": "array", "minItems": 2, "maxItems": 64, "items": { "type": "string" } }, "observedAt": { "type": "string", "format": "date-time" } } }, { "type": "null" } ] } } }, "GuardrailProviderCatalog": { "type": "object", "additionalProperties": false, "required": [ "items" ], "properties": { "items": { "type": "array", "maxItems": 32, "items": { "oneOf": [ { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]*$" }, "revision": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]*$" }, "protocol": { "const": "agent-platform.guardrail-runtime.detector/v1" }, "url": { "type": "string", "minLength": 1, "maxLength": 2048 }, "credentialRef": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]*$" }, "maxResponseBytes": { "type": "integer", "minimum": 64, "maximum": 131072 }, "maxInputBytes": { "type": "integer", "minimum": 1, "maximum": 131072 } }, "required": [ "id", "revision", "protocol", "url", "credentialRef", "maxResponseBytes", "maxInputBytes" ] }, { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]*$" }, "revision": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]*$" }, "protocol": { "enum": [ "openai.chat-completions.classifier/v1", "deepseek.chat-completions.classifier/v1" ] }, "url": { "type": "string", "minLength": 1, "maxLength": 2048 }, "credentialRef": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]*$" }, "maxResponseBytes": { "type": "integer", "minimum": 64, "maximum": 131072 }, "maxInputBytes": { "type": "integer", "minimum": 1, "maximum": 131072 }, "model": { "type": "string", "minLength": 1, "maxLength": 200 }, "modelRevision": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]*$" } }, "required": [ "id", "revision", "protocol", "url", "credentialRef", "maxResponseBytes", "maxInputBytes", "model", "modelRevision" ] } ] } } } } }, "responses": { "OperationAccepted": {"description": "Durable intent accepted; this is not verified success", "x-authorization-projection-gate": "operation:{operationId}#requester confirmed and consistency token persisted before 202", "content": {"application/json": {"schema": {"$ref": "../schemas/operation-v1.schema.json"}}}}, "RecoveryPreviewStored": {"description": "Immutable stored observe-only preview; no provider mutation has started", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/RecoveryPreview"}}}}, "InvalidRequest": {"description": "Malformed or invalid closed-shape request", "content": {"application/json": {"schema": {"$ref": "../schemas/error-v1.schema.json"}}}}, "Unauthenticated": {"description": "Missing or invalid platform management token", "content": {"application/json": {"schema": {"$ref": "../schemas/error-v1.schema.json"}}}}, "Forbidden": {"description": "Authenticated subject lacks the direct functional permission", "content": {"application/json": {"schema": {"$ref": "../schemas/error-v1.schema.json"}}}}, "NotFound": {"description": "Resource does not exist", "content": {"application/json": {"schema": {"$ref": "../schemas/error-v1.schema.json"}}}}, "HiddenOrAbsent": {"description": "Caller-owned resource is absent or intentionally hidden", "content": {"application/json": {"schema": {"$ref": "../schemas/error-v1.schema.json"}}}}, "Conflict": {"description": "Idempotency conflict, dependency conflict or incompatible active state", "content": {"application/json": {"schema": {"$ref": "../schemas/error-v1.schema.json"}}}}, "PreconditionFailed": {"description": "If-Match does not name the current exact revision", "content": {"application/json": {"schema": {"$ref": "../schemas/error-v1.schema.json"}}}}, "AuthorizationUnavailable": {"description": "Authorization dependency unavailable; request fails closed", "content": {"application/json": {"schema": {"$ref": "../schemas/error-v1.schema.json"}}}}, "VerificationTimeout": {"description": "Key candidate was not verified within the synchronous budget; no secret is returned. Error operationId/operationLink identify durable retry_wait or compensation.", "content": {"application/json": {"schema": {"$ref": "../schemas/error-v1.schema.json"}}}}, "PreviewExpired": {"description": "Stored bulk or recovery preview expired and must be recreated", "content": {"application/json": {"schema": {"$ref": "../schemas/error-v1.schema.json"}}}} } } }