{ "openapi": "3.1.0", "info": { "title": "Beep Grid open source API", "version": "0.1.0-dev", "license": { "name": "Apache-2.0" } }, "servers": [ { "url": "/" } ], "security": [ { "bearer": [] }, { "session": [] } ], "paths": { "/api/v1/people": { "get": { "operationId": "get_api_v1_people", "description": "List visible people.\n\nAuthenticated identity; mutations require management authority over the relevant resource. Enrollment requires a bounded launcher or operator.\n\nReturns: Array of Person records. Use query for complete pagination.\n\nRecovery: Unknown/hidden identity is 404 or denied. Stale version conflicts. Delegated managers cannot create broader authority than they possess; revoked credentials cannot be used.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Person" } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [], "summary": "List visible people", "tags": [ "identities" ] }, "post": { "operationId": "post_api_v1_people", "description": "Create or update a person identity.\n\nAuthenticated identity; mutations require management authority over the relevant resource. Enrollment requires a bounded launcher or operator.\n\nReturns: Person with its stable id. Email metadata alone does not verify a provider account.\n\nRecovery: Unknown/hidden identity is 404 or denied. Stale version conflicts. Delegated managers cannot create broader authority than they possess; revoked credentials cannot be used.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Person" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonInput" } } } }, "summary": "Create or update a person identity", "tags": [ "identities" ] } }, "/api/v1/people/{id}/status": { "post": { "operationId": "post_api_v1_people_id_status", "description": "Disable or re-enable a person.\n\nAuthenticated identity; mutations require management authority over the relevant resource. Enrollment requires a bounded launcher or operator.\n\nReturns: `{ok: true}` after the authorized change commits. This acknowledgment does not contain an updated resource or prove business execution.\n\nRecovery: Unknown/hidden identity is 404 or denied. Stale version conflicts. Delegated managers cannot create broader authority than they possess; revoked credentials cannot be used.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "description": "True after the operation succeeds." } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "disabled": { "type": "boolean", "description": "Whether the identity is disabled; disabled identities cannot retain normal access." } }, "required": [ "disabled" ], "additionalProperties": false } } } }, "summary": "Disable or re-enable a person", "tags": [ "identities" ] } }, "/api/v1/agents": { "get": { "operationId": "get_api_v1_agents", "description": "List visible logical agents.\n\nAuthenticated identity; mutations require management authority over the relevant resource. Enrollment requires a bounded launcher or operator.\n\nReturns: Array of Agent records, separate from runtime instances.\n\nRecovery: Unknown/hidden identity is 404 or denied. Stale version conflicts. Delegated managers cannot create broader authority than they possess; revoked credentials cannot be used.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Agent" } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [], "summary": "List visible logical agents", "tags": [ "identities" ] } }, "/api/v1/agents/{id}/status": { "post": { "operationId": "post_api_v1_agents_id_status", "description": "Disable or re-enable a logical agent.\n\nAuthenticated identity; mutations require management authority over the relevant resource. Enrollment requires a bounded launcher or operator.\n\nReturns: `{ok: true}` after the authorized change commits. This acknowledgment does not contain an updated resource or prove business execution.\n\nRecovery: Unknown/hidden identity is 404 or denied. Stale version conflicts. Delegated managers cannot create broader authority than they possess; revoked credentials cannot be used.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "description": "True after the operation succeeds." } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "disabled": { "type": "boolean", "description": "Whether the identity is disabled; disabled identities cannot retain normal access." } }, "required": [ "disabled" ], "additionalProperties": false } } } }, "summary": "Disable or re-enable a logical agent", "tags": [ "identities" ] } }, "/api/v1/services": { "get": { "operationId": "get_api_v1_services", "description": "List visible software service identities.\n\nAuthenticated identity; mutations require management authority over the relevant resource. Enrollment requires a bounded launcher or operator.\n\nReturns: Array of Service records.\n\nRecovery: Unknown/hidden identity is 404 or denied. Stale version conflicts. Delegated managers cannot create broader authority than they possess; revoked credentials cannot be used.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Service" } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [], "summary": "List visible software service identities", "tags": [ "identities" ] }, "post": { "operationId": "post_api_v1_services", "description": "Create or update a software service identity.\n\nAuthenticated identity; mutations require management authority over the relevant resource. Enrollment requires a bounded launcher or operator.\n\nReturns: Service with a stable id for credentials and contact policy.\n\nRecovery: Unknown/hidden identity is 404 or denied. Stale version conflicts. Delegated managers cannot create broader authority than they possess; revoked credentials cannot be used.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Service" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "external_id": { "type": "string", "description": "Your stable identifier for this person, agent or service within the workspace." }, "name": { "type": "string", "description": "Human-readable name. It is not necessarily unique." } }, "required": [ "external_id", "name" ], "additionalProperties": false } } } }, "summary": "Create or update a software service identity", "tags": [ "identities" ] } }, "/api/v1/services/{id}/status": { "post": { "operationId": "post_api_v1_services_id_status", "description": "Disable or re-enable a software service.\n\nAuthenticated identity; mutations require management authority over the relevant resource. Enrollment requires a bounded launcher or operator.\n\nReturns: `{ok: true}` after the authorized change commits. This acknowledgment does not contain an updated resource or prove business execution.\n\nRecovery: Unknown/hidden identity is 404 or denied. Stale version conflicts. Delegated managers cannot create broader authority than they possess; revoked credentials cannot be used.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "description": "True after the operation succeeds." } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "disabled": { "type": "boolean", "description": "Whether the identity is disabled; disabled identities cannot retain normal access." } }, "required": [ "disabled" ], "additionalProperties": false } } } }, "summary": "Disable or re-enable a software service", "tags": [ "identities" ] } }, "/api/v1/capabilities": { "post": { "operationId": "post_api_v1_capabilities", "description": "Current operation eligibility, not an authorization token. Every mutation rechecks current policy. Exact requests include audience, original Ask, reverse response and conditions.\n\nAuthenticated caller with view/message/ask authority for the resolved recipients or current conversation history.\n\nReturns: CapabilityResult: observed_at, operation-name booleans, and optional request_version/outcomes for a requested decision.\n\nRecovery: Changed audience/preview, conflicting versions, hidden history or missing reverse contact rights reject the operation. Reuse the same saved key only for the same intended write.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "observed_at": { "type": "string", "description": "Timestamp of this capability snapshot." }, "operations": { "type": "object", "additionalProperties": { "type": "boolean" }, "description": "Map of action names to currently allowed booleans. Actual mutation checks again." }, "request_version": { "type": "integer", "description": "Request version observed during capability evaluation." }, "outcomes": { "type": "array", "items": { "type": "string" }, "description": "Currently allowed typed decision outcomes." } }, "required": [], "additionalProperties": false } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "target": { "type": "object", "properties": { "kind": { "type": "string", "description": "Resource or operation kind. Use one of the listed values, not a display label." }, "id": { "type": "string", "description": "Stable identifier returned by the engine. Treat it as opaque." } }, "required": [], "additionalProperties": false, "description": "Target kind and stable ID. Choose a new target or an existing conversation, not both." }, "request_id": { "type": "string", "description": "Canonical durable request ID. This is not a worker delivery ID." }, "connection_id": { "type": "string", "description": "Configured channel connection ID." }, "descriptor": { "$ref": "#/components/schemas/Action", "description": "Optional exact Action descriptor used to evaluate conditional permission, not an executed action." } }, "required": [], "additionalProperties": false } } } }, "summary": "Current operation eligibility, not an authorization token", "tags": [ "communication" ] } }, "/api/v1/access": { "get": { "operationId": "get_api_v1_access", "description": "Own effective access, including direct/group role provenance. Inspecting another subject requires identity visibility and explicit view access:, or an administrator credential.\n\nAuthenticated caller with view/message/ask authority for the resolved recipients or current conversation history.\n\nReturns: AccessSnapshot: subject, authority basis, role assignments with provenance and observation time.\n\nRecovery: Changed audience/preview, conflicting versions, hidden history or missing reverse contact rights reject the operation. Reuse the same saved key only for the same intended write.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "subject": { "type": "object", "description": "Authorized subject projection of the access inspection." }, "basis": { "type": "string", "description": "Recorded authorization basis for this access projection; not a transferable grant." }, "roles": { "type": "array", "items": { "type": "object", "properties": { "role": { "$ref": "#/components/schemas/Role", "description": "Policy role object to preview or inspect; separate from an agent_role directory group." }, "subject_kind": { "type": "string", "description": "principal for an individual identity, or group for a directory group." }, "subject_id": { "type": "string", "description": "Identity or directory group receiving a policy-role assignment." } }, "required": [], "additionalProperties": false }, "description": "Effective policy-role assignments with direct/group provenance." }, "observed_at": { "type": "string", "description": "Timestamp of this capability snapshot." } }, "required": [], "additionalProperties": false } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "subject_id", "in": "query", "schema": { "type": "string" } } ], "summary": "Own effective access, including direct/group role provenance", "tags": [ "communication" ] } }, "/api/v1/query": { "post": { "operationId": "post_api_v1_query", "description": "Complete bounded keyset reads with current per-record authorization. Continue until next_cursor is absent, including empty pages. Cursors are encrypted and bound to scope, actor, filters and limit for 24 hours. Message history requires conversation_id and is chronological; other collections use stable ascending IDs. Unsupported filters are rejected.\n\nAuthenticated caller with view/message/ask authority for the resolved recipients or current conversation history.\n\nReturns: QueryPage: collection-specific items, optional next_cursor and stable order. Continue while next_cursor exists, including empty visible pages.\n\nRecovery: Changed audience/preview, conflicting versions, hidden history or missing reverse contact rights reject the operation. Reuse the same saved key only for the same intended write.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": {}, "description": "Authorized records returned by this page." }, "next_cursor": { "type": "string", "description": "Opaque next-page cursor. Continue even when the current items array is empty." }, "order": { "type": "string", "description": "Documented ordering for this collection." } }, "required": [], "additionalProperties": false } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "collection": { "enum": [ "people", "agents", "services", "groups", "roles", "connections", "destinations", "credentials", "instances", "requests", "conversations", "messages", "answers", "executions", "deliveries", "delivery_attempts", "attachments", "overseer_plans" ], "description": "One of the documented query collections." }, "search": { "type": "string", "description": "Optional text search, at most 200 characters." }, "filters": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Supported exact collection filters, not arbitrary SQL or JSON selectors." }, "limit": { "type": "integer", "minimum": 1, "maximum": 200, "description": "Page size: default 50, minimum 1, maximum 200." }, "cursor": { "type": "string", "description": "Opaque continuation token, scoped to the same actor, workspace and query; expires after 24 hours." } }, "required": [ "collection" ], "additionalProperties": false } } } }, "summary": "Complete bounded keyset reads with current per-record authorization", "tags": [ "communication" ] } }, "/api/v1/agents/{id}/contacts": { "post": { "operationId": "post_api_v1_agents_id_contacts", "description": "Non-sending current contact observation for an agent. Requires subject access inspection. Returns only caller-visible contacts that the agent can view and contact. Channel kinds/modes are shown only where the caller can inspect the recipient destination. No addresses, installation IDs, credentials or send authority are returned.\n\nAuthenticated identity; mutations require management authority over the relevant resource. Enrollment requires a bounded launcher or operator.\n\nReturns: AgentContacts: contacts with target, name, message/ask capability and route projections, plus observed_at.\n\nRecovery: Unknown/hidden identity is 404 or denied. Stale version conflicts. Delegated managers cannot create broader authority than they possess; revoked credentials cannot be used.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "contacts": { "type": "array", "items": { "type": "object", "properties": { "target": { "$ref": "#/components/schemas/Target", "description": "Target kind and stable ID. Choose a new target or an existing conversation, not both." }, "name": { "type": "string", "description": "Human-readable name. It is not necessarily unique." }, "message": { "type": "boolean", "description": "Safe human-readable API error message." }, "ask": { "type": "boolean", "description": "Whether the subject may initiate a requested reply to this contact." }, "routes": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "description": "Resource or operation kind. Use one of the listed values, not a display label." }, "mode": { "type": "string", "description": "primary, copy or fallback routing mode." }, "enabled": { "type": "boolean", "description": "Whether this configured connection is enabled." }, "permitted": { "type": "boolean", "description": "Whether current contact and route policy permits this route." }, "reason": { "type": "string", "description": "Human-readable explanation of the current policy or routing result." } }, "required": [], "additionalProperties": false }, "description": "Visible route projections; no destination secrets or installation credentials." } }, "required": [], "additionalProperties": false }, "description": "Authorized contact observations, including available operations and delivery route evidence." }, "observed_at": { "type": "string", "description": "Timestamp of this capability snapshot." } }, "required": [], "additionalProperties": false } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "targets": { "type": "array", "items": { "$ref": "#/components/schemas/Target" }, "maxItems": 100, "description": "Explicit targets for a private batch or shared chat. These have different audience semantics." } }, "required": [ "targets" ], "additionalProperties": false } } } }, "summary": "Non-sending current contact observation for an agent", "tags": [ "identities" ] } }, "/api/v1/dispatch-preview": { "post": { "operationId": "post_api_v1_dispatch_preview", "description": "Non-sending preview of 1 to 100 explicit individual/instance targets. Includes native, primary, copy and fallback permission/enablement observations. Token binds the authorized audience and route revisions for ten minutes. Hidden recipient identities and addresses remain private.\n\nAuthenticated caller with view/message/ask authority for the resolved recipients or current conversation history.\n\nReturns: Resolved recipient and route projection, a short-lived token and expiry; `sends` is false.\n\nRecovery: Changed audience/preview, conflicting versions, hidden history or missing reverse contact rights reject the operation. Reuse the same saved key only for the same intended write.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "recipients": { "type": "array", "items": { "type": "object", "properties": { "target": { "$ref": "#/components/schemas/Target", "description": "Target kind and stable ID. Choose a new target or an existing conversation, not both." }, "name": { "type": "string", "description": "Visible recipient display name." }, "routes": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "description": "Connection/provider kind." }, "mode": { "type": "string", "description": "Destination routing mode." }, "enabled": { "type": "boolean", "description": "Connection enabled state." }, "permitted": { "type": "boolean", "description": "Current policy result." }, "reason": { "type": "string", "description": "Reason for the routing result." } } }, "description": "Permitted and rejected visible routes." } } }, "description": "Recipients visible to this caller." }, "count": { "type": "integer", "description": "Total eligible recipient count." }, "hidden_recipients": { "type": "integer", "description": "Recipient count whose metadata is not disclosed." }, "token": { "type": "string", "description": "Short-lived audience/route fingerprint for the matching write." }, "expires_at": { "type": "string", "description": "Token expiry.", "format": "date-time" }, "sends": { "type": "boolean", "description": "Always false; preview does not dispatch." } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "targets": { "type": "array", "items": { "$ref": "#/components/schemas/Target" }, "description": "Explicit targets for a private batch or shared chat. These have different audience semantics." }, "operation": { "enum": [ "message", "ask" ], "description": "Requested operation, with values defined by that endpoint." }, "descriptor": { "$ref": "#/components/schemas/Action", "description": "Optional exact Action descriptor used to evaluate conditional permission, not an executed action." } }, "required": [ "targets", "operation" ], "additionalProperties": false } } } }, "summary": "Non-sending preview of 1 to 100 explicit individual/instance targets", "tags": [ "communication" ] } }, "/api/v1/message-batches": { "post": { "operationId": "post_api_v1_message_batches", "description": "Atomic explicit recipient dispatch, deduplicated by logical identity. Conflicting replica targets are rejected. Private conversations and per-target receipts; failure rolls back the entire batch. Optional preview token prevents changed routes/audience from silently proceeding.\n\nAuthenticated caller with view/message/ask authority for the resolved recipients or current conversation history.\n\nReturns: Array of {target, result: SendResult}. Every target retains its own private history and canonical attribution.\n\nRecovery: Changed audience/preview, conflicting versions, hidden history or missing reverse contact rights reject the operation. Reuse the same saved key only for the same intended write.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "target": { "$ref": "#/components/schemas/Target", "description": "Target kind and stable ID. Choose a new target or an existing conversation, not both." }, "result": { "$ref": "#/components/schemas/SendResult", "description": "Executor-reported JSON result. It is not independent proof of an external effect." } }, "required": [], "additionalProperties": false } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "targets": { "type": "array", "items": { "$ref": "#/components/schemas/Target" }, "description": "Explicit targets for a private batch or shared chat. These have different audience semantics." }, "body": { "type": "string", "description": "Message or request content, bounded to 32 KiB of UTF-8 bytes." }, "title": { "type": "string", "description": "Optional short label. A normal message does not require a title." }, "preview_token": { "type": "string", "description": "Dispatch preview token. A stale audience or route requires a fresh preview." }, "attachment_ids": { "type": "array", "items": { "type": "string" }, "maxItems": 5, "uniqueItems": true, "description": "IDs of staged private drafts to claim in the initial operation; at most five." } }, "required": [ "targets", "body" ], "additionalProperties": false } } } }, "summary": "Atomic explicit recipient dispatch, deduplicated by logical identity", "tags": [ "communication" ] } }, "/api/v1/request-batches": { "post": { "operationId": "post_api_v1_request_batches", "description": "Atomic private request per explicit target. Each request has an independent response and execution lifecycle; no implicit shared approval or first-responder broadcast. The nested request must omit target and conversation_id.\n\nAuthenticated caller with view/message/ask authority for the resolved recipients or current conversation history.\n\nReturns: Array of {target, request: Request}. Requests resolve independently after atomic batch creation.\n\nRecovery: Changed audience/preview, conflicting versions, hidden history or missing reverse contact rights reject the operation. Reuse the same saved key only for the same intended write.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "target": { "$ref": "#/components/schemas/Target", "description": "Target kind and stable ID. Choose a new target or an existing conversation, not both." }, "request": { "$ref": "#/components/schemas/Request", "description": "Nested requested-decision input or canonical request in a batch result." } }, "required": [], "additionalProperties": false } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "targets": { "type": "array", "items": { "$ref": "#/components/schemas/Target" }, "description": "Explicit targets for a private batch or shared chat. These have different audience semantics." }, "request": { "$ref": "#/components/schemas/AskInput", "description": "Nested requested-decision input or canonical request in a batch result." }, "preview_token": { "type": "string", "description": "Dispatch preview token. A stale audience or route requires a fresh preview." } }, "required": [ "targets", "request" ], "additionalProperties": false } } } }, "summary": "Atomic private request per explicit target", "tags": [ "communication" ] } }, "/api/v1/integrations/catalog": { "get": { "operationId": "get_api_v1_integrations_catalog", "description": "Supported providers and actual fields/capabilities only. Native inbox is built in; no planned integration is installable.\n\nAuthenticated identity with current connection/destination visibility or management authority. Sending a test also requires contact rights.\n\nReturns: Array of ProviderCapability records with required configuration fields, native reply/approval support and setup modes.\n\nRecovery: Invalid provider fields, missing verified account or disallowed URL fail validation. A stale configuration version conflicts. Provider acceptance alone does not establish a reply.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ProviderCapability" } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [], "summary": "Supported providers and actual fields/capabilities only", "tags": [ "channels" ] } }, "/api/v1/connections/{id}/diagnostics": { "get": { "operationId": "get_api_v1_connections_id_diagnostics", "description": "Non-sending credential checks and correlated diagnostic transport evidence. Configuration changes reset test evidence. Provider acceptance is distinct from attributed reply and independent live qualification.\n\nAuthenticated identity with current connection/destination visibility or management authority. Sending a test also requires contact rights.\n\nReturns: ConnectionDiagnostic with safe configuration, provider acceptance and attributed engine-observed test evidence. This read sends nothing.\n\nRecovery: Invalid provider fields, missing verified account or disallowed URL fail validation. A stale configuration version conflicts. Provider acceptance alone does not establish a reply.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionDiagnostic" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "summary": "Non-sending credential checks and correlated diagnostic transport evidence", "tags": [ "channels" ] } }, "/api/v1/connections/{id}/test": { "post": { "operationId": "post_api_v1_connections_id_test", "description": "Explicit durable test message to one configured destination only. Requires installation/destination management and Message permission. Queue acceptance is not provider acceptance. Inspect delivery evidence afterwards.\n\nAuthenticated identity with current connection/destination visibility or management authority. Sending a test also requires contact rights.\n\nReturns: Queued test Delivery. Read diagnostics and obtain an attributed native reply separately; acceptance is not receipt.\n\nRecovery: Invalid provider fields, missing verified account or disallowed URL fail validation. A stale configuration version conflicts. Provider acceptance alone does not establish a reply.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Delivery" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "destination_id": { "type": "string", "description": "One configured delivery destination to receive this explicit connection test." } }, "required": [ "destination_id" ], "additionalProperties": false } } } }, "summary": "Explicit durable test message to one configured destination only", "tags": [ "channels" ] } }, "/api/v1/requests/{id}/trace": { "get": { "operationId": "get_api_v1_requests_id_trace", "description": "Current authorized request, paged delivery evidence and execution reports. Audience members see their own projection; requesters can inspect their outgoing deliveries. Provider acceptance never proves execution.\n\nCurrent requester, authorized original decision recipient or exact bound executor, according to operation.\n\nReturns: `request` plus independently paginated `deliveries` and `executions`, with an `evidence` explanation. Continue transport pages using the supplied cursor.\n\nRecovery: Invalid outcome/choice fails validation. A stale request version or terminal-state race conflicts. Permission is rechecked at decision, redemption and reporting.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "request": { "$ref": "#/components/schemas/Request", "description": "Nested requested-decision input or canonical request in a batch result." }, "deliveries": { "type": "object", "properties": { "items": { "type": "array", "items": {}, "description": "Authorized records returned by this page." }, "next_cursor": { "type": "string", "description": "Opaque next-page cursor. Continue even when the current items array is empty." }, "order": { "type": "string", "description": "Documented ordering for this collection." } }, "required": [], "additionalProperties": false, "description": "Paginated transport evidence; continue using its own next_cursor." }, "executions": { "type": "object", "properties": { "items": { "type": "array", "items": {}, "description": "Authorized records returned by this page." }, "next_cursor": { "type": "string", "description": "Opaque next-page cursor. Continue even when the current items array is empty." }, "order": { "type": "string", "description": "Documented ordering for this collection." } }, "required": [], "additionalProperties": false, "description": "Paginated authenticated executor reports, separate from transport delivery." }, "evidence": { "type": "string", "description": "Explains transport versus executor-reported business evidence." } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "delivery_cursor", "in": "query", "schema": { "type": "string" } } ], "summary": "Current authorized request, paged delivery evidence and execution reports", "tags": [ "requests" ] } }, "/api/v1/workspace": { "get": { "operationId": "get_api_v1_workspace", "description": "Authenticated scope, company, environment, deployment kind and schema version. Managed composition supplies deployment metadata explicitly.\n\nAuthenticated caller with view/message/ask authority for the resolved recipients or current conversation history.\n\nReturns: Workspace metadata and current account-read capability.\n\nRecovery: Changed audience/preview, conflicting versions, hidden history or missing reverse contact rights reject the operation. Reuse the same saved key only for the same intended write.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "scope": { "type": "string", "description": "Selected workspace scope ID." }, "company": { "type": "string", "description": "Workspace display name." }, "environment": { "type": "string", "description": "Selected environment label." }, "can_read_account": { "type": "boolean", "description": "Whether this caller may inspect the account projection." } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [], "summary": "Authenticated scope, company, environment, deployment kind and schema version", "tags": [ "communication" ] } }, "/api/v1/workspace/account": { "get": { "operationId": "get_api_v1_workspace_account", "description": "Person-only scoped account access requires view account:workspace or an administrator credential. This entry point permits status inspection during service suspension with a still-valid credential and current account policy. Runtime-applied quotas/usage are separate from server-side managed requested/provisioning/entitlement state. No operator tokens enter the browser; managed read failures are 503, never zero usage.\n\nAuthenticated caller with view/message/ask authority for the resolved recipients or current conversation history.\n\nReturns: Current authorized account snapshot, applied limits and UTC-month usage. This OSS projection does not expose a managed payment provider.\n\nRecovery: Changed audience/preview, conflicting versions, hidden history or missing reverse contact rights reject the operation. Reuse the same saved key only for the same intended write.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "scope": { "type": "string", "description": "Selected workspace scope ID." }, "company": { "type": "string", "description": "Workspace display name." }, "environment": { "type": "string", "description": "Selected environment label." }, "can_read_account": { "type": "boolean", "description": "Whether this caller may inspect the account projection." }, "suspended": { "type": "boolean", "description": "Whether the workspace is suspended." }, "recovery_hold": { "type": "boolean", "description": "Whether restore reconciliation holds outbound work." }, "access_until": { "type": "string", "description": "Optional access cutoff.", "format": "date-time" }, "control_version": { "type": "integer", "description": "Applied control revision." }, "budget": { "type": "object", "properties": { "version": { "type": "integer", "description": "Applied budget revision." }, "messages": { "type": "integer", "description": "Monthly canonical recipient-message allowance; -1 means unlimited." }, "requests": { "type": "integer", "description": "Monthly requested-reply allowance; -1 means unlimited." }, "upload_bytes": { "type": "integer", "description": "Monthly accepted-upload byte allowance; -1 means unlimited." } }, "description": "Applied runtime budget, or null when none is configured." }, "usage": { "type": "array", "items": { "type": "object", "properties": { "period": { "type": "string", "description": "UTC month boundary.", "format": "date-time" }, "metric": { "type": "string", "description": "Counted usage category." }, "units": { "type": "integer", "description": "Recorded canonical units." } } }, "description": "Recorded usage, not provider attempts or CPU/memory." }, "metered": { "type": "boolean", "description": "Whether an applied budget is configured." }, "source": { "type": "string", "description": "applied_runtime for the OSS store; a configured account bridge may supply its own source." } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [], "summary": "Person-only scoped account access requires view account:workspace or an administrator credential", "tags": [ "communication" ] } }, "/api/v1/roles/preview": { "post": { "operationId": "post_api_v1_roles_preview", "description": "Non-saving, version-checked role-edit preview. Same rule ceiling and assignment boundaries as SaveRole; reports exact affected assignments and before/after role-grant checks for authorized subjects. Administrator credential power and new assignments are not simulated. Other assigned roles remain effective.\n\nAuthenticated identity; mutations require management authority over the relevant resource. Enrollment requires a bounded launcher or operator.\n\nReturns: `can_save`, current `version`, `affected_assignments`, before/after `checks`, `basis` and `saves=false`. This simulates existing assignments without saving or granting new ones.\n\nRecovery: Unknown/hidden identity is 404 or denied. Stale version conflicts. Delegated managers cannot create broader authority than they possess; revoked credentials cannot be used.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "can_save": { "type": "boolean", "description": "Whether current authority permits this proposal." }, "version": { "type": "integer", "description": "Current role revision." }, "affected_assignments": { "type": "array", "items": { "$ref": "#/components/schemas/Binding" }, "description": "Existing bindings affected by this role." }, "checks": { "type": "array", "items": { "type": "object", "properties": { "check": { "type": "object", "properties": { "subject_id": { "type": "string", "description": "Principal whose effective grants are simulated." }, "action": { "type": "string", "description": "Permission action." }, "target": { "$ref": "#/components/schemas/Target", "description": "Target kind and stable ID. Choose a new target or an existing conversation, not both." }, "connection_id": { "type": "string", "description": "Optional route condition." }, "action_name": { "type": "string", "description": "Optional business action name." }, "descriptor": { "$ref": "#/components/schemas/Action", "description": "Optional exact Action descriptor used to evaluate conditional permission, not an executed action." } }, "description": "The concrete subject, action, target and optional conditions being simulated." }, "before": { "type": "boolean", "description": "Current effective permission." }, "after": { "type": "boolean", "description": "Effective permission under the proposed role." } } }, "description": "Bounded permission comparisons." }, "basis": { "type": "string", "description": "effective_role_grants; administrator bypass is excluded from simulation." }, "saves": { "type": "boolean", "description": "Always false." } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "$ref": "#/components/schemas/Role", "description": "Policy role object to preview or inspect; separate from an agent_role directory group." }, "checks": { "type": "array", "items": { "type": "object", "properties": { "subject_id": { "type": "string", "description": "Identity or directory group receiving a policy-role assignment." }, "action": { "type": "string", "description": "Optional exact bound-action descriptor for the advanced execution contract." }, "target": { "type": "object", "properties": { "kind": { "type": "string", "description": "Resource or operation kind. Use one of the listed values, not a display label." }, "id": { "type": "string", "description": "Stable identifier returned by the engine. Treat it as opaque." } }, "required": [], "additionalProperties": false, "description": "Target kind and stable ID. Choose a new target or an existing conversation, not both." }, "connection_id": { "type": "string", "description": "Configured channel connection ID." }, "action_name": { "type": "string", "description": "Optional action-name constraint; not required for ordinary approval communication." }, "descriptor": { "$ref": "#/components/schemas/Action", "description": "Optional exact Action descriptor used to evaluate conditional permission, not an executed action." } }, "required": [ "subject_id", "action", "target" ], "additionalProperties": false }, "description": "Concrete subject/action/target checks for a non-saving policy-role preview." } }, "required": [ "role" ], "additionalProperties": false } } } }, "summary": "Non-saving, version-checked role-edit preview", "tags": [ "identities" ] } }, "/api/v1/appearance": { "post": { "operationId": "post_api_v1_appearance", "description": "Change an Agent or group icon from the bundled pack, or reset its default.\n\nA current manager of the target Agent or group.\n\nReturns: Target, selected icon and current group version. Appearance changes do not alter membership or permissions.\n\nRecovery: Invalid icons are rejected. A stale group revision conflicts. Other workspaces and unmanaged identities remain inaccessible.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "target": { "$ref": "#/components/schemas/Target", "description": "Target kind and stable ID. Choose a new target or an existing conversation, not both." }, "icon": { "type": "string", "description": "mark-0 through mark-11 for an Agent; role-0 through role-11 for a group. Empty resets to its default." }, "version": { "type": "integer", "description": "Current group revision. Required for an existing group." } }, "required": [ "target", "icon" ], "additionalProperties": false } } } }, "summary": "Change an Agent or group icon from the bundled pack, or reset its default", "tags": [ "identities" ] } }, "/api/v1/me": { "get": { "operationId": "get_api_v1_me", "description": "Read the authenticated identity and credential scope.\n\nAuthenticated caller with view/message/ask authority for the resolved recipients or current conversation history.\n\nReturns: `identity_type`, matching `person`/`agent`/`service`, `instance_id`, `admin`, `can_publish_answers`, `company` and `environment`. Only the matching identity-kind key is returned.\n\nRecovery: Changed audience/preview, conflicting versions, hidden history or missing reverse contact rights reject the operation. Reuse the same saved key only for the same intended write.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "identity_type": { "type": "string", "description": "person, agent or service." }, "person": { "oneOf": [ { "$ref": "#/components/schemas/Person" }, { "$ref": "#/components/schemas/Agent" }, { "$ref": "#/components/schemas/Service" } ], "description": "Person identity projection; present only for a person caller." }, "agent": { "oneOf": [ { "$ref": "#/components/schemas/Person" }, { "$ref": "#/components/schemas/Agent" }, { "$ref": "#/components/schemas/Service" } ], "description": "Stable agent external ID when enrolling; an Agent object in a Session response." }, "service": { "oneOf": [ { "$ref": "#/components/schemas/Person" }, { "$ref": "#/components/schemas/Agent" }, { "$ref": "#/components/schemas/Service" } ], "description": "Software service projection; present only for a service caller." }, "instance_id": { "type": "string", "description": "Current exact runtime ID, or empty for a non-runtime credential." }, "admin": { "type": "boolean", "description": "Whether the actual credential has administrator authority." }, "can_publish_answers": { "type": "boolean", "description": "Current answer-publication capability." }, "company": { "type": "string", "description": "Workspace display name." }, "environment": { "type": "string", "description": "Environment label." } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [], "summary": "Read the authenticated identity and credential scope", "tags": [ "communication" ] } }, "/api/v1/people/{id}/profile": { "post": { "operationId": "post_api_v1_people_id_profile", "description": "Update a person's profile information.\n\nAuthenticated identity; mutations require management authority over the relevant resource. Enrollment requires a bounded launcher or operator.\n\nReturns: Updated Person. This does not change their policy-role bindings.\n\nRecovery: Unknown/hidden identity is 404 or denied. Stale version conflicts. Delegated managers cannot create broader authority than they possess; revoked credentials cannot be used.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Person" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonInput" } } } }, "summary": "Update a person's profile information", "tags": [ "identities" ] } }, "/api/v1/sessions": { "post": { "operationId": "post_api_v1_sessions", "description": "Enroll a runtime through a bounded launcher or operator.\n\nAuthenticated identity; mutations require management authority over the relevant resource. Enrollment requires a bounded launcher or operator.\n\nReturns: Session containing a new worker token, logical Agent, exact instance_id and expires_at. The token is secret.\n\nRecovery: Unknown/hidden identity is 404 or denied. Stale version conflicts. Delegated managers cannot create broader authority than they possess; revoked credentials cannot be used.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Session" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Enrollment" } } } }, "summary": "Enroll a runtime through a bounded launcher or operator", "tags": [ "identities" ] } }, "/api/v1/agents/{id}/instances": { "get": { "operationId": "get_api_v1_agents_id_instances", "description": "Read an agent's visible runtime connections.\n\nAuthenticated identity; mutations require management authority over the relevant resource. Enrollment requires a bounded launcher or operator.\n\nReturns: Array of Instance presence/progress observations.\n\nRecovery: Unknown/hidden identity is 404 or denied. Stale version conflicts. Delegated managers cannot create broader authority than they possess; revoked credentials cannot be used.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Instance" } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "summary": "Read an agent's visible runtime connections", "tags": [ "identities" ] } }, "/api/v1/groups": { "get": { "operationId": "get_api_v1_groups", "description": "List visible directory groups.\n\nAuthenticated identity; mutations require management authority over the relevant resource. Enrollment requires a bounded launcher or operator.\n\nReturns: Group array. purpose distinguishes teams, agent roles and contact groups.\n\nRecovery: Unknown/hidden identity is 404 or denied. Stale version conflicts. Delegated managers cannot create broader authority than they possess; revoked credentials cannot be used.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Group" } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [], "summary": "List visible directory groups", "tags": [ "identities" ] }, "post": { "operationId": "post_api_v1_groups", "description": "Create or update a directory group and its members.\n\nAuthenticated identity; mutations require management authority over the relevant resource. Enrollment requires a bounded launcher or operator.\n\nReturns: Group with id and version. This does not create a shared chat.\n\nRecovery: Unknown/hidden identity is 404 or denied. Stale version conflicts. Delegated managers cannot create broader authority than they possess; revoked credentials cannot be used.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Group" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Group" } } } }, "summary": "Create or update a directory group and its members", "tags": [ "identities" ] } }, "/api/v1/roles": { "get": { "operationId": "get_api_v1_roles", "description": "List visible policy roles.\n\nAuthenticated identity; mutations require management authority over the relevant resource. Enrollment requires a bounded launcher or operator.\n\nReturns: Role array. These are permission rule sets, separate from agent roles.\n\nRecovery: Unknown/hidden identity is 404 or denied. Stale version conflicts. Delegated managers cannot create broader authority than they possess; revoked credentials cannot be used.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Role" } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [], "summary": "List visible policy roles", "tags": [ "identities" ] }, "post": { "operationId": "post_api_v1_roles", "description": "Create or version-update a policy role.\n\nAuthenticated identity; mutations require management authority over the relevant resource. Enrollment requires a bounded launcher or operator.\n\nReturns: Saved Role. Delegated managers cannot grant authority beyond their own ceiling.\n\nRecovery: Unknown/hidden identity is 404 or denied. Stale version conflicts. Delegated managers cannot create broader authority than they possess; revoked credentials cannot be used.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Role" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Role" } } } }, "summary": "Create or version-update a policy role", "tags": [ "identities" ] } }, "/api/v1/role-bindings": { "get": { "operationId": "get_api_v1_role_bindings", "description": "Read visible individual and group role assignments.\n\nAuthenticated identity; mutations require management authority over the relevant resource. Enrollment requires a bounded launcher or operator.\n\nReturns: Binding array.\n\nRecovery: Unknown/hidden identity is 404 or denied. Stale version conflicts. Delegated managers cannot create broader authority than they possess; revoked credentials cannot be used.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Binding" } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [], "summary": "Read visible individual and group role assignments", "tags": [ "identities" ] }, "post": { "operationId": "post_api_v1_role_bindings", "description": "Add or remove a policy-role assignment.\n\nAuthenticated identity; mutations require management authority over the relevant resource. Enrollment requires a bounded launcher or operator.\n\nReturns: `{ok: true}` after the authorized change commits. This acknowledgment does not contain an updated resource or prove business execution.\n\nRecovery: Unknown/hidden identity is 404 or denied. Stale version conflicts. Delegated managers cannot create broader authority than they possess; revoked credentials cannot be used.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "description": "True after the operation succeeds." } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Binding" } } } }, "summary": "Add or remove a policy-role assignment", "tags": [ "identities" ] } }, "/api/v1/connections": { "get": { "operationId": "get_api_v1_connections", "description": "List visible provider connections.\n\nAuthenticated identity with current connection/destination visibility or management authority. Sending a test also requires contact rights.\n\nReturns: Safe Connection array; provider secrets are not returned.\n\nRecovery: Invalid provider fields, missing verified account or disallowed URL fail validation. A stale configuration version conflicts. Provider acceptance alone does not establish a reply.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Connection" } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [], "summary": "List visible provider connections", "tags": [ "channels" ] }, "post": { "operationId": "post_api_v1_connections", "description": "Create or version-update a channel connection.\n\nAuthenticated identity with current connection/destination visibility or management authority. Sending a test also requires contact rights.\n\nReturns: Saved Connection with secret_configured, not the secret value.\n\nRecovery: Invalid provider fields, missing verified account or disallowed URL fail validation. A stale configuration version conflicts. Provider acceptance alone does not establish a reply.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Connection" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Connection" } } } }, "summary": "Create or version-update a channel connection", "tags": [ "channels" ] } }, "/api/v1/destinations": { "get": { "operationId": "get_api_v1_destinations", "description": "Read visible identity delivery destinations.\n\nAuthenticated identity with current connection/destination visibility or management authority. Sending a test also requires contact rights.\n\nReturns: Destination array with connection, address, mode and priority.\n\nRecovery: Invalid provider fields, missing verified account or disallowed URL fail validation. A stale configuration version conflicts. Provider acceptance alone does not establish a reply.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Destination" } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [], "summary": "Read visible identity delivery destinations", "tags": [ "channels" ] }, "post": { "operationId": "post_api_v1_destinations", "description": "Create or version-update a linked identity's channel destination.\n\nAuthenticated identity with current connection/destination visibility or management authority. Sending a test also requires contact rights.\n\nReturns: Saved Destination. A destination does not grant contact permission.\n\nRecovery: Invalid provider fields, missing verified account or disallowed URL fail validation. A stale configuration version conflicts. Provider acceptance alone does not establish a reply.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Destination" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Destination" } } } }, "summary": "Create or version-update a linked identity's channel destination", "tags": [ "channels" ] } }, "/api/v1/destinations/{id}/remove": { "post": { "operationId": "post_api_v1_destinations_id_remove", "description": "Remove a channel destination.\n\nAuthenticated identity with current connection/destination visibility or management authority. Sending a test also requires contact rights.\n\nReturns: `{removed: true}` after the authorized change commits. This acknowledgment does not contain an updated resource or prove business execution.\n\nRecovery: Invalid provider fields, missing verified account or disallowed URL fail validation. A stale configuration version conflicts. Provider acceptance alone does not establish a reply.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "removed": { "type": "boolean", "description": "True after the operation succeeds." } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false } } } }, "summary": "Remove a channel destination", "tags": [ "channels" ] } }, "/api/v1/people/{id}/delivery-preferences": { "get": { "operationId": "get_api_v1_people_id_delivery_preferences", "description": "Read recipient channel defaults and ordered Agent/Agent role overrides.\n\nPerson self, administrator or an explicitly authorized identity manager. Preferences never grant contact or channel authority.\n\nReturns: DeliveryPreferences with its current version; null default retains legacy destination settings.\n\nRecovery: Forbidden for another Person without management authority; stale versions conflict. Invalid selectors, foreign destinations and invalid timer bounds fail validation.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryPreferences" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "summary": "Read recipient channel defaults and ordered Agent/Agent role overrides", "tags": [ "Channels" ] }, "post": { "operationId": "post_api_v1_people_id_delivery_preferences", "description": "Save versioned recipient channel preferences. Individual Agent overrides win, then the first matching Agent role, then default. Preferred channels fail over on definite failure and optionally on an unresolved question/approval timer after provider acceptance. All sends selected channels immediately. Empty destinations means workspace only. Saving cancels pending external sends from the previous configuration; in-flight effects cannot be recalled.\n\nPerson self, administrator or an explicitly authorized identity manager. Preferences never grant contact or channel authority.\n\nReturns: Saved DeliveryPreferences with the incremented version.\n\nRecovery: Forbidden for another Person without management authority; stale versions conflict. Invalid selectors, foreign destinations and invalid timer bounds fail validation.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryPreferences" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryPreferences" } } } }, "summary": "Save versioned recipient channel preferences", "tags": [ "Channels" ] } }, "/api/v1/credentials": { "get": { "operationId": "get_api_v1_credentials", "description": "List credential metadata visible to the operator.\n\nAuthenticated identity; mutations require management authority over the relevant resource. Enrollment requires a bounded launcher or operator.\n\nReturns: Metadata array with expiry/revocation state; no recoverable plaintext tokens.\n\nRecovery: Unknown/hidden identity is 404 or denied. Stale version conflicts. Delegated managers cannot create broader authority than they possess; revoked credentials cannot be used.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Credential" } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [], "summary": "List credential metadata visible to the operator", "tags": [ "identities" ] }, "post": { "operationId": "post_api_v1_credentials", "description": "Issue a named API or namespace-restricted enrollment token with an optional expiry and API permission ceiling. Defaults to 30 days.\n\nAuthenticated identity; mutations require management authority over the relevant resource. Enrollment requires a bounded launcher or operator.\n\nReturns: Token secret once with id, kind and expires_at. Metadata listing never recovers plaintext.\n\nRecovery: Unknown/hidden identity is 404 or denied. Stale version conflicts. Delegated managers cannot create broader authority than they possess; revoked credentials cannot be used.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "New credential ID." }, "token": { "type": "string", "description": "One-time secret; save in a protected credential file." }, "kind": { "type": "string", "description": "Issued credential kind: api or enrollment." } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "principal_id": { "type": "string", "description": "Person, agent or service identity ID. This is an API term, not a separate product entity." }, "kind": { "enum": [ "api", "enrollment" ], "description": "Resource or operation kind. Use one of the listed values, not a display label." }, "prefix": { "type": "string", "description": "Permitted enrollment namespace prefix for a bounded launcher." }, "name": { "type": "string", "description": "Human-readable name. It is not necessarily unique." }, "never_expires": { "type": "boolean", "default": false, "description": "Explicitly request a non-expiring credential. Cannot be combined with an expiry or renewable worker lease." }, "expires_at": { "type": "string", "format": "date-time", "description": "Expiry timestamp. Ordinary communication has no implicit deadline (represented as 9999-01-01T00:00:00Z). Bound action approvals default to seven days; explicit expiry must be within ninety days. Local wait timeout never changes it." }, "permissions": { "type": "array", "items": { "enum": [ "read", "message", "request", "respond", "execute", "manage" ] }, "description": "Optional credential-specific restriction to read, message, request, respond, execute or manage. Underlying identity permissions still apply." } }, "required": [ "principal_id", "kind" ], "additionalProperties": false } } } }, "summary": "Issue a named API or namespace-restricted enrollment token with an optional expiry and API permission ceiling", "tags": [ "identities" ] } }, "/api/v1/credentials/{id}/revoke": { "post": { "operationId": "post_api_v1_credentials_id_revoke", "description": "Revoke this exact credential, including its rotation overlap. An enrollment token may explicitly revoke_workers to stop connections it issued after lineage tracking was introduced.\n\nAuthenticated identity; mutations require management authority over the relevant resource. Enrollment requires a bounded launcher or operator.\n\nReturns: `{revoked: true}` after the authorized change commits. This acknowledgment does not contain an updated resource or prove business execution.\n\nRecovery: Unknown/hidden identity is 404 or denied. Stale version conflicts. Delegated managers cannot create broader authority than they possess; revoked credentials cannot be used.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "revoked": { "type": "boolean", "description": "True after the operation succeeds." } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "revoke_workers": { "type": "boolean", "default": false, "description": "Also revoke worker credentials enrolled through this credential." } }, "required": [], "additionalProperties": false } } } }, "summary": "Revoke this exact credential, including its rotation overlap", "tags": [ "identities" ] } }, "/api/v1/credentials/{id}/edit": { "post": { "operationId": "post_api_v1_credentials_id_edit", "description": "Rename a token, change expiry or update its permission ceiling using the observed version.\n\nAuthorized credential manager, or the current worker for self-renewal. Token limits never grant identity permissions.\n\nReturns: Current metadata with the next version. Never returns the secret.\n\nRecovery: Stale versions conflict. Expired or revoked tokens cannot renew or rotate. Restricted tokens cannot mint or broaden credentials.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Credential" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "integer", "description": "Current optimistic-concurrency version. Read the object before a guarded change; a stale version conflicts." }, "name": { "type": "string", "description": "Human-readable name. It is not necessarily unique." }, "never_expires": { "type": "boolean", "description": "Explicitly request a non-expiring credential. Cannot be combined with an expiry or renewable worker lease." }, "expires_at": { "type": "string", "format": "date-time", "description": "Expiry timestamp. Ordinary communication has no implicit deadline (represented as 9999-01-01T00:00:00Z). Bound action approvals default to seven days; explicit expiry must be within ninety days. Local wait timeout never changes it." }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "Optional credential-specific restriction to read, message, request, respond, execute or manage. Underlying identity permissions still apply." }, "clear_permissions": { "type": "boolean", "description": "Remove the credential-specific permission restriction. This does not grant permissions absent from the underlying identity." } }, "required": [ "version" ], "additionalProperties": false } } } }, "summary": "Rename a token, change expiry or update its permission ceiling using the observed version", "tags": [ "identities" ] } }, "/api/v1/credentials/{id}/rotate": { "post": { "operationId": "post_api_v1_credentials_id_rotate", "description": "Replace a token secret while preserving its identity, instance and permissions. Choose a zero to 86400 second overlap.\n\nAuthorized credential manager, or the current worker for self-renewal. Token limits never grant identity permissions.\n\nReturns: New token secret once, plus metadata including previous_until. No automatic retry after an uncertain outcome.\n\nRecovery: Stale versions conflict. Expired or revoked tokens cannot renew or rotate. Restricted tokens cannot mint or broaden credentials.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CredentialReplacement" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "integer", "description": "Current optimistic-concurrency version. Read the object before a guarded change; a stale version conflicts." }, "overlap_seconds": { "type": "integer", "minimum": 0, "maximum": 86400, "default": 3600, "description": "How long the previous token remains usable after rotation, from zero to 86400 seconds. Defaults to 3600." } }, "required": [ "version" ], "additionalProperties": false } } } }, "summary": "Replace a token secret while preserving its identity, instance and permissions", "tags": [ "identities" ] } }, "/api/v1/credentials/self/renew": { "post": { "operationId": "post_api_v1_credentials_self_renew", "description": "Renew the current renewable worker lease, capped by its hard deadline. Active traffic renews near expiry automatically.\n\nAuthorized credential manager, or the current worker for self-renewal. Token limits never grant identity permissions.\n\nReturns: Current credential metadata. No new instance or secret is created.\n\nRecovery: Stale versions conflict. Expired or revoked tokens cannot renew or rotate. Restricted tokens cannot mint or broaden credentials.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Credential" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false } } } }, "summary": "Renew the current renewable worker lease, capped by its hard deadline", "tags": [ "identities" ] } }, "/api/v1/permissions/explain": { "post": { "operationId": "post_api_v1_permissions_explain", "description": "Explain the current decision for a subject, action and target.\n\nAuthenticated caller with view/message/ask authority for the resolved recipients or current conversation history.\n\nReturns: Allowed/denied projection and the applicable authorization basis.\n\nRecovery: Changed audience/preview, conflicting versions, hidden history or missing reverse contact rights reject the operation. Reuse the same saved key only for the same intended write.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "subject_id": { "type": "string", "description": "Identity or directory group receiving a policy-role assignment." }, "action": { "type": "string", "description": "Optional exact bound-action descriptor for the advanced execution contract." }, "target": { "type": "object", "properties": { "kind": { "type": "string", "description": "Resource or operation kind. Use one of the listed values, not a display label." }, "id": { "type": "string", "description": "Stable identifier returned by the engine. Treat it as opaque." } }, "required": [ "kind", "id" ], "additionalProperties": false, "description": "Target kind and stable ID. Choose a new target or an existing conversation, not both." }, "connection_id": { "type": "string", "description": "Configured channel connection ID." }, "action_name": { "type": "string", "description": "Optional action-name constraint; not required for ordinary approval communication." }, "descriptor": { "$ref": "#/components/schemas/Action", "description": "Optional exact Action descriptor used to evaluate conditional permission, not an executed action." } }, "required": [ "action", "target" ], "additionalProperties": false } } } }, "summary": "Explain the current decision for a subject, action and target", "tags": [ "communication" ] } }, "/api/v1/route-preview": { "post": { "operationId": "post_api_v1_route_preview", "description": "Inspect eligible delivery routes without sending.\n\nAuthenticated identity with current connection/destination visibility or management authority. Sending a test also requires contact rights.\n\nReturns: `recipients`, total `count`, `hidden_recipients`, `mode=private_per_recipient` and `sends=false`. This preview has no dispatch token.\n\nRecovery: Invalid provider fields, missing verified account or disallowed URL fail validation. A stale configuration version conflicts. Provider acceptance alone does not establish a reply.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "recipients": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/Person" }, { "$ref": "#/components/schemas/Agent" }, { "$ref": "#/components/schemas/Service" } ] }, "description": "Visible resolved recipients." }, "count": { "type": "integer", "description": "Total eligible recipients." }, "hidden_recipients": { "type": "integer", "description": "Eligible recipients whose metadata is hidden." }, "mode": { "type": "string", "description": "private_per_recipient." }, "sends": { "type": "boolean", "description": "Always false." } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "target": { "$ref": "#/components/schemas/Target", "description": "Target kind and stable ID. Choose a new target or an existing conversation, not both." }, "action": { "type": "string", "description": "Communication action to inspect, for example message or ask; not a bound business Action descriptor." } }, "required": [ "target", "action" ], "additionalProperties": false } } } }, "summary": "Inspect eligible delivery routes without sending", "tags": [ "channels" ] } }, "/api/v1/conversations": { "post": { "operationId": "post_api_v1_conversations", "description": "Start an explicit shared chat with a durable first message. Individual recipients only; all members must have current mutual view permission. Every later send checks current contact access. Idempotent; private broadcast contracts are unchanged.\n\nAuthenticated caller with view/message/ask authority for the resolved recipients or current conversation history.\n\nReturns: SendResult containing the new shared conversation_id and canonical first messages.\n\nRecovery: Changed audience/preview, conflicting versions, hidden history or missing reverse contact rights reject the operation. Reuse the same saved key only for the same intended write.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendResult" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "targets": { "type": "array", "items": { "$ref": "#/components/schemas/Target" }, "description": "Explicit targets for a private batch or shared chat. These have different audience semantics." }, "body": { "type": "string", "description": "Message or request content, bounded to 32 KiB of UTF-8 bytes." }, "title": { "type": "string", "description": "Optional short label. A normal message does not require a title." }, "approval": { "type": "boolean", "description": "Attach a typed approval request to the initial shared chat message. False by default." }, "choices": { "type": "array", "items": { "type": "string" }, "description": "Optional exact answer strings. A chosen answer must match an offered value." }, "mentions": { "type": "array", "items": { "$ref": "#/components/schemas/Mention" }, "maxItems": 20, "description": "Addressing metadata for existing chat participants. It does not narrow audience or grant authority." }, "attachment_ids": { "type": "array", "items": { "type": "string" }, "maxItems": 5, "uniqueItems": true, "description": "IDs of staged private drafts to claim in the initial operation; at most five." } }, "required": [ "targets", "body" ], "additionalProperties": false } } } }, "summary": "Start an explicit shared chat with a durable first message", "tags": [ "communication" ] }, "get": { "operationId": "get_api_v1_conversations", "description": "Read visible conversation summaries in recent-activity order.\n\nAuthenticated caller with view/message/ask authority for the resolved recipients or current conversation history.\n\nReturns: Conversation array. Use query for bounded complete pagination.\n\nRecovery: Changed audience/preview, conflicting versions, hidden history or missing reverse contact rights reject the operation. Reuse the same saved key only for the same intended write.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Conversation" } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [], "summary": "Read visible conversation summaries in recent-activity order", "tags": [ "communication" ] } }, "/api/v1/contact-permissions/preview": { "post": { "operationId": "post_api_v1_contact_permissions_preview", "description": "Preview current contact permissions or a proposed versioned edit without saving. Explicit blocks override matching role grants.\n\nThe subject, an authorized access inspector or the administrator. Proposed edits require current management and assignment authority.\n\nReturns: The current direct policy, effective action cells and sources for up to 100 contacts, warnings and save eligibility.\n\nRecovery: Reload on version conflict. Visibility and assignment authority remain separate. A preview is never a grant.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "subject": { "$ref": "#/components/schemas/Target", "description": "Authorized subject projection of the access inspection." }, "rules": { "type": "array", "items": { "$ref": "#/components/schemas/Rule" }, "description": "Directional permission rules granted by this policy role." }, "version": { "type": "integer", "description": "Current optimistic-concurrency version. Read the object before a guarded change; a stale version conflicts." }, "targets": { "type": "array", "items": { "$ref": "#/components/schemas/Target" }, "maxItems": 100, "description": "Explicit targets for a private batch or shared chat. These have different audience semantics." } }, "required": [ "subject" ], "additionalProperties": false } } } }, "summary": "Preview current contact permissions or a proposed versioned edit without saving", "tags": [ "Permissions" ] } }, "/api/v1/contact-permissions": { "post": { "operationId": "post_api_v1_contact_permissions", "description": "Atomically save and assign a dedicated contact-access policy. Only view, message, ask and decide toward exact contacts. Existing delegation ceilings and observed-version checks apply. Inherited policies remain effective.\n\nAuthenticated caller with view/message/ask authority for the resolved recipients or current conversation history.\n\nReturns: The saved Role containing the chosen directional contact rules. Chat membership is separate.\n\nRecovery: Changed audience/preview, conflicting versions, hidden history or missing reverse contact rights reject the operation. Reuse the same saved key only for the same intended write.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Role" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "subject": { "$ref": "#/components/schemas/Target", "description": "Authorized subject projection of the access inspection." }, "rules": { "type": "array", "items": { "$ref": "#/components/schemas/Rule" }, "description": "Directional permission rules granted by this policy role." }, "version": { "type": "integer", "description": "Current optimistic-concurrency version. Read the object before a guarded change; a stale version conflicts." } }, "required": [ "subject", "rules", "version" ], "additionalProperties": false } } } }, "summary": "Atomically save and assign a dedicated contact-access policy", "tags": [ "communication" ] } }, "/api/v1/conversations/{id}/membership": { "post": { "operationId": "post_api_v1_conversations_id_membership", "description": "Versioned and idempotent shared-chat membership. Manager or admin can rename/add/remove; members can leave. New members see history from joining unless share_history is explicitly true. Current mutual View is required; membership grants no contact, decision or tool authority. Removing or leaving stops future read and delivery; already downloaded data cannot be recalled. A departing manager names an existing successor.\n\nAuthenticated caller with view/message/ask authority for the resolved recipients or current conversation history.\n\nReturns: conversation_id and new version, with left=true when the caller leaves.\n\nRecovery: Changed audience/preview, conflicting versions, hidden history or missing reverse contact rights reject the operation. Reuse the same saved key only for the same intended write.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "conversation_id": { "type": "string", "description": "Canonical conversation ID. Use it to continue the same authorized history." }, "version": { "type": "integer", "description": "Current optimistic-concurrency version. Read the object before a guarded change; a stale version conflicts." }, "left": { "type": "boolean", "description": "True when the membership operation removed the caller from the shared conversation." } }, "required": [], "additionalProperties": false } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "operation": { "enum": [ "rename", "add", "remove", "leave" ], "description": "Requested operation, with values defined by that endpoint." }, "version": { "type": "integer", "minimum": 1, "description": "Current optimistic-concurrency version. Read the object before a guarded change; a stale version conflicts." }, "title": { "type": "string", "description": "Optional short label. A normal message does not require a title." }, "members": { "type": "array", "items": { "type": "string" }, "maxItems": 100, "uniqueItems": true, "description": "Directory-group or chat member identity IDs. Membership never substitutes for contact authority." }, "share_history": { "type": "boolean", "default": false, "description": "Explicitly disclose earlier history to additions. False by default." }, "next_manager": { "type": "string", "description": "Existing participant to manage the chat when the current manager leaves." } }, "required": [ "operation", "version" ], "additionalProperties": false } } } }, "summary": "Versioned and idempotent shared-chat membership", "tags": [ "communication" ] } }, "/api/v1/conversations/{id}": { "get": { "operationId": "get_api_v1_conversations_id", "description": "Read a conversation's currently disclosed history.\n\nAuthenticated caller with view/message/ask authority for the resolved recipients or current conversation history.\n\nReturns: Conversation with participants, messages and shared membership metadata.\n\nRecovery: Changed audience/preview, conflicting versions, hidden history or missing reverse contact rights reject the operation. Reuse the same saved key only for the same intended write.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conversation" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "summary": "Read a conversation's currently disclosed history", "tags": [ "communication" ] } }, "/api/v1/messages": { "post": { "operationId": "post_api_v1_messages", "description": "Durably store canonical messages and queue deliveries. Prefer: return=minimal returns a compact acceptance receipt; it is not delivery or execution confirmation. Replay the same input and idempotency key without Prefer to retrieve the full result without resending.\n\nAuthenticated caller with view/message/ask authority for the resolved recipients or current conversation history.\n\nReturns: SendResult containing conversation_id and messages, or SendReceipt containing conversation_id and message_count when Prefer: return=minimal is requested.\n\nRecovery: Changed audience/preview, conflicting versions, hidden history or missing reverse contact rights reject the operation. Reuse the same saved key only for the same intended write.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/SendResult" }, { "$ref": "#/components/schemas/SendReceipt" } ] } } }, "headers": { "Preference-Applied": { "schema": { "type": "string" }, "description": "return=minimal when requested and applied." } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "Prefer", "in": "header", "schema": { "type": "string" }, "description": "Optional return=minimal; full SendResult remains the default." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendInput" } } } }, "summary": "Durably store canonical messages and queue deliveries", "tags": [ "communication" ] } }, "/api/v1/requests": { "get": { "operationId": "get_api_v1_requests", "description": "List requests visible to the caller.\n\nCurrent requester, authorized original decision recipient or exact bound executor, according to operation.\n\nReturns: Request array. Use query to filter/page; visibility is not the same as being the requester.\n\nRecovery: Invalid outcome/choice fails validation. A stale request version or terminal-state race conflicts. Permission is rechecked at decision, redemption and reporting.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Request" } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [], "summary": "List requests visible to the caller", "tags": [ "requests" ] }, "post": { "operationId": "post_api_v1_requests", "description": "Open a question, approval or task with a saved final response.\n\nCurrent requester, authorized original decision recipient or exact bound executor, according to operation.\n\nReturns: Request with state=open and current version. Ordinary communication has no implicit deadline; bound action approvals default to seven days when expiry is omitted.\n\nRecovery: Invalid outcome/choice fails validation. A stale request version or terminal-state race conflicts. Permission is rechecked at decision, redemption and reporting.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Request" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AskInput" } } } }, "summary": "Open a question, approval or task with a saved final response", "tags": [ "requests" ] } }, "/api/v1/requests/{id}": { "get": { "operationId": "get_api_v1_requests_id", "description": "Read a visible request and its current decision.\n\nCurrent requester, authorized original decision recipient or exact bound executor, according to operation.\n\nReturns: Request with optional response. Terminal state must be inspected explicitly.\n\nRecovery: Invalid outcome/choice fails validation. A stale request version or terminal-state race conflicts. Permission is rechecked at decision, redemption and reporting.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Request" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "summary": "Read a visible request and its current decision", "tags": [ "requests" ] } }, "/api/v1/requests/{id}/responses": { "post": { "operationId": "post_api_v1_requests_id_responses", "description": "Record an eligible typed final decision.\n\nCurrent requester, authorized original decision recipient or exact bound executor, according to operation.\n\nReturns: Updated Request. Sending ordinary conversation text never records this decision.\n\nRecovery: Invalid outcome/choice fails validation. A stale request version or terminal-state race conflicts. Permission is rechecked at decision, redemption and reporting.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Request" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseInput" } } } }, "summary": "Record an eligible typed final decision", "tags": [ "requests" ] } }, "/api/v1/requests/{id}/answer-and-share": { "post": { "operationId": "post_api_v1_requests_id_answer_and_share", "description": "Answer a question and publish authorized reusable information atomically.\n\nCurrent requester, authorized original decision recipient or exact bound executor, according to operation.\n\nReturns: Resolved Request and published answer information. Only informational question answers can be reused.\n\nRecovery: Invalid outcome/choice fails validation. A stale request version or terminal-state race conflicts. Permission is rechecked at decision, redemption and reporting.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Request" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "outcome": { "const": "answered", "description": "Typed final result: answered; approved/denied; or completed/failed/rejected according to request kind." }, "answer": { "description": "JSON response value; for choices, the selected exact string." }, "version": { "type": "integer", "description": "Current optimistic-concurrency version. Read the object before a guarded change; a stale version conflicts." }, "audience": { "type": "array", "items": { "type": "string" }, "description": "Explicit identities allowed to reuse the published informational answer." } }, "required": [ "outcome", "answer", "version", "audience" ], "additionalProperties": false } } } }, "summary": "Answer a question and publish authorized reusable information atomically", "tags": [ "requests" ] } }, "/api/v1/requests/{id}/replace": { "post": { "operationId": "post_api_v1_requests_id_replace", "description": "Atomically supersede your pending request and create its replacement.\n\nCurrent requester, authorized original decision recipient or exact bound executor, according to operation.\n\nReturns: Object with previous and replacement Request records. Continue using replacement.id.\n\nRecovery: Invalid outcome/choice fails validation. A stale request version or terminal-state race conflicts. Permission is rechecked at decision, redemption and reporting.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "previous": { "$ref": "#/components/schemas/Request", "description": "Original request after supersession." }, "replacement": { "$ref": "#/components/schemas/Request", "description": "New pending request; future decisions use this ID." } }, "required": [ "previous", "replacement" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "integer", "description": "Current optimistic-concurrency version. Read the object before a guarded change; a stale version conflicts." }, "body": { "type": "string", "minLength": 1, "maxLength": 32768, "description": "Message or request content, bounded to 32 KiB of UTF-8 bytes." }, "mentions": { "type": "array", "items": { "$ref": "#/components/schemas/Mention" }, "maxItems": 20, "description": "Addressing metadata for existing chat participants. It does not narrow audience or grant authority." } }, "required": [ "version", "body" ], "additionalProperties": false } } } }, "summary": "Atomically supersede your pending request and create its replacement", "tags": [ "requests" ] } }, "/api/v1/requests/{id}/cancel": { "post": { "operationId": "post_api_v1_requests_id_cancel", "description": "Withdraw your own pending request at its current version.\n\nCurrent requester, authorized original decision recipient or exact bound executor, according to operation.\n\nReturns: Request with state=cancelled. Does not undo an external effect.\n\nRecovery: Invalid outcome/choice fails validation. A stale request version or terminal-state race conflicts. Permission is rechecked at decision, redemption and reporting.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Request" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "integer", "description": "Current optimistic-concurrency version. Read the object before a guarded change; a stale version conflicts." } }, "required": [ "version" ], "additionalProperties": false } } } }, "summary": "Withdraw your own pending request at its current version", "tags": [ "requests" ] } }, "/api/v1/requests/{id}/supersede": { "post": { "operationId": "post_api_v1_requests_id_supersede", "description": "Mark your pending request as superseded.\n\nCurrent requester, authorized original decision recipient or exact bound executor, according to operation.\n\nReturns: Request with state=superseded; this does not create a replacement. Use replace to create a revised request atomically.\n\nRecovery: Invalid outcome/choice fails validation. A stale request version or terminal-state race conflicts. Permission is rechecked at decision, redemption and reporting.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Request" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "integer", "description": "Current optimistic-concurrency version. Read the object before a guarded change; a stale version conflicts." } }, "required": [ "version" ], "additionalProperties": false } } } }, "summary": "Mark your pending request as superseded", "tags": [ "requests" ] } }, "/api/v1/requests/{id}/redeem": { "post": { "operationId": "post_api_v1_requests_id_redeem", "description": "Redeem an exact bound approval for its declared executor/action.\n\nCurrent requester, authorized original decision recipient or exact bound executor, according to operation.\n\nReturns: Execution intent. The external resource owner still enforces execution and idempotency fences.\n\nRecovery: Invalid outcome/choice fails validation. A stale request version or terminal-state race conflicts. Permission is rechecked at decision, redemption and reporting.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Execution" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Action" } } } }, "summary": "Redeem an exact bound approval for its declared executor/action", "tags": [ "requests" ] } }, "/api/v1/executions": { "get": { "operationId": "get_api_v1_executions", "description": "Read currently visible execution observations.\n\nCurrent requester, authorized original decision recipient or exact bound executor, according to operation.\n\nReturns: Execution array; worker-reported state is not independent verification.\n\nRecovery: Invalid outcome/choice fails validation. A stale request version or terminal-state race conflicts. Permission is rechecked at decision, redemption and reporting.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Execution" } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [], "summary": "Read currently visible execution observations", "tags": [ "requests" ] } }, "/api/v1/executions/{id}": { "post": { "operationId": "post_api_v1_executions_id", "description": "Record an authorized executor's observed outcome.\n\nCurrent requester, authorized original decision recipient or exact bound executor, according to operation.\n\nReturns: Updated Execution; terminal results cannot be overwritten.\n\nRecovery: Invalid outcome/choice fails validation. A stale request version or terminal-state race conflicts. Permission is rechecked at decision, redemption and reporting.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Execution" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "state": { "enum": [ "running", "succeeded", "failed", "unknown" ], "description": "Lifecycle state. Read the resource-specific enum; request and execution states differ." }, "result": { "description": "Executor-reported JSON result. It is not independent proof of an external effect." } }, "required": [ "state" ], "additionalProperties": false } } } }, "summary": "Record an authorized executor's observed outcome", "tags": [ "requests" ] } }, "/api/v1/worker/inbox": { "get": { "operationId": "get_api_v1_worker_inbox", "description": "Lease pending deliveries for this worker instance.\n\nCurrent worker for inbox/heartbeat/ack; currently authorized caller for event and delivery projections. Activity is administrative.\n\nReturns: Delivery array containing canonical payload, id and lease generation.\n\nRecovery: Expired delivery leases reject stale generations. Revoked credentials or policy denial terminate streams. Delivery retry is blocked when a safe repeat cannot be established.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Delivery" } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "wait_ms", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 20000 } }, { "name": "wait_ms", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 20000, "default": 0 }, "description": "Optional long-poll wait in milliseconds." } ], "summary": "Lease pending deliveries for this worker instance", "tags": [ "workers" ] } }, "/api/v1/worker/heartbeat": { "post": { "operationId": "post_api_v1_worker_heartbeat", "description": "Refresh this runtime's presence with optional progress metadata.\n\nCurrent worker for inbox/heartbeat/ack; currently authorized caller for event and delivery projections. Activity is administrative.\n\nReturns: `{ok: true}` after the authorized change commits. This acknowledgment does not contain an updated resource or prove business execution.\n\nRecovery: Expired delivery leases reject stale generations. Revoked credentials or policy denial terminate streams. Delivery retry is blocked when a safe repeat cannot be established.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "description": "True after the operation succeeds." } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "summary": "Refresh this runtime's presence with optional progress metadata", "tags": [ "workers" ] } }, "/api/v1/worker/inbox/{id}/ack": { "post": { "operationId": "post_api_v1_worker_inbox_id_ack", "description": "Acknowledge safe handling of the current delivery lease.\n\nCurrent worker for inbox/heartbeat/ack; currently authorized caller for event and delivery projections. Activity is administrative.\n\nReturns: `{received: true}` after the authorized change commits. This acknowledgment does not contain an updated resource or prove business execution.\n\nRecovery: Expired delivery leases reject stale generations. Revoked credentials or policy denial terminate streams. Delivery retry is blocked when a safe repeat cannot be established.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "received": { "type": "boolean", "description": "True after the operation succeeds." } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "generation": { "type": "integer", "description": "Current inbox lease generation. Ack must echo this generation." } }, "required": [ "generation" ], "additionalProperties": false } } } }, "summary": "Acknowledge safe handling of the current delivery lease", "tags": [ "workers" ] } }, "/api/v1/deliveries": { "get": { "operationId": "get_api_v1_deliveries", "description": "Read authorized transport delivery evidence.\n\nCurrent worker for inbox/heartbeat/ack; currently authorized caller for event and delivery projections. Activity is administrative.\n\nReturns: Delivery array with current state and attempts.\n\nRecovery: Expired delivery leases reject stale generations. Revoked credentials or policy denial terminate streams. Delivery retry is blocked when a safe repeat cannot be established.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Delivery" } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [], "summary": "Read authorized transport delivery evidence", "tags": [ "workers" ] } }, "/api/v1/deliveries/{id}/retry": { "post": { "operationId": "post_api_v1_deliveries_id_retry", "description": "Request an authorized retry of a safely retryable failed delivery.\n\nCurrent worker for inbox/heartbeat/ack; currently authorized caller for event and delivery projections. Activity is administrative.\n\nReturns: `{queued: true}` after the authorized change commits. This acknowledgment does not contain an updated resource or prove business execution.\n\nRecovery: Expired delivery leases reject stale generations. Revoked credentials or policy denial terminate streams. Delivery retry is blocked when a safe repeat cannot be established.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "queued": { "type": "boolean", "description": "True after the operation succeeds." } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false } } } }, "summary": "Request an authorized retry of a safely retryable failed delivery", "tags": [ "workers" ] } }, "/api/v1/events": { "get": { "operationId": "get_api_v1_events", "description": "Read canonical authorized events after a sequence, or follow them as an SSE stream.\n\nCurrent worker for inbox/heartbeat/ack; currently authorized caller for event and delivery projections. Activity is administrative.\n\nReturns: JSON event page when stream is omitted; text/event-stream when stream=1. Summary mode omits full payload bodies.\n\nRecovery: Expired delivery leases reject stale generations. Revoked credentials or policy denial terminate streams. Delivery retry is blocked when a safe repeat cannot be established.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } } }, "text/event-stream": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "after", "in": "query", "schema": { "type": "integer", "minimum": 0 } }, { "name": "stream", "in": "query", "schema": { "enum": [ "0", "1" ] } }, { "name": "summary", "in": "query", "description": "With stream=1, summary=1 omits event data while preserving current authorization, metadata and replay cursors. Full events remain the default.", "schema": { "enum": [ "0", "1" ] } }, { "name": "conversation_id", "in": "query", "schema": { "type": "string" }, "description": "Optional conversation filter for stream=1 and summary=1; does not narrow the full-payload stream." } ], "summary": "Read canonical authorized events after a sequence, or follow them as an SSE stream", "tags": [ "workers" ] } }, "/api/v1/activity": { "get": { "operationId": "get_api_v1_activity", "description": "Read administrative activity evidence.\n\nCurrent worker for inbox/heartbeat/ack; currently authorized caller for event and delivery projections. Activity is administrative.\n\nReturns: Authorized event/activity records. This is not a model execution tracing system.\n\nRecovery: Expired delivery leases reject stale generations. Revoked credentials or policy denial terminate streams. Delivery retry is blocked when a safe repeat cannot be established.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [], "summary": "Read administrative activity evidence", "tags": [ "workers" ] } }, "/api/v1/answers": { "get": { "operationId": "get_api_v1_answers", "description": "Find currently usable published informational answers.\n\nCurrent authorized reader, or publisher with manage answer authority. Reuse requires audience membership and current source/publisher authority.\n\nReturns: SharedAnswer array filtered by current source/publisher authority, audience and validity.\n\nRecovery: Expired, invalidated or unauthorized sources cannot be reused. An approval or task outcome cannot be published as a reusable informational answer.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SharedAnswer" } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [], "summary": "Find currently usable published informational answers", "tags": [ "answers" ] }, "post": { "operationId": "post_api_v1_answers", "description": "Publish an existing resolved question's answer for an explicit audience.\n\nCurrent authorized reader, or publisher with manage answer authority. Reuse requires audience membership and current source/publisher authority.\n\nReturns: SharedAnswer with source provenance, context hash and validity.\n\nRecovery: Expired, invalidated or unauthorized sources cannot be reused. An approval or task outcome cannot be published as a reusable informational answer.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SharedAnswer" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishAnswer" } } } }, "summary": "Publish an existing resolved question's answer for an explicit audience", "tags": [ "answers" ] } }, "/api/v1/answers/{id}/invalidate": { "post": { "operationId": "post_api_v1_answers_id_invalidate", "description": "Invalidate a published informational answer.\n\nCurrent authorized reader, or publisher with manage answer authority. Reuse requires audience membership and current source/publisher authority.\n\nReturns: `{invalidated: true}` after the authorized change commits. This acknowledgment does not contain an updated resource or prove business execution.\n\nRecovery: Expired, invalidated or unauthorized sources cannot be reused. An approval or task outcome cannot be published as a reusable informational answer.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "invalidated": { "type": "boolean", "description": "True after the operation succeeds." } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false } } } }, "summary": "Invalidate a published informational answer", "tags": [ "answers" ] } }, "/api/v1/assistance/settings": { "get": { "operationId": "get_api_v1_assistance_settings", "description": "Read OSS Coordinator settings and provider availability.\n\nAuthenticated person with current fleet visibility and required contact/assistance permissions. This is available in OSS without the UI.\n\nReturns: AssistanceSettings: overseer, version and overseer_configured.\n\nRecovery: Disabled/unconfigured assistance or provider failure returns an assistance error. Stale/expired plans, changed scope or revoked access block dispatch. Per-person model calls are rate-limited.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssistanceSettings" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [], "summary": "Read OSS Coordinator settings and provider availability", "tags": [ "coordinator" ] }, "post": { "operationId": "post_api_v1_assistance_settings", "description": "Owner-controlled optional assistance. Enabling requires a configured provider. Coordinator supports automatic dispatch and a separate explicit review flow.\n\nAuthenticated person with current fleet visibility and required contact/assistance permissions. This is available in OSS without the UI.\n\nReturns: Updated AssistanceSettings. Provider setup is a separate server configuration.\n\nRecovery: Disabled/unconfigured assistance or provider failure returns an assistance error. Stale/expired plans, changed scope or revoked access block dispatch. Per-person model calls are rate-limited.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssistanceSettings" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssistanceUpdate" } } } }, "summary": "Owner-controlled optional assistance", "tags": [ "coordinator" ] } }, "/api/v1/fleet/status": { "post": { "operationId": "post_api_v1_fleet_status", "description": "Read-only structured fleet status filtered by current View permission.\n\nAuthenticated person with current fleet visibility and required contact/assistance permissions. This is available in OSS without the UI.\n\nReturns: Authorized `agents`, dependency `deadlocks`, counts and `as_of`. Each agent item contains `agent`, `instances` and `fresh`. This is communication/presence evidence, not inferred model execution.\n\nRecovery: Disabled/unconfigured assistance or provider failure returns an assistance error. Stale/expired plans, changed scope or revoked access block dispatch. Per-person model calls are rate-limited.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "agents": { "type": "array", "items": { "type": "object", "properties": { "agent": { "oneOf": [ { "$ref": "#/components/schemas/Person" }, { "$ref": "#/components/schemas/Agent" }, { "$ref": "#/components/schemas/Service" } ], "description": "Stable agent external ID when enrolling; an Agent object in a Session response." }, "instances": { "type": "array", "items": { "$ref": "#/components/schemas/Instance" }, "description": "Visible runtime observations." }, "fresh": { "type": "boolean", "description": "At least one valid runtime is currently connected." } } }, "description": "At most 100 selected/visible agents." }, "deadlocks": { "type": "array", "items": { "type": "object", "properties": { "dependencies": { "type": "array", "items": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Explicitly blocking open request." }, "conversation_id": { "type": "string", "description": "Its current authorized history." }, "from": { "oneOf": [ { "$ref": "#/components/schemas/Person" }, { "$ref": "#/components/schemas/Agent" }, { "$ref": "#/components/schemas/Service" } ], "description": "The agent that declared this blocking communication dependency." }, "to": { "oneOf": [ { "$ref": "#/components/schemas/Person" }, { "$ref": "#/components/schemas/Agent" }, { "$ref": "#/components/schemas/Service" } ], "description": "The individual agent whose reply is blocking the requester." } } }, "description": "Explicit blocking-request edges in this cycle." } } }, "description": "Currently visible communication cycles." }, "total": { "type": "integer", "description": "Number of included agents." }, "fresh": { "type": "integer", "description": "Number with a connected instance." }, "missing_or_stale": { "type": "integer", "description": "Number without a currently connected instance." }, "as_of": { "type": "string", "description": "Observation time.", "format": "date-time" }, "summary": { "type": "string", "description": "Human-readable presence summary." }, "mode": { "type": "string", "description": "read_only." }, "commands_supported": { "type": "boolean", "description": "False; this endpoint does not dispatch work." } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "target": { "$ref": "#/components/schemas/Target", "description": "Target kind and stable ID. Choose a new target or an existing conversation, not both." } }, "required": [], "additionalProperties": false } } } }, "summary": "Read-only structured fleet status filtered by current View permission", "tags": [ "coordinator" ] } }, "/api/v1/fleet/plan": { "post": { "operationId": "post_api_v1_fleet_plan", "description": "Optional overseer. Acts only as the caller. Outbound messages, questions and tasks require a saved preview and explicit confirmation.\n\nAuthenticated person with current fleet visibility and required contact/assistance permissions. This is available in OSS without the UI.\n\nReturns: OverseerPlan; instructions are not dispatched until confirmation where required.\n\nRecovery: Disabled/unconfigured assistance or provider failure returns an assistance error. Stale/expired plans, changed scope or revoked access block dispatch. Per-person model calls are rate-limited.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OverseerPlan" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OverseerInput" } } } }, "summary": "Optional overseer", "tags": [ "coordinator" ] } }, "/api/v1/fleet/plans": { "get": { "operationId": "get_api_v1_fleet_plans", "description": "List Coordinator plans belonging to the authorized caller.\n\nAuthenticated person with current fleet visibility and required contact/assistance permissions. This is available in OSS without the UI.\n\nReturns: OverseerPlan array.\n\nRecovery: Disabled/unconfigured assistance or provider failure returns an assistance error. Stale/expired plans, changed scope or revoked access block dispatch. Per-person model calls are rate-limited.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/OverseerPlan" } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [], "summary": "List Coordinator plans belonging to the authorized caller", "tags": [ "coordinator" ] } }, "/api/v1/fleet/plans/{id}": { "get": { "operationId": "get_api_v1_fleet_plans_id", "description": "Read a Coordinator plan and its current attributed replies.\n\nAuthenticated person with current fleet visibility and required contact/assistance permissions. This is available in OSS without the UI.\n\nReturns: OverseerPlan with dispatches, replies and optional summary.\n\nRecovery: Disabled/unconfigured assistance or provider failure returns an assistance error. Stale/expired plans, changed scope or revoked access block dispatch. Per-person model calls are rate-limited.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OverseerPlan" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "summary": "Read a Coordinator plan and its current attributed replies", "tags": [ "coordinator" ] } }, "/api/v1/fleet/plans/{id}/summary": { "post": { "operationId": "post_api_v1_fleet_plans_id_summary", "description": "Read-only summary of currently authorized replies; changed permissions or replies invalidate derived output.\n\nAuthenticated person with current fleet visibility and required contact/assistance permissions. This is available in OSS without the UI.\n\nReturns: Updated OverseerPlan with reply_summary or safe summary error.\n\nRecovery: Disabled/unconfigured assistance or provider failure returns an assistance error. Stale/expired plans, changed scope or revoked access block dispatch. Per-person model calls are rate-limited.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OverseerPlan" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false } } } }, "summary": "Read-only summary of currently authorized replies; changed permissions or replies invalidate derived output", "tags": [ "coordinator" ] } }, "/api/v1/fleet/command": { "post": { "operationId": "post_api_v1_fleet_command", "description": "Atomically confirm a server-saved preview under current caller permissions. Idempotent per plan. No free-form targets or instructions accepted.\n\nAuthenticated person with current fleet visibility and required contact/assistance permissions. This is available in OSS without the UI.\n\nReturns: OverseerPlan with attributed dispatches. Repeated confirmation does not create duplicate instructions.\n\nRecovery: Disabled/unconfigured assistance or provider failure returns an assistance error. Stale/expired plans, changed scope or revoked access block dispatch. Per-person model calls are rate-limited.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OverseerPlan" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "plan_id": { "type": "string", "description": "Saved Coordinator plan ID; confirmation accepts this server-owned plan, not arbitrary replacement instructions." } }, "required": [ "plan_id" ], "additionalProperties": false } } } }, "summary": "Atomically confirm a server-saved preview under current caller permissions", "tags": [ "coordinator" ] } }, "/api/v1/conversations/{id}/attachments": { "get": { "operationId": "get_api_v1_conversations_id_attachments", "description": "List currently visible attachments in a conversation.\n\nAuthenticated uploader or currently authorized conversation participant, subject to history visibility.\n\nReturns: Array of Attachment metadata.\n\nRecovery: Empty/oversized files are rejected. An already claimed or expired staged ID cannot be bound again. Removed members cannot bypass history checks with a known ID.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Attachment" } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "summary": "List currently visible attachments in a conversation", "tags": [ "files" ] }, "post": { "operationId": "post_api_v1_conversations_id_attachments", "description": "Upload a file into existing authorized history.\n\nAuthenticated uploader or currently authorized conversation participant, subject to history visibility.\n\nReturns: Attachment metadata; multipart/form-data with one file field, bounded to 5 MiB.\n\nRecovery: Empty/oversized files are rejected. An already claimed or expired staged ID cannot be bound again. Removed members cannot bypass history checks with a known ID.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Attachment" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "Multipart form field containing one file; 1 byte through 5 MiB for HTTP/SDK uploads." } }, "required": [ "file" ], "additionalProperties": false } } } }, "summary": "Upload a file into existing authorized history", "tags": [ "files" ] } }, "/api/v1/attachments": { "post": { "operationId": "post_api_v1_attachments", "description": "Stage a private file for up to 24 hours. Only its uploader can read it until a keyed communication atomically claims attachment_ids. Maximum five files per message, 5 MiB each. An abandoned draft expires; upload itself has no automatic retry contract.\n\nAuthenticated uploader or currently authorized conversation participant, subject to history visibility.\n\nReturns: Attachment metadata with its private draft ID or authorized conversation association. The response is not the file bytes.\n\nRecovery: Empty/oversized files are rejected. An already claimed or expired staged ID cannot be bound again. Removed members cannot bypass history checks with a known ID.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Attachment" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "Multipart form field containing one file; 1 byte through 5 MiB for HTTP/SDK uploads." } }, "required": [ "file" ], "additionalProperties": false } } } }, "summary": "Stage a private file for up to 24 hours", "tags": [ "files" ] } }, "/api/v1/attachments/{id}": { "get": { "operationId": "get_api_v1_attachments_id", "description": "Download a currently visible attachment.\n\nAuthenticated uploader or currently authorized conversation participant, subject to history visibility.\n\nReturns: Raw file bytes with media type and download filename, not a JSON envelope.\n\nRecovery: Empty/oversized files are rejected. An already claimed or expired staged ID cannot be bound again. Removed members cannot bypass history checks with a known ID.", "responses": { "200": { "description": "Authenticated attachment download, at most 5 MiB", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "summary": "Download a currently visible attachment", "tags": [ "files" ] } }, "/api/v1/people/{id}/slack-account": { "post": { "operationId": "post_api_v1_people_id_slack_account", "description": "Link an administrator-attested immutable Slack account to a person.\n\nAuthenticated identity; mutations require management authority over the relevant resource. Enrollment requires a bounded launcher or operator.\n\nReturns: `{linked: true}` after the authorized change commits. This acknowledgment does not contain an updated resource or prove business execution.\n\nRecovery: Unknown/hidden identity is 404 or denied. Stale version conflicts. Delegated managers cannot create broader authority than they possess; revoked credentials cannot be used.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "linked": { "type": "boolean", "description": "True after the operation succeeds." } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "team_id": { "type": "string", "description": "Immutable Slack workspace/team ID for the linked account." }, "user_id": { "type": "string", "description": "Immutable provider user ID; not the display name or email." } }, "required": [ "team_id", "user_id" ], "additionalProperties": false } } } }, "summary": "Link an administrator-attested immutable Slack account to a person", "tags": [ "identities" ] } }, "/api/v1/people/{id}/oidc-account": { "post": { "operationId": "post_api_v1_people_id_oidc_account", "description": "Link a verified OIDC issuer/subject to a person.\n\nAuthenticated identity; mutations require management authority over the relevant resource. Enrollment requires a bounded launcher or operator.\n\nReturns: `{linked: true}` after the authorized change commits. This acknowledgment does not contain an updated resource or prove business execution.\n\nRecovery: Unknown/hidden identity is 404 or denied. Stale version conflicts. Delegated managers cannot create broader authority than they possess; revoked credentials cannot be used.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "linked": { "type": "boolean", "description": "True after the operation succeeds." } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "issuer": { "type": "string", "description": "Exact OIDC issuer URL used with the immutable subject; email matching alone is not identity linking." }, "subject": { "type": "string", "description": "Authorized subject projection of the access inspection." } }, "required": [ "issuer", "subject" ], "additionalProperties": false } } } }, "summary": "Link a verified OIDC issuer/subject to a person", "tags": [ "identities" ] } }, "/healthz": { "get": { "operationId": "get_healthz", "description": "Check that the engine process is alive.\n\nPublic health/discovery or browser authentication flow, as indicated by the operation. Provider callbacks validate their own state.\n\nReturns: `{status: \"ok\"}` on success. Readiness returns status unavailable with HTTP 503 when the database cannot be reached.\n\nRecovery: Readiness may return 503. Login rejects missing/invalid credentials and OIDC state; a redirect is not JSON.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Process/readiness result." } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [], "security": [], "summary": "Check that the engine process is alive", "tags": [ "authentication" ] } }, "/readyz": { "get": { "operationId": "get_readyz", "description": "Check that the engine can serve with its database/schema.\n\nPublic health/discovery or browser authentication flow, as indicated by the operation. Provider callbacks validate their own state.\n\nReturns: `{status: \"ready\"}` on success. Readiness returns status unavailable with HTTP 503 when the database cannot be reached.\n\nRecovery: Readiness may return 503. Login rejects missing/invalid credentials and OIDC state; a redirect is not JSON.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Process/readiness result." } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [], "security": [], "summary": "Check that the engine can serve with its database/schema", "tags": [ "authentication" ] } }, "/openapi.json": { "get": { "operationId": "get_openapi_json", "description": "Retrieve this engine's public API contract.\n\nPublic health/discovery or browser authentication flow, as indicated by the operation. Provider callbacks validate their own state.\n\nReturns: OpenAPI JSON document.\n\nRecovery: Readiness may return 503. Login rejects missing/invalid credentials and OIDC state; a redirect is not JSON.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [], "security": [], "summary": "Retrieve this engine's public API contract", "tags": [ "authentication" ] } }, "/api/v1/auth/methods": { "get": { "operationId": "get_api_v1_auth_methods", "description": "Discover the login methods configured for this deployment.\n\nPublic health/discovery or browser authentication flow, as indicated by the operation. Provider callbacks validate their own state.\n\nReturns: `token` and `oidc` booleans describe the configured login methods, without secrets.\n\nRecovery: Readiness may return 503. Login rejects missing/invalid credentials and OIDC state; a redirect is not JSON.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "boolean", "description": "Token login is available." }, "oidc": { "type": "boolean", "description": "Whether OIDC is configured." } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [], "security": [], "summary": "Discover the login methods configured for this deployment", "tags": [ "authentication" ] } }, "/auth/oidc/start": { "get": { "operationId": "get_auth_oidc_start", "description": "Start the configured OIDC browser login flow.\n\nPublic health/discovery or browser authentication flow, as indicated by the operation. Provider callbacks validate their own state.\n\nReturns: Browser redirect with protected state and nonce cookies.\n\nRecovery: Readiness may return 503. Login rejects missing/invalid credentials and OIDC state; a redirect is not JSON.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "303": { "description": "Redirect after verified login" } }, "parameters": [], "security": [], "summary": "Start the configured OIDC browser login flow", "tags": [ "authentication" ] } }, "/auth/oidc/callback": { "get": { "operationId": "get_auth_oidc_callback", "description": "Complete the configured OIDC login flow.\n\nPublic health/discovery or browser authentication flow, as indicated by the operation. Provider callbacks validate their own state.\n\nReturns: Validated browser session and redirect; not a general worker token endpoint.\n\nRecovery: Readiness may return 503. Login rejects missing/invalid credentials and OIDC state; a redirect is not JSON.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "303": { "description": "Redirect after verified login" } }, "parameters": [], "security": [], "summary": "Complete the configured OIDC login flow", "tags": [ "authentication" ] } }, "/api/v1/auth/login": { "post": { "operationId": "post_api_v1_auth_login", "description": "Create a browser session using the deployment's enabled login mechanism.\n\nPublic health/discovery or browser authentication flow, as indicated by the operation. Provider callbacks validate their own state.\n\nReturns: `{ok: true}` after the authorized change commits. This acknowledgment does not contain an updated resource or prove business execution.\n\nRecovery: Readiness may return 503. Login rejects missing/invalid credentials and OIDC state; a redirect is not JSON.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "description": "True after the operation succeeds." } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "Bearer credential. Save in protected server-side storage and never expose it in browser code or logs." } }, "required": [ "token" ], "additionalProperties": false } } } }, "security": [], "summary": "Create a browser session using the deployment's enabled login mechanism", "tags": [ "authentication" ] } }, "/api/v1/auth/logout": { "post": { "operationId": "post_api_v1_auth_logout", "description": "End the current browser session.\n\nPublic health/discovery or browser authentication flow, as indicated by the operation. Provider callbacks validate their own state.\n\nReturns: `{ok: true}` after the authorized change commits. This acknowledgment does not contain an updated resource or prove business execution.\n\nRecovery: Readiness may return 503. Login rejects missing/invalid credentials and OIDC state; a redirect is not JSON.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "description": "True after the operation succeeds." } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false } } } }, "summary": "End the current browser session", "tags": [ "authentication" ] } }, "/integrations/webhook/{id}": { "post": { "operationId": "post_integrations_webhook_id", "description": "Accept a signed inbound webhook for one configured connection.\n\nProvider callback. Use its native signature/secret verification, not a worker bearer token.\n\nReturns: SendResult: canonical conversation_id and messages. This signed callback supports ordinary messages, not implicit final approval.\n\nRecovery: Invalid signatures or account linkage are rejected. Duplicate delivery is deduplicated; changed content under the same provider event identity conflicts.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Beepgrid-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Beepgrid-Signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Beepgrid-Event-ID", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendInput" } } } }, "security": [], "summary": "Accept a signed inbound webhook for one configured connection", "tags": [ "callbacks" ] } }, "/integrations/slack/{id}": { "post": { "operationId": "post_integrations_slack_id", "description": "Accept authenticated Slack interactive actions for a connection.\n\nProvider callback. Use its native signature/secret verification, not a worker bearer token.\n\nReturns: Slack acknowledgment after canonical handling; current decision authority still applies.\n\nRecovery: Invalid signatures or account linkage are rejected. Duplicate delivery is deduplicated; changed content under the same provider event identity conflicts.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Slack-Request-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Slack-Signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "payload": { "type": "string", "description": "Canonical message/request information inside a delivery envelope." } }, "required": [ "payload" ], "additionalProperties": false } } } }, "security": [], "summary": "Accept authenticated Slack interactive actions for a connection", "tags": [ "callbacks" ] } }, "/integrations/slack/{id}/events": { "post": { "operationId": "post_integrations_slack_id_events", "description": "Accept authenticated Slack event callbacks.\n\nProvider callback. Use its native signature/secret verification, not a worker bearer token.\n\nReturns: Slack challenge or event acknowledgment with duplicate-event handling.\n\nRecovery: Invalid signatures or account linkage are rejected. Duplicate delivery is deduplicated; changed content under the same provider event identity conflicts.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Slack-Request-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Slack-Signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "security": [], "summary": "Accept authenticated Slack event callbacks", "tags": [ "callbacks" ] } }, "/api/v1/requests/{id}/blocking": { "post": { "operationId": "setRequestBlocking", "description": "Only the requesting agent may declare or clear its own open single-agent blocking dependency. Does not cancel the request.\n\nCurrent requester, authorized original decision recipient or exact bound executor, according to operation.\n\nReturns: Updated Request with blocking state.\n\nRecovery: Invalid outcome/choice fails validation. A stale request version or terminal-state race conflicts. Permission is rechecked at decision, redemption and reporting.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "blocking" ], "additionalProperties": false, "properties": { "blocking": { "type": "boolean", "description": "Explicit requester-declared agent dependency. Ordinary pending questions are not automatically blocking." } } } } } }, "responses": { "200": { "description": "Current request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Request" } } } }, "403": { "description": "Caller is not the requesting agent" }, "409": { "description": "Request is no longer open" } }, "summary": "Only the requesting agent may declare or clear its own open single-agent blocking dependency", "tags": [ "requests" ] } }, "/api/v1/fleet/coordinate": { "post": { "operationId": "coordinate", "description": "Plan and dispatch distinct ordinary communications under current permissions, then durably collect and summarize settled replies. Idempotent recovery. Does not grant business execution authority. Use /fleet/plan and /fleet/command for explicit review.\n\nAuthenticated person with current fleet visibility and required contact/assistance permissions. This is available in OSS without the UI.\n\nReturns: Automatic OverseerPlan with selected specialists and attributed dispatches, or a status answer.\n\nRecovery: Disabled/unconfigured assistance or provider failure returns an assistance error. Stale/expired plans, changed scope or revoked access block dispatch. Per-person model calls are rate-limited.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OverseerPlan" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OverseerInput" } } } }, "summary": "Plan and dispatch distinct ordinary communications under current permissions, then durably collect and summarize settled replies", "tags": [ "coordinator" ] } }, "/api/v1/connections/{id}/setup": { "get": { "operationId": "get_api_v1_connections_id_setup", "description": "Authorized credential-free setup steps and generated BYO manifest. Never contacts providers or changes registrations.\n\nAuthenticated identity with current connection/destination visibility or management authority. Sending a test also requires contact rights.\n\nReturns: ProviderSetup: safe callbacks, manifests/registration steps and current diagnostic evidence, without credentials.\n\nRecovery: Invalid provider fields, missing verified account or disallowed URL fail validation. A stale configuration version conflicts. Provider acceptance alone does not establish a reply.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderSetup" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "summary": "Authorized credential-free setup steps and generated BYO manifest", "tags": [ "channels" ] } }, "/api/v1/people/{id}/telegram-account": { "post": { "operationId": "post_api_v1_people_id_telegram_account", "description": "Administrator-attested immutable private Telegram identity. Grants no contact or decision authority.\n\nAuthenticated identity; mutations require management authority over the relevant resource. Enrollment requires a bounded launcher or operator.\n\nReturns: `{linked: true}` after the authorized change commits. This acknowledgment does not contain an updated resource or prove business execution.\n\nRecovery: Unknown/hidden identity is 404 or denied. Stale version conflicts. Delegated managers cannot create broader authority than they possess; revoked credentials cannot be used.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "linked": { "type": "boolean", "description": "True after the operation succeeds." } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "bot_id": { "type": "string", "description": "Provider-native bot identity for the configured application." }, "user_id": { "type": "string", "description": "Immutable provider user ID; not the display name or email." } }, "required": [ "bot_id", "user_id" ], "additionalProperties": false } } } }, "summary": "Administrator-attested immutable private Telegram identity", "tags": [ "identities" ] } }, "/api/v1/people/{id}/telegram-account/remove": { "post": { "operationId": "post_api_v1_people_id_telegram_account_remove", "description": "Unlink the Person Telegram identity under current account-link authority. Old destinations and callbacks lose authority.\n\nAuthenticated identity; mutations require management authority over the relevant resource. Enrollment requires a bounded launcher or operator.\n\nReturns: `{removed: true}` after the authorized change commits. This acknowledgment does not contain an updated resource or prove business execution.\n\nRecovery: Unknown/hidden identity is 404 or denied. Stale version conflicts. Delegated managers cannot create broader authority than they possess; revoked credentials cannot be used.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "removed": { "type": "boolean", "description": "True after the operation succeeds." } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "summary": "Unlink the Person Telegram identity under current account-link authority", "tags": [ "identities" ] } }, "/integrations/telegram/{id}": { "post": { "operationId": "post_integrations_telegram_id", "description": "Secret-authenticated private bot updates. Canonical message/decision, thread and dedup receipt commit before success. Same ID with changed content conflicts. See docs/TELEGRAM.md.\n\nProvider callback. Use its native signature/secret verification, not a worker bearer token.\n\nReturns: A message receipt has conversation_id and message_count. A decision receipt has conversation_id, request_id and outcome (approved or denied). Ignored unsupported update categories return {ignored: true}. Each handled receipt follows durable commit.\n\nRecovery: Invalid signatures or account linkage are rejected. Duplicate delivery is deduplicated; changed content under the same provider event identity conflicts.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Telegram-Bot-Api-Secret-Token", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "update_id": { "type": "integer", "minimum": 0, "description": "Telegram update identity used for canonical duplicate handling." }, "message": { "type": "object", "description": "Safe human-readable API error message." }, "callback_query": { "type": "object", "description": "Native Telegram callback query object, verified against the connection and linked person." } }, "required": [ "update_id" ], "additionalProperties": false } } } }, "security": [], "summary": "Secret-authenticated private bot updates", "tags": [ "callbacks" ] } }, "/api/v1/people/{id}/discord-account": { "post": { "operationId": "post_api_v1_people_id_discord_account", "description": "Administrator-attested immutable Discord application/user identity. Grants no contact or decision authority.\n\nAuthenticated identity; mutations require management authority over the relevant resource. Enrollment requires a bounded launcher or operator.\n\nReturns: `{linked: true}` after the authorized change commits. This acknowledgment does not contain an updated resource or prove business execution.\n\nRecovery: Unknown/hidden identity is 404 or denied. Stale version conflicts. Delegated managers cannot create broader authority than they possess; revoked credentials cannot be used.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "linked": { "type": "boolean", "description": "True after the operation succeeds." } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "application_id": { "type": "string", "description": "Immutable Discord application ID for the configured connection." }, "user_id": { "type": "string", "description": "Immutable provider user ID; not the display name or email." } }, "required": [ "application_id", "user_id" ], "additionalProperties": false } } } }, "summary": "Administrator-attested immutable Discord application/user identity", "tags": [ "identities" ] } }, "/api/v1/people/{id}/discord-account/remove": { "post": { "operationId": "post_api_v1_people_id_discord_account_remove", "description": "Unlink the Person Discord identity. Queued sends and callbacks lose authority.\n\nAuthenticated identity; mutations require management authority over the relevant resource. Enrollment requires a bounded launcher or operator.\n\nReturns: `{removed: true}` after the authorized change commits. This acknowledgment does not contain an updated resource or prove business execution.\n\nRecovery: Unknown/hidden identity is 404 or denied. Stale version conflicts. Delegated managers cannot create broader authority than they possess; revoked credentials cannot be used.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "removed": { "type": "boolean", "description": "True after the operation succeeds." } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "summary": "Unlink the Person Discord identity", "tags": [ "identities" ] } }, "/integrations/discord/{id}": { "post": { "operationId": "post_integrations_discord_id", "description": "Ed25519-authenticated Discord interactions. Bot DM commands, reply forms and versioned approvals only. Commits canonical actions and dedup receipt before acknowledgment. See docs/DISCORD.md.\n\nProvider callback. Use its native signature/secret verification, not a worker bearer token.\n\nReturns: Discord interaction response: type plus optional data in the native Discord schema. Canonical receipt metadata stays internal; do not expect a Beepgrid message object in this HTTP response.\n\nRecovery: Invalid signatures or account linkage are rejected. Duplicate delivery is deduplicated; changed content under the same provider event identity conflicts.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Signature-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Signature-Ed25519", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "security": [], "summary": "Ed25519-authenticated Discord interactions", "tags": [ "callbacks" ] } } }, "components": { "schemas": { "Target": { "type": "object", "properties": { "kind": { "enum": [ "person", "agent", "service", "group", "instance" ], "description": "Resource or operation kind. Use one of the listed values, not a display label." }, "id": { "type": "string", "description": "Stable identifier returned by the engine. Treat it as opaque." } }, "required": [ "kind", "id" ], "additionalProperties": false }, "Person": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable identifier returned by the engine. Treat it as opaque." }, "kind": { "const": "person", "description": "Resource or operation kind. Use one of the listed values, not a display label." }, "external_id": { "type": "string", "description": "Your stable identifier for this person, agent or service within the workspace." }, "name": { "type": "string", "description": "Human-readable name. It is not necessarily unique." }, "metadata": { "type": "object", "description": "Application-supplied JSON metadata. Do not put credentials here." }, "disabled": { "type": "boolean", "description": "Whether the identity is disabled; disabled identities cannot retain normal access." }, "created_at": { "type": "string", "format": "date-time", "description": "Creation timestamp in RFC 3339 UTC." } }, "required": [ "id", "kind", "name" ], "additionalProperties": false }, "Agent": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable identifier returned by the engine. Treat it as opaque." }, "kind": { "const": "agent", "description": "Resource or operation kind. Use one of the listed values, not a display label." }, "external_id": { "type": "string", "description": "Your stable identifier for this person, agent or service within the workspace." }, "name": { "type": "string", "description": "Human-readable name. It is not necessarily unique." }, "metadata": { "type": "object", "description": "Application-supplied JSON metadata. Do not put credentials here." }, "disabled": { "type": "boolean", "description": "Whether the identity is disabled; disabled identities cannot retain normal access." }, "created_at": { "type": "string", "format": "date-time", "description": "Creation timestamp in RFC 3339 UTC." }, "instances": { "type": "array", "items": { "$ref": "#/components/schemas/Instance" }, "description": "Runtime connections and their observed presence." } }, "required": [ "id", "kind", "name" ], "additionalProperties": false }, "Service": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable identifier returned by the engine. Treat it as opaque." }, "kind": { "const": "service", "description": "Resource or operation kind. Use one of the listed values, not a display label." }, "external_id": { "type": "string", "description": "Your stable identifier for this person, agent or service within the workspace." }, "name": { "type": "string", "description": "Human-readable name. It is not necessarily unique." }, "metadata": { "type": "object", "description": "Application-supplied JSON metadata. Do not put credentials here." }, "disabled": { "type": "boolean", "description": "Whether the identity is disabled; disabled identities cannot retain normal access." }, "created_at": { "type": "string", "format": "date-time", "description": "Creation timestamp in RFC 3339 UTC." } }, "required": [ "id", "kind", "name" ], "additionalProperties": false }, "Instance": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable identifier returned by the engine. Treat it as opaque." }, "agent_id": { "type": "string", "description": "Logical agent identity ID, shared by its runtime instances." }, "presence": { "enum": [ "connected", "stale", "offline" ], "description": "Observed runtime presence: connected, stale or offline." }, "last_seen": { "type": "string", "description": "Most recent runtime heartbeat timestamp." }, "capabilities": { "type": "array", "items": { "type": "string" }, "description": "Application-declared runtime capabilities. This does not grant contact permission." }, "progress": { "type": "object", "description": "Explicit application-reported progress metadata; not automatic model telemetry." } }, "required": [], "additionalProperties": false }, "PersonInput": { "type": "object", "properties": { "external_id": { "type": "string", "description": "Your stable identifier for this person, agent or service within the workspace." }, "name": { "type": "string", "description": "Human-readable name. It is not necessarily unique." }, "email": { "type": "string", "description": "Person email address. An address alone does not prove identity or decision authority." }, "department": { "type": "string", "description": "Optional person organization metadata." }, "manager_id": { "type": "string", "description": "Manager identity for a person, or current shared-chat manager according to the resource." } }, "required": [ "name" ], "additionalProperties": false }, "Enrollment": { "type": "object", "properties": { "agent": { "type": "string", "description": "Stable agent external ID when enrolling; an Agent object in a Session response." }, "name": { "type": "string", "description": "Human-readable name. It is not necessarily unique." }, "parent_id": { "type": "string", "description": "Optional parent agent identity for a deliberately bounded enrollment." }, "capabilities": { "type": "array", "items": { "type": "string" }, "description": "Application-declared runtime capabilities. This does not grant contact permission." }, "metadata": { "type": "object", "description": "Application-supplied JSON metadata. Do not put credentials here." }, "connection_name": { "type": "string", "description": "Human-readable label for this Agent runtime connection." }, "never_expires": { "type": "boolean", "default": false, "description": "Explicit non-expiring connection. Cannot be combined with renewable or expires_at." }, "renewable": { "type": "boolean", "default": false, "description": "Use a renewable 24-hour worker lease bounded by the supplied hard expiry. Renewal never extends the hard deadline." }, "expires_at": { "type": "string", "format": "date-time", "description": "Hard deadline. Renewable workers use a 24-hour active lease up to this date." } }, "required": [ "agent", "name" ], "additionalProperties": false }, "Session": { "type": "object", "properties": { "token": { "type": "string", "writeOnly": false, "description": "Bearer credential. Save in protected server-side storage and never expose it in browser code or logs." }, "agent": { "$ref": "#/components/schemas/Agent", "description": "Stable agent external ID when enrolling; an Agent object in a Session response." }, "instance_id": { "type": "string", "description": "Exact connected runtime ID, separate from the logical agent identity." }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Expiry timestamp. Ordinary communication has no implicit deadline (represented as 9999-01-01T00:00:00Z). Bound action approvals default to seven days; explicit expiry must be within ninety days. Local wait timeout never changes it." } }, "required": [], "additionalProperties": false }, "Action": { "type": "object", "properties": { "name": { "type": "string", "description": "Human-readable name. It is not necessarily unique." }, "executor_id": { "type": "string", "description": "Identity allowed to redeem the exact approved action." }, "resource": { "type": "string", "description": "Customer-defined resource identifier. The engine does not control the external resource." }, "resource_version": { "type": "string", "description": "Customer-defined version fence that the external tool must also enforce." }, "operation_key": { "type": "string", "description": "Stable identity of the external business operation, separate from the HTTP retry key." }, "arguments": { "type": "object", "description": "JSON action arguments covered by the exact approval binding." } }, "required": [ "name", "executor_id", "resource", "resource_version", "operation_key" ], "additionalProperties": false }, "SendInput": { "type": "object", "properties": { "preview_token": { "type": "string", "description": "Dispatch preview token. A stale audience or route requires a fresh preview." }, "target": { "$ref": "#/components/schemas/Target", "description": "Target kind and stable ID. Choose a new target or an existing conversation, not both." }, "conversation_id": { "type": "string", "description": "Canonical conversation ID. Use it to continue the same authorized history." }, "body": { "type": "string", "description": "Message or request content, bounded to 32 KiB of UTF-8 bytes." }, "title": { "type": "string", "description": "Optional short label. A normal message does not require a title." }, "mentions": { "type": "array", "items": { "$ref": "#/components/schemas/Mention" }, "maxItems": 20, "description": "Addressing metadata for existing chat participants. It does not narrow audience or grant authority." }, "reuse_direct": { "type": "boolean", "description": "Reuse authorized exact two-principal history. Defaults to false. Does not merge shared group chats.", "default": false }, "attachment_ids": { "type": "array", "items": { "type": "string" }, "maxItems": 5, "uniqueItems": true, "description": "IDs of staged private drafts to claim in the initial operation; at most five." } }, "required": [ "body" ], "additionalProperties": false }, "Message": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable identifier returned by the engine. Treat it as opaque." }, "conversation_id": { "type": "string", "description": "Canonical conversation ID. Use it to continue the same authorized history." }, "sender_id": { "type": "string", "description": "Identity that sent the message, independent of the delivering channel." }, "instance_id": { "type": "string", "description": "Exact connected runtime ID, separate from the logical agent identity." }, "body": { "type": "string", "description": "Message or request content, bounded to 32 KiB of UTF-8 bytes." }, "created_at": { "type": "string", "description": "Creation timestamp in RFC 3339 UTC." }, "mentions": { "type": "array", "items": { "$ref": "#/components/schemas/Mention" }, "maxItems": 20, "description": "Addressing metadata for existing chat participants. It does not narrow audience or grant authority." }, "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/Attachment" }, "description": "Currently visible attachment metadata." }, "received_by": { "type": "array", "items": { "type": "string" }, "description": "Read-only native Agent runtime acknowledgement IDs, visible only to the message sender for current Agent participants. Not evidence of model reading or business execution. Provider acceptance is excluded." } }, "required": [], "additionalProperties": false }, "SendResult": { "type": "object", "properties": { "conversation_id": { "type": "string", "description": "Canonical conversation ID. Use it to continue the same authorized history." }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" }, "description": "Canonical message records in this response, not worker delivery envelopes." } }, "required": [], "additionalProperties": false }, "SendReceipt": { "type": "object", "properties": { "conversation_id": { "type": "string", "description": "Canonical conversation ID. Use it to continue the same authorized history." }, "message_count": { "type": "integer", "minimum": 1, "description": "Number of canonical messages accepted in the compact receipt; no bodies returned." } }, "required": [], "additionalProperties": false }, "Conversation": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable identifier returned by the engine. Treat it as opaque." }, "title": { "type": "string", "description": "Optional short label. A normal message does not require a title." }, "created_by": { "type": "string", "description": "Identity that created the resource." }, "created_at": { "type": "string", "description": "Creation timestamp in RFC 3339 UTC." }, "participants": { "type": "array", "items": { "type": "object" }, "description": "Current participants in the authorized history projection." }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" }, "description": "Canonical message records in this response, not worker delivery envelopes." }, "last_activity_at": { "type": "string", "format": "date-time", "description": "Most recent conversation activity timestamp; used for recency ordering." }, "last_preview": { "type": "string", "description": "Last visible message preview; hidden history is not exposed through previews." }, "shared": { "type": "boolean", "description": "True for a shared chat, distinct from private histories created by a batch." }, "version": { "type": "integer", "description": "Current optimistic-concurrency version. Read the object before a guarded change; a stale version conflicts." }, "manager_id": { "type": "string", "description": "Manager identity for a person, or current shared-chat manager according to the resource." }, "history_start": { "type": "integer", "description": "Earliest event boundary disclosed to this participant." }, "past_participants": { "type": "array", "items": { "type": "object" }, "description": "Former participant metadata visible to the caller; does not restore their access." } }, "required": [], "additionalProperties": false }, "AskInput": { "type": "object", "properties": { "preview_token": { "type": "string", "description": "Dispatch preview token. A stale audience or route requires a fresh preview." }, "target": { "$ref": "#/components/schemas/Target", "description": "Target kind and stable ID. Choose a new target or an existing conversation, not both." }, "conversation_id": { "type": "string", "description": "Canonical conversation ID. Use it to continue the same authorized history." }, "kind": { "enum": [ "question", "approval", "task" ], "description": "Resource or operation kind. Use one of the listed values, not a display label.", "default": "question" }, "title": { "type": "string", "description": "Optional short label. A normal message does not require a title." }, "body": { "type": "string", "description": "Message or request content, bounded to 32 KiB of UTF-8 bytes." }, "choices": { "type": "array", "items": { "type": "string" }, "description": "Optional exact answer strings. A chosen answer must match an offered value." }, "action": { "$ref": "#/components/schemas/Action", "description": "Optional exact bound-action descriptor for the advanced execution contract." }, "expires_at": { "type": "string", "description": "Expiry timestamp. Ordinary communication has no implicit deadline (represented as 9999-01-01T00:00:00Z). Bound action approvals default to seven days; explicit expiry must be within ninety days. Local wait timeout never changes it." }, "shared_key": { "type": "string", "description": "Explicit reusable-answer key; reuse also requires exact matching question context and current authority." }, "mentions": { "type": "array", "items": { "$ref": "#/components/schemas/Mention" }, "maxItems": 20, "description": "Addressing metadata for existing chat participants. It does not narrow audience or grant authority." }, "reuse_direct": { "type": "boolean", "description": "Reuse authorized exact two-principal history. Defaults to false. Does not merge shared group chats.", "default": false }, "blocking": { "type": "boolean", "description": "Explicit agent-to-individual-agent dependency. Ordinary open requests are not deadlocks." }, "attachment_ids": { "type": "array", "items": { "type": "string" }, "maxItems": 5, "uniqueItems": true, "description": "IDs of staged private drafts to claim in the initial operation; at most five." } }, "required": [], "additionalProperties": false }, "ResponseInput": { "type": "object", "properties": { "outcome": { "enum": [ "answered", "approved", "denied", "completed", "failed", "rejected" ], "description": "Typed final result: answered; approved/denied; or completed/failed/rejected according to request kind." }, "answer": { "description": "JSON response value; for choices, the selected exact string." }, "version": { "type": "integer", "description": "Current optimistic-concurrency version. Read the object before a guarded change; a stale version conflicts." } }, "required": [ "outcome", "version" ], "additionalProperties": false }, "Response": { "type": "object", "properties": { "responder_instance_id": { "type": "string", "description": "Runtime that supplied the final response, when applicable." }, "outcome": { "type": "string", "description": "Typed final result: answered; approved/denied; or completed/failed/rejected according to request kind." }, "answer": { "description": "JSON response value; for choices, the selected exact string." }, "version": { "type": "integer", "description": "Current optimistic-concurrency version. Read the object before a guarded change; a stale version conflicts." }, "source_answer_id": { "type": "string", "description": "Published answer used as response provenance." }, "source_invalidated": { "type": "boolean", "description": "Whether the source informational answer has since been invalidated." }, "reuse_method": { "type": "string", "description": "How an existing informational answer was reused." }, "reuse_reason": { "type": "string", "description": "Recorded reason or provenance for reuse." } }, "required": [], "additionalProperties": false }, "Request": { "type": "object", "properties": { "requester_instance_id": { "type": "string", "description": "Runtime that initiated the request, when applicable." }, "id": { "type": "string", "description": "Stable identifier returned by the engine. Treat it as opaque." }, "requester_id": { "type": "string", "description": "Identity that opened the requested decision." }, "conversation_id": { "type": "string", "description": "Canonical conversation ID. Use it to continue the same authorized history." }, "kind": { "type": "string", "description": "Resource or operation kind. Use one of the listed values, not a display label.", "enum": [ "question", "approval", "task" ] }, "title": { "type": "string", "description": "Optional short label. A normal message does not require a title." }, "body": { "type": "string", "description": "Message or request content, bounded to 32 KiB of UTF-8 bytes." }, "choices": { "type": "array", "items": { "type": "string" }, "description": "Optional exact answer strings. A chosen answer must match an offered value." }, "action": { "$ref": "#/components/schemas/Action", "description": "Optional exact bound-action descriptor for the advanced execution contract." }, "state": { "enum": [ "open", "resolved", "cancelled", "expired", "superseded" ], "description": "Lifecycle state. Read the resource-specific enum; request and execution states differ." }, "version": { "type": "integer", "description": "Current optimistic-concurrency version. Read the object before a guarded change; a stale version conflicts." }, "response": { "$ref": "#/components/schemas/Response", "description": "Recorded final typed decision, absent while pending." }, "resolved_by": { "type": "string", "description": "Identity that resolved the request." }, "resolved_at": { "type": "string", "description": "Timestamp of the terminal decision." }, "expires_at": { "type": "string", "description": "Expiry timestamp. Ordinary communication has no implicit deadline (represented as 9999-01-01T00:00:00Z). Bound action approvals default to seven days; explicit expiry must be within ninety days. Local wait timeout never changes it." }, "created_at": { "type": "string", "description": "Creation timestamp in RFC 3339 UTC." }, "shared_key": { "type": "string", "description": "Explicit reusable-answer key; reuse also requires exact matching question context and current authority." }, "mentions": { "type": "array", "items": { "$ref": "#/components/schemas/Mention" }, "maxItems": 20, "description": "Addressing metadata for existing chat participants. It does not narrow audience or grant authority." }, "blocking": { "type": "boolean", "description": "Explicit agent-to-individual-agent dependency. Ordinary open requests are not deadlocks." }, "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/Attachment" }, "description": "Currently visible attachment metadata." } }, "required": [], "additionalProperties": false }, "Rule": { "type": "object", "properties": { "effect": { "enum": [ "allow", "deny" ], "description": "Omitted means allow. Explicit contact blocks override all matching role grants, except administrator credentials." }, "action": { "enum": [ "view", "message", "ask", "decide", "manage", "*" ], "description": "Directional permission action: view, message, ask, decide, manage or an explicitly granted wildcard." }, "target_kind": { "type": "string", "description": "Kind of identity or managed resource matched by the rule." }, "target_id": { "type": "string", "description": "Stable ID or explicitly supported wildcard of the rule's target." }, "connection_id": { "type": "string", "description": "Configured channel connection ID." }, "action_name": { "type": "string", "description": "Optional action-name constraint; not required for ordinary approval communication." }, "conditions": { "type": "object", "properties": { "resource": { "type": "string", "description": "Customer-defined resource identifier. The engine does not control the external resource." }, "resource_version": { "type": "string", "description": "Customer-defined version fence that the external tool must also enforce." }, "currency": { "type": "string", "description": "Optional currency code used to constrain a bound business action." }, "max_amount_minor": { "type": "integer", "minimum": 0, "description": "Optional maximum action amount in minor currency units." }, "before": { "type": "string", "description": "Whether the check is allowed under the current effective role grants." } }, "required": [], "additionalProperties": false, "description": "Optional descriptor/time/amount constraints on the rule." } }, "required": [ "action", "target_kind", "target_id" ], "additionalProperties": false }, "Role": { "type": "object", "properties": { "version": { "type": "integer", "minimum": 0, "description": "Current optimistic-concurrency version. Read the object before a guarded change; a stale version conflicts." }, "id": { "type": "string", "description": "Stable identifier returned by the engine. Treat it as opaque." }, "name": { "type": "string", "description": "Human-readable name. It is not necessarily unique." }, "rules": { "type": "array", "items": { "$ref": "#/components/schemas/Rule" }, "description": "Directional permission rules granted by this policy role." } }, "required": [ "name", "rules" ], "additionalProperties": false }, "Group": { "type": "object", "properties": { "icon": { "type": "string", "readOnly": true, "description": "Presentation-only role icon. Change with POST /appearance." }, "purpose": { "enum": [ "contacts", "team", "agent_role" ], "description": "Directory group purpose: contacts, team or agent_role. This is separate from policy roles." }, "created_by": { "type": "string", "readOnly": true, "description": "Identity that created the resource." }, "version": { "type": "integer", "minimum": 0, "description": "Current optimistic-concurrency version. Read the object before a guarded change; a stale version conflicts." }, "member": { "type": "boolean", "readOnly": true, "description": "Whether the current identity belongs to this directory group." }, "members_complete": { "type": "boolean", "readOnly": true, "description": "Whether the visible member list is complete rather than permission-projected." }, "id": { "type": "string", "description": "Stable identifier returned by the engine. Treat it as opaque." }, "name": { "type": "string", "description": "Human-readable name. It is not necessarily unique." }, "members": { "type": "array", "items": { "type": "string" }, "description": "Directory-group or chat member identity IDs. Membership never substitutes for contact authority." } }, "required": [ "name", "members" ], "additionalProperties": false }, "Binding": { "type": "object", "properties": { "role_id": { "type": "string", "description": "Policy role ID used by a binding; not the agent_role directory-group ID." }, "subject_kind": { "enum": [ "principal", "group" ], "description": "principal for an individual identity, or group for a directory group." }, "subject_id": { "type": "string", "description": "Identity or directory group receiving a policy-role assignment." }, "remove": { "type": "boolean", "description": "True to remove the specified role binding rather than add it." } }, "required": [ "role_id", "subject_kind", "subject_id" ], "additionalProperties": false }, "Connection": { "type": "object", "properties": { "version": { "type": "integer", "minimum": 0, "description": "Current optimistic-concurrency version. Read the object before a guarded change; a stale version conflicts." }, "id": { "type": "string", "description": "Stable identifier returned by the engine. Treat it as opaque." }, "name": { "type": "string", "description": "Human-readable name. It is not necessarily unique." }, "kind": { "enum": [ "webhook", "slack", "email", "telegram", "discord" ], "description": "Resource or operation kind. Use one of the listed values, not a display label." }, "config": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Provider-specific configuration. Use the catalog's actual fields; secret material is separately protected." }, "enabled": { "type": "boolean", "description": "Whether this configured connection is enabled." }, "secret_configured": { "type": "boolean", "description": "Whether protected secret material is configured, without returning it." }, "secret": { "type": "string", "writeOnly": true, "description": "Write-only provider secret. Omitted from ordinary read/setup responses." } }, "required": [ "name", "kind" ], "additionalProperties": false }, "Destination": { "type": "object", "properties": { "version": { "type": "integer", "minimum": 0, "description": "Current optimistic-concurrency version. Read the object before a guarded change; a stale version conflicts." }, "id": { "type": "string", "description": "Stable identifier returned by the engine. Treat it as opaque." }, "connection_id": { "type": "string", "description": "Configured channel connection ID." }, "principal_id": { "type": "string", "description": "Person, agent or service identity ID. This is an API term, not a separate product entity." }, "address": { "type": "string", "description": "Provider-native destination address for a linked identity." }, "mode": { "enum": [ "primary", "fallback", "copy" ], "description": "primary, copy or fallback routing mode." }, "priority": { "type": "integer", "description": "Routing order within the applicable mode; lower numeric values are considered first." } }, "required": [ "connection_id", "principal_id", "address" ], "additionalProperties": false }, "Execution": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable identifier returned by the engine. Treat it as opaque." }, "request_id": { "type": "string", "description": "Canonical durable request ID. This is not a worker delivery ID." }, "executor_id": { "type": "string", "description": "Identity allowed to redeem the exact approved action." }, "operation_key": { "type": "string", "description": "Stable identity of the external business operation, separate from the HTTP retry key." }, "action": { "$ref": "#/components/schemas/Action", "description": "Optional exact bound-action descriptor for the advanced execution contract." }, "state": { "type": "string", "description": "Lifecycle state. Read the resource-specific enum; request and execution states differ.", "enum": [ "authorized", "running", "succeeded", "failed", "unknown" ] }, "result": { "description": "Executor-reported JSON result. It is not independent proof of an external effect." } }, "required": [], "additionalProperties": false }, "Delivery": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable identifier returned by the engine. Treat it as opaque." }, "recipient_id": { "type": "string", "description": "Intended individual identity for the delivery or event projection." }, "operation_id": { "type": "string", "description": "Canonical operation correlation identifier." }, "payload": { "type": "object", "description": "Canonical message/request information inside a delivery envelope." }, "state": { "type": "string", "description": "Lifecycle state. Read the resource-specific enum; request and execution states differ." }, "generation": { "type": "integer", "description": "Current inbox lease generation. Ack must echo this generation." }, "attempts": { "type": "integer", "description": "Delivery attempt count or recorded attempt evidence, as defined by this response." }, "last_error": { "type": "string", "description": "Latest safe delivery error, not a successful execution report." }, "connection_id": { "type": "string", "description": "Configured channel connection ID." }, "address": { "type": "string", "description": "Provider-native destination address for a linked identity." }, "expires_at": { "type": "string", "description": "Expiry timestamp. Ordinary communication has no implicit deadline (represented as 9999-01-01T00:00:00Z). Bound action approvals default to seven days; explicit expiry must be within ninety days. Local wait timeout never changes it." } }, "required": [], "additionalProperties": false }, "Attachment": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable identifier returned by the engine. Treat it as opaque." }, "conversation_id": { "type": "string", "description": "Canonical conversation ID. Use it to continue the same authorized history." }, "file_name": { "type": "string", "description": "Safe file name shown with the attachment." }, "media_type": { "type": "string", "description": "Declared media type, for example application/pdf." }, "size": { "type": "integer", "description": "File length in bytes, from 1 byte through 5 MiB." }, "sha256": { "type": "string", "description": "SHA-256 digest of the stored file bytes." }, "created_at": { "type": "string", "description": "Creation timestamp in RFC 3339 UTC." }, "message_id": { "type": "string", "description": "Canonical message ID for deduplication and correlation." }, "request_id": { "type": "string", "description": "Canonical durable request ID. This is not a worker delivery ID." } }, "required": [], "additionalProperties": false }, "PublishAnswer": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Canonical durable request ID. This is not a worker delivery ID." }, "key": { "type": "string", "description": "Stable idempotency key or shared-answer lookup key according to the endpoint." }, "audience": { "type": "array", "items": { "type": "string" }, "description": "Explicit identities allowed to reuse the published informational answer." }, "valid_until": { "type": "string", "description": "Reusable-answer expiry timestamp; omission defaults to 24 hours." } }, "required": [ "request_id", "audience" ], "additionalProperties": false }, "SharedAnswer": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable identifier returned by the engine. Treat it as opaque." }, "key": { "type": "string", "description": "Stable idempotency key or shared-answer lookup key according to the endpoint." }, "context_hash": { "type": "string", "description": "Digest of the exact shared key, title, body and choices used for reuse eligibility." }, "question": { "type": "string", "description": "Original informational question title, retained with the published answer." }, "answer": { "description": "JSON response value; for choices, the selected exact string." }, "author_id": { "type": "string", "description": "Identity that supplied the original informational answer." }, "publisher_id": { "type": "string", "description": "Identity whose current publication authority must remain valid for reuse." }, "audience": { "type": "array", "items": { "type": "string" }, "description": "Explicit identities allowed to reuse the published informational answer." }, "valid_until": { "type": "string", "format": "date-time", "description": "Reusable-answer expiry timestamp; omission defaults to 24 hours." }, "invalidated": { "type": "boolean", "description": "Whether this published informational answer has been explicitly invalidated." }, "source_request": { "type": "string", "description": "Canonical question request from which this answer was published." } }, "required": [], "additionalProperties": false }, "AssistanceSettings": { "type": "object", "properties": { "overseer": { "type": "boolean", "description": "Whether OSS Coordinator is enabled in this workspace. The wire name is retained for compatibility." }, "version": { "type": "integer", "description": "Current optimistic-concurrency version. Read the object before a guarded change; a stale version conflicts." }, "overseer_configured": { "type": "boolean", "description": "Whether the engine has a configured Coordinator provider; not the enablement switch." } }, "required": [], "additionalProperties": false }, "AssistanceUpdate": { "type": "object", "properties": { "version": { "type": "integer", "minimum": 0, "description": "Current optimistic-concurrency version. Read the object before a guarded change; a stale version conflicts." }, "overseer": { "type": "boolean", "description": "Whether OSS Coordinator is enabled in this workspace. The wire name is retained for compatibility." } }, "required": [], "additionalProperties": false }, "FleetAgent": { "type": "object", "properties": { "agent": { "$ref": "#/components/schemas/Agent", "description": "Stable agent external ID when enrolling; an Agent object in a Session response." }, "instances": { "type": "array", "items": { "$ref": "#/components/schemas/Instance" }, "description": "Runtime connections and their observed presence." }, "fresh": { "type": "boolean", "description": "Whether the reported runtime evidence is current." } }, "required": [], "additionalProperties": false }, "OverseerInput": { "type": "object", "properties": { "prompt": { "type": "string", "maxLength": 4000, "description": "Instruction to Coordinator. The engine supplies only currently permitted specialist context." }, "target": { "$ref": "#/components/schemas/Target", "description": "Target kind and stable ID. Choose a new target or an existing conversation, not both." }, "previous_plan_id": { "type": "string", "description": "Optional prior plan belonging to the caller for continuing permitted context." } }, "required": [ "prompt" ], "additionalProperties": false }, "OverseerDispatch": { "type": "object", "properties": { "agent_id": { "type": "string", "description": "Logical agent identity ID, shared by its runtime instances." }, "conversation_id": { "type": "string", "description": "Canonical conversation ID. Use it to continue the same authorized history." }, "request_id": { "type": "string", "description": "Canonical durable request ID. This is not a worker delivery ID." } }, "required": [], "additionalProperties": false }, "OverseerPlan": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable identifier returned by the engine. Treat it as opaque." }, "prompt": { "type": "string", "description": "Instruction to Coordinator. The engine supplies only currently permitted specialist context." }, "context_agent_ids": { "type": "array", "items": { "type": "string" }, "description": "Agent IDs included in the current permitted plan context." }, "target": { "$ref": "#/components/schemas/Target", "description": "Target kind and stable ID. Choose a new target or an existing conversation, not both." }, "operation": { "enum": [ "status", "message", "question", "task" ], "description": "Requested operation, with values defined by that endpoint." }, "summary": { "type": "string", "description": "Plan explanation or status answer, as defined by its operation." }, "body": { "type": "string", "description": "Message or request content, bounded to 32 KiB of UTF-8 bytes." }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/FleetAgent" }, "description": "Authorized specialist context used for this plan, not omniscient agent execution state." }, "requires_confirmation": { "type": "boolean", "description": "Whether this saved plan needs explicit confirmation before dispatch." }, "created_at": { "type": "string", "description": "Creation timestamp in RFC 3339 UTC." }, "expires_at": { "type": "string", "description": "Expiry timestamp. Ordinary communication has no implicit deadline (represented as 9999-01-01T00:00:00Z). Bound action approvals default to seven days; explicit expiry must be within ninety days. Local wait timeout never changes it." }, "dispatches": { "type": "array", "items": { "$ref": "#/components/schemas/OverseerDispatch" }, "description": "Attributed conversation/request IDs created by a confirmed or automatic plan." }, "replies": { "type": "array", "items": { "$ref": "#/components/schemas/Request" }, "description": "Specialist requested decisions visible to the current caller." }, "reply_summary": { "type": "string", "description": "Model-generated summary of the authorized replies, including pending/missing evidence." }, "reply_digest": { "type": "string", "description": "Digest identifying the reply evidence used by the summary." }, "instructions": { "type": "array", "items": { "type": "object", "required": [ "agent_id", "operation", "body" ], "properties": { "agent_id": { "type": "string", "description": "Logical agent identity ID, shared by its runtime instances." }, "operation": { "enum": [ "message", "question", "task" ], "description": "Requested operation, with values defined by that endpoint." }, "body": { "type": "string", "description": "Message or request content, bounded to 32 KiB of UTF-8 bytes." } } }, "description": "Per-agent communication instructions, when different specialists need different tasks." }, "automatic": { "type": "boolean", "description": "True when Coordinator delegated without a separate review step." }, "summary_error": { "type": "string", "description": "Safe model-summary error. Existing durable instructions remain separately inspectable." } }, "required": [], "additionalProperties": false }, "Event": { "type": "object", "properties": { "sequence": { "type": "integer", "description": "Monotonically ordered canonical event sequence. Checkpoint after application processing." }, "kind": { "type": "string", "description": "Resource or operation kind. Use one of the listed values, not a display label." }, "actor_id": { "type": "string", "description": "Identity responsible for the canonical event." }, "conversation_id": { "type": "string", "description": "Canonical conversation ID. Use it to continue the same authorized history." }, "recipient_id": { "type": "string", "description": "Intended individual identity for the delivery or event projection." }, "data": { "description": "Event-specific JSON data. Full events contain the canonical payload; summary mode is smaller." }, "created_at": { "type": "string", "description": "Creation timestamp in RFC 3339 UTC." } }, "required": [], "additionalProperties": false }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable API error code for programmatic handling." }, "message": { "type": "string", "description": "Safe human-readable API error message." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "Error envelope with code and message; do not treat it as a successful result." } }, "required": [ "error" ], "additionalProperties": false }, "Mention": { "type": "object", "required": [ "principal_id", "start", "end" ], "additionalProperties": false, "properties": { "principal_id": { "type": "string", "description": "Person, agent or service identity ID. This is an API term, not a separate product entity." }, "start": { "type": "integer", "minimum": 0, "description": "Inclusive Unicode code-point offset of the mention, not a byte or UTF-16 index." }, "end": { "type": "integer", "minimum": 1, "description": "Exclusive Unicode code-point offset of the mention." } }, "description": "Stable explicit addressee. start/end are Unicode code-point offsets for the exact @name token. Must be a current visible conversation participant. All members receive the original message and may contribute." }, "ChannelPolicy": { "type": "object", "properties": { "mode": { "enum": [ "preferred", "all" ], "description": "preferred follows destination order with failure fallback and optional unanswered-request follow-up; all sends to all selected channels immediately." }, "destinations": { "type": "array", "items": { "type": "string" }, "maxItems": 16, "uniqueItems": true, "description": "Recipient-owned delivery destination IDs in preference order. An empty list keeps delivery in the workspace only." }, "followup_seconds": { "type": "integer", "minimum": 0, "maximum": 604800, "description": "0 disables unanswered-request follow-ups. Otherwise 5 to 900 seconds. Previously saved longer delays may be retained unchanged. Only questions and approvals; all mode requires 0." } }, "required": [ "mode", "destinations", "followup_seconds" ], "additionalProperties": false }, "ChannelOverride": { "type": "object", "properties": { "source": { "type": "object", "properties": { "kind": { "enum": [ "agent", "group" ], "description": "Resource or operation kind. Use one of the listed values, not a display label." }, "id": { "type": "string", "description": "Stable identifier returned by the engine. Treat it as opaque." } }, "required": [ "kind", "id" ], "additionalProperties": false, "description": "Sender selector for a channel override: an exact Agent or an Agent role group." }, "policy": { "$ref": "#/components/schemas/ChannelPolicy", "description": "Channel delivery policy. It changes delivery destinations without granting contact or decision authority." } }, "required": [ "source", "policy" ], "additionalProperties": false }, "DeliveryPreferences": { "type": "object", "properties": { "person_id": { "type": "string", "description": "Stable recipient Person identity ID." }, "version": { "type": "integer", "minimum": 0, "description": "Current optimistic-concurrency version. Read the object before a guarded change; a stale version conflicts." }, "default": { "anyOf": [ { "$ref": "#/components/schemas/ChannelPolicy" }, { "type": "null" } ], "description": "Recipient default channel policy; null preserves existing destination-based routing." }, "overrides": { "type": "array", "items": { "$ref": "#/components/schemas/ChannelOverride" }, "maxItems": 64, "description": "Ordered sender-specific delivery preferences. An exact Agent match precedes matching Agent roles, then the recipient default." } }, "required": [ "version", "default", "overrides" ], "additionalProperties": false }, "Credential": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable identifier returned by the engine. Treat it as opaque." }, "principal_id": { "type": "string", "description": "Person, agent or service identity ID. This is an API term, not a separate product entity." }, "owner_name": { "type": "string", "description": "Display name of the identity that owns the credential." }, "name": { "type": "string", "description": "Human-readable name. It is not necessarily unique." }, "kind": { "type": "string", "description": "Resource or operation kind. Use one of the listed values, not a display label." }, "prefix": { "type": "string", "description": "Permitted enrollment namespace prefix for a bounded launcher." }, "token_hint": { "type": "string", "description": "Non-secret token suffix used to identify a credential. It cannot authenticate." }, "created_at": { "type": "string", "description": "Creation timestamp in RFC 3339 UTC." }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Most recently recorded authenticated use, or null. Updates are throttled and are not an exact per-request audit trail." }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Credential expiry timestamp, or null for a non-expiring credential. Renewable worker leases remain bounded by renewable_until." }, "renewable_until": { "type": [ "string", "null" ], "format": "date-time", "description": "Hard deadline for a renewable worker credential, or null when it is not renewable." }, "previous_until": { "type": [ "string", "null" ], "format": "date-time", "description": "Deadline for the previous token during rotation overlap, or null when no previous token remains valid." }, "permissions": { "type": [ "array", "null" ], "items": { "enum": [ "read", "message", "request", "respond", "execute", "manage" ] }, "description": "Optional credential-specific restriction to read, message, request, respond, execute or manage. Underlying identity permissions still apply." }, "version": { "type": "integer", "description": "Current optimistic-concurrency version. Read the object before a guarded change; a stale version conflicts." }, "revoked": { "type": "boolean", "description": "Whether the credential has been revoked and can no longer authenticate." }, "parent_credential_id": { "type": "string", "description": "Credential that enrolled this worker, when applicable; used for optional worker revocation with the parent." } }, "required": [], "additionalProperties": false }, "IssuedCredential": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable identifier returned by the engine. Treat it as opaque." }, "kind": { "type": "string", "description": "Resource or operation kind. Use one of the listed values, not a display label." }, "token": { "type": "string", "description": "Bearer credential. Save in protected server-side storage and never expose it in browser code or logs." }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Credential expiry timestamp, or null for a non-expiring credential. Renewable worker leases remain bounded by renewable_until." } }, "required": [], "additionalProperties": false }, "CredentialReplacement": { "type": "object", "properties": { "token": { "type": "string", "description": "Bearer credential. Save in protected server-side storage and never expose it in browser code or logs." }, "credential": { "$ref": "#/components/schemas/Credential", "description": "Non-secret credential metadata returned with a newly rotated bearer token." } }, "required": [], "additionalProperties": false }, "ProviderField": { "type": "object", "properties": { "name": { "type": "string", "description": "Human-readable name. It is not necessarily unique." }, "required": { "type": "boolean", "description": "Whether this provider field must be configured." }, "secret": { "type": "boolean", "description": "Write-only provider secret. Omitted from ordinary read/setup responses." } }, "required": [], "additionalProperties": false }, "ProviderCapability": { "type": "object", "properties": { "kind": { "type": "string", "description": "Resource or operation kind. Use one of the listed values, not a display label." }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/ProviderField" }, "description": "Provider setup field definitions with types, requirements and safe constraints." }, "inbound_messages": { "type": "boolean", "description": "Whether native inbound messages are accepted." }, "native_approvals": { "type": "boolean", "description": "Whether authenticated native channel decisions are supported." }, "web_continuation": { "type": "boolean", "description": "Whether the conversation can continue in the workspace." }, "attachments": { "type": "boolean", "description": "Currently visible attachment metadata." }, "builtin": { "type": "boolean", "description": "Whether the capability is provided by the engine without a provider installation." }, "directions": { "type": "array", "items": { "type": "string" }, "description": "Supported inbound/outbound directions." }, "replies": { "type": "boolean", "description": "Specialist requested decisions visible to the current caller." }, "file_mode": { "enum": [ "native", "workspace_link" ], "description": "Actual attachment transport behavior for the provider." }, "setup_modes": { "type": "array", "items": { "type": "string" }, "description": "Supported setup methods; use only advertised modes." }, "identity": { "type": "string", "description": "Provider identity-linking requirements or current evidence." }, "constraints": { "type": "array", "items": { "type": "string" }, "description": "Provider field validation constraints." } }, "required": [], "additionalProperties": false }, "ConnectionTestEvidence": { "type": "object", "properties": { "delivery_id": { "type": "string", "description": "Transport delivery record ID. Different attempts can refer to the same canonical message/request." }, "conversation_id": { "type": "string", "description": "Canonical conversation ID. Use it to continue the same authorized history." }, "state": { "type": "string", "description": "Lifecycle state. Read the resource-specific enum; request and execution states differ." }, "detail": { "type": "string", "description": "Safe diagnostic explanation, without credentials." }, "created_at": { "type": "string", "description": "Creation timestamp in RFC 3339 UTC." }, "inbound_reply": { "type": "boolean", "description": "Whether authenticated native replies can update canonical conversations." } }, "required": [], "additionalProperties": false }, "ConnectionDiagnostic": { "type": "object", "properties": { "connection_id": { "type": "string", "description": "Configured channel connection ID." }, "version": { "type": "integer", "description": "Current optimistic-concurrency version. Read the object before a guarded change; a stale version conflicts." }, "enabled": { "type": "boolean", "description": "Whether this configured connection is enabled." }, "configuration_valid": { "type": "boolean", "description": "Whether the current non-sending configuration check passed." }, "issues": { "type": "array", "items": { "type": "string" }, "description": "Safe configuration issues that need operator attention." }, "provider_acceptance": { "enum": [ "not_tested", "observed" ], "description": "Transport acceptance evidence, separate from an attributed reply." }, "sends": { "const": false, "description": "Whether a preview itself sends anything; dispatch preview returns false." }, "state": { "enum": [ "configured", "setup_incomplete", "disconnected", "verifying", "action_needed", "connected" ], "description": "Lifecycle state. Read the resource-specific enum; request and execution states differ." }, "qualification": { "enum": [ "not_verified", "provider_acceptance_observed", "engine_round_trip_observed" ], "description": "Recorded qualification evidence level; configuration alone is not a live round trip." }, "last_test": { "$ref": "#/components/schemas/ConnectionTestEvidence", "description": "Latest explicit connection test evidence." } }, "required": [], "additionalProperties": false }, "ProviderSetup": { "type": "object", "properties": { "connection_id": { "type": "string", "description": "Configured channel connection ID." }, "kind": { "type": "string", "description": "Resource or operation kind. Use one of the listed values, not a display label." }, "version": { "type": "integer", "description": "Current optimistic-concurrency version. Read the object before a guarded change; a stale version conflicts." }, "mode": { "type": "string", "description": "primary, copy or fallback routing mode." }, "steps": { "type": "array", "items": { "type": "string" }, "description": "Ordered setup actions supported by this provider." }, "callbacks": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Safe callback URLs and verification requirements." }, "manifest": { "type": "object", "description": "Safe provider application manifest for setup." }, "registration": { "type": "object", "description": "Provider callback registration information." }, "diagnostic": { "$ref": "#/components/schemas/ConnectionDiagnostic", "description": "Non-sending configuration and identity diagnostic projection." } }, "required": [], "additionalProperties": false } }, "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer" }, "session": { "type": "apiKey", "in": "cookie", "name": "beepgrid_session" } } } }