{ "openapi": "3.1.2", "info": { "title": "Mystro Platform API", "version": "0.1.0-draft.3", "description": "PROPOSED CONTRACT — not a live service. Your product. Powered by agents. Dedicated tenant/environment cells; customer applications retain identity and business authorization. All mutation requests require Idempotency-Key. Canonical request replay lasts 7 days; metadata tombstones 90 days prevent recreation. Actor + method + path + tenant + environment scope keys. Changed payload returns 409. Secret-bearing replay returns metadata only. Lists default 50/max100 opaque cursor items. /v1 changes additive; breaking changes use /v2. No automatic external write retries. This document is the only maintained platform API source.\nView: public; maximum lifecycle stage: proposed." }, "x-default-rate-limits": { "cell_requests_per_second": 60, "cell_request_burst": 120, "cell_open_sse_streams": 128, "actor_open_sse_streams": 16 }, "servers": [ { "url": "https://api.mystro.invalid", "description": "Reserved documentation placeholder; service not available." } ], "security": [ { "ServiceKey": [] } ], "tags": [ { "name": "tenants" }, { "name": "tenant_id" }, { "name": "environments" }, { "name": "environment" }, { "name": "production-request" }, { "name": "api-keys" }, { "name": "key_id" }, { "name": "rotate" }, { "name": "revoke" }, { "name": "users" }, { "name": "user_id" }, { "name": "service-actors" }, { "name": "service_actor_id" }, { "name": "actor-sessions" }, { "name": "workspaces" }, { "name": "workspace_id" }, { "name": "agents" }, { "name": "agent_id" }, { "name": "revisions" }, { "name": "revision_id" }, { "name": "model-profiles" }, { "name": "model_profile_id" }, { "name": "connections" }, { "name": "connection_id" }, { "name": "tools" }, { "name": "tool_id" }, { "name": "conversations" }, { "name": "conversation_id" }, { "name": "runs" }, { "name": "run_id" }, { "name": "cancel" }, { "name": "events" }, { "name": "stream" }, { "name": "approvals" }, { "name": "approval_id" }, { "name": "decision" }, { "name": "files" }, { "name": "file_id" }, { "name": "download" }, { "name": "webhook-endpoints" }, { "name": "webhook_endpoint_id" }, { "name": "rotate-secret" }, { "name": "webhook-deliveries" }, { "name": "webhook_delivery_id" }, { "name": "replay" }, { "name": "usage" }, { "name": "records" }, { "name": "quotas" }, { "name": "settings" }, { "name": "audit" }, { "name": "deletion_job_id" }, { "name": "jwks.json" }, { "name": "Console" }, { "name": "Operations" }, { "name": "start" }, { "name": "callback" }, { "name": "schedules" }, { "name": "schedule_id" }, { "name": "memory" }, { "name": "memory_id" } ], "paths": { "/v1/tenants": { "get": { "operationId": "listTenants", "summary": "List authorized tenants", "tags": [ "tenants" ], "x-release-stage": "proposed", "x-visibility": "public", "x-required-scopes": [ "tenants:read" ], "security": [ { "ServiceKey": [] } ], "description": "List authorized tenants", "parameters": [ { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Tenant" } }, "next_cursor": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "items", "next_cursor", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/v1/tenants/{tenant_id}": { "get": { "operationId": "getTenant", "summary": "Get tenant", "tags": [ "tenant_id" ], "x-release-stage": "proposed", "x-visibility": "public", "x-required-scopes": [ "tenants:read" ], "security": [ { "ServiceKey": [] } ], "description": "Get tenant", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Tenant" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } } }, "patch": { "operationId": "updateTenant", "summary": "Update tenant name", "tags": [ "tenant_id" ], "x-release-stage": "proposed", "x-visibility": "public", "x-required-scopes": [ "tenants:write" ], "security": [ { "ServiceKey": [] } ], "description": "Update tenant name", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Tenant" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTenant" } } } } }, "delete": { "operationId": "deleteTenant", "summary": "Delete tenant", "tags": [ "tenant_id" ], "x-release-stage": "proposed", "x-visibility": "public", "x-required-scopes": [ "tenants:write" ], "security": [ { "ServiceKey": [] } ], "description": "Delete tenant", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "202": { "description": "Success", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." }, "Location": { "schema": { "type": "string" }, "description": "Poll the accepted resource at this path." } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/DeletionJob" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/v1/tenants/{tenant_id}/environments": { "get": { "operationId": "listEnvironments", "summary": "List tenant environments", "tags": [ "environments" ], "x-release-stage": "proposed", "x-visibility": "public", "x-required-scopes": [ "environments:read" ], "security": [ { "ServiceKey": [] } ], "description": "List tenant environments", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Environment" } }, "next_cursor": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "items", "next_cursor", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/v1/tenants/{tenant_id}/environments/{environment}": { "get": { "operationId": "getEnvironment", "summary": "Get environment provisioning state", "tags": [ "environment" ], "x-release-stage": "proposed", "x-visibility": "public", "x-required-scopes": [ "environments:read" ], "security": [ { "ServiceKey": [] } ], "description": "Get environment provisioning state", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "environment", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/EnvironmentName" } } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Environment" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } } }, "delete": { "operationId": "deleteEnvironment", "summary": "Delete environment", "tags": [ "environment" ], "x-release-stage": "proposed", "x-visibility": "public", "x-required-scopes": [ "environments:write" ], "security": [ { "ServiceKey": [] } ], "description": "Delete environment", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "environment", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/EnvironmentName" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "202": { "description": "Success", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." }, "Location": { "schema": { "type": "string" }, "description": "Poll the accepted resource at this path." } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/DeletionJob" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/v1/tenants/{tenant_id}/environments/{environment}/api-keys": { "get": { "operationId": "listApiKey", "summary": "List api-keys", "tags": [ "api-keys" ], "x-release-stage": "proposed", "x-visibility": "public", "x-required-scopes": [ "keys:read" ], "security": [ { "ServiceKey": [] } ], "description": "List api-keys", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "environment", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/EnvironmentName" } }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" } }, "next_cursor": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "items", "next_cursor", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/v1/tenants/{tenant_id}/environments/{environment}/api-keys/{key_id}": { "get": { "operationId": "getApiKey", "summary": "Get key", "tags": [ "key_id" ], "x-release-stage": "proposed", "x-visibility": "public", "x-required-scopes": [ "keys:read" ], "security": [ { "ServiceKey": [] } ], "description": "Get key", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "environment", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/EnvironmentName" } }, { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ApiKey" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/v1/tenants/{tenant_id}/environments/{environment}/api-keys/{key_id}/revoke": { "post": { "operationId": "revokeApiKey", "summary": "Revoke API key", "tags": [ "revoke" ], "x-release-stage": "proposed", "x-visibility": "public", "x-required-scopes": [ "keys:revoke" ], "security": [ { "ServiceKey": [] } ], "description": "Within management ceiling only. Immediately rejects next request/tool and invalidates descendant leases; SSE ends within 15 seconds. Accepted external operations may finish and retain receipts.", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "environment", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/EnvironmentName" } }, { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ApiKey" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/v1/tenants/{tenant_id}/environments/{environment}/users": { "get": { "operationId": "listUser", "summary": "List users", "tags": [ "users" ], "x-release-stage": "proposed", "x-visibility": "public", "x-required-scopes": [ "users:read" ], "security": [ { "ServiceKey": [] } ], "description": "List users", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "environment", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/EnvironmentName" } }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/User" } }, "next_cursor": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "items", "next_cursor", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } } }, "post": { "operationId": "createUser", "summary": "Create user", "tags": [ "users" ], "x-release-stage": "proposed", "x-visibility": "public", "x-required-scopes": [ "users:write" ], "security": [ { "ServiceKey": [] } ], "description": "Create user", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "environment", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/EnvironmentName" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Success", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/User" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateUser" } } } } } }, "/v1/tenants/{tenant_id}/environments/{environment}/users/{user_id}": { "get": { "operationId": "getUser", "summary": "Get user", "tags": [ "user_id" ], "x-release-stage": "proposed", "x-visibility": "public", "x-required-scopes": [ "users:read" ], "security": [ { "ServiceKey": [] } ], "description": "Get user", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "environment", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/EnvironmentName" } }, { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/User" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } } }, "patch": { "operationId": "updateUser", "summary": "Update user", "tags": [ "user_id" ], "x-release-stage": "proposed", "x-visibility": "public", "x-required-scopes": [ "users:write" ], "security": [ { "ServiceKey": [] } ], "description": "Update user", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "environment", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/EnvironmentName" } }, { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/User" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateActor" } } } } }, "delete": { "operationId": "deleteUser", "summary": "Delete user", "tags": [ "user_id" ], "x-release-stage": "proposed", "x-visibility": "public", "x-required-scopes": [ "users:write" ], "security": [ { "ServiceKey": [] } ], "description": "Immediately deny access and revoke derived authority. Live purge within 24 hours; backups expire separately within 30 days. Restore replays deletion journal before serving.", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "environment", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/EnvironmentName" } }, { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "202": { "description": "Success", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." }, "Location": { "schema": { "type": "string" }, "description": "Poll the accepted resource at this path." } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/DeletionJob" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/v1/tenants/{tenant_id}/environments/{environment}/service-actors": { "get": { "operationId": "listServiceActor", "summary": "List service-actors", "tags": [ "service-actors" ], "x-release-stage": "proposed", "x-visibility": "public", "x-required-scopes": [ "service-actors:read" ], "security": [ { "ServiceKey": [] } ], "description": "List service-actors", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "environment", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/EnvironmentName" } }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ServiceActor" } }, "next_cursor": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "items", "next_cursor", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } } }, "post": { "operationId": "createServiceActor", "summary": "Create service_actor", "tags": [ "service-actors" ], "x-release-stage": "proposed", "x-visibility": "public", "x-required-scopes": [ "service-actors:write" ], "security": [ { "ServiceKey": [] } ], "description": "Create service_actor", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "environment", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/EnvironmentName" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Success", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ServiceActor" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateServiceActor" } } } } } }, "/v1/tenants/{tenant_id}/environments/{environment}/service-actors/{service_actor_id}": { "get": { "operationId": "getServiceActor", "summary": "Get service_actor", "tags": [ "service_actor_id" ], "x-release-stage": "proposed", "x-visibility": "public", "x-required-scopes": [ "service-actors:read" ], "security": [ { "ServiceKey": [] } ], "description": "Get service_actor", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "environment", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/EnvironmentName" } }, { "name": "service_actor_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ServiceActor" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } } }, "patch": { "operationId": "updateServiceActor", "summary": "Update service_actor", "tags": [ "service_actor_id" ], "x-release-stage": "proposed", "x-visibility": "public", "x-required-scopes": [ "service-actors:write" ], "security": [ { "ServiceKey": [] } ], "description": "Update service_actor", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "environment", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/EnvironmentName" } }, { "name": "service_actor_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ServiceActor" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateActor" } } } } }, "delete": { "operationId": "deleteServiceActor", "summary": "Delete service_actor", "tags": [ "service_actor_id" ], "x-release-stage": "proposed", "x-visibility": "public", "x-required-scopes": [ "service-actors:write" ], "security": [ { "ServiceKey": [] } ], "description": "Immediately deny access and revoke derived authority. Live purge within 24 hours; backups expire separately within 30 days. Restore replays deletion journal before serving.", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "environment", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/EnvironmentName" } }, { "name": "service_actor_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "202": { "description": "Success", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." }, "Location": { "schema": { "type": "string" }, "description": "Poll the accepted resource at this path." } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/DeletionJob" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/v1/tenants/{tenant_id}/environments/{environment}/actor-sessions": { "post": { "operationId": "createActorSession", "summary": "Issue delegated user session", "tags": [ "actor-sessions" ], "x-release-stage": "proposed", "x-visibility": "public", "x-required-scopes": [], "security": [ { "ServiceKey": [] } ], "description": "Trusted backend delegation requires identity:delegate OR approval:delegate. An identity-only key may mint its configured execution/files scope subset, never approval scopes. An approval-only key may mint only approvals:read and approvals:write leases. Both authorities are required to mix those scope categories. Requested scopes must also be a subset of the active parent key scopes. Five-minute user-only lease; current active user and matching workspace owner are checked. Service actors cannot become approvers. Fresh issuance returns token_available:true and a token; replay returns token_available:false and no token. Use a fresh idempotency key for a new lease. Parent key revocation invalidates derived leases.", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "environment", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/EnvironmentName" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Success", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ActorSession" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActorSessionRequest" } } } }, "x-any-required-scopes": [ "identity:delegate", "approval:delegate" ] } }, "/v1/tenants/{tenant_id}/environments/{environment}/workspaces": { "get": { "operationId": "listWorkspace", "summary": "List workspaces", "tags": [ "workspaces" ], "x-release-stage": "proposed", "x-visibility": "public", "x-required-scopes": [ "workspaces:read" ], "security": [ { "ServiceKey": [] }, { "ActorToken": [] } ], "description": "List workspaces", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "environment", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/EnvironmentName" } }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Workspace" } }, "next_cursor": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "items", "next_cursor", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } } }, "post": { "operationId": "createWorkspace", "summary": "Create workspace", "tags": [ "workspaces" ], "x-release-stage": "proposed", "x-visibility": "public", "x-required-scopes": [ "workspaces:write" ], "security": [ { "ServiceKey": [] }, { "ActorToken": [] } ], "description": "One workspace per owner actor/environment. Server derives ownership from authenticated authority; a delegated user requires identity:delegate. Another actor workspace is inaccessible.", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "environment", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/EnvironmentName" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Success", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Workspace" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWorkspace" } } } } } }, "/v1/tenants/{tenant_id}/environments/{environment}/workspaces/{workspace_id}": { "get": { "operationId": "getWorkspace", "summary": "Get workspace", "tags": [ "workspace_id" ], "x-release-stage": "proposed", "x-visibility": "public", "x-required-scopes": [ "workspaces:read" ], "security": [ { "ServiceKey": [] }, { "ActorToken": [] } ], "description": "Get workspace", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "environment", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/EnvironmentName" } }, { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Workspace" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } } }, "delete": { "operationId": "deleteWorkspace", "summary": "Delete workspace", "tags": [ "workspace_id" ], "x-release-stage": "proposed", "x-visibility": "public", "x-required-scopes": [ "workspaces:write" ], "security": [ { "ServiceKey": [] }, { "ActorToken": [] } ], "description": "Immediately deny access and revoke derived authority. Live purge within 24 hours; backups expire separately within 30 days. Restore replays deletion journal before serving.", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "environment", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/EnvironmentName" } }, { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "202": { "description": "Success", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." }, "Location": { "schema": { "type": "string" }, "description": "Poll the accepted resource at this path." } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/DeletionJob" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/v1/tenants/{tenant_id}/environments/{environment}/agents": { "get": { "operationId": "listAgent", "summary": "List agents", "tags": [ "agents" ], "x-release-stage": "proposed", "x-visibility": "public", "x-required-scopes": [ "agents:read" ], "security": [ { "ServiceKey": [] } ], "description": "List agents", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "environment", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/EnvironmentName" } }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Agent" } }, "next_cursor": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "items", "next_cursor", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } } }, "post": { "operationId": "createAgent", "summary": "Create agent", "tags": [ "agents" ], "x-release-stage": "proposed", "x-visibility": "public", "x-required-scopes": [ "agents:write" ], "security": [ { "ServiceKey": [] } ], "description": "Create agent", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "environment", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/EnvironmentName" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Success", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Agent" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAgent" } } } } } }, "/v1/tenants/{tenant_id}/environments/{environment}/agents/{agent_id}": { "get": { "operationId": "getAgent", "summary": "Get agent", "tags": [ "agent_id" ], "x-release-stage": "proposed", "x-visibility": "public", "x-required-scopes": [ "agents:read" ], "security": [ { "ServiceKey": [] } ], "description": "Get agent", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "environment", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/EnvironmentName" } }, { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Agent" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } } }, "patch": { "operationId": "updateAgent", "summary": "Update agent", "tags": [ "agent_id" ], "x-release-stage": "proposed", "x-visibility": "public", "x-required-scopes": [ "agents:write" ], "security": [ { "ServiceKey": [] } ], "description": "Update agent", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "environment", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/EnvironmentName" } }, { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Agent" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Archive" } } } } } }, "/v1/tenants/{tenant_id}/environments/{environment}/agents/{agent_id}/revisions": { "post": { "operationId": "createAgentRevision", "summary": "Freeze immutable agent revision", "tags": [ "revisions" ], "x-release-stage": "proposed", "x-visibility": "public", "x-required-scopes": [ "agents:write" ], "security": [ { "ServiceKey": [] } ], "description": "Freeze immutable agent revision", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "environment", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/EnvironmentName" } }, { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Success", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/AgentRevision" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAgentRevision" }, "example": { "instructions": "Summarize the supplied operations report. Use only approved tools.", "model_profile": "standard", "tool_ids": [], "memory": { "mode": "off" }, "limits": { "max_active_seconds": 300, "max_steps": 20, "max_input_tokens": 32768, "max_output_tokens": 8192, "max_cost_usd": "1.00" } } } } } }, "get": { "operationId": "listAgentRevisions", "summary": "List agent revisions", "tags": [ "revisions" ], "x-release-stage": "proposed", "x-visibility": "public", "x-required-scopes": [ "agents:read" ], "security": [ { "ServiceKey": [] } ], "description": "List agent revisions", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "environment", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/EnvironmentName" } }, { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AgentRevision" } }, "next_cursor": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "items", "next_cursor", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/v1/tenants/{tenant_id}/environments/{environment}/agents/{agent_id}/revisions/{revision_id}": { "get": { "operationId": "getAgentRevision", "summary": "Get agent revision", "tags": [ "revision_id" ], "x-release-stage": "proposed", "x-visibility": "public", "x-required-scopes": [ "agents:read" ], "security": [ { "ServiceKey": [] } ], "description": "Get agent revision", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "environment", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/EnvironmentName" } }, { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "revision_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/AgentRevision" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/v1/tenants/{tenant_id}/environments/{environment}/model-profiles": { "get": { "operationId": "listModelProfile", "summary": "List model-profiles", "tags": [ "model-profiles" ], "x-release-stage": "proposed", "x-visibility": "public", "x-required-scopes": [ "models:read" ], "security": [ { "ServiceKey": [] } ], "description": "List model-profiles", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "environment", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/EnvironmentName" } }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ModelProfile" } }, "next_cursor": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "items", "next_cursor", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/v1/tenants/{tenant_id}/environments/{environment}/model-profiles/{model_profile_id}": { "get": { "operationId": "getModelProfile", "summary": "Get model_profile", "tags": [ "model_profile_id" ], "x-release-stage": "proposed", "x-visibility": "public", "x-required-scopes": [ "models:read" ], "security": [ { "ServiceKey": [] } ], "description": "Get model_profile", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "environment", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/EnvironmentName" } }, { "name": "model_profile_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ModelProfile" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/v1/tenants/{tenant_id}/environments/{environment}/connections": { "get": { "operationId": "listConnection", "summary": "List connections", "tags": [ "connections" ], "x-release-stage": "proposed", "x-visibility": "public", "x-required-scopes": [ "connections:read" ], "security": [ { "ServiceKey": [] }, { "ActorToken": [] } ], "description": "List connections", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "environment", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/EnvironmentName" } }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Connection" } }, "next_cursor": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "items", "next_cursor", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } } }, "post": { "operationId": "createConnection", "summary": "Create connection", "tags": [ "connections" ], "x-release-stage": "proposed", "x-visibility": "public", "x-required-scopes": [ "connections:write" ], "security": [ { "ServiceKey": [] }, { "ActorToken": [] } ], "description": "Pending operator review. Server validates owner and HTTPS destinations, binds tenant/user/service owner, freezes operation schema. Only activated tools execute. Financial execution and arbitrary code are rejected. Service actors cannot consume user-owned connections.", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "environment", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/EnvironmentName" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Success", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Connection" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateConnection" }, "example": { "name": "Acme tickets", "type": "customer_https", "owner": { "type": "tenant" }, "base_url": "https://tools.acme.invalid", "authentication": { "type": "mystro_signed_request" }, "operations": [ { "name": "get_ticket", "effect": "read", "path": "/tickets/read", "input_schema": { "type": "object", "properties": { "ticket_id": { "type": "string" } }, "required": [ "ticket_id" ], "additionalProperties": false }, "output_schema": { "type": "object", "properties": { "title": { "type": "string" } }, "required": [ "title" ], "additionalProperties": false } }, { "name": "add_note", "effect": "write", "path": "/tickets/notes", "reconciliation_path": "/operations/{operation_id}", "input_schema": { "type": "object", "properties": { "ticket_id": { "type": "string" }, "note": { "type": "string" } }, "required": [ "ticket_id", "note" ], "additionalProperties": false }, "output_schema": { "type": "object", "properties": { "note_id": { "type": "string" } }, "required": [ "note_id" ], "additionalProperties": false } } ] } } } } } }, "/v1/tenants/{tenant_id}/environments/{environment}/connections/{connection_id}": { "get": { "operationId": "getConnection", "summary": "Get connection", "tags": [ "connection_id" ], "x-release-stage": "proposed", "x-visibility": "public", "x-required-scopes": [ "connections:read" ], "security": [ { "ServiceKey": [] }, { "ActorToken": [] } ], "description": "Get connection", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "environment", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/EnvironmentName" } }, { "name": "connection_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Connection" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } } }, "patch": { "operationId": "updateConnection", "summary": "Update connection", "tags": [ "connection_id" ], "x-release-stage": "proposed", "x-visibility": "public", "x-required-scopes": [ "connections:write" ], "security": [ { "ServiceKey": [] }, { "ActorToken": [] } ], "description": "Update connection", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "environment", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/EnvironmentName" } }, { "name": "connection_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Connection" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisableConnection" } } } } } }, "/v1/tenants/{tenant_id}/environments/{environment}/connections/{connection_id}/revoke": { "post": { "operationId": "revokeConnection", "summary": "Revoke connection and pending approvals", "tags": [ "revoke" ], "x-release-stage": "proposed", "x-visibility": "public", "x-required-scopes": [ "connections:write" ], "security": [ { "ServiceKey": [] }, { "ActorToken": [] } ], "description": "Revoke connection and pending approvals", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "environment", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/EnvironmentName" } }, { "name": "connection_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Connection" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/v1/tenants/{tenant_id}/environments/{environment}/tools": { "get": { "operationId": "listTool", "summary": "List tools", "tags": [ "tools" ], "x-release-stage": "proposed", "x-visibility": "public", "x-required-scopes": [ "tools:read" ], "security": [ { "ServiceKey": [] }, { "ActorToken": [] } ], "description": "List tools", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "environment", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/EnvironmentName" } }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Tool" } }, "next_cursor": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "items", "next_cursor", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/v1/tenants/{tenant_id}/environments/{environment}/tools/{tool_id}": { "get": { "operationId": "getTool", "summary": "Get tool", "tags": [ "tool_id" ], "x-release-stage": "proposed", "x-visibility": "public", "x-required-scopes": [ "tools:read" ], "security": [ { "ServiceKey": [] }, { "ActorToken": [] } ], "description": "Get tool", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "environment", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/EnvironmentName" } }, { "name": "tool_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Tool" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/v1/tenants/{tenant_id}/environments/{environment}/conversations": { "get": { "operationId": "listConversation", "summary": "List conversations", "tags": [ "conversations" ], "x-release-stage": "proposed", "x-visibility": "public", "x-required-scopes": [ "conversations:read" ], "security": [ { "ServiceKey": [] }, { "ActorToken": [] } ], "description": "List conversations", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "environment", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/EnvironmentName" } }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Conversation" } }, "next_cursor": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "items", "next_cursor", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } } }, "post": { "operationId": "createConversation", "summary": "Create conversation", "tags": [ "conversations" ], "x-release-stage": "proposed", "x-visibility": "public", "x-required-scopes": [ "conversations:write" ], "security": [ { "ServiceKey": [] }, { "ActorToken": [] } ], "description": "Create conversation", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "environment", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/EnvironmentName" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Success", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Conversation" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateConversation" } } } } } }, "/v1/tenants/{tenant_id}/environments/{environment}/conversations/{conversation_id}": { "get": { "operationId": "getConversation", "summary": "Get conversation", "tags": [ "conversation_id" ], "x-release-stage": "proposed", "x-visibility": "public", "x-required-scopes": [ "conversations:read" ], "security": [ { "ServiceKey": [] }, { "ActorToken": [] } ], "description": "Get conversation", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "environment", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/EnvironmentName" } }, { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Conversation" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } } }, "patch": { "operationId": "updateConversation", "summary": "Update conversation", "tags": [ "conversation_id" ], "x-release-stage": "proposed", "x-visibility": "public", "x-required-scopes": [ "conversations:write" ], "security": [ { "ServiceKey": [] }, { "ActorToken": [] } ], "description": "Update conversation", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "environment", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/EnvironmentName" } }, { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Conversation" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Archive" } } } } }, "delete": { "operationId": "deleteConversation", "summary": "Delete conversation", "tags": [ "conversation_id" ], "x-release-stage": "proposed", "x-visibility": "public", "x-required-scopes": [ "conversations:write" ], "security": [ { "ServiceKey": [] }, { "ActorToken": [] } ], "description": "Immediately deny access and revoke derived authority. Live purge within 24 hours; backups expire separately within 30 days. Restore replays deletion journal before serving.", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "environment", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/EnvironmentName" } }, { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "202": { "description": "Success", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." }, "Location": { "schema": { "type": "string" }, "description": "Poll the accepted resource at this path." } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/DeletionJob" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/v1/tenants/{tenant_id}/environments/{environment}/conversations/{conversation_id}/runs": { "post": { "operationId": "createRun", "summary": "Start durable work", "tags": [ "runs" ], "x-release-stage": "proposed", "x-visibility": "public", "x-required-scopes": [ "runs:write" ], "security": [ { "ServiceKey": [] }, { "ActorToken": [] } ], "description": "202 only after control-plane acceptance reservation and cell persistence. Prefer: wait=10 may return the same terminal run with 200; disconnect never cancels. Admission grants a bounded 15-minute durable execution authorization, independent of the five-minute actor token used to submit the request. Persist the original opaque lease ID, user epoch, workspace and scopes with the run. Each dispatch still checks the current parent key, tenant/environment generation, current user status and revocation; revocation invalidates admitted authority. Token expiry alone does not interrupt admitted work. The 15-minute total authorization wall clock includes queue and human-approval waits; active execution remains at most five minutes and an individual approval at most ten minutes. Retry is explicit new key plus retry_of_run_id; unresolved writes reject retry. Per-workspace one active, cell two active, queue100 and five-minute start deadline. Model admission fails closed on budget/control-plane outage.", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "environment", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/EnvironmentName" } }, { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "Prefer", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "wait=10" ] } } ], "responses": { "200": { "description": "Same run reached terminal state within requested wait", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Run" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "data", "request_id" ] } } } }, "202": { "description": "Success", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." }, "Location": { "schema": { "type": "string" }, "description": "Poll the accepted resource at this path." } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Run" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRun" }, "example": { "input": [ { "type": "text", "text": "Read ticket T-104 and propose a concise internal follow-up note." } ] } } } } } }, "/v1/tenants/{tenant_id}/environments/{environment}/runs": { "get": { "operationId": "listRun", "summary": "List runs", "tags": [ "runs" ], "x-release-stage": "proposed", "x-visibility": "public", "x-required-scopes": [ "runs:read" ], "security": [ { "ServiceKey": [] }, { "ActorToken": [] } ], "description": "List runs", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "environment", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/EnvironmentName" } }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Run" } }, "next_cursor": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "items", "next_cursor", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/v1/tenants/{tenant_id}/environments/{environment}/runs/{run_id}": { "get": { "operationId": "getRun", "summary": "Get run", "tags": [ "run_id" ], "x-release-stage": "proposed", "x-visibility": "public", "x-required-scopes": [ "runs:read" ], "security": [ { "ServiceKey": [] }, { "ActorToken": [] } ], "description": "Get run", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "environment", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/EnvironmentName" } }, { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Run" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/v1/tenants/{tenant_id}/environments/{environment}/runs/{run_id}/cancel": { "post": { "operationId": "cancelRun", "summary": "Request run cancellation", "tags": [ "cancel" ], "x-release-stage": "proposed", "x-visibility": "public", "x-required-scopes": [ "runs:write" ], "security": [ { "ServiceKey": [] }, { "ActorToken": [] } ], "description": "Stop new tool dispatch and interrupt runtime. Cancellation is best effort; an unresolved dispatched write yields outcome_unknown, never false cancelled success.", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "environment", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/EnvironmentName" } }, { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "202": { "description": "Success", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." }, "Location": { "schema": { "type": "string" }, "description": "Poll the accepted resource at this path." } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Run" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/v1/tenants/{tenant_id}/environments/{environment}/runs/{run_id}/events": { "get": { "operationId": "listRunEvents", "summary": "Read durable ordered run events", "tags": [ "events" ], "x-release-stage": "proposed", "x-visibility": "public", "x-required-scopes": [ "runs:read" ], "security": [ { "ServiceKey": [] }, { "ActorToken": [] } ], "description": "Stable durable per-run sequence. Opaque cursor bound to tenant/environment/run. Same IDs as SSE; historic terminal events remain immutable.", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "environment", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/EnvironmentName" } }, { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" }, { "name": "after_event_id", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } }, "next_cursor": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "items", "next_cursor", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/v1/tenants/{tenant_id}/environments/{environment}/runs/{run_id}/events/stream": { "get": { "operationId": "streamRunEvents", "summary": "Stream durable run events over SSE", "tags": [ "stream" ], "x-release-stage": "proposed", "x-visibility": "public", "x-required-scopes": [ "runs:read" ], "security": [ { "ServiceKey": [] }, { "ActorToken": [] } ], "description": "text/event-stream: id is durable event ID, event is typed event name, data is Event JSON. Reconnect with Last-Event-ID; client deduplicates. Heartbeat at most15s; reauthorize within15s. No guaranteed token-level stream. Replay expiry returns410 before stream opens. Disconnect does not cancel.", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "environment", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/EnvironmentName" } }, { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "Last-Event-ID", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "responses": { "200": { "description": "SSE durable event stream", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." } }, "content": { "text/event-stream": { "schema": { "type": "string" }, "example": "id: evt_1\nevent: run.queued\ndata: {\"id\":\"evt_1\",\"run_id\":\"run_demo\",\"sequence\":1,\"type\":\"run.queued\",\"created_at\":\"2026-09-07T10:00:00Z\",\"data\":{}}\n\n" } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/v1/tenants/{tenant_id}/environments/{environment}/approvals": { "get": { "operationId": "listApproval", "summary": "List approvals", "tags": [ "approvals" ], "x-release-stage": "proposed", "x-visibility": "public", "x-required-scopes": [ "approvals:read" ], "security": [ { "ServiceKey": [] }, { "ActorToken": [] } ], "description": "List approvals", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "environment", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/EnvironmentName" } }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Approval" } }, "next_cursor": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "items", "next_cursor", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/v1/tenants/{tenant_id}/environments/{environment}/approvals/{approval_id}": { "get": { "operationId": "getApproval", "summary": "Get approval", "tags": [ "approval_id" ], "x-release-stage": "proposed", "x-visibility": "public", "x-required-scopes": [ "approvals:read" ], "security": [ { "ServiceKey": [] }, { "ActorToken": [] } ], "description": "Get approval", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "environment", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/EnvironmentName" } }, { "name": "approval_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Approval" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/v1/tenants/{tenant_id}/environments/{environment}/approvals/{approval_id}/decision": { "post": { "operationId": "decideApproval", "summary": "Approve or deny exact tool operation", "tags": [ "decision" ], "x-release-stage": "proposed", "x-visibility": "public", "x-required-scopes": [ "approvals:write" ], "security": [ { "ServiceKey": [] }, { "ActorToken": [] } ], "description": "Authenticated current user only, or separately authorized approval:delegate backend asserting current user. Service actors cannot approve. Uses server-stored immutable10min operation authorization bound to run, actor, input hash, tool revision and connector generation. Approval persists continuation, releases runtime and resumes without replaying completed tools.", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "environment", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/EnvironmentName" } }, { "name": "approval_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Approval" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalDecision" } } } }, "x-authorization": { "any_of": [ "approvals:write with current user actor", "approval:delegate with explicit current user identity" ], "denied_actor_types": [ "service_actor" ] } } }, "/v1/tenants/{tenant_id}/environments/{environment}/files": { "get": { "operationId": "listFile", "summary": "List files", "tags": [ "files" ], "x-release-stage": "proposed", "x-visibility": "public", "x-required-scopes": [ "files:read" ], "security": [ { "ServiceKey": [] }, { "ActorToken": [] } ], "description": "List files", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "environment", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/EnvironmentName" } }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/File" } }, "next_cursor": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "items", "next_cursor", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } } }, "post": { "operationId": "createFile", "summary": "Create file", "tags": [ "files" ], "x-release-stage": "proposed", "x-visibility": "public", "x-required-scopes": [ "files:write" ], "security": [ { "ServiceKey": [] }, { "ActorToken": [] } ], "description": "Create file", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "environment", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/EnvironmentName" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Success", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/File" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadFile" } } } } } }, "/v1/tenants/{tenant_id}/environments/{environment}/files/{file_id}": { "get": { "operationId": "getFile", "summary": "Get file", "tags": [ "file_id" ], "x-release-stage": "proposed", "x-visibility": "public", "x-required-scopes": [ "files:read" ], "security": [ { "ServiceKey": [] }, { "ActorToken": [] } ], "description": "Get file", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "environment", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/EnvironmentName" } }, { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/File" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } } }, "delete": { "operationId": "deleteFile", "summary": "Delete file", "tags": [ "file_id" ], "x-release-stage": "proposed", "x-visibility": "public", "x-required-scopes": [ "files:write" ], "security": [ { "ServiceKey": [] }, { "ActorToken": [] } ], "description": "Immediately deny access and revoke derived authority. Live purge within 24 hours; backups expire separately within 30 days. Restore replays deletion journal before serving.", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "environment", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/EnvironmentName" } }, { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "202": { "description": "Success", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." }, "Location": { "schema": { "type": "string" }, "description": "Poll the accepted resource at this path." } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/DeletionJob" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/v1/tenants/{tenant_id}/environments/{environment}/files/{file_id}/download": { "get": { "operationId": "downloadFile", "summary": "Download available file through authenticated proxy", "tags": [ "download" ], "x-release-stage": "proposed", "x-visibility": "public", "x-required-scopes": [ "files:read" ], "security": [ { "ServiceKey": [] }, { "ActorToken": [] } ], "description": "Only scanned available files; authorization checked on every download. No public signed URL. nosniff and attachment disposition.", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "environment", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/EnvironmentName" } }, { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "responses": { "200": { "description": "Bounded file bytes", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string" }, "example": "nosniff" } }, "content": { "text/plain": { "schema": { "type": "string" } }, "application/json": { "schema": {} } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/v1/tenants/{tenant_id}/environments/{environment}/webhook-endpoints": { "get": { "operationId": "listWebhookEndpoint", "summary": "List webhook-endpoints", "tags": [ "webhook-endpoints" ], "x-release-stage": "proposed", "x-visibility": "public", "x-required-scopes": [ "webhooks:read" ], "security": [ { "ServiceKey": [] } ], "description": "Environment-wide administrative webhook capability, restricted to the explicit webhooks scope. Notifications contain reference-only event ID, run ID, type, status and creation time; never prompts, results, file content or secrets. The webhook administration scope is not authority to read end-user content. Protected run/file reads independently require the receiving application actor authorization. New or changed destinations require operator review before dispatch.", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "environment", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/EnvironmentName" } }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpoint" } }, "next_cursor": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "items", "next_cursor", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } } }, "post": { "operationId": "createWebhookEndpoint", "summary": "Create webhook_endpoint", "tags": [ "webhook-endpoints" ], "x-release-stage": "proposed", "x-visibility": "public", "x-required-scopes": [ "webhooks:write" ], "security": [ { "ServiceKey": [] } ], "description": "Environment-wide administrative webhook capability, restricted to the explicit webhooks scope. Notifications contain reference-only event ID, run ID, type, status and creation time; never prompts, results, file content or secrets. The webhook administration scope is not authority to read end-user content. Protected run/file reads independently require the receiving application actor authorization. New or changed destinations require operator review before dispatch.", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "environment", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/EnvironmentName" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Success", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/WebhookSecret" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhook" } } } } } }, "/v1/tenants/{tenant_id}/environments/{environment}/webhook-endpoints/{webhook_endpoint_id}": { "get": { "operationId": "getWebhookEndpoint", "summary": "Get webhook_endpoint", "tags": [ "webhook_endpoint_id" ], "x-release-stage": "proposed", "x-visibility": "public", "x-required-scopes": [ "webhooks:read" ], "security": [ { "ServiceKey": [] } ], "description": "Environment-wide administrative webhook capability, restricted to the explicit webhooks scope. Notifications contain reference-only event ID, run ID, type, status and creation time; never prompts, results, file content or secrets. The webhook administration scope is not authority to read end-user content. Protected run/file reads independently require the receiving application actor authorization. New or changed destinations require operator review before dispatch.", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "environment", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/EnvironmentName" } }, { "name": "webhook_endpoint_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/WebhookEndpoint" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } } }, "patch": { "operationId": "updateWebhookEndpoint", "summary": "Update webhook_endpoint", "tags": [ "webhook_endpoint_id" ], "x-release-stage": "proposed", "x-visibility": "public", "x-required-scopes": [ "webhooks:write" ], "security": [ { "ServiceKey": [] } ], "description": "Environment-wide administrative webhook capability, restricted to the explicit webhooks scope. Notifications contain reference-only event ID, run ID, type, status and creation time; never prompts, results, file content or secrets. The webhook administration scope is not authority to read end-user content. Protected run/file reads independently require the receiving application actor authorization. New or changed destinations require operator review before dispatch.", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "environment", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/EnvironmentName" } }, { "name": "webhook_endpoint_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/WebhookEndpoint" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWebhook" } } } } }, "delete": { "operationId": "deleteWebhookEndpoint", "summary": "Delete webhook_endpoint", "tags": [ "webhook_endpoint_id" ], "x-release-stage": "proposed", "x-visibility": "public", "x-required-scopes": [ "webhooks:write" ], "security": [ { "ServiceKey": [] } ], "description": "Immediately deny access and revoke derived authority. Live purge within 24 hours; backups expire separately within 30 days. Restore replays deletion journal before serving.", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "environment", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/EnvironmentName" } }, { "name": "webhook_endpoint_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "202": { "description": "Success", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." }, "Location": { "schema": { "type": "string" }, "description": "Poll the accepted resource at this path." } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/DeletionJob" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/v1/tenants/{tenant_id}/environments/{environment}/webhook-endpoints/{webhook_endpoint_id}/rotate-secret": { "post": { "operationId": "rotateWebhookSecret", "summary": "Rotate webhook signing secret", "tags": [ "rotate-secret" ], "x-release-stage": "proposed", "x-visibility": "public", "x-required-scopes": [ "webhooks:write" ], "security": [ { "ServiceKey": [] } ], "description": "Fresh response only, no-store; replay exposes original rotation metadata only. Rotation returns current_version, previous_version and previous_retire_at. Sender includes both signature digests during a bounded 24-hour overlap. A second distinct rotation returns 409 rotation_overlap_active until the previous version retires. The same idempotency key replays original metadata without a secret, even after later rotations. A lost new-secret response cannot be recovered; retain the previous verifier during overlap, then perform a fresh rotation after retirement and safely store its secret before resuming deliveries.", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "environment", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/EnvironmentName" } }, { "name": "webhook_endpoint_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/WebhookSecret" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/v1/tenants/{tenant_id}/environments/{environment}/webhook-deliveries": { "get": { "operationId": "listWebhookDelivery", "summary": "List webhook-deliveries", "tags": [ "webhook-deliveries" ], "x-release-stage": "proposed", "x-visibility": "public", "x-required-scopes": [ "webhooks:read" ], "security": [ { "ServiceKey": [] } ], "description": "Environment-wide administrative webhook capability, restricted to the explicit webhooks scope. Notifications contain reference-only event ID, run ID, type, status and creation time; never prompts, results, file content or secrets. The webhook administration scope is not authority to read end-user content. Protected run/file reads independently require the receiving application actor authorization. New or changed destinations require operator review before dispatch.", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "environment", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/EnvironmentName" } }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } }, "next_cursor": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "items", "next_cursor", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/v1/tenants/{tenant_id}/environments/{environment}/webhook-deliveries/{webhook_delivery_id}": { "get": { "operationId": "getWebhookDelivery", "summary": "Get webhook_delivery", "tags": [ "webhook_delivery_id" ], "x-release-stage": "proposed", "x-visibility": "public", "x-required-scopes": [ "webhooks:read" ], "security": [ { "ServiceKey": [] } ], "description": "Environment-wide administrative webhook capability, restricted to the explicit webhooks scope. Notifications contain reference-only event ID, run ID, type, status and creation time; never prompts, results, file content or secrets. The webhook administration scope is not authority to read end-user content. Protected run/file reads independently require the receiving application actor authorization. New or changed destinations require operator review before dispatch.", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "environment", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/EnvironmentName" } }, { "name": "webhook_delivery_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/WebhookDelivery" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/v1/tenants/{tenant_id}/environments/{environment}/webhook-deliveries/{webhook_delivery_id}/replay": { "post": { "operationId": "replayWebhookDelivery", "summary": "Replay failed reference-only webhook", "tags": [ "replay" ], "x-release-stage": "proposed", "x-visibility": "public", "x-required-scopes": [ "webhooks:write" ], "security": [ { "ServiceKey": [] } ], "description": "Environment-wide administrative webhook capability, restricted to the explicit webhooks scope. Notifications contain reference-only event ID, run ID, type, status and creation time; never prompts, results, file content or secrets. The webhook administration scope is not authority to read end-user content. Protected run/file reads independently require the receiving application actor authorization. New or changed destinations require operator review before dispatch. Replay delivery does not rerun the agent or repeat tool operations.", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "environment", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/EnvironmentName" } }, { "name": "webhook_delivery_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "202": { "description": "Success", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." }, "Location": { "schema": { "type": "string" }, "description": "Poll the accepted resource at this path." } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/WebhookDelivery" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/v1/tenants/{tenant_id}/environments/{environment}/usage": { "get": { "operationId": "getUsage", "summary": "Inspect usage aggregates and held reservations", "tags": [ "usage" ], "x-release-stage": "proposed", "x-visibility": "public", "x-required-scopes": [ "usage:read" ], "security": [ { "ServiceKey": [] }, { "ActorToken": [] } ], "description": "Returns only the own authenticated actor usage in this tenant and environment, including held reservations. Public credentials cannot request tenant billing totals in the MVP; those remain in an authorized human console. Measured vendor cost is separate from customer rating. rated_charge_usd is null with rating_status:unrated until all included usage is rated; a rated zero is explicit. Unknown supplier usage remains provisional and reserved. Omit both from and to to use the current UTC month start through request time. When either bound is supplied, both are required as UTC ISO 8601 timestamps ending in Z; from must precede to and the window must not exceed 90 days. Invalid windows return 400.", "x-date-window": { "default": "current_utc_month_to_now", "paired": [ "from", "to" ], "timezone": "UTC", "ordering": "from < to", "max_duration_days": 90 }, "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "environment", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/EnvironmentName" } }, { "name": "from", "in": "query", "required": false, "description": "Optional UTC timestamp ending in Z. Supply both from and to, with from < to and a maximum 90-day window; omit both for current UTC month start through now.", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": false, "description": "Optional UTC timestamp ending in Z. Supply both from and to, with from < to and a maximum 90-day window; omit both for current UTC month start through now.", "schema": { "type": "string", "format": "date-time" } }, { "name": "run_id", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Usage" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/v1/tenants/{tenant_id}/environments/{environment}/usage/records": { "get": { "operationId": "listUsageRecords", "summary": "Read immutable usage ledger", "tags": [ "records" ], "x-release-stage": "proposed", "x-visibility": "public", "x-required-scopes": [ "usage:read" ], "security": [ { "ServiceKey": [] }, { "ActorToken": [] } ], "description": "Read immutable ledger entries belonging only to the own authenticated actor. Measured supplier cost is retained even when rating is pending. rated_charge_usd is null if and only if rating_status is unrated; rated zero must be explicit. Tenant-wide billing access is not granted by public usage:read.", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "environment", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/EnvironmentName" } }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/UsageRecord" } }, "next_cursor": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "items", "next_cursor", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/v1/tenants/{tenant_id}/environments/{environment}/quotas": { "get": { "operationId": "getQuotas", "summary": "Get quotas", "tags": [ "quotas" ], "x-release-stage": "proposed", "x-visibility": "public", "x-required-scopes": [ "quotas:read" ], "security": [ { "ServiceKey": [] } ], "description": "Get quotas", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "environment", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/EnvironmentName" } } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Quotas" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } } }, "patch": { "operationId": "updateQuotas", "summary": "Update quotas", "tags": [ "quotas" ], "x-release-stage": "proposed", "x-visibility": "public", "x-required-scopes": [ "quotas:write" ], "security": [ { "ServiceKey": [] } ], "description": "Update quotas", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "environment", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/EnvironmentName" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Quotas" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateQuotas" } } } } } }, "/v1/tenants/{tenant_id}/environments/{environment}/settings": { "get": { "operationId": "getSettings", "summary": "Get settings", "tags": [ "settings" ], "x-release-stage": "proposed", "x-visibility": "public", "x-required-scopes": [ "settings:read" ], "security": [ { "ServiceKey": [] } ], "description": "Get settings", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "environment", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/EnvironmentName" } } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Settings" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } } }, "patch": { "operationId": "updateSettings", "summary": "Update settings", "tags": [ "settings" ], "x-release-stage": "proposed", "x-visibility": "public", "x-required-scopes": [ "settings:write" ], "security": [ { "ServiceKey": [] } ], "description": "Update settings", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "environment", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/EnvironmentName" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Settings" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSettings" } } } } } }, "/v1/tenants/{tenant_id}/environments/{environment}/audit": { "get": { "operationId": "listAuditEntries", "summary": "Read sanitized audit events", "tags": [ "audit" ], "x-release-stage": "proposed", "x-visibility": "public", "x-required-scopes": [ "audit:read" ], "security": [ { "ServiceKey": [] } ], "description": "Read sanitized audit events", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "environment", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/EnvironmentName" } }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AuditEntry" } }, "next_cursor": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "items", "next_cursor", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/v1/tenants/{tenant_id}/environments/{environment}/deletion-jobs/{deletion_job_id}": { "get": { "operationId": "getDeletionJob", "summary": "Inspect purge and backup expiry", "tags": [ "deletion_job_id" ], "x-release-stage": "proposed", "x-visibility": "public", "x-required-scopes": [ "deletions:read" ], "security": [ { "ServiceKey": [] }, { "ActorToken": [] } ], "description": "Inspect purge and backup expiry", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "environment", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/EnvironmentName" } }, { "name": "deletion_job_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/DeletionJob" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/.well-known/jwks.json": { "get": { "operationId": "getToolJwks", "summary": "Read Mystro outbound verification keys", "tags": [ "jwks.json" ], "x-release-stage": "proposed", "x-visibility": "public", "x-required-scopes": [], "security": [], "description": "Customer tools verify JWT kid/signature/audience/expiry/operation digest/generation using this keyset. Public keys only; key rotation overlaps outstanding token lifetimes.", "parameters": [], "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Jwks" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } } } } }, "components": { "securitySchemes": { "ServiceKey": { "type": "http", "scheme": "bearer", "description": "Server-only API key. Per-environment, immutable scopes and actor; management keys cannot mint keys or imply end-user content access." }, "ActorToken": { "type": "http", "scheme": "bearer", "bearerFormat": "opaque", "description": "Delegated actor request tokens last five minutes and authorize new API requests only. Bound to current workspace, scopes, parent-key epoch and user epoch; revocation closes streams within 15 seconds. A run accepted before token expiry has a separate, bounded 15-minute durable execution authorization tied to its original opaque lease, current parent key and current user/workspace revocation. Expiry of the request token never grants access to additional resources or extends admitted authorization." } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[A-Za-z0-9_.:-]+$" } }, "Cursor": { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 2048 } }, "Limit": { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } }, "responses": { "Error400": { "description": "Invalid request", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error401": { "description": "Invalid or expired authentication", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error403": { "description": "Scope or human authorization required", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error404": { "description": "Missing or inaccessible resource", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error409": { "description": "Idempotency, ownership or state conflict", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error410": { "description": "Expired idempotency replay; never recreate", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error429": { "description": "Rate, budget or quota exceeded", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds until retry may be attempted." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error503": { "description": "Admission or dependency unavailable", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Sanitized support correlation ID." }, "Cache-Control": { "schema": { "type": "string" }, "example": "no-store", "description": "Responses containing credentials or private data are never cached." }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds until retry may be attempted." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "Id": { "type": "string", "minLength": 1, "maxLength": 128 }, "Money": { "type": "string", "pattern": "^(0|[1-9][0-9]*)(\\.[0-9]{1,6})?$", "example": "1.00" }, "Scope": { "type": "string", "enum": [ "tenants:read", "tenants:write", "environments:read", "environments:write", "keys:read", "keys:revoke", "users:read", "users:write", "service-actors:read", "service-actors:write", "identity:delegate", "approval:delegate", "workspaces:read", "workspaces:write", "agents:read", "agents:write", "models:read", "connections:read", "connections:write", "tools:read", "conversations:read", "conversations:write", "runs:read", "runs:write", "approvals:read", "approvals:write", "files:read", "files:write", "webhooks:read", "webhooks:write", "usage:read", "quotas:read", "quotas:write", "settings:read", "settings:write", "audit:read", "deletions:read" ] }, "Actor": { "type": "object", "additionalProperties": false, "properties": { "type": { "type": "string", "enum": [ "user", "service_actor" ] }, "id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "type", "id" ] }, "EnvironmentName": { "type": "string", "enum": [ "sandbox", "production" ] }, "Error": { "type": "object", "additionalProperties": false, "properties": { "error": { "type": "object", "additionalProperties": false, "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" } }, "required": [ "code", "message", "retryable" ] }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "error", "request_id" ], "example": { "error": { "code": "scope_required", "message": "The credential does not authorize this operation.", "retryable": false }, "request_id": "req_demo" } }, "Tenant": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "active", "suspended", "deleting", "deleted" ] }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "status", "created_at" ], "example": { "id": "ten_demo", "name": "Acme Operations", "status": "pending", "created_at": "2026-09-07T10:00:00Z" } }, "UpdateTenant": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 } }, "required": [ "name" ] }, "Environment": { "type": "object", "additionalProperties": true, "properties": { "tenant_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "environment": { "$ref": "#/components/schemas/EnvironmentName" }, "status": { "type": "string", "enum": [ "absent", "provisioning", "ready", "failed", "suspended", "deleting", "deleted" ] }, "generation": { "type": "integer", "minimum": 0 }, "failure_code": { "type": [ "string", "null" ] } }, "required": [ "tenant_id", "environment", "status", "generation", "failure_code" ] }, "User": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "tenant_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "environment": { "$ref": "#/components/schemas/EnvironmentName" }, "external_id": { "type": "string", "minLength": 1, "maxLength": 256 }, "status": { "type": "string", "enum": [ "active", "disabled", "deleting", "deleted" ] }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "tenant_id", "environment", "external_id", "status", "created_at" ] }, "CreateUser": { "type": "object", "additionalProperties": false, "properties": { "external_id": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "external_id" ] }, "UpdateActor": { "type": "object", "additionalProperties": false, "properties": { "status": { "type": "string", "enum": [ "active", "disabled" ] } }, "required": [ "status" ] }, "ServiceActor": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "tenant_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "environment": { "$ref": "#/components/schemas/EnvironmentName" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "disabled", "deleting", "deleted" ] }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "tenant_id", "environment", "name", "status", "created_at" ] }, "CreateServiceActor": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 } }, "required": [ "name" ] }, "ActorSessionRequest": { "type": "object", "additionalProperties": false, "properties": { "actor": { "type": "object", "additionalProperties": false, "properties": { "type": { "type": "string", "const": "user" }, "id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "type", "id" ] }, "workspace_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "scopes": { "type": "array", "items": { "$ref": "#/components/schemas/Scope" }, "minItems": 1, "uniqueItems": true } }, "required": [ "actor", "workspace_id", "scopes" ] }, "ActorSession": { "type": "object", "additionalProperties": false, "properties": { "token": { "type": "string", "x-sensitive": true, "description": "One-time fresh response only. Never logged, cached, persisted in replay, or included in analytics." }, "expires_at": { "type": "string", "format": "date-time" }, "workspace_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "actor": { "$ref": "#/components/schemas/Actor" }, "scopes": { "type": "array", "items": { "$ref": "#/components/schemas/Scope" } }, "token_available": { "type": "boolean" } }, "required": [ "expires_at", "workspace_id", "actor", "scopes", "token_available" ], "description": "Fresh issuance contains token and token_available:true; replay has token_available:false and omits token. Obtain a new lease with a fresh idempotency key.", "allOf": [ { "if": { "properties": { "token_available": { "const": true } } }, "then": { "required": [ "token" ] }, "else": { "not": { "required": [ "token" ] } } } ] }, "Workspace": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "tenant_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "environment": { "$ref": "#/components/schemas/EnvironmentName" }, "owner": { "$ref": "#/components/schemas/Actor" }, "status": { "type": "string", "enum": [ "active", "deleting", "deleted" ] }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "tenant_id", "environment", "owner", "status", "created_at" ] }, "CreateWorkspace": { "type": "object", "additionalProperties": false, "properties": { "owner": { "$ref": "#/components/schemas/Actor" } }, "required": [ "owner" ] }, "Agent": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "tenant_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "environment": { "$ref": "#/components/schemas/EnvironmentName" }, "name": { "type": "string" }, "archived": { "type": "boolean" }, "latest_revision_id": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "tenant_id", "environment", "name", "archived", "latest_revision_id", "created_at" ] }, "CreateAgent": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 } }, "required": [ "name" ] }, "Archive": { "type": "object", "additionalProperties": false, "properties": { "archived": { "type": "boolean" } }, "required": [ "archived" ] }, "RunLimits": { "type": "object", "additionalProperties": false, "properties": { "max_active_seconds": { "type": "integer", "minimum": 1, "maximum": 300, "default": 300 }, "max_steps": { "type": "integer", "minimum": 1, "maximum": 20, "default": 20 }, "max_input_tokens": { "type": "integer", "minimum": 1, "maximum": 32768, "default": 32768 }, "max_output_tokens": { "type": "integer", "minimum": 1, "maximum": 8192, "default": 8192 }, "max_cost_usd": { "$ref": "#/components/schemas/Money" } }, "required": [ "max_active_seconds", "max_steps", "max_input_tokens", "max_output_tokens", "max_cost_usd" ] }, "CreateAgentRevision": { "type": "object", "additionalProperties": false, "properties": { "instructions": { "type": "string", "minLength": 1, "maxLength": 32768 }, "model_profile": { "type": "string", "enum": [ "standard" ] }, "tool_ids": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 }, "maxItems": 20, "uniqueItems": true }, "memory": { "type": "object", "additionalProperties": false, "properties": { "mode": { "type": "string", "const": "off" } }, "required": [ "mode" ] }, "limits": { "$ref": "#/components/schemas/RunLimits" } }, "required": [ "instructions", "model_profile", "tool_ids", "memory", "limits" ], "example": { "instructions": "Summarize the supplied operations report. Use only approved tools.", "model_profile": "standard", "tool_ids": [], "memory": { "mode": "off" }, "limits": { "max_active_seconds": 300, "max_steps": 20, "max_input_tokens": 32768, "max_output_tokens": 8192, "max_cost_usd": "1.00" } } }, "AgentRevision": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "tenant_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "environment": { "$ref": "#/components/schemas/EnvironmentName" }, "agent_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "instructions": { "type": "string" }, "model_profile": { "type": "string", "enum": [ "standard" ] }, "tool_ids": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 } }, "memory": { "type": "object", "additionalProperties": false, "properties": { "mode": { "type": "string", "const": "off" } }, "required": [ "mode" ] }, "limits": { "$ref": "#/components/schemas/RunLimits" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "tenant_id", "environment", "agent_id", "instructions", "model_profile", "tool_ids", "memory", "limits", "created_at" ] }, "ModelProfile": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string", "enum": [ "standard" ] }, "name": { "type": "string" }, "input_token_limit": { "type": "integer" }, "output_token_limit": { "type": "integer" }, "available": { "type": "boolean" } }, "required": [ "id", "name", "input_token_limit", "output_token_limit", "available" ] }, "ConnectionOwner": { "oneOf": [ { "type": "object", "additionalProperties": false, "properties": { "type": { "type": "string", "enum": [ "tenant" ] } }, "required": [ "type" ] }, { "$ref": "#/components/schemas/Actor" } ] }, "ToolOperation": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,63}$" }, "effect": { "type": "string", "enum": [ "read", "write" ] }, "path": { "type": "string", "pattern": "^/[^?#]*$" }, "reconciliation_path": { "type": "string", "pattern": "^/[^?#]*$" }, "input_schema": { "type": "object", "description": "JSON Schema 2020-12, reviewed and frozen before activation." }, "output_schema": { "type": "object", "description": "JSON Schema 2020-12, reviewed and frozen before activation." } }, "required": [ "name", "effect", "path", "input_schema", "output_schema" ], "description": "Writes require reconciliation_path and human approval. Financial execution, arbitrary code and credential return are prohibited.", "if": { "properties": { "effect": { "const": "write" } }, "required": [ "effect" ] }, "then": { "required": [ "reconciliation_path" ] } }, "CreateConnection": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "type": { "type": "string", "enum": [ "customer_https" ] }, "owner": { "$ref": "#/components/schemas/ConnectionOwner" }, "base_url": { "type": "string", "format": "uri", "pattern": "^https://" }, "authentication": { "type": "object", "additionalProperties": false, "properties": { "type": { "type": "string", "enum": [ "mystro_signed_request" ] } }, "required": [ "type" ] }, "operations": { "type": "array", "items": { "$ref": "#/components/schemas/ToolOperation" }, "minItems": 1, "maxItems": 20 } }, "required": [ "name", "type", "owner", "base_url", "authentication", "operations" ], "example": { "name": "Acme tickets", "type": "customer_https", "owner": { "type": "tenant" }, "base_url": "https://tools.acme.invalid", "authentication": { "type": "mystro_signed_request" }, "operations": [ { "name": "get_ticket", "effect": "read", "path": "/tickets/read", "input_schema": { "type": "object", "properties": { "ticket_id": { "type": "string" } }, "required": [ "ticket_id" ], "additionalProperties": false }, "output_schema": { "type": "object", "properties": { "title": { "type": "string" } }, "required": [ "title" ], "additionalProperties": false } }, { "name": "add_note", "effect": "write", "path": "/tickets/notes", "reconciliation_path": "/operations/{operation_id}", "input_schema": { "type": "object", "properties": { "ticket_id": { "type": "string" }, "note": { "type": "string" } }, "required": [ "ticket_id", "note" ], "additionalProperties": false }, "output_schema": { "type": "object", "properties": { "note_id": { "type": "string" } }, "required": [ "note_id" ], "additionalProperties": false } } ] } }, "Connection": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "tenant_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "environment": { "$ref": "#/components/schemas/EnvironmentName" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "customer_https" ] }, "owner": { "$ref": "#/components/schemas/ConnectionOwner" }, "base_url": { "type": "string", "format": "uri" }, "status": { "type": "string", "enum": [ "pending_review", "active", "disabled", "revoked" ] }, "generation": { "type": "integer", "minimum": 1 }, "tool_ids": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 } }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "tenant_id", "environment", "name", "type", "owner", "base_url", "status", "generation", "tool_ids", "created_at" ] }, "DisableConnection": { "type": "object", "additionalProperties": false, "properties": { "disabled": { "type": "boolean" } }, "required": [ "disabled" ] }, "Tool": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "tenant_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "environment": { "$ref": "#/components/schemas/EnvironmentName" }, "connection_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "revision_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "name": { "type": "string" }, "effect": { "type": "string", "enum": [ "read", "write" ] }, "path": { "type": "string" }, "reconciliation_path": { "type": "string" }, "input_schema": { "type": "object" }, "output_schema": { "type": "object" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "tenant_id", "environment", "connection_id", "revision_id", "name", "effect", "path", "input_schema", "output_schema", "created_at" ] }, "CreateConversation": { "type": "object", "additionalProperties": false, "properties": { "workspace_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "agent_revision_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "workspace_id", "agent_revision_id" ] }, "Conversation": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "tenant_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "environment": { "$ref": "#/components/schemas/EnvironmentName" }, "workspace_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "agent_revision_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "archived": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "tenant_id", "environment", "workspace_id", "agent_revision_id", "archived", "created_at" ] }, "RunInput": { "type": "array", "minItems": 1, "maxItems": 10, "items": { "oneOf": [ { "type": "object", "additionalProperties": false, "properties": { "type": { "const": "text" }, "text": { "type": "string", "minLength": 1, "maxLength": 131072 } }, "required": [ "type", "text" ] }, { "type": "object", "additionalProperties": false, "properties": { "type": { "const": "file" }, "file_id": { "$ref": "#/components/schemas/Id" } }, "required": [ "type", "file_id" ] } ] } }, "CreateRun": { "type": "object", "additionalProperties": false, "properties": { "input": { "$ref": "#/components/schemas/RunInput" }, "retry_of_run_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "input" ], "example": { "input": [ { "type": "text", "text": "Read ticket T-104 and propose a concise internal follow-up note." } ] } }, "RunStatus": { "type": "string", "enum": [ "queued", "running", "requires_action", "cancel_requested", "succeeded", "failed", "cancelled", "expired", "interrupted", "outcome_unknown" ] }, "Run": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "tenant_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "environment": { "$ref": "#/components/schemas/EnvironmentName" }, "conversation_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "workspace_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "actor": { "$ref": "#/components/schemas/Actor" }, "agent_revision_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "status": { "$ref": "#/components/schemas/RunStatus" }, "retry_of_run_id": { "type": [ "string", "null" ] }, "last_event_id": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "terminal_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "tenant_id", "environment", "conversation_id", "workspace_id", "actor", "agent_revision_id", "status", "retry_of_run_id", "last_event_id", "created_at", "started_at", "terminal_at" ], "example": { "id": "run_demo", "tenant_id": "ten_demo", "environment": "sandbox", "conversation_id": "con_demo", "workspace_id": "wrk_demo", "actor": { "type": "user", "id": "usr_demo" }, "agent_revision_id": "rev_demo", "status": "queued", "retry_of_run_id": null, "last_event_id": "evt_1", "created_at": "2026-09-07T10:00:00Z", "started_at": null, "terminal_at": null } }, "Event": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "run_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "sequence": { "type": "integer", "minimum": 1 }, "type": { "type": "string", "enum": [ "run.queued", "run.started", "assistant.message", "tool.started", "tool.completed", "run.requires_action", "run.cancel_requested", "run.completed", "reconciliation.receipt" ] }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "description": "Event-specific payload; do not assume model-token granularity." } }, "required": [ "id", "run_id", "sequence", "type", "created_at", "data" ] }, "Approval": { "type": "object", "additionalProperties": true, "description": "Read-authorized immutable proposal for human review. Render the exact destination and validated input as escaped data before allowing approve. Content remains in the tenant cell; hashes alone are insufficient for informed approval. Recheck actor, tool revision, connector generation and expiry immediately before dispatch.", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "tenant_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "environment": { "$ref": "#/components/schemas/EnvironmentName" }, "run_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "operation_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "actor": { "$ref": "#/components/schemas/Actor" }, "input_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "tool_revision_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "connector_generation": { "type": "integer", "minimum": 1 }, "proposal": { "type": "object", "additionalProperties": false, "properties": { "tool_id": { "$ref": "#/components/schemas/Id" }, "display_name": { "type": "string", "minLength": 1, "maxLength": 200 }, "destination": { "type": "string", "format": "uri" }, "input": { "type": "object", "additionalProperties": true } }, "required": [ "tool_id", "display_name", "destination", "input" ] }, "status": { "type": "string", "enum": [ "pending", "approved", "denied", "expired", "revoked" ] }, "expires_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "tenant_id", "environment", "run_id", "operation_id", "actor", "input_hash", "tool_revision_id", "connector_generation", "proposal", "status", "expires_at", "created_at" ] }, "ApprovalDecision": { "type": "object", "additionalProperties": false, "properties": { "decision": { "type": "string", "enum": [ "approve", "deny" ] } }, "required": [ "decision" ] }, "File": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "tenant_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "environment": { "$ref": "#/components/schemas/EnvironmentName" }, "workspace_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "name": { "type": "string" }, "content_type": { "type": "string", "enum": [ "text/plain", "application/json" ] }, "size_bytes": { "type": "integer", "minimum": 0, "maximum": 10485760 }, "status": { "type": "string", "enum": [ "quarantined", "available", "rejected", "deleting", "deleted" ] }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "tenant_id", "environment", "workspace_id", "name", "content_type", "size_bytes", "status", "created_at" ] }, "UploadFile": { "type": "object", "additionalProperties": false, "properties": { "workspace_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "content_type": { "type": "string", "enum": [ "text/plain", "application/json" ] }, "content_base64": { "type": "string", "contentEncoding": "base64", "maxLength": 13981016, "description": "Decoded content maximum 10 MiB. Strict base64 decoder required; scan before availability." } }, "required": [ "workspace_id", "name", "content_type", "content_base64" ], "description": "Strict canonical base64 text/json upload. Total HTTP request maximum14MiB and decoded file maximum10MiB; reject invalid base64, MIME mismatch and oversized content before scan. Bounded buffering has memory overhead; streaming upload is deferred." }, "CreateWebhook": { "type": "object", "additionalProperties": false, "properties": { "url": { "type": "string", "format": "uri", "pattern": "^https://" }, "event_types": { "type": "array", "items": { "type": "string", "enum": [ "run.completed", "run.requires_action" ] }, "minItems": 1, "uniqueItems": true } }, "required": [ "url", "event_types" ] }, "UpdateWebhook": { "type": "object", "additionalProperties": false, "properties": { "url": { "type": "string", "format": "uri", "pattern": "^https://" }, "event_types": { "type": "array", "items": { "type": "string", "enum": [ "run.completed", "run.requires_action" ] }, "minItems": 1, "uniqueItems": true }, "enabled": { "type": "boolean" } }, "required": [], "minProperties": 1 }, "WebhookEndpoint": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "tenant_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "environment": { "$ref": "#/components/schemas/EnvironmentName" }, "url": { "type": "string", "format": "uri" }, "event_types": { "type": "array", "items": { "type": "string" } }, "enabled": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "tenant_id", "environment", "url", "event_types", "enabled", "created_at" ] }, "WebhookSecret": { "type": "object", "additionalProperties": false, "properties": { "endpoint": { "$ref": "#/components/schemas/WebhookEndpoint" }, "secret_available": { "type": "boolean" }, "secret": { "type": "string", "x-sensitive": true, "description": "One-time fresh response only. Never logged, cached, persisted in replay, or included in analytics." }, "rotation": { "type": "object", "additionalProperties": false, "properties": { "current_version": { "type": "integer", "minimum": 2 }, "previous_version": { "type": "integer", "minimum": 1 }, "previous_retire_at": { "type": "string", "format": "date-time" } }, "required": [ "current_version", "previous_version", "previous_retire_at" ], "description": "Returned on rotation only, including metadata-only replay of the original rotation." } }, "required": [ "endpoint", "secret_available" ] }, "WebhookDelivery": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "endpoint_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "event_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "run_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "status": { "type": "string", "enum": [ "pending", "delivered", "failed" ] }, "attempts": { "type": "integer", "minimum": 0 }, "next_attempt_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "endpoint_id", "event_id", "run_id", "status", "attempts", "next_attempt_at", "created_at" ] }, "WebhookEvent": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "run_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "type": { "type": "string", "enum": [ "run.completed", "run.requires_action" ] }, "status": { "$ref": "#/components/schemas/RunStatus" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "run_id", "type", "status", "created_at" ], "example": { "id": "evt_9", "run_id": "run_demo", "type": "run.completed", "status": "succeeded", "created_at": "2026-09-07T10:00:00Z" } }, "UsageRecord": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "tenant_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "environment": { "$ref": "#/components/schemas/EnvironmentName" }, "run_id": { "type": [ "string", "null" ] }, "operation_id": { "type": [ "string", "null" ] }, "kind": { "type": "string", "enum": [ "measured", "adjustment" ] }, "quantity": { "type": "string", "pattern": "^-?[0-9]+(\\.[0-9]+)?$" }, "unit": { "type": "string", "enum": [ "input_tokens", "output_tokens", "runtime_seconds", "storage_bytes", "tool_calls" ] }, "measured_cost_usd": { "type": "string", "pattern": "^-?[0-9]+(\\.[0-9]{1,6})?$" }, "rated_charge_usd": { "type": [ "string", "null" ], "pattern": "^-?[0-9]+(\\.[0-9]{1,6})?$", "description": "Null until customer rating is known; never represent an unknown price as zero." }, "adjustment_of": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "rating_status": { "type": "string", "enum": [ "unrated", "rated" ] } }, "required": [ "id", "tenant_id", "environment", "run_id", "operation_id", "kind", "quantity", "unit", "measured_cost_usd", "rated_charge_usd", "adjustment_of", "created_at", "rating_status" ], "allOf": [ { "if": { "properties": { "rating_status": { "const": "unrated" } } }, "then": { "properties": { "rated_charge_usd": { "type": "null" } } }, "else": { "properties": { "rated_charge_usd": { "type": "string" } } } } ] }, "Usage": { "type": "object", "additionalProperties": true, "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" }, "measured_cost_usd": { "$ref": "#/components/schemas/Money" }, "rated_charge_usd": { "type": [ "string", "null" ], "pattern": "^-?[0-9]+(\\.[0-9]{1,6})?$", "description": "Null until customer rating is known; never represent an unknown price as zero." }, "reserved_cost_usd": { "$ref": "#/components/schemas/Money" }, "input_tokens": { "type": "integer", "minimum": 0 }, "output_tokens": { "type": "integer", "minimum": 0 }, "runtime_seconds": { "type": "number", "minimum": 0 }, "storage_bytes": { "type": "integer", "minimum": 0 }, "provisional": { "type": "boolean" }, "rating_status": { "type": "string", "enum": [ "unrated", "rated" ] } }, "required": [ "from", "to", "measured_cost_usd", "rated_charge_usd", "reserved_cost_usd", "input_tokens", "output_tokens", "runtime_seconds", "storage_bytes", "provisional", "rating_status" ], "allOf": [ { "if": { "properties": { "rating_status": { "const": "unrated" } } }, "then": { "properties": { "rated_charge_usd": { "type": "null" } } }, "else": { "properties": { "rated_charge_usd": { "type": "string" } } } } ] }, "Quotas": { "type": "object", "additionalProperties": true, "properties": { "monthly_budget_usd": { "$ref": "#/components/schemas/Money" }, "per_run_budget_usd": { "$ref": "#/components/schemas/Money" }, "running_per_workspace": { "type": "integer", "const": 1 }, "running_per_cell": { "type": "integer", "const": 2 }, "queued_per_cell": { "type": "integer", "const": 100 }, "storage_bytes": { "type": "integer", "maximum": 1073741824 }, "queue_deadline_seconds": { "type": "integer", "const": 300 } }, "required": [ "monthly_budget_usd", "per_run_budget_usd", "running_per_workspace", "running_per_cell", "queued_per_cell", "storage_bytes", "queue_deadline_seconds" ] }, "UpdateQuotas": { "type": "object", "additionalProperties": false, "properties": { "monthly_budget_usd": { "$ref": "#/components/schemas/Money" }, "per_run_budget_usd": { "$ref": "#/components/schemas/Money" } }, "required": [], "minProperties": 1, "description": "Within operator-approved ceilings only; protective budget is not a quoted price." }, "Settings": { "type": "object", "additionalProperties": true, "properties": { "content_retention_days": { "type": "integer", "enum": [ 7, 30, 90 ] }, "audit_retention_days": { "type": "integer", "const": 90 }, "billing_retention_months": { "type": "integer", "const": 13 }, "backup_retention_days": { "type": "integer", "const": 30 } }, "required": [ "content_retention_days", "audit_retention_days", "billing_retention_months", "backup_retention_days" ] }, "UpdateSettings": { "type": "object", "additionalProperties": false, "properties": { "content_retention_days": { "type": "integer", "enum": [ 7, 30, 90 ] } }, "required": [ "content_retention_days" ] }, "AuditEntry": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "actor_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "action": { "type": "string" }, "resource_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "outcome": { "type": "string", "enum": [ "allowed", "denied", "failed" ] }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "actor_id", "action", "resource_id", "outcome", "created_at" ] }, "DeletionJob": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "tenant_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "environment": { "type": [ "string", "null" ], "enum": [ "sandbox", "production", null ], "description": "Null for a tenant-wide deletion spanning all environments." }, "resource_type": { "type": "string" }, "resource_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "status": { "type": "string", "enum": [ "pending", "purging", "completed", "failed" ] }, "live_purge_due_at": { "type": "string", "format": "date-time" }, "backup_expiry_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "tenant_id", "environment", "resource_type", "resource_id", "status", "live_purge_due_at", "backup_expiry_at", "created_at" ] }, "ApiKey": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "tenant_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "environment": { "$ref": "#/components/schemas/EnvironmentName" }, "name": { "type": "string" }, "public_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "prefix": { "type": "string" }, "last4": { "type": "string", "minLength": 4, "maxLength": 4 }, "scopes": { "type": "array", "items": { "$ref": "#/components/schemas/Scope" } }, "actor": { "$ref": "#/components/schemas/Actor" }, "creator_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "family_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "expires_at": { "type": "string", "format": "date-time" }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" }, "retires_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "tenant_id", "environment", "name", "public_id", "prefix", "last4", "scopes", "actor", "creator_id", "family_id", "expires_at", "last_used_at", "revoked_at", "retires_at", "created_at" ] }, "ToolInvocation": { "type": "object", "additionalProperties": false, "properties": { "operation_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "tool_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "tool_revision_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "run_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "tenant_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "environment": { "$ref": "#/components/schemas/EnvironmentName" }, "actor": { "$ref": "#/components/schemas/Actor" }, "input_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "input": { "type": "object" } }, "required": [ "operation_id", "tool_id", "tool_revision_id", "run_id", "tenant_id", "environment", "actor", "input_hash", "input" ], "example": { "operation_id": "op_demo", "tool_id": "tool_note", "tool_revision_id": "tr_demo", "run_id": "run_demo", "tenant_id": "ten_demo", "environment": "sandbox", "actor": { "type": "user", "id": "usr_demo" }, "input_hash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "input": { "ticket_id": "T-104", "note": "Follow up on the delayed shipment." } } }, "ToolResult": { "type": "object", "additionalProperties": false, "properties": { "operation_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "status": { "type": "string", "enum": [ "succeeded", "failed", "pending", "not_found" ] }, "output": {}, "error_code": { "type": "string" } }, "required": [ "operation_id", "status" ] }, "ToolJwtClaims": { "type": "object", "additionalProperties": false, "properties": { "iss": { "type": "string", "format": "uri" }, "aud": { "type": "string", "format": "uri" }, "sub": { "type": "string", "minLength": 1, "maxLength": 128 }, "tenant_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "environment": { "$ref": "#/components/schemas/EnvironmentName" }, "actor": { "$ref": "#/components/schemas/Actor" }, "operation_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "input_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "cell_generation": { "type": "integer", "minimum": 1 }, "iat": { "type": "integer" }, "exp": { "type": "integer" } }, "required": [ "iss", "aud", "sub", "tenant_id", "environment", "actor", "operation_id", "input_hash", "cell_generation", "iat", "exp" ] }, "Jwks": { "type": "object", "additionalProperties": false, "properties": { "keys": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "kid": { "type": "string", "minLength": 1, "maxLength": 128 }, "kty": { "type": "string", "enum": [ "RSA" ] }, "use": { "type": "string", "enum": [ "sig" ] }, "alg": { "type": "string", "enum": [ "RS256" ] }, "n": { "type": "string" }, "e": { "type": "string" } }, "required": [ "kid", "kty", "use", "alg", "n", "e" ] } } }, "required": [ "keys" ] } } }, "webhooks": { "runEvent": { "post": { "operationId": "receiveMystroWebhook", "summary": "Customer receives reference-only run webhook", "x-release-stage": "proposed", "x-visibility": "public", "security": [], "description": "Customer-hosted endpoint, not Mystro ingress. Headers: X-Mystro-Timestamp unix seconds, X-Mystro-Event-Id, X-Mystro-Signature one or two comma-separated v1=hex digests (current first during a 24-hour rotation overlap), computed as HMAC-SHA256(secret, timestamp + \".\" + eventid + \".\" + rawbody). Reject skew>5min, compare constant-time, dedupe eventID, acknowledge2xx after durable receipt. Atleastonce/unordered; retry24h. Fetch authorized content separately.", "parameters": [ { "name": "X-Mystro-Timestamp", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[0-9]+$" } }, { "name": "X-Mystro-Event-Id", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "X-Mystro-Signature", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^v1=[a-f0-9]{64}(,\\s*v1=[a-f0-9]{64})?$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "id": "evt_9", "run_id": "run_demo", "type": "run.completed", "status": "succeeded", "created_at": "2026-09-07T10:00:00Z" } } } }, "responses": { "204": { "description": "Durably received" }, "400": { "description": "Invalid signature or payload" }, "503": { "description": "Retryable receiver failure" } } } } }, "x-customer-tool-protocol": { "description": "Customer routes configured in CreateConnection, not Mystro API routes. POST configured operation.path with ToolInvocation, Authorization Bearer ToolJwt. Customer checks JWT aud/iss/signature/expiry/digest/actor live permissions then transactionally deduplicates operation_id with business write. GET configured reconciliation_path substitutes operation_id and returns ToolResult. No redirect/private IP/DNS rebinding. Ambiguous writes reconcile only, never replay.", "invocation_schema": { "$ref": "#/components/schemas/ToolInvocation" }, "result_schema": { "$ref": "#/components/schemas/ToolResult" }, "jwt_claims_schema": { "$ref": "#/components/schemas/ToolJwtClaims" } } }