{ "openapi": "3.1.0", "info": { "title": "Zupflow API", "version": "0.1.0", "description": "Generated from @zupflow/contract. Every response is an envelope `{ data, meta, error }`; IDs are prefixed, opaque strings.", "license": { "name": "Apache-2.0", "identifier": "Apache-2.0" } }, "servers": [ { "url": "https://api.zupflow.example" } ], "components": { "securitySchemes": { "consoleSession": { "type": "http", "scheme": "bearer", "description": "A Console session. Workspace routes also need the `organization` header." }, "organization": { "type": "apiKey", "in": "header", "name": "Zupflow-Organization", "description": "The organization a Console call acts in (`org_…`). Required with a Console session on workspace routes; 400 `organization_required` without it." }, "apiKey": { "type": "http", "scheme": "bearer", "description": "An environment-bound API key (`zf_live_…`, `zf_test_…`)." } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[\\x20-\\x7E]+$" }, "description": "Makes a retry safe: 1–255 printable ASCII characters, scoped to the caller that sent it, kept for 24 hours. The same key and request replays the saved response; the same key with a different request answers `422 idempotency_key_reused`; a key still in flight answers `409 idempotency_request_in_progress`; a malformed key answers `400 invalid_idempotency_key`. Routes marked `x-zupflow-shows-secret-once` never save their body: a retry answers `409 idempotency_key_completed`." } }, "responses": { "Error": { "description": "An error: branch on `error.code`, never on `error.message`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "type": "null" }, "meta": { "type": "null" }, "error": { "$ref": "#/components/schemas/Error" } } } } } } }, "schemas": { "AccountConnection": { "type": "object", "properties": { "account": { "$ref": "#/components/schemas/ConnectedAccount" }, "granted_scopes": { "type": "array", "items": { "type": "string" } }, "credential_version": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "connected_at": { "$ref": "#/components/schemas/Instant" }, "expires_at": { "anyOf": [ { "$ref": "#/components/schemas/Instant" }, { "type": "null" } ] } }, "required": [ "account", "granted_scopes", "credential_version", "connected_at", "expires_at" ] }, "Agent": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/AgentId" }, "workspace_id": { "$ref": "#/components/schemas/WorkspaceId" }, "name": { "type": "string" }, "description": { "type": "string" }, "model_id": { "anyOf": [ { "$ref": "#/components/schemas/ModelId" }, { "type": "null" } ] }, "instructions": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "paused" ] }, "grant_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "runs_last_24h": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "last_run_at": { "anyOf": [ { "$ref": "#/components/schemas/Instant" }, { "type": "null" } ] }, "created_at": { "$ref": "#/components/schemas/Instant" }, "updated_at": { "$ref": "#/components/schemas/Instant" } }, "required": [ "id", "workspace_id", "name", "description", "model_id", "instructions", "status", "grant_count", "runs_last_24h", "last_run_at", "created_at", "updated_at" ] }, "AgentChannel": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/AgentChannelId" }, "workspace_id": { "$ref": "#/components/schemas/WorkspaceId" }, "agent_id": { "$ref": "#/components/schemas/AgentId" }, "connection_id": { "$ref": "#/components/schemas/ChannelConnectionId" }, "tools": { "type": "array", "items": { "type": "string" } }, "approval_required": { "type": "array", "items": { "type": "string" } }, "audience": { "type": "string", "enum": [ "origin", "listed", "anywhere" ] }, "audience_conversations": { "type": "array", "items": { "$ref": "#/components/schemas/ChannelConversationId" } }, "persona": { "anyOf": [ { "$ref": "#/components/schemas/ChannelPersona" }, { "type": "null" } ] }, "answers_dms": { "type": "boolean" }, "answers_mentions": { "type": "boolean" }, "thread_follow_up": { "type": "string", "enum": [ "off", "when_last_addressed", "always" ] }, "agent_messages": { "type": "string", "enum": [ "ignore", "mentions" ] }, "max_agent_hops": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "mid_run": { "type": "string", "enum": [ "steer", "collect" ] }, "senders": { "type": "string", "enum": [ "anyone", "listed" ] }, "sender_list": { "type": "array", "items": { "type": "string" } }, "allow_automated": { "type": "boolean" }, "allow_external": { "type": "boolean" }, "reply_with_output": { "type": "boolean" }, "created_at": { "$ref": "#/components/schemas/Instant" }, "updated_at": { "$ref": "#/components/schemas/Instant" } }, "required": [ "id", "workspace_id", "agent_id", "connection_id", "tools", "approval_required", "audience", "audience_conversations", "persona", "answers_dms", "answers_mentions", "thread_follow_up", "agent_messages", "max_agent_hops", "mid_run", "senders", "sender_list", "allow_automated", "allow_external", "reply_with_output", "created_at", "updated_at" ] }, "AgentChannelId": { "type": "string", "pattern": "^agch_[0-9A-Za-z]{22}$" }, "AgentId": { "type": "string", "pattern": "^agt_[0-9A-Za-z]{22}$" }, "AnyId": { "type": "string", "pattern": "^(org|ws|usr|mem|app|inst|cs|agt|grt|run|rev|call|ses|key|we|evt|whd|aud|mcn|mdl|chmgr|chapp|chcon|agch|conv|chmsg|person)_[0-9A-Za-z]{22}$" }, "ApiKey": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/ApiKeyId" }, "organization_id": { "$ref": "#/components/schemas/OrganizationId" }, "environment": { "$ref": "#/components/schemas/Environment" }, "name": { "type": "string" }, "prefix": { "type": "string" }, "last4": { "type": "string" }, "created_by": { "$ref": "#/components/schemas/User" }, "created_at": { "$ref": "#/components/schemas/Instant" }, "last_used_at": { "anyOf": [ { "$ref": "#/components/schemas/Instant" }, { "type": "null" } ] }, "revoked_at": { "anyOf": [ { "$ref": "#/components/schemas/Instant" }, { "type": "null" } ] } }, "required": [ "id", "organization_id", "environment", "name", "prefix", "last4", "created_by", "created_at", "last_used_at", "revoked_at" ] }, "ApiKeyId": { "type": "string", "pattern": "^key_[0-9A-Za-z]{22}$" }, "App": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/AppId" }, "organization_id": { "$ref": "#/components/schemas/OrganizationId" }, "owner_workspace_id": { "anyOf": [ { "$ref": "#/components/schemas/WorkspaceId" }, { "type": "null" } ] }, "owner_scope": { "type": "string", "enum": [ "organization", "workspace" ] }, "kind": { "type": "string", "enum": [ "mcp" ] }, "name": { "type": "string" }, "key": { "$ref": "#/components/schemas/AppKey" }, "description": { "type": "string" }, "icon": { "$ref": "#/components/schemas/AppIcon" }, "auth": { "$ref": "#/components/schemas/AuthTemplate" }, "tools": { "type": "array", "items": { "$ref": "#/components/schemas/ToolDefinition" } }, "version": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "configurations": { "type": "array", "items": { "$ref": "#/components/schemas/ConfigurationSummary" } }, "installation_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "created_at": { "$ref": "#/components/schemas/Instant" }, "updated_at": { "$ref": "#/components/schemas/Instant" } }, "required": [ "id", "organization_id", "owner_workspace_id", "owner_scope", "kind", "name", "key", "description", "icon", "auth", "tools", "version", "configurations", "installation_count", "created_at", "updated_at" ] }, "AppIcon": { "type": "object", "properties": { "glyph": { "type": "string" }, "color": { "type": "string" } }, "required": [ "glyph", "color" ] }, "AppId": { "type": "string", "pattern": "^app_[0-9A-Za-z]{22}$" }, "AppInstallationRef": { "type": "object", "properties": { "installation": { "$ref": "#/components/schemas/Installation" }, "workspace": { "$ref": "#/components/schemas/WorkspaceRef" } }, "required": [ "installation", "workspace" ] }, "AppKey": { "type": "string", "minLength": 1, "maxLength": 24, "pattern": "^[a-z][a-z0-9]*(_[a-z0-9]+)*$" }, "AppToolLevel": { "type": "object", "properties": { "app_id": { "$ref": "#/components/schemas/AppId" }, "tool": { "type": "string" }, "level": { "type": "string", "enum": [ "allow", "approve", "deny" ] }, "confirmed": { "type": "boolean" }, "destructive": { "type": "boolean" }, "updated_at": { "$ref": "#/components/schemas/Instant" }, "updated_by": { "anyOf": [ { "$ref": "#/components/schemas/User" }, { "type": "null" } ] } }, "required": [ "app_id", "tool", "level", "confirmed", "destructive", "updated_at", "updated_by" ] }, "AppToolsChangedWebhookEvent": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/WebhookEventId" }, "created_at": { "$ref": "#/components/schemas/Instant" }, "environment": { "$ref": "#/components/schemas/Environment" }, "organization_id": { "$ref": "#/components/schemas/OrganizationId" }, "type": { "type": "string", "const": "app.tools_changed" }, "workspace": { "$ref": "#/components/schemas/WebhookEventWorkspace" }, "data": { "type": "object", "properties": { "object": { "type": "string", "const": "installation" }, "id": { "$ref": "#/components/schemas/InstallationId" }, "app_id": { "$ref": "#/components/schemas/AppId" }, "status": { "type": "string", "enum": [ "connected" ] } }, "required": [ "object", "id", "app_id", "status" ] } }, "required": [ "id", "created_at", "environment", "organization_id", "type", "workspace", "data" ] }, "AuditEvent": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/AuditEventId" }, "organization_id": { "$ref": "#/components/schemas/OrganizationId" }, "workspace_id": { "anyOf": [ { "$ref": "#/components/schemas/WorkspaceId" }, { "type": "null" } ] }, "workspace": { "anyOf": [ { "$ref": "#/components/schemas/WorkspaceRef" }, { "type": "null" } ] }, "environment": { "anyOf": [ { "$ref": "#/components/schemas/Environment" }, { "type": "null" } ] }, "actor": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "user", "api_key", "system" ] }, "id": { "anyOf": [ { "$ref": "#/components/schemas/AnyId" }, { "type": "null" } ] }, "name": { "type": "string" } }, "required": [ "type", "id", "name" ] }, "action": { "type": "string" }, "target": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "anyOf": [ { "$ref": "#/components/schemas/AnyId" }, { "type": "null" } ] }, "name": { "type": "string" } }, "required": [ "type", "id", "name" ] }, "created_at": { "$ref": "#/components/schemas/Instant" } }, "required": [ "id", "organization_id", "workspace_id", "workspace", "environment", "actor", "action", "target", "created_at" ] }, "AuditEventId": { "type": "string", "pattern": "^aud_[0-9A-Za-z]{22}$" }, "AuthorizeConnectResult": { "type": "object", "properties": { "authorization_url": { "type": "string", "format": "uri" } }, "required": [ "authorization_url" ] }, "AuthTemplate": { "oneOf": [ { "$ref": "#/components/schemas/OAuthAuthTemplate" }, { "$ref": "#/components/schemas/McpOAuthAuthTemplate" }, { "$ref": "#/components/schemas/TokenAuthTemplate" } ] }, "AvailableApp": { "type": "object", "properties": { "app": { "$ref": "#/components/schemas/App" }, "configuration": { "$ref": "#/components/schemas/ConfigurationSummary" } }, "required": [ "app", "configuration" ] }, "ChannelApp": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/ChannelAppId" }, "workspace_id": { "$ref": "#/components/schemas/WorkspaceId" }, "manager_id": { "$ref": "#/components/schemas/ChannelAppManagerId" }, "agent_id": { "$ref": "#/components/schemas/AgentId" }, "provider": { "$ref": "#/components/schemas/ChannelProvider" }, "external_app_id": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "creating", "awaiting_install", "installed", "updating", "deleting", "deleted", "failed" ] }, "last_error": { "type": [ "string", "null" ] }, "connection_id": { "anyOf": [ { "$ref": "#/components/schemas/ChannelConnectionId" }, { "type": "null" } ] }, "created_at": { "$ref": "#/components/schemas/Instant" }, "updated_at": { "$ref": "#/components/schemas/Instant" } }, "required": [ "id", "workspace_id", "manager_id", "agent_id", "provider", "external_app_id", "status", "last_error", "connection_id", "created_at", "updated_at" ] }, "ChannelAppId": { "type": "string", "pattern": "^chapp_[0-9A-Za-z]{22}$" }, "ChannelAppManager": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/ChannelAppManagerId" }, "workspace_id": { "$ref": "#/components/schemas/WorkspaceId" }, "provider": { "$ref": "#/components/schemas/ChannelProvider" }, "method": { "type": "string", "enum": [ "configuration_token" ] }, "team": { "$ref": "#/components/schemas/ChannelTeam" }, "status": { "type": "string", "enum": [ "active", "token_expired", "disconnected" ] }, "configuration_token": { "$ref": "#/components/schemas/SecretState" }, "token_expires_at": { "anyOf": [ { "$ref": "#/components/schemas/Instant" }, { "type": "null" } ] }, "app_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "created_by": { "anyOf": [ { "$ref": "#/components/schemas/User" }, { "type": "null" } ] }, "created_at": { "$ref": "#/components/schemas/Instant" }, "updated_at": { "$ref": "#/components/schemas/Instant" } }, "required": [ "id", "workspace_id", "provider", "method", "team", "status", "configuration_token", "token_expires_at", "app_count", "created_by", "created_at", "updated_at" ] }, "ChannelAppManagerConnectResult": { "type": "object", "properties": { "session": { "$ref": "#/components/schemas/ConnectSession" }, "channel_app_manager": { "$ref": "#/components/schemas/ChannelAppManager" } }, "required": [ "session", "channel_app_manager" ] }, "ChannelAppManagerId": { "type": "string", "pattern": "^chmgr_[0-9A-Za-z]{22}$" }, "ChannelAppManagerStatusChangedWebhookEvent": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/WebhookEventId" }, "created_at": { "$ref": "#/components/schemas/Instant" }, "environment": { "$ref": "#/components/schemas/Environment" }, "organization_id": { "$ref": "#/components/schemas/OrganizationId" }, "type": { "type": "string", "const": "channel_app_manager.status_changed" }, "workspace": { "$ref": "#/components/schemas/WebhookEventWorkspace" }, "data": { "type": "object", "properties": { "object": { "type": "string", "const": "channel_app_manager" }, "id": { "$ref": "#/components/schemas/ChannelAppManagerId" }, "status": { "type": "string", "enum": [ "active", "token_expired", "disconnected" ] } }, "required": [ "object", "id", "status" ] } }, "required": [ "id", "created_at", "environment", "organization_id", "type", "workspace", "data" ] }, "ChannelAppStatusChangedWebhookEvent": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/WebhookEventId" }, "created_at": { "$ref": "#/components/schemas/Instant" }, "environment": { "$ref": "#/components/schemas/Environment" }, "organization_id": { "$ref": "#/components/schemas/OrganizationId" }, "type": { "type": "string", "const": "channel_app.status_changed" }, "workspace": { "$ref": "#/components/schemas/WebhookEventWorkspace" }, "data": { "type": "object", "properties": { "object": { "type": "string", "const": "channel_app" }, "id": { "$ref": "#/components/schemas/ChannelAppId" }, "agent_id": { "$ref": "#/components/schemas/AgentId" }, "status": { "type": "string", "enum": [ "creating", "awaiting_install", "installed", "updating", "deleting", "deleted", "failed" ] } }, "required": [ "object", "id", "agent_id", "status" ] } }, "required": [ "id", "created_at", "environment", "organization_id", "type", "workspace", "data" ] }, "ChannelConnection": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/ChannelConnectionId" }, "workspace_id": { "$ref": "#/components/schemas/WorkspaceId" }, "provider": { "$ref": "#/components/schemas/ChannelProvider" }, "app_id": { "anyOf": [ { "$ref": "#/components/schemas/ChannelAppId" }, { "type": "null" } ] }, "agent_id": { "anyOf": [ { "$ref": "#/components/schemas/AgentId" }, { "type": "null" } ] }, "short_id": { "$ref": "#/components/schemas/InstallationShortId" }, "label": { "type": "string" }, "handler": { "type": "string", "enum": [ "mention" ] }, "status": { "type": "string", "enum": [ "connected", "reconnect_required", "disconnected" ] }, "team": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "enterprise_id": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "enterprise_id" ] }, "identity": { "type": "object", "properties": { "external_id": { "type": "string" }, "handle": { "type": "string" } }, "required": [ "external_id", "handle" ] }, "granted_scopes": { "type": "array", "items": { "type": "string" } }, "connected_at": { "anyOf": [ { "$ref": "#/components/schemas/Instant" }, { "type": "null" } ] }, "last_event_at": { "anyOf": [ { "$ref": "#/components/schemas/Instant" }, { "type": "null" } ] }, "created_at": { "$ref": "#/components/schemas/Instant" }, "updated_at": { "$ref": "#/components/schemas/Instant" } }, "required": [ "id", "workspace_id", "provider", "app_id", "agent_id", "short_id", "label", "handler", "status", "team", "identity", "granted_scopes", "connected_at", "last_event_at", "created_at", "updated_at" ] }, "ChannelConnectionConnectResult": { "type": "object", "properties": { "session": { "$ref": "#/components/schemas/ConnectSession" }, "channel_connection": { "$ref": "#/components/schemas/ChannelConnection" } }, "required": [ "session", "channel_connection" ] }, "ChannelConnectionId": { "type": "string", "pattern": "^chcon_[0-9A-Za-z]{22}$" }, "ChannelConnectionStatusChangedWebhookEvent": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/WebhookEventId" }, "created_at": { "$ref": "#/components/schemas/Instant" }, "environment": { "$ref": "#/components/schemas/Environment" }, "organization_id": { "$ref": "#/components/schemas/OrganizationId" }, "type": { "type": "string", "const": "channel_connection.status_changed" }, "workspace": { "$ref": "#/components/schemas/WebhookEventWorkspace" }, "data": { "type": "object", "properties": { "object": { "type": "string", "const": "channel_connection" }, "id": { "$ref": "#/components/schemas/ChannelConnectionId" }, "app_id": { "anyOf": [ { "$ref": "#/components/schemas/ChannelAppId" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "connected", "reconnect_required", "disconnected" ] } }, "required": [ "object", "id", "app_id", "status" ] } }, "required": [ "id", "created_at", "environment", "organization_id", "type", "workspace", "data" ] }, "ChannelConversation": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/ChannelConversationId" }, "workspace_id": { "$ref": "#/components/schemas/WorkspaceId" }, "connection_id": { "$ref": "#/components/schemas/ChannelConnectionId" }, "external_id": { "type": "string" }, "kind": { "type": "string", "enum": [ "channel", "private_channel", "dm", "group_dm" ] }, "name": { "type": [ "string", "null" ] }, "is_external": { "type": "boolean" }, "identity_is_member": { "type": "boolean" }, "last_message_at": { "anyOf": [ { "$ref": "#/components/schemas/Instant" }, { "type": "null" } ] }, "paused_until": { "anyOf": [ { "$ref": "#/components/schemas/Instant" }, { "type": "null" } ] }, "created_at": { "$ref": "#/components/schemas/Instant" } }, "required": [ "id", "workspace_id", "connection_id", "external_id", "kind", "name", "is_external", "identity_is_member", "last_message_at", "paused_until", "created_at" ] }, "ChannelConversationId": { "type": "string", "pattern": "^conv_[0-9A-Za-z]{22}$" }, "ChannelConversationPausedWebhookEvent": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/WebhookEventId" }, "created_at": { "$ref": "#/components/schemas/Instant" }, "environment": { "$ref": "#/components/schemas/Environment" }, "organization_id": { "$ref": "#/components/schemas/OrganizationId" }, "type": { "type": "string", "const": "channel_conversation.paused" }, "workspace": { "$ref": "#/components/schemas/WebhookEventWorkspace" }, "data": { "type": "object", "properties": { "object": { "type": "string", "const": "channel_conversation" }, "id": { "$ref": "#/components/schemas/ChannelConversationId" }, "connection_id": { "$ref": "#/components/schemas/ChannelConnectionId" }, "paused_until": { "$ref": "#/components/schemas/Instant" } }, "required": [ "object", "id", "connection_id", "paused_until" ] } }, "required": [ "id", "created_at", "environment", "organization_id", "type", "workspace", "data" ] }, "ChannelInboundAnswer": { "type": "object", "properties": { "challenge": { "type": [ "string", "null" ] } }, "required": [ "challenge" ] }, "ChannelMessage": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/ChannelMessageId" }, "workspace_id": { "$ref": "#/components/schemas/WorkspaceId" }, "connection_id": { "$ref": "#/components/schemas/ChannelConnectionId" }, "conversation_id": { "$ref": "#/components/schemas/ChannelConversationId" }, "external_id": { "type": "string" }, "thread_key": { "type": "string" }, "direction": { "type": "string", "enum": [ "inbound", "outbound" ] }, "author": { "anyOf": [ { "$ref": "#/components/schemas/ChannelPerson" }, { "type": "null" } ] }, "text": { "type": "string" }, "mentions": { "type": "array", "items": { "type": "string" } }, "run_id": { "anyOf": [ { "$ref": "#/components/schemas/RunId" }, { "type": "null" } ] }, "tool_call_id": { "anyOf": [ { "$ref": "#/components/schemas/ToolCallId" }, { "type": "null" } ] }, "agent_hop": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "sent_at": { "$ref": "#/components/schemas/Instant" }, "edited_at": { "anyOf": [ { "$ref": "#/components/schemas/Instant" }, { "type": "null" } ] }, "deleted_at": { "anyOf": [ { "$ref": "#/components/schemas/Instant" }, { "type": "null" } ] }, "created_at": { "$ref": "#/components/schemas/Instant" } }, "required": [ "id", "workspace_id", "connection_id", "conversation_id", "external_id", "thread_key", "direction", "author", "text", "mentions", "run_id", "tool_call_id", "agent_hop", "sent_at", "edited_at", "deleted_at", "created_at" ] }, "ChannelMessageId": { "type": "string", "pattern": "^chmsg_[0-9A-Za-z]{22}$" }, "ChannelMessageReceivedWebhookEvent": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/WebhookEventId" }, "created_at": { "$ref": "#/components/schemas/Instant" }, "environment": { "$ref": "#/components/schemas/Environment" }, "organization_id": { "$ref": "#/components/schemas/OrganizationId" }, "type": { "type": "string", "const": "channel_message.received" }, "workspace": { "$ref": "#/components/schemas/WebhookEventWorkspace" }, "data": { "type": "object", "properties": { "object": { "type": "string", "const": "channel_message" }, "id": { "$ref": "#/components/schemas/ChannelMessageId" }, "connection_id": { "$ref": "#/components/schemas/ChannelConnectionId" }, "conversation_id": { "$ref": "#/components/schemas/ChannelConversationId" } }, "required": [ "object", "id", "connection_id", "conversation_id" ] } }, "required": [ "id", "created_at", "environment", "organization_id", "type", "workspace", "data" ] }, "ChannelMessageSentWebhookEvent": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/WebhookEventId" }, "created_at": { "$ref": "#/components/schemas/Instant" }, "environment": { "$ref": "#/components/schemas/Environment" }, "organization_id": { "$ref": "#/components/schemas/OrganizationId" }, "type": { "type": "string", "const": "channel_message.sent" }, "workspace": { "$ref": "#/components/schemas/WebhookEventWorkspace" }, "data": { "type": "object", "properties": { "object": { "type": "string", "const": "channel_message" }, "id": { "$ref": "#/components/schemas/ChannelMessageId" }, "connection_id": { "$ref": "#/components/schemas/ChannelConnectionId" }, "conversation_id": { "$ref": "#/components/schemas/ChannelConversationId" } }, "required": [ "object", "id", "connection_id", "conversation_id" ] } }, "required": [ "id", "created_at", "environment", "organization_id", "type", "workspace", "data" ] }, "ChannelPerson": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/ChannelPersonId" }, "handle": { "type": [ "string", "null" ] }, "display_name": { "type": [ "string", "null" ] }, "is_automated": { "type": "boolean" } }, "required": [ "id", "handle", "display_name", "is_automated" ] }, "ChannelPersona": { "type": "object", "properties": { "name": { "type": "string" }, "avatar_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] } }, "required": [ "name", "avatar_url" ] }, "ChannelPersonId": { "type": "string", "pattern": "^person_[0-9A-Za-z]{22}$" }, "ChannelProvider": { "type": "string", "enum": [ "slack" ] }, "ChannelSettings": { "type": "object", "properties": { "organization_id": { "$ref": "#/components/schemas/OrganizationId" }, "breaker_runs": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "breaker_window_minutes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "breaker_pause_minutes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "message_retention_days": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "updated_at": { "anyOf": [ { "$ref": "#/components/schemas/Instant" }, { "type": "null" } ] }, "updated_by": { "anyOf": [ { "$ref": "#/components/schemas/User" }, { "type": "null" } ] } }, "required": [ "organization_id", "breaker_runs", "breaker_window_minutes", "breaker_pause_minutes", "message_retention_days", "updated_at", "updated_by" ] }, "ChannelTeam": { "type": "object", "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "ChannelToolLevel": { "type": "object", "properties": { "provider": { "$ref": "#/components/schemas/ChannelProvider" }, "tool": { "type": "string" }, "level": { "type": "string", "enum": [ "allow", "approve", "deny" ] }, "confirmed": { "type": "boolean" }, "effect": { "type": "string", "enum": [ "read", "write", "destructive" ] }, "updated_at": { "anyOf": [ { "$ref": "#/components/schemas/Instant" }, { "type": "null" } ] }, "updated_by": { "anyOf": [ { "$ref": "#/components/schemas/User" }, { "type": "null" } ] } }, "required": [ "provider", "tool", "level", "confirmed", "effect", "updated_at", "updated_by" ] }, "ClientConfiguration": { "type": "object", "properties": { "app_id": { "$ref": "#/components/schemas/AppId" }, "environment": { "$ref": "#/components/schemas/Environment" }, "status": { "type": "string", "enum": [ "unconfigured", "incomplete", "ready" ] }, "version": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "mcp": { "type": "object", "properties": { "server_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "transport": { "type": "string", "const": "streamable_http" } }, "required": [ "server_url", "transport" ] }, "oauth": { "anyOf": [ { "type": "object", "properties": { "client_id": { "type": [ "string", "null" ] }, "client_secret": { "$ref": "#/components/schemas/SecretState" }, "redirect_uri": { "type": "string", "format": "uri" }, "scopes": { "type": "array", "items": { "type": "string" } } }, "required": [ "client_id", "client_secret", "redirect_uri", "scopes" ] }, { "type": "null" } ] }, "missing": { "type": "array", "items": { "type": "string" } }, "updated_at": { "anyOf": [ { "$ref": "#/components/schemas/Instant" }, { "type": "null" } ] }, "updated_by": { "anyOf": [ { "$ref": "#/components/schemas/User" }, { "type": "null" } ] } }, "required": [ "app_id", "environment", "status", "version", "mcp", "oauth", "missing", "updated_at", "updated_by" ] }, "ConfigurationSummary": { "type": "object", "properties": { "environment": { "$ref": "#/components/schemas/Environment" }, "status": { "type": "string", "enum": [ "unconfigured", "incomplete", "ready" ] }, "version": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "updated_at": { "anyOf": [ { "$ref": "#/components/schemas/Instant" }, { "type": "null" } ] } }, "required": [ "environment", "status", "version", "updated_at" ] }, "ConnectedAccount": { "type": "object", "properties": { "external_id": { "type": "string" }, "display_name": { "type": "string" }, "email": { "anyOf": [ { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "null" } ] } }, "required": [ "external_id", "display_name", "email" ] }, "ConnectResult": { "anyOf": [ { "$ref": "#/components/schemas/InstallationConnectResult" }, { "$ref": "#/components/schemas/ChannelAppManagerConnectResult" }, { "$ref": "#/components/schemas/ChannelConnectionConnectResult" } ] }, "ConnectSession": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/ConnectSessionId" }, "workspace_id": { "$ref": "#/components/schemas/WorkspaceId" }, "environment": { "$ref": "#/components/schemas/Environment" }, "app": { "anyOf": [ { "$ref": "#/components/schemas/InstallationApp" }, { "type": "null" } ] }, "target": { "anyOf": [ { "$ref": "#/components/schemas/ConnectTarget" }, { "type": "null" } ] }, "intent": { "type": "string", "enum": [ "create", "reconnect" ] }, "installation_id": { "anyOf": [ { "$ref": "#/components/schemas/InstallationId" }, { "type": "null" } ] }, "label": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "completed", "expired", "cancelled", "failed" ] }, "return_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "created_at": { "$ref": "#/components/schemas/Instant" }, "expires_at": { "$ref": "#/components/schemas/Instant" }, "completed_at": { "anyOf": [ { "$ref": "#/components/schemas/Instant" }, { "type": "null" } ] }, "failure_code": { "type": [ "string", "null" ] }, "auth": { "anyOf": [ { "$ref": "#/components/schemas/AuthTemplate" }, { "type": "null" } ] }, "requested_scopes": { "type": "array", "items": { "type": "string" } }, "expected_account": { "anyOf": [ { "$ref": "#/components/schemas/ConnectedAccount" }, { "type": "null" } ] } }, "required": [ "id", "workspace_id", "environment", "app", "target", "intent", "installation_id", "label", "status", "return_url", "created_at", "expires_at", "completed_at", "failure_code", "auth", "requested_scopes", "expected_account" ] }, "ConnectSessionCompletedWebhookEvent": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/WebhookEventId" }, "created_at": { "$ref": "#/components/schemas/Instant" }, "environment": { "$ref": "#/components/schemas/Environment" }, "organization_id": { "$ref": "#/components/schemas/OrganizationId" }, "type": { "type": "string", "const": "connect_session.completed" }, "workspace": { "$ref": "#/components/schemas/WebhookEventWorkspace" }, "data": { "type": "object", "properties": { "object": { "type": "string", "const": "connect_session" }, "id": { "$ref": "#/components/schemas/ConnectSessionId" }, "status": { "type": "string", "enum": [ "completed" ] }, "installation_id": { "anyOf": [ { "$ref": "#/components/schemas/InstallationId" }, { "type": "null" } ] }, "target": { "anyOf": [ { "$ref": "#/components/schemas/ConnectTarget" }, { "type": "null" } ] }, "failure_code": { "type": [ "string", "null" ] } }, "required": [ "object", "id", "status", "installation_id", "target", "failure_code" ] } }, "required": [ "id", "created_at", "environment", "organization_id", "type", "workspace", "data" ] }, "ConnectSessionFailedWebhookEvent": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/WebhookEventId" }, "created_at": { "$ref": "#/components/schemas/Instant" }, "environment": { "$ref": "#/components/schemas/Environment" }, "organization_id": { "$ref": "#/components/schemas/OrganizationId" }, "type": { "type": "string", "const": "connect_session.failed" }, "workspace": { "$ref": "#/components/schemas/WebhookEventWorkspace" }, "data": { "type": "object", "properties": { "object": { "type": "string", "const": "connect_session" }, "id": { "$ref": "#/components/schemas/ConnectSessionId" }, "status": { "type": "string", "enum": [ "failed", "expired", "cancelled" ] }, "installation_id": { "anyOf": [ { "$ref": "#/components/schemas/InstallationId" }, { "type": "null" } ] }, "target": { "anyOf": [ { "$ref": "#/components/schemas/ConnectTarget" }, { "type": "null" } ] }, "failure_code": { "type": [ "string", "null" ] } }, "required": [ "object", "id", "status", "installation_id", "target", "failure_code" ] } }, "required": [ "id", "created_at", "environment", "organization_id", "type", "workspace", "data" ] }, "ConnectSessionId": { "type": "string", "pattern": "^cs_[0-9A-Za-z]{22}$" }, "ConnectSettings": { "type": "object", "properties": { "environment": { "$ref": "#/components/schemas/Environment" }, "return_urls": { "type": "array", "items": { "type": "string", "format": "uri" } }, "allowed_origins": { "type": "array", "items": { "type": "string" } }, "updated_at": { "anyOf": [ { "$ref": "#/components/schemas/Instant" }, { "type": "null" } ] } }, "required": [ "environment", "return_urls", "allowed_origins", "updated_at" ] }, "ConnectTarget": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "channel_app_manager" }, "provider": { "$ref": "#/components/schemas/ChannelProvider" }, "manager": { "anyOf": [ { "$ref": "#/components/schemas/ChannelAppManagerId" }, { "type": "null" } ] } }, "required": [ "kind", "provider", "manager" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "channel_app" }, "provider": { "$ref": "#/components/schemas/ChannelProvider" }, "app": { "$ref": "#/components/schemas/ChannelAppId" }, "connection": { "anyOf": [ { "$ref": "#/components/schemas/ChannelConnectionId" }, { "type": "null" } ] } }, "required": [ "kind", "provider", "app", "connection" ] } ] }, "CreatedApiKey": { "type": "object", "properties": { "key": { "$ref": "#/components/schemas/ApiKey" }, "secret": { "type": "string" } }, "required": [ "key", "secret" ] }, "CreatedConnectSession": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/ConnectSessionId" }, "workspace_id": { "$ref": "#/components/schemas/WorkspaceId" }, "environment": { "$ref": "#/components/schemas/Environment" }, "app": { "anyOf": [ { "$ref": "#/components/schemas/InstallationApp" }, { "type": "null" } ] }, "target": { "anyOf": [ { "$ref": "#/components/schemas/ConnectTarget" }, { "type": "null" } ] }, "intent": { "type": "string", "enum": [ "create", "reconnect" ] }, "installation_id": { "anyOf": [ { "$ref": "#/components/schemas/InstallationId" }, { "type": "null" } ] }, "label": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "completed", "expired", "cancelled", "failed" ] }, "return_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "created_at": { "$ref": "#/components/schemas/Instant" }, "expires_at": { "$ref": "#/components/schemas/Instant" }, "completed_at": { "anyOf": [ { "$ref": "#/components/schemas/Instant" }, { "type": "null" } ] }, "failure_code": { "type": [ "string", "null" ] }, "auth": { "anyOf": [ { "$ref": "#/components/schemas/AuthTemplate" }, { "type": "null" } ] }, "requested_scopes": { "type": "array", "items": { "type": "string" } }, "expected_account": { "anyOf": [ { "$ref": "#/components/schemas/ConnectedAccount" }, { "type": "null" } ] }, "url": { "type": "string", "format": "uri" } }, "required": [ "id", "workspace_id", "environment", "app", "target", "intent", "installation_id", "label", "status", "return_url", "created_at", "expires_at", "completed_at", "failure_code", "auth", "requested_scopes", "expected_account", "url" ] }, "CreatedWebhookEndpoint": { "type": "object", "properties": { "endpoint": { "$ref": "#/components/schemas/WebhookEndpoint" }, "signing_secret": { "type": "string" } }, "required": [ "endpoint", "signing_secret" ] }, "DefaultModel": { "type": "object", "properties": { "environment": { "$ref": "#/components/schemas/Environment" }, "model": { "anyOf": [ { "$ref": "#/components/schemas/Model" }, { "type": "null" } ] }, "updated_at": { "anyOf": [ { "$ref": "#/components/schemas/Instant" }, { "type": "null" } ] }, "updated_by": { "anyOf": [ { "$ref": "#/components/schemas/User" }, { "type": "null" } ] } }, "required": [ "environment", "model", "updated_at", "updated_by" ] }, "Environment": { "type": "string", "enum": [ "sandbox", "production" ] }, "Error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "fields": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, { "type": "null" } ] } }, "required": [ "code", "message", "fields" ] }, "Grant": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/GrantId" }, "workspace_id": { "$ref": "#/components/schemas/WorkspaceId" }, "agent_id": { "$ref": "#/components/schemas/AgentId" }, "installation_id": { "$ref": "#/components/schemas/InstallationId" }, "tools": { "type": "array", "items": { "type": "string" } }, "approval_required": { "type": "array", "items": { "type": "string" } }, "created_at": { "$ref": "#/components/schemas/Instant" }, "updated_at": { "$ref": "#/components/schemas/Instant" } }, "required": [ "id", "workspace_id", "agent_id", "installation_id", "tools", "approval_required", "created_at", "updated_at" ] }, "GrantId": { "type": "string", "pattern": "^grt_[0-9A-Za-z]{22}$" }, "Installation": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/InstallationId" }, "workspace_id": { "$ref": "#/components/schemas/WorkspaceId" }, "app": { "$ref": "#/components/schemas/InstallationApp" }, "short_id": { "$ref": "#/components/schemas/InstallationShortId" }, "label": { "type": "string" }, "status": { "type": "string", "enum": [ "connected", "reconnect_required", "disconnected" ] }, "configuration_version": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "connection": { "anyOf": [ { "$ref": "#/components/schemas/AccountConnection" }, { "type": "null" } ] }, "grant_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "created_at": { "$ref": "#/components/schemas/Instant" }, "updated_at": { "$ref": "#/components/schemas/Instant" } }, "required": [ "id", "workspace_id", "app", "short_id", "label", "status", "configuration_version", "connection", "grant_count", "created_at", "updated_at" ] }, "InstallationApp": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/AppId" }, "name": { "type": "string" }, "key": { "$ref": "#/components/schemas/AppKey" }, "owner_scope": { "type": "string", "enum": [ "organization", "workspace" ] }, "icon": { "$ref": "#/components/schemas/AppIcon" }, "auth_type": { "type": "string", "enum": [ "oauth2", "mcp_oauth", "token" ] } }, "required": [ "id", "name", "key", "owner_scope", "icon", "auth_type" ] }, "InstallationConnectedWebhookEvent": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/WebhookEventId" }, "created_at": { "$ref": "#/components/schemas/Instant" }, "environment": { "$ref": "#/components/schemas/Environment" }, "organization_id": { "$ref": "#/components/schemas/OrganizationId" }, "type": { "type": "string", "const": "installation.connected" }, "workspace": { "$ref": "#/components/schemas/WebhookEventWorkspace" }, "data": { "type": "object", "properties": { "object": { "type": "string", "const": "installation" }, "id": { "$ref": "#/components/schemas/InstallationId" }, "app_id": { "$ref": "#/components/schemas/AppId" }, "status": { "type": "string", "enum": [ "connected" ] } }, "required": [ "object", "id", "app_id", "status" ] } }, "required": [ "id", "created_at", "environment", "organization_id", "type", "workspace", "data" ] }, "InstallationConnectResult": { "type": "object", "properties": { "session": { "$ref": "#/components/schemas/ConnectSession" }, "installation": { "$ref": "#/components/schemas/Installation" } }, "required": [ "session", "installation" ] }, "InstallationDisconnectedWebhookEvent": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/WebhookEventId" }, "created_at": { "$ref": "#/components/schemas/Instant" }, "environment": { "$ref": "#/components/schemas/Environment" }, "organization_id": { "$ref": "#/components/schemas/OrganizationId" }, "type": { "type": "string", "const": "installation.disconnected" }, "workspace": { "$ref": "#/components/schemas/WebhookEventWorkspace" }, "data": { "type": "object", "properties": { "object": { "type": "string", "const": "installation" }, "id": { "$ref": "#/components/schemas/InstallationId" }, "app_id": { "$ref": "#/components/schemas/AppId" }, "status": { "type": "string", "enum": [ "disconnected" ] } }, "required": [ "object", "id", "app_id", "status" ] } }, "required": [ "id", "created_at", "environment", "organization_id", "type", "workspace", "data" ] }, "InstallationId": { "type": "string", "pattern": "^inst_[0-9A-Za-z]{22}$" }, "InstallationReconnectRequiredWebhookEvent": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/WebhookEventId" }, "created_at": { "$ref": "#/components/schemas/Instant" }, "environment": { "$ref": "#/components/schemas/Environment" }, "organization_id": { "$ref": "#/components/schemas/OrganizationId" }, "type": { "type": "string", "const": "installation.reconnect_required" }, "workspace": { "$ref": "#/components/schemas/WebhookEventWorkspace" }, "data": { "type": "object", "properties": { "object": { "type": "string", "const": "installation" }, "id": { "$ref": "#/components/schemas/InstallationId" }, "app_id": { "$ref": "#/components/schemas/AppId" }, "status": { "type": "string", "enum": [ "reconnect_required" ] } }, "required": [ "object", "id", "app_id", "status" ] } }, "required": [ "id", "created_at", "environment", "organization_id", "type", "workspace", "data" ] }, "InstallationShortId": { "type": "string", "pattern": "^[a-z2-7]{6}$" }, "InstallationTool": { "type": "object", "properties": { "name": { "type": "string" }, "effect": { "type": "string", "enum": [ "read", "write", "destructive" ] }, "status": { "type": "string", "enum": [ "current", "changed", "gone" ] }, "pinned": { "$ref": "#/components/schemas/ToolText" }, "pinned_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "latest": { "anyOf": [ { "$ref": "#/components/schemas/ToolText" }, { "type": "null" } ] }, "latest_hash": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-f]{64}$" }, { "type": "null" } ] }, "first_seen_at": { "$ref": "#/components/schemas/Instant" }, "seen_at": { "$ref": "#/components/schemas/Instant" }, "changed_at": { "anyOf": [ { "$ref": "#/components/schemas/Instant" }, { "type": "null" } ] }, "gone_at": { "anyOf": [ { "$ref": "#/components/schemas/Instant" }, { "type": "null" } ] } }, "required": [ "name", "effect", "status", "pinned", "pinned_hash", "latest", "latest_hash", "first_seen_at", "seen_at", "changed_at", "gone_at" ] }, "Instant": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "Invitation": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/MemberId" }, "organization": { "$ref": "#/components/schemas/InvitationOrganization" }, "role": { "type": "string", "enum": [ "owner", "admin", "developer", "viewer" ] }, "invited_by": { "$ref": "#/components/schemas/Inviter" }, "status": { "type": "string", "enum": [ "pending", "expired" ] }, "invited_at": { "$ref": "#/components/schemas/Instant" }, "expires_at": { "$ref": "#/components/schemas/Instant" } }, "required": [ "id", "organization", "role", "invited_by", "status", "invited_at", "expires_at" ] }, "InvitationOrganization": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/OrganizationId" }, "name": { "type": "string" }, "slug": { "type": "string" } }, "required": [ "id", "name", "slug" ] }, "Inviter": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" } }, "required": [ "name", "email" ] }, "LocalSignIn": { "type": "object", "properties": { "mode": { "type": "string", "const": "local" } }, "required": [ "mode" ] }, "McpOAuthAuthTemplate": { "type": "object", "properties": { "type": { "type": "string", "const": "mcp_oauth" }, "scopes": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" } }, "required": [ "name", "description" ] } }, "identity_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] } }, "required": [ "type", "scopes", "identity_url" ] }, "Member": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/MemberId" }, "organization_id": { "$ref": "#/components/schemas/OrganizationId" }, "user": { "$ref": "#/components/schemas/User" }, "role": { "type": "string", "enum": [ "owner", "admin", "developer", "viewer" ] }, "status": { "type": "string", "enum": [ "active", "invited" ] }, "invited_at": { "$ref": "#/components/schemas/Instant" }, "expires_at": { "anyOf": [ { "$ref": "#/components/schemas/Instant" }, { "type": "null" } ] }, "joined_at": { "anyOf": [ { "$ref": "#/components/schemas/Instant" }, { "type": "null" } ] }, "last_active_at": { "anyOf": [ { "$ref": "#/components/schemas/Instant" }, { "type": "null" } ] } }, "required": [ "id", "organization_id", "user", "role", "status", "invited_at", "expires_at", "joined_at", "last_active_at" ] }, "MemberId": { "type": "string", "pattern": "^mem_[0-9A-Za-z]{22}$" }, "Meta": { "type": "object", "properties": { "pagination": { "anyOf": [ { "$ref": "#/components/schemas/Pagination" }, { "type": "null" } ] } }, "required": [ "pagination" ] }, "Model": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/ModelId" }, "organization_id": { "$ref": "#/components/schemas/OrganizationId" }, "environment": { "$ref": "#/components/schemas/Environment" }, "route": { "$ref": "#/components/schemas/ModelRoute" }, "provider_model_id": { "type": "string" }, "name": { "type": "string" }, "author": { "type": "string" }, "context_window": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "supports_tools": { "type": "boolean" }, "status": { "type": "string", "enum": [ "available", "unavailable" ] }, "is_default": { "type": "boolean" }, "agent_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "created_at": { "$ref": "#/components/schemas/Instant" }, "updated_at": { "$ref": "#/components/schemas/Instant" } }, "required": [ "id", "organization_id", "environment", "route", "provider_model_id", "name", "author", "context_window", "supports_tools", "status", "is_default", "agent_count", "created_at", "updated_at" ] }, "ModelConnection": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/ModelConnectionId" }, "organization_id": { "$ref": "#/components/schemas/OrganizationId" }, "environment": { "$ref": "#/components/schemas/Environment" }, "kind": { "$ref": "#/components/schemas/ModelProviderKind" }, "label": { "type": "string" }, "api_key": { "$ref": "#/components/schemas/SecretState" }, "key_version": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "status": { "type": "string", "enum": [ "active", "invalid_key" ] }, "model_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "created_at": { "$ref": "#/components/schemas/Instant" }, "updated_at": { "$ref": "#/components/schemas/Instant" } }, "required": [ "id", "organization_id", "environment", "kind", "label", "api_key", "key_version", "status", "model_count", "created_at", "updated_at" ] }, "ModelConnectionId": { "type": "string", "pattern": "^mcn_[0-9A-Za-z]{22}$" }, "ModelId": { "type": "string", "pattern": "^mdl_[0-9A-Za-z]{22}$" }, "ModelPricing": { "type": "object", "properties": { "input_per_million_usd": { "type": "number" }, "output_per_million_usd": { "type": "number" } }, "required": [ "input_per_million_usd", "output_per_million_usd" ] }, "ModelProviderKind": { "type": "string", "enum": [ "openai", "anthropic", "openrouter" ] }, "ModelRoute": { "type": "object", "properties": { "connection_id": { "$ref": "#/components/schemas/ModelConnectionId" }, "kind": { "$ref": "#/components/schemas/ModelProviderKind" }, "label": { "type": "string" } }, "required": [ "connection_id", "kind", "label" ] }, "OAuthAuthTemplate": { "type": "object", "properties": { "type": { "type": "string", "const": "oauth2" }, "authorize_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "token_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "issuer": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "available_scopes": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" } }, "required": [ "name", "description" ] } }, "pkce": { "type": "boolean" }, "identity_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] } }, "required": [ "type", "authorize_url", "token_url", "available_scopes", "pkce", "identity_url" ] }, "OidcSignIn": { "type": "object", "properties": { "mode": { "type": "string", "const": "oidc" }, "issuer": { "type": "string", "format": "uri" }, "client_id": { "type": "string", "minLength": 1 } }, "required": [ "mode", "issuer", "client_id" ] }, "Organization": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/OrganizationId" }, "name": { "type": "string" }, "slug": { "type": "string" }, "role": { "type": "string", "enum": [ "owner", "admin", "developer", "viewer" ] }, "created_at": { "$ref": "#/components/schemas/Instant" }, "setup": { "$ref": "#/components/schemas/OrganizationSetup" } }, "required": [ "id", "name", "slug", "role", "created_at", "setup" ] }, "OrganizationId": { "type": "string", "pattern": "^org_[0-9A-Za-z]{22}$" }, "OrganizationRun": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/RunId" }, "workspace_id": { "$ref": "#/components/schemas/WorkspaceId" }, "agent_id": { "$ref": "#/components/schemas/AgentId" }, "agent_name": { "type": "string" }, "session_id": { "$ref": "#/components/schemas/SessionId" }, "trigger": { "type": "string", "enum": [ "api", "console", "channel" ] }, "channel": { "anyOf": [ { "$ref": "#/components/schemas/RunChannel" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "queued", "running", "waiting_for_approval", "completed", "failed", "cancelled" ] }, "input": { "type": "string" }, "output": { "type": [ "string", "null" ] }, "usage": { "$ref": "#/components/schemas/RunUsage" }, "error": { "anyOf": [ { "$ref": "#/components/schemas/RunError" }, { "type": "null" } ] }, "created_at": { "$ref": "#/components/schemas/Instant" }, "started_at": { "anyOf": [ { "$ref": "#/components/schemas/Instant" }, { "type": "null" } ] }, "finished_at": { "anyOf": [ { "$ref": "#/components/schemas/Instant" }, { "type": "null" } ] }, "workspace": { "$ref": "#/components/schemas/WorkspaceRef" } }, "required": [ "id", "workspace_id", "agent_id", "agent_name", "session_id", "trigger", "channel", "status", "input", "output", "usage", "error", "created_at", "started_at", "finished_at", "workspace" ] }, "OrganizationSetup": { "type": "object", "properties": { "has_app": { "type": "boolean" }, "has_ready_configuration": { "type": "boolean" }, "has_workspace": { "type": "boolean" }, "has_api_key": { "type": "boolean" }, "has_installation": { "type": "boolean" }, "has_agent": { "type": "boolean" }, "has_run": { "type": "boolean" } }, "required": [ "has_app", "has_ready_configuration", "has_workspace", "has_api_key", "has_installation", "has_agent", "has_run" ] }, "Pagination": { "type": "object", "properties": { "next_cursor": { "type": [ "string", "null" ] }, "total": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "next_cursor", "total" ] }, "ProviderModel": { "type": "object", "properties": { "provider_model_id": { "type": "string" }, "name": { "type": "string" }, "author": { "type": "string" }, "context_window": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "supports_tools": { "type": "boolean" }, "pricing": { "anyOf": [ { "$ref": "#/components/schemas/ModelPricing" }, { "type": "null" } ] }, "added_model_id": { "anyOf": [ { "$ref": "#/components/schemas/ModelId" }, { "type": "null" } ] } }, "required": [ "provider_model_id", "name", "author", "context_window", "supports_tools", "pricing", "added_model_id" ] }, "Run": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/RunId" }, "workspace_id": { "$ref": "#/components/schemas/WorkspaceId" }, "agent_id": { "$ref": "#/components/schemas/AgentId" }, "agent_name": { "type": "string" }, "session_id": { "$ref": "#/components/schemas/SessionId" }, "trigger": { "type": "string", "enum": [ "api", "console", "channel" ] }, "channel": { "anyOf": [ { "$ref": "#/components/schemas/RunChannel" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "queued", "running", "waiting_for_approval", "completed", "failed", "cancelled" ] }, "input": { "type": "string" }, "output": { "type": [ "string", "null" ] }, "usage": { "$ref": "#/components/schemas/RunUsage" }, "error": { "anyOf": [ { "$ref": "#/components/schemas/RunError" }, { "type": "null" } ] }, "created_at": { "$ref": "#/components/schemas/Instant" }, "started_at": { "anyOf": [ { "$ref": "#/components/schemas/Instant" }, { "type": "null" } ] }, "finished_at": { "anyOf": [ { "$ref": "#/components/schemas/Instant" }, { "type": "null" } ] } }, "required": [ "id", "workspace_id", "agent_id", "agent_name", "session_id", "trigger", "channel", "status", "input", "output", "usage", "error", "created_at", "started_at", "finished_at" ] }, "RunCancelledWebhookEvent": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/WebhookEventId" }, "created_at": { "$ref": "#/components/schemas/Instant" }, "environment": { "$ref": "#/components/schemas/Environment" }, "organization_id": { "$ref": "#/components/schemas/OrganizationId" }, "type": { "type": "string", "const": "run.cancelled" }, "workspace": { "$ref": "#/components/schemas/WebhookEventWorkspace" }, "data": { "type": "object", "properties": { "object": { "type": "string", "const": "run" }, "id": { "$ref": "#/components/schemas/RunId" }, "agent_id": { "$ref": "#/components/schemas/AgentId" }, "status": { "type": "string", "enum": [ "cancelled" ] } }, "required": [ "object", "id", "agent_id", "status" ] } }, "required": [ "id", "created_at", "environment", "organization_id", "type", "workspace", "data" ] }, "RunChannel": { "type": "object", "properties": { "connection_id": { "$ref": "#/components/schemas/ChannelConnectionId" }, "conversation_id": { "$ref": "#/components/schemas/ChannelConversationId" }, "thread_key": { "type": "string" }, "origin_message_id": { "anyOf": [ { "$ref": "#/components/schemas/ChannelMessageId" }, { "type": "null" } ] }, "reason": { "type": "string", "enum": [ "direct_message", "mentioned", "thread_follow_up" ] }, "silent_reason": { "type": [ "string", "null" ] } }, "required": [ "connection_id", "conversation_id", "thread_key", "origin_message_id", "reason", "silent_reason" ] }, "RunCompletedWebhookEvent": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/WebhookEventId" }, "created_at": { "$ref": "#/components/schemas/Instant" }, "environment": { "$ref": "#/components/schemas/Environment" }, "organization_id": { "$ref": "#/components/schemas/OrganizationId" }, "type": { "type": "string", "const": "run.completed" }, "workspace": { "$ref": "#/components/schemas/WebhookEventWorkspace" }, "data": { "type": "object", "properties": { "object": { "type": "string", "const": "run" }, "id": { "$ref": "#/components/schemas/RunId" }, "agent_id": { "$ref": "#/components/schemas/AgentId" }, "status": { "type": "string", "enum": [ "completed" ] } }, "required": [ "object", "id", "agent_id", "status" ] } }, "required": [ "id", "created_at", "environment", "organization_id", "type", "workspace", "data" ] }, "RunError": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "RunEvent": { "oneOf": [ { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/RunEventId" }, "run_id": { "$ref": "#/components/schemas/RunId" }, "workspace_id": { "$ref": "#/components/schemas/WorkspaceId" }, "sequence": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "created_at": { "$ref": "#/components/schemas/Instant" }, "type": { "type": "string", "const": "run.queued" }, "data": { "type": "object", "properties": {} } }, "required": [ "id", "run_id", "workspace_id", "sequence", "created_at", "type", "data" ] }, { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/RunEventId" }, "run_id": { "$ref": "#/components/schemas/RunId" }, "workspace_id": { "$ref": "#/components/schemas/WorkspaceId" }, "sequence": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "created_at": { "$ref": "#/components/schemas/Instant" }, "type": { "type": "string", "const": "run.started" }, "data": { "type": "object", "properties": { "model": { "type": "string" }, "model_id": { "anyOf": [ { "$ref": "#/components/schemas/ModelId" }, { "type": "null" } ] }, "connection_id": { "anyOf": [ { "$ref": "#/components/schemas/ModelConnectionId" }, { "type": "null" } ] } }, "required": [ "model", "model_id", "connection_id" ] } }, "required": [ "id", "run_id", "workspace_id", "sequence", "created_at", "type", "data" ] }, { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/RunEventId" }, "run_id": { "$ref": "#/components/schemas/RunId" }, "workspace_id": { "$ref": "#/components/schemas/WorkspaceId" }, "sequence": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "created_at": { "$ref": "#/components/schemas/Instant" }, "type": { "type": "string", "const": "message.assistant" }, "data": { "type": "object", "properties": { "text": { "type": "string" } }, "required": [ "text" ] } }, "required": [ "id", "run_id", "workspace_id", "sequence", "created_at", "type", "data" ] }, { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/RunEventId" }, "run_id": { "$ref": "#/components/schemas/RunId" }, "workspace_id": { "$ref": "#/components/schemas/WorkspaceId" }, "sequence": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "created_at": { "$ref": "#/components/schemas/Instant" }, "type": { "type": "string", "const": "channel_messages.received" }, "data": { "type": "object", "properties": { "outcome": { "type": "string", "enum": [ "started", "steered", "collected" ] }, "connection_id": { "$ref": "#/components/schemas/ChannelConnectionId" }, "conversation_id": { "$ref": "#/components/schemas/ChannelConversationId" }, "message_ids": { "type": "array", "items": { "$ref": "#/components/schemas/ChannelMessageId" } } }, "required": [ "outcome", "connection_id", "conversation_id", "message_ids" ] } }, "required": [ "id", "run_id", "workspace_id", "sequence", "created_at", "type", "data" ] }, { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/RunEventId" }, "run_id": { "$ref": "#/components/schemas/RunId" }, "workspace_id": { "$ref": "#/components/schemas/WorkspaceId" }, "sequence": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "created_at": { "$ref": "#/components/schemas/Instant" }, "type": { "type": "string", "const": "tool_call.started" }, "data": { "anyOf": [ { "type": "object", "properties": { "call_id": { "$ref": "#/components/schemas/ToolCallId" }, "installation_id": { "$ref": "#/components/schemas/InstallationId" }, "installation_label": { "type": "string" }, "app_name": { "type": "string" }, "tool": { "type": "string" }, "arguments": {} }, "required": [ "call_id", "installation_id", "installation_label", "app_name", "tool", "arguments" ] }, { "type": "object", "properties": { "call_id": { "$ref": "#/components/schemas/ToolCallId" }, "channel_connection_id": { "$ref": "#/components/schemas/ChannelConnectionId" }, "connection_label": { "type": "string" }, "provider": { "$ref": "#/components/schemas/ChannelProvider" }, "tool": { "type": "string" }, "arguments": {} }, "required": [ "call_id", "channel_connection_id", "connection_label", "provider", "tool", "arguments" ] } ] } }, "required": [ "id", "run_id", "workspace_id", "sequence", "created_at", "type", "data" ] }, { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/RunEventId" }, "run_id": { "$ref": "#/components/schemas/RunId" }, "workspace_id": { "$ref": "#/components/schemas/WorkspaceId" }, "sequence": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "created_at": { "$ref": "#/components/schemas/Instant" }, "type": { "type": "string", "const": "tool_call.completed" }, "data": { "anyOf": [ { "type": "object", "properties": { "call_id": { "$ref": "#/components/schemas/ToolCallId" }, "installation_id": { "$ref": "#/components/schemas/InstallationId" }, "installation_label": { "type": "string" }, "app_name": { "type": "string" }, "tool": { "type": "string" }, "result": {}, "duration_ms": { "type": "number" } }, "required": [ "call_id", "installation_id", "installation_label", "app_name", "tool", "result", "duration_ms" ] }, { "type": "object", "properties": { "call_id": { "$ref": "#/components/schemas/ToolCallId" }, "channel_connection_id": { "$ref": "#/components/schemas/ChannelConnectionId" }, "connection_label": { "type": "string" }, "provider": { "$ref": "#/components/schemas/ChannelProvider" }, "tool": { "type": "string" }, "result": {}, "duration_ms": { "type": "number" } }, "required": [ "call_id", "channel_connection_id", "connection_label", "provider", "tool", "result", "duration_ms" ] } ] } }, "required": [ "id", "run_id", "workspace_id", "sequence", "created_at", "type", "data" ] }, { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/RunEventId" }, "run_id": { "$ref": "#/components/schemas/RunId" }, "workspace_id": { "$ref": "#/components/schemas/WorkspaceId" }, "sequence": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "created_at": { "$ref": "#/components/schemas/Instant" }, "type": { "type": "string", "const": "tool_call.failed" }, "data": { "anyOf": [ { "type": "object", "properties": { "call_id": { "$ref": "#/components/schemas/ToolCallId" }, "installation_id": { "$ref": "#/components/schemas/InstallationId" }, "installation_label": { "type": "string" }, "app_name": { "type": "string" }, "tool": { "type": "string" }, "error": { "$ref": "#/components/schemas/RunError" }, "duration_ms": { "type": "number" } }, "required": [ "call_id", "installation_id", "installation_label", "app_name", "tool", "error", "duration_ms" ] }, { "type": "object", "properties": { "call_id": { "$ref": "#/components/schemas/ToolCallId" }, "channel_connection_id": { "$ref": "#/components/schemas/ChannelConnectionId" }, "connection_label": { "type": "string" }, "provider": { "$ref": "#/components/schemas/ChannelProvider" }, "tool": { "type": "string" }, "error": { "$ref": "#/components/schemas/RunError" }, "duration_ms": { "type": "number" } }, "required": [ "call_id", "channel_connection_id", "connection_label", "provider", "tool", "error", "duration_ms" ] } ] } }, "required": [ "id", "run_id", "workspace_id", "sequence", "created_at", "type", "data" ] }, { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/RunEventId" }, "run_id": { "$ref": "#/components/schemas/RunId" }, "workspace_id": { "$ref": "#/components/schemas/WorkspaceId" }, "sequence": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "created_at": { "$ref": "#/components/schemas/Instant" }, "type": { "type": "string", "const": "approval.requested" }, "data": { "anyOf": [ { "type": "object", "properties": { "call_id": { "$ref": "#/components/schemas/ToolCallId" }, "installation_id": { "$ref": "#/components/schemas/InstallationId" }, "installation_label": { "type": "string" }, "app_name": { "type": "string" }, "tool": { "type": "string" }, "arguments": {} }, "required": [ "call_id", "installation_id", "installation_label", "app_name", "tool", "arguments" ] }, { "type": "object", "properties": { "call_id": { "$ref": "#/components/schemas/ToolCallId" }, "channel_connection_id": { "$ref": "#/components/schemas/ChannelConnectionId" }, "connection_label": { "type": "string" }, "provider": { "$ref": "#/components/schemas/ChannelProvider" }, "tool": { "type": "string" }, "arguments": {} }, "required": [ "call_id", "channel_connection_id", "connection_label", "provider", "tool", "arguments" ] } ] } }, "required": [ "id", "run_id", "workspace_id", "sequence", "created_at", "type", "data" ] }, { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/RunEventId" }, "run_id": { "$ref": "#/components/schemas/RunId" }, "workspace_id": { "$ref": "#/components/schemas/WorkspaceId" }, "sequence": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "created_at": { "$ref": "#/components/schemas/Instant" }, "type": { "type": "string", "const": "approval.resolved" }, "data": { "type": "object", "properties": { "call_id": { "$ref": "#/components/schemas/ToolCallId" }, "decision": { "type": "string", "enum": [ "approved", "denied" ] }, "api_key_id": { "$ref": "#/components/schemas/ApiKeyId" } }, "required": [ "call_id", "decision", "api_key_id" ] } }, "required": [ "id", "run_id", "workspace_id", "sequence", "created_at", "type", "data" ] }, { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/RunEventId" }, "run_id": { "$ref": "#/components/schemas/RunId" }, "workspace_id": { "$ref": "#/components/schemas/WorkspaceId" }, "sequence": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "created_at": { "$ref": "#/components/schemas/Instant" }, "type": { "type": "string", "const": "run.stayed_silent" }, "data": { "type": "object", "properties": { "reason": { "type": "string" } }, "required": [ "reason" ] } }, "required": [ "id", "run_id", "workspace_id", "sequence", "created_at", "type", "data" ] }, { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/RunEventId" }, "run_id": { "$ref": "#/components/schemas/RunId" }, "workspace_id": { "$ref": "#/components/schemas/WorkspaceId" }, "sequence": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "created_at": { "$ref": "#/components/schemas/Instant" }, "type": { "type": "string", "const": "run.completed" }, "data": { "type": "object", "properties": { "usage": { "$ref": "#/components/schemas/RunUsage" } }, "required": [ "usage" ] } }, "required": [ "id", "run_id", "workspace_id", "sequence", "created_at", "type", "data" ] }, { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/RunEventId" }, "run_id": { "$ref": "#/components/schemas/RunId" }, "workspace_id": { "$ref": "#/components/schemas/WorkspaceId" }, "sequence": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "created_at": { "$ref": "#/components/schemas/Instant" }, "type": { "type": "string", "const": "run.failed" }, "data": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/RunError" } }, "required": [ "error" ] } }, "required": [ "id", "run_id", "workspace_id", "sequence", "created_at", "type", "data" ] }, { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/RunEventId" }, "run_id": { "$ref": "#/components/schemas/RunId" }, "workspace_id": { "$ref": "#/components/schemas/WorkspaceId" }, "sequence": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "created_at": { "$ref": "#/components/schemas/Instant" }, "type": { "type": "string", "const": "run.cancelled" }, "data": { "type": "object", "properties": { "cancelled_by": { "type": "string" } }, "required": [ "cancelled_by" ] } }, "required": [ "id", "run_id", "workspace_id", "sequence", "created_at", "type", "data" ] } ] }, "RunEventId": { "type": "string", "pattern": "^rev_[0-9A-Za-z]{22}$" }, "RunFailedWebhookEvent": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/WebhookEventId" }, "created_at": { "$ref": "#/components/schemas/Instant" }, "environment": { "$ref": "#/components/schemas/Environment" }, "organization_id": { "$ref": "#/components/schemas/OrganizationId" }, "type": { "type": "string", "const": "run.failed" }, "workspace": { "$ref": "#/components/schemas/WebhookEventWorkspace" }, "data": { "type": "object", "properties": { "object": { "type": "string", "const": "run" }, "id": { "$ref": "#/components/schemas/RunId" }, "agent_id": { "$ref": "#/components/schemas/AgentId" }, "status": { "type": "string", "enum": [ "failed" ] } }, "required": [ "object", "id", "agent_id", "status" ] } }, "required": [ "id", "created_at", "environment", "organization_id", "type", "workspace", "data" ] }, "RunId": { "type": "string", "pattern": "^run_[0-9A-Za-z]{22}$" }, "RunUsage": { "type": "object", "properties": { "input_tokens": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Every token the model read, those read from or written to the provider's prompt cache included." }, "output_tokens": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Every token the model wrote." }, "cache_read_input_tokens": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The part of `input_tokens` the provider served from its prompt cache." }, "cache_write_input_tokens": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The part of `input_tokens` the provider wrote to its prompt cache. Providers that cache on their own report none." }, "tool_calls": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "input_tokens", "output_tokens", "cache_read_input_tokens", "cache_write_input_tokens", "tool_calls" ] }, "RunWaitingForApprovalWebhookEvent": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/WebhookEventId" }, "created_at": { "$ref": "#/components/schemas/Instant" }, "environment": { "$ref": "#/components/schemas/Environment" }, "organization_id": { "$ref": "#/components/schemas/OrganizationId" }, "type": { "type": "string", "const": "run.waiting_for_approval" }, "workspace": { "$ref": "#/components/schemas/WebhookEventWorkspace" }, "data": { "type": "object", "properties": { "object": { "type": "string", "const": "run" }, "id": { "$ref": "#/components/schemas/RunId" }, "agent_id": { "$ref": "#/components/schemas/AgentId" }, "status": { "type": "string", "enum": [ "waiting_for_approval" ] } }, "required": [ "object", "id", "agent_id", "status" ] } }, "required": [ "id", "created_at", "environment", "organization_id", "type", "workspace", "data" ] }, "SecretState": { "type": "object", "properties": { "set": { "type": "boolean" }, "last4": { "type": [ "string", "null" ] }, "updated_at": { "anyOf": [ { "$ref": "#/components/schemas/Instant" }, { "type": "null" } ] } }, "required": [ "set", "last4", "updated_at" ] }, "SessionId": { "type": "string", "pattern": "^ses_[0-9A-Za-z]{22}$" }, "SignInSettings": { "oneOf": [ { "$ref": "#/components/schemas/LocalSignIn" }, { "$ref": "#/components/schemas/OidcSignIn" } ] }, "TokenAuthTemplate": { "type": "object", "properties": { "type": { "type": "string", "const": "token" }, "inputs": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "secret": { "type": "boolean" }, "help": { "type": [ "string", "null" ] }, "placeholder": { "type": [ "string", "null" ] }, "pattern": { "type": [ "string", "null" ] } }, "required": [ "key", "label", "secret", "help", "placeholder", "pattern" ] } }, "placement": { "type": "object", "properties": { "location": { "type": "string", "const": "header" }, "name": { "type": "string" }, "prefix": { "type": "string" } }, "required": [ "location", "name", "prefix" ] }, "verify_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "instructions": { "type": "string" }, "docs_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] } }, "required": [ "type", "inputs", "placement", "verify_url", "instructions", "docs_url" ] }, "ToolCallId": { "type": "string", "pattern": "^call_[0-9A-Za-z]{22}$" }, "ToolDefinition": { "type": "object", "properties": { "name": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "effect": { "type": "string", "enum": [ "read", "write", "destructive" ] } }, "required": [ "name", "title", "description", "effect" ] }, "ToolPolicy": { "type": "object", "properties": { "organization_id": { "$ref": "#/components/schemas/OrganizationId" }, "mode": { "type": "string", "enum": [ "manual" ] }, "new_tool_level": { "type": "string", "enum": [ "approve", "deny" ] }, "updated_at": { "anyOf": [ { "$ref": "#/components/schemas/Instant" }, { "type": "null" } ] }, "updated_by": { "anyOf": [ { "$ref": "#/components/schemas/User" }, { "type": "null" } ] } }, "required": [ "organization_id", "mode", "new_tool_level", "updated_at", "updated_by" ] }, "ToolText": { "type": "object", "properties": { "title": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "input_schema": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "output_schema": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "annotations": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] } }, "required": [ "title", "description", "input_schema", "output_schema", "annotations" ] }, "UsageDay": { "type": "object", "properties": { "date": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, "runs": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "failed_runs": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "tool_calls": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "input_tokens": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Every token the model read, those read from or written to the provider's prompt cache included." }, "output_tokens": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Every token the model wrote." }, "cache_read_input_tokens": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The part of `input_tokens` the provider served from its prompt cache." }, "cache_write_input_tokens": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The part of `input_tokens` the provider wrote to its prompt cache. Providers that cache on their own report none." } }, "required": [ "date", "runs", "failed_runs", "tool_calls", "input_tokens", "output_tokens", "cache_read_input_tokens", "cache_write_input_tokens" ] }, "UsageReport": { "type": "object", "properties": { "environment": { "$ref": "#/components/schemas/Environment" }, "days": { "type": "array", "items": { "$ref": "#/components/schemas/UsageDay" } }, "totals": { "type": "object", "properties": { "runs": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "failed_runs": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "tool_calls": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "input_tokens": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Every token the model read, those read from or written to the provider's prompt cache included." }, "output_tokens": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Every token the model wrote." }, "cache_read_input_tokens": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The part of `input_tokens` the provider served from its prompt cache." }, "cache_write_input_tokens": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The part of `input_tokens` the provider wrote to its prompt cache. Providers that cache on their own report none." } }, "required": [ "runs", "failed_runs", "tool_calls", "input_tokens", "output_tokens", "cache_read_input_tokens", "cache_write_input_tokens" ] } }, "required": [ "environment", "days", "totals" ] }, "User": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/UserId" }, "name": { "type": "string" }, "email": { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "avatar_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] } }, "required": [ "id", "name", "email", "avatar_url" ] }, "UserId": { "type": "string", "pattern": "^usr_[0-9A-Za-z]{22}$" }, "Viewer": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/User" }, "organizations": { "type": "array", "items": { "$ref": "#/components/schemas/Organization" } } }, "required": [ "user", "organizations" ] }, "WebhookDelivery": { "type": "object", "properties": { "status_code": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "delivered_at": { "$ref": "#/components/schemas/Instant" } }, "required": [ "status_code", "delivered_at" ] }, "WebhookDeliveryAttempt": { "type": "object", "properties": { "number": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status_code": { "anyOf": [ { "type": "integer", "minimum": 100, "maximum": 999 }, { "type": "null" } ] }, "error_class": { "anyOf": [ { "type": "string", "enum": [ "status", "refused", "redirected", "timeout", "too_large", "unreachable", "failed", "store_unavailable", "secret_unavailable" ] }, { "type": "null" } ] }, "attempted_at": { "$ref": "#/components/schemas/Instant" }, "duration_ms": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "number", "status_code", "error_class", "attempted_at", "duration_ms" ] }, "WebhookDeliveryDetail": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/WebhookDeliveryId" }, "organization_id": { "$ref": "#/components/schemas/OrganizationId" }, "endpoint_id": { "$ref": "#/components/schemas/WebhookEndpointId" }, "event_id": { "$ref": "#/components/schemas/WebhookEventId" }, "environment": { "$ref": "#/components/schemas/Environment" }, "event_type": { "type": "string", "enum": [ "installation.connected", "installation.reconnect_required", "installation.disconnected", "connect_session.completed", "connect_session.failed", "run.completed", "run.failed", "run.waiting_for_approval", "run.cancelled", "app.tools_changed", "channel_message.received", "channel_message.sent", "channel_app_manager.status_changed", "channel_app.status_changed", "channel_connection.status_changed", "channel_conversation.paused", "webhook.test" ] }, "event_created_at": { "$ref": "#/components/schemas/Instant" }, "workspace": { "anyOf": [ { "$ref": "#/components/schemas/WebhookEventWorkspace" }, { "type": "null" } ] }, "state": { "type": "string", "enum": [ "pending", "succeeded", "failed", "skipped" ] }, "attempts": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "last_status_code": { "anyOf": [ { "type": "integer", "minimum": 100, "maximum": 999 }, { "type": "null" } ] }, "last_error": { "anyOf": [ { "type": "string", "enum": [ "status", "refused", "redirected", "timeout", "too_large", "unreachable", "failed", "store_unavailable", "secret_unavailable" ] }, { "type": "null" } ] }, "last_attempt_at": { "anyOf": [ { "$ref": "#/components/schemas/Instant" }, { "type": "null" } ] }, "next_attempt_at": { "anyOf": [ { "$ref": "#/components/schemas/Instant" }, { "type": "null" } ] }, "created_at": { "$ref": "#/components/schemas/Instant" }, "event": { "$ref": "#/components/schemas/WebhookEvent" }, "attempt_history_complete": { "type": "boolean" } }, "required": [ "id", "organization_id", "endpoint_id", "event_id", "environment", "event_type", "event_created_at", "workspace", "state", "attempts", "last_status_code", "last_error", "last_attempt_at", "next_attempt_at", "created_at", "event", "attempt_history_complete" ] }, "WebhookDeliveryId": { "type": "string", "pattern": "^whd_[0-9A-Za-z]{22}$" }, "WebhookDeliverySummary": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/WebhookDeliveryId" }, "organization_id": { "$ref": "#/components/schemas/OrganizationId" }, "endpoint_id": { "$ref": "#/components/schemas/WebhookEndpointId" }, "event_id": { "$ref": "#/components/schemas/WebhookEventId" }, "environment": { "$ref": "#/components/schemas/Environment" }, "event_type": { "type": "string", "enum": [ "installation.connected", "installation.reconnect_required", "installation.disconnected", "connect_session.completed", "connect_session.failed", "run.completed", "run.failed", "run.waiting_for_approval", "run.cancelled", "app.tools_changed", "channel_message.received", "channel_message.sent", "channel_app_manager.status_changed", "channel_app.status_changed", "channel_connection.status_changed", "channel_conversation.paused", "webhook.test" ] }, "event_created_at": { "$ref": "#/components/schemas/Instant" }, "workspace": { "anyOf": [ { "$ref": "#/components/schemas/WebhookEventWorkspace" }, { "type": "null" } ] }, "state": { "type": "string", "enum": [ "pending", "succeeded", "failed", "skipped" ] }, "attempts": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "last_status_code": { "anyOf": [ { "type": "integer", "minimum": 100, "maximum": 999 }, { "type": "null" } ] }, "last_error": { "anyOf": [ { "type": "string", "enum": [ "status", "refused", "redirected", "timeout", "too_large", "unreachable", "failed", "store_unavailable", "secret_unavailable" ] }, { "type": "null" } ] }, "last_attempt_at": { "anyOf": [ { "$ref": "#/components/schemas/Instant" }, { "type": "null" } ] }, "next_attempt_at": { "anyOf": [ { "$ref": "#/components/schemas/Instant" }, { "type": "null" } ] }, "created_at": { "$ref": "#/components/schemas/Instant" } }, "required": [ "id", "organization_id", "endpoint_id", "event_id", "environment", "event_type", "event_created_at", "workspace", "state", "attempts", "last_status_code", "last_error", "last_attempt_at", "next_attempt_at", "created_at" ] }, "WebhookEndpoint": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/WebhookEndpointId" }, "organization_id": { "$ref": "#/components/schemas/OrganizationId" }, "environment": { "$ref": "#/components/schemas/Environment" }, "url": { "type": "string", "format": "uri" }, "description": { "type": "string" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "installation.connected", "installation.reconnect_required", "installation.disconnected", "connect_session.completed", "connect_session.failed", "run.completed", "run.failed", "run.waiting_for_approval", "run.cancelled", "app.tools_changed", "channel_message.received", "channel_message.sent", "channel_app_manager.status_changed", "channel_app.status_changed", "channel_connection.status_changed", "channel_conversation.paused" ] } }, "enabled": { "type": "boolean" }, "signing_secret_last4": { "type": "string" }, "previous_signing_secret_expires_at": { "anyOf": [ { "$ref": "#/components/schemas/Instant" }, { "type": "null" } ] }, "created_at": { "$ref": "#/components/schemas/Instant" }, "last_delivery": { "anyOf": [ { "$ref": "#/components/schemas/WebhookDelivery" }, { "type": "null" } ] } }, "required": [ "id", "organization_id", "environment", "url", "description", "events", "enabled", "signing_secret_last4", "previous_signing_secret_expires_at", "created_at", "last_delivery" ] }, "WebhookEndpointId": { "type": "string", "pattern": "^we_[0-9A-Za-z]{22}$" }, "WebhookEvent": { "oneOf": [ { "$ref": "#/components/schemas/InstallationConnectedWebhookEvent" }, { "$ref": "#/components/schemas/InstallationReconnectRequiredWebhookEvent" }, { "$ref": "#/components/schemas/InstallationDisconnectedWebhookEvent" }, { "$ref": "#/components/schemas/ConnectSessionCompletedWebhookEvent" }, { "$ref": "#/components/schemas/ConnectSessionFailedWebhookEvent" }, { "$ref": "#/components/schemas/RunCompletedWebhookEvent" }, { "$ref": "#/components/schemas/RunFailedWebhookEvent" }, { "$ref": "#/components/schemas/RunWaitingForApprovalWebhookEvent" }, { "$ref": "#/components/schemas/RunCancelledWebhookEvent" }, { "$ref": "#/components/schemas/AppToolsChangedWebhookEvent" }, { "$ref": "#/components/schemas/ChannelMessageReceivedWebhookEvent" }, { "$ref": "#/components/schemas/ChannelMessageSentWebhookEvent" }, { "$ref": "#/components/schemas/ChannelAppManagerStatusChangedWebhookEvent" }, { "$ref": "#/components/schemas/ChannelAppStatusChangedWebhookEvent" }, { "$ref": "#/components/schemas/ChannelConnectionStatusChangedWebhookEvent" }, { "$ref": "#/components/schemas/ChannelConversationPausedWebhookEvent" }, { "$ref": "#/components/schemas/WebhookTestWebhookEvent" } ] }, "WebhookEventEnvelope": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/WebhookEventId" }, "created_at": { "$ref": "#/components/schemas/Instant" }, "environment": { "$ref": "#/components/schemas/Environment" }, "organization_id": { "$ref": "#/components/schemas/OrganizationId" }, "type": { "type": "string" }, "workspace": { "anyOf": [ { "$ref": "#/components/schemas/WebhookEventWorkspace" }, { "type": "null" } ] }, "data": { "type": "object", "properties": { "object": { "type": "string" }, "id": { "type": "string" } }, "required": [ "object", "id" ], "additionalProperties": {} } }, "required": [ "id", "created_at", "environment", "organization_id", "type", "workspace", "data" ], "additionalProperties": {} }, "WebhookEventId": { "type": "string", "pattern": "^evt_[0-9A-Za-z]{22}$" }, "WebhookEventWorkspace": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/WorkspaceId" }, "external_id": { "type": [ "string", "null" ] } }, "required": [ "id", "external_id" ] }, "WebhookTestWebhookEvent": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/WebhookEventId" }, "created_at": { "$ref": "#/components/schemas/Instant" }, "environment": { "$ref": "#/components/schemas/Environment" }, "organization_id": { "$ref": "#/components/schemas/OrganizationId" }, "type": { "type": "string", "const": "webhook.test" }, "workspace": { "type": "null" }, "data": { "type": "object", "properties": { "object": { "type": "string", "const": "webhook_endpoint" }, "id": { "$ref": "#/components/schemas/WebhookEndpointId" } }, "required": [ "object", "id" ] } }, "required": [ "id", "created_at", "environment", "organization_id", "type", "workspace", "data" ] }, "Workspace": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/WorkspaceId" }, "organization_id": { "$ref": "#/components/schemas/OrganizationId" }, "name": { "type": "string" }, "slug": { "type": "string" }, "environment": { "$ref": "#/components/schemas/Environment" }, "external_id": { "type": [ "string", "null" ] }, "created_at": { "$ref": "#/components/schemas/Instant" }, "stats": { "$ref": "#/components/schemas/WorkspaceStats" } }, "required": [ "id", "organization_id", "name", "slug", "environment", "external_id", "created_at", "stats" ] }, "WorkspaceId": { "type": "string", "pattern": "^ws_[0-9A-Za-z]{22}$" }, "WorkspaceRef": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/WorkspaceId" }, "name": { "type": "string" }, "slug": { "type": "string" }, "environment": { "$ref": "#/components/schemas/Environment" } }, "required": [ "id", "name", "slug", "environment" ] }, "WorkspaceStats": { "type": "object", "properties": { "agents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "installations": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "runs_last_24h": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "agents", "installations", "runs_last_24h" ] } } }, "paths": { "/v1/sign-in-settings": { "get": { "operationId": "getSignInSettings", "summary": "How the Console signs in: `local`, or `oidc` with the issuer and client ID", "security": [ {} ], "x-zupflow-callers": [ "public" ], "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "$ref": "#/components/schemas/SignInSettings" }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/me": { "get": { "operationId": "getViewer", "summary": "The signed-in member and their organizations", "security": [ { "consoleSession": [] } ], "x-zupflow-callers": [ "console" ], "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "$ref": "#/components/schemas/Viewer" }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/me/invitations": { "get": { "operationId": "listInvitations", "summary": "The signed-in person's own invitations, pending and expired, newest first: at most `INVITATION_LIST_LIMIT` (50), leaving out any expired more than `EXPIRED_INVITATION_SHOWN_DAYS` (30) days ago. `403 email_unverified` when the sign-in doesn't vouch for the user's address now (backend only: the mock doesn't simulate verification)", "security": [ { "consoleSession": [] } ], "x-zupflow-callers": [ "console" ], "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Invitation" } }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/me/invitations/{invitation}/accept": { "post": { "operationId": "acceptInvitation", "summary": "Join the invitation's organization with the invited role. Someone else's invitation, or one withdrawn (by an admin, or because its grantor can't grant it any more) or declined, is `404`; an accepted one `409 invitation_accepted`; an expired one `422 invitation_expired`; `403 email_unverified` as for the list (backend only)", "security": [ { "consoleSession": [] } ], "x-zupflow-callers": [ "console" ], "parameters": [ { "name": "invitation", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/MemberId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "$ref": "#/components/schemas/Organization" }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/me/invitations/{invitation}/decline": { "post": { "operationId": "declineInvitation", "summary": "Decline an invitation, expired or not: it's withdrawn. Someone else's, or one already gone, is `404`; an accepted one `409 invitation_accepted`; `403 email_unverified` as for the list (backend only)", "security": [ { "consoleSession": [] } ], "x-zupflow-callers": [ "console" ], "parameters": [ { "name": "invitation", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/MemberId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "204": { "description": "Done" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/organizations": { "post": { "operationId": "createOrganization", "summary": "Create an organization; the caller becomes its owner", "security": [ { "consoleSession": [] } ], "x-zupflow-callers": [ "console" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "$ref": "#/components/schemas/Organization" }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "slug": { "type": "string" } }, "required": [ "name", "slug" ] } } } } } }, "/v1/organizations/{org}": { "get": { "operationId": "getOrganization", "summary": "An organization", "security": [ { "consoleSession": [] } ], "x-zupflow-callers": [ "console" ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "$ref": "#/components/schemas/Organization" }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } }, "patch": { "operationId": "updateOrganization", "summary": "Rename an organization", "security": [ { "consoleSession": [] } ], "x-zupflow-callers": [ "console" ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "$ref": "#/components/schemas/Organization" }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "slug": { "type": "string" } } } } } } } }, "/v1/organizations/{org}/usage": { "get": { "operationId": "getUsage", "summary": "Runs, failures, tool calls and tokens per UTC day", "security": [ { "consoleSession": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "environment", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/Environment" } }, { "name": "days", "in": "query", "required": false, "schema": { "description": "1 to 90 (default 14); values outside are clamped, and a non-integer means the default.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "$ref": "#/components/schemas/UsageReport" }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/organizations/{org}/members": { "get": { "operationId": "listMembers", "summary": "Members and invitations", "security": [ { "consoleSession": [] } ], "x-zupflow-callers": [ "console" ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Member" } }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "inviteMember", "summary": "Invite a member: an owner or admin, and an owner to invite an owner. Inviting an address whose invitation expired renews it, with this role and grantor", "security": [ { "consoleSession": [] } ], "x-zupflow-callers": [ "console" ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "$ref": "#/components/schemas/Member" }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" }, "role": { "type": "string", "enum": [ "owner", "admin", "developer", "viewer" ] } }, "required": [ "email", "role" ] } } } } } }, "/v1/organizations/{org}/members/{member}": { "patch": { "operationId": "updateMember", "summary": "Change a member's role. On an invitation, the owner changing it becomes its grantor; a member demoted loses the invitations they granted above what they can grant now", "security": [ { "consoleSession": [] } ], "x-zupflow-callers": [ "console" ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "member", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/MemberId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "$ref": "#/components/schemas/Member" }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "owner", "admin", "developer", "viewer" ] } }, "required": [ "role" ] } } } } }, "delete": { "operationId": "removeMember", "summary": "Remove a member or withdraw an invitation. Removing a member withdraws the invitations they granted; so does a demotion, for the roles they can't grant any more", "security": [ { "consoleSession": [] } ], "x-zupflow-callers": [ "console" ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "member", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/MemberId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "status", "in": "query", "required": false, "schema": { "description": "`invited`: withdraw an invitation only. One accepted in the meantime is left alone, and answers `409 invitation_accepted`.", "type": "string", "enum": [ "invited" ] } } ], "responses": { "204": { "description": "Done" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/organizations/{org}/runs": { "get": { "operationId": "listOrganizationRuns", "summary": "Runs across the organization's workspaces, newest first", "security": [ { "consoleSession": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "environment", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Environment" } }, { "name": "workspace_id", "in": "query", "required": false, "schema": { "description": "Only this workspace's rows. A malformed or unknown ID matches nothing.", "$ref": "#/components/schemas/WorkspaceId" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "queued", "running", "waiting_for_approval", "completed", "failed", "cancelled" ] } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "description": "Page size, 1 to 100 (default 25); values outside are clamped, and a non-integer means the default.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OrganizationRun" } }, "meta": { "$ref": "#/components/schemas/Meta" }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/organizations/{org}/audit-events": { "get": { "operationId": "listAuditEvents", "summary": "The audit log", "security": [ { "consoleSession": [] } ], "x-zupflow-callers": [ "console" ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "workspace_id", "in": "query", "required": false, "schema": { "description": "Only this workspace's rows. A malformed or unknown ID matches nothing.", "$ref": "#/components/schemas/WorkspaceId" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "description": "Page size, 1 to 100 (default 50); values outside are clamped, and a non-integer means the default.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AuditEvent" } }, "meta": { "$ref": "#/components/schemas/Meta" }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/organizations/{org}/workspaces": { "get": { "operationId": "listWorkspaces", "summary": "Workspaces, searched and paged on the server", "security": [ { "consoleSession": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "environment", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Environment" } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "name", "activity" ] } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "description": "Page size, 1 to 100 (default 25); values outside are clamped, and a non-integer means the default.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Workspace" } }, "meta": { "$ref": "#/components/schemas/Meta" }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "createWorkspace", "summary": "Create a workspace in one environment", "security": [ { "consoleSession": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "$ref": "#/components/schemas/Workspace" }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "slug": { "type": "string" }, "environment": { "$ref": "#/components/schemas/Environment" }, "external_id": { "type": [ "string", "null" ] } }, "required": [ "name", "slug", "environment", "external_id" ] } } } } } }, "/v1/workspaces/{ws}": { "get": { "operationId": "getWorkspace", "summary": "A workspace", "security": [ { "consoleSession": [], "organization": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "ws", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/WorkspaceId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "$ref": "#/components/schemas/Workspace" }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } }, "patch": { "operationId": "updateWorkspace", "summary": "Rename a workspace or change its External ID", "security": [ { "consoleSession": [], "organization": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "ws", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/WorkspaceId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "$ref": "#/components/schemas/Workspace" }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "external_id": { "type": [ "string", "null" ] } } } } } } }, "delete": { "operationId": "deleteWorkspace", "summary": "Delete a workspace and everything in it", "security": [ { "consoleSession": [], "organization": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "ws", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/WorkspaceId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." } ], "responses": { "204": { "description": "Done" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/organizations/{org}/apps": { "get": { "operationId": "listOrganizationApps", "summary": "The organization's app catalog", "security": [ { "consoleSession": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/App" } }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "createOrganizationApp", "summary": "Add an app to the catalog", "security": [ { "consoleSession": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "$ref": "#/components/schemas/App" }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "mcp" ] }, "name": { "type": "string" }, "key": { "type": "string" }, "description": { "type": "string" }, "auth_type": { "type": "string", "enum": [ "oauth2", "mcp_oauth", "token" ] } }, "required": [ "kind", "name", "key", "description", "auth_type" ] } } } } } }, "/v1/organizations/{org}/apps/{app}": { "get": { "operationId": "getOrganizationApp", "summary": "A catalog app", "security": [ { "consoleSession": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "app", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/AppId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "$ref": "#/components/schemas/App" }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } }, "patch": { "operationId": "updateOrganizationApp", "summary": "Rename or describe a catalog app, or set how it authenticates", "security": [ { "consoleSession": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "app", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/AppId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "$ref": "#/components/schemas/App" }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "auth": { "$ref": "#/components/schemas/AuthTemplate" } } } } } } } }, "/v1/organizations/{org}/apps/{app}/environments/{env}/configuration": { "get": { "operationId": "getOrganizationAppConfiguration", "summary": "A catalog app's client configuration in one environment", "security": [ { "consoleSession": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "app", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/AppId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "env", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Environment" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "$ref": "#/components/schemas/ClientConfiguration" }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } }, "put": { "operationId": "updateOrganizationAppConfiguration", "summary": "Set a catalog app's client configuration in one environment", "security": [ { "consoleSession": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "app", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/AppId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "env", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Environment" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "$ref": "#/components/schemas/ClientConfiguration" }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mcp_server_url": { "type": [ "string", "null" ] }, "oauth_client_id": { "type": [ "string", "null" ] }, "oauth_client_secret": { "type": "string" }, "oauth_scopes": { "type": "array", "items": { "type": "string" } } } } } } } } }, "/v1/organizations/{org}/apps/{app}/installations": { "get": { "operationId": "listOrganizationAppInstallations", "summary": "Installations of a catalog app across workspaces", "security": [ { "consoleSession": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "app", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/AppId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "environment", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Environment" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "description": "Page size, 1 to 100 (default 25); values outside are clamped, and a non-integer means the default.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AppInstallationRef" } }, "meta": { "$ref": "#/components/schemas/Meta" }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/organizations/{org}/tool-policy": { "get": { "operationId": "getToolPolicy", "summary": "The organization's tool policy", "security": [ { "consoleSession": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "$ref": "#/components/schemas/ToolPolicy" }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } }, "put": { "operationId": "updateToolPolicy", "summary": "Set the organization's tool policy; owners and admins", "security": [ { "consoleSession": [] } ], "x-zupflow-callers": [ "console" ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "$ref": "#/components/schemas/ToolPolicy" }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "manual" ] }, "new_tool_level": { "type": "string", "enum": [ "approve", "deny" ] } }, "required": [ "mode", "new_tool_level" ] } } } } } }, "/v1/organizations/{org}/apps/{app}/tool-levels": { "get": { "operationId": "listAppToolLevels", "summary": "The organization's levels for a catalog app's tools, a page at a time by name", "security": [ { "consoleSession": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "app", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/AppId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "description": "Page size, 1 to 100 (default 25); values outside are clamped, and a non-integer means the default.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AppToolLevel" } }, "meta": { "$ref": "#/components/schemas/Meta" }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } }, "patch": { "operationId": "updateAppToolLevels", "summary": "Set levels for a catalog app's tools, by name; owners and admins", "security": [ { "consoleSession": [] } ], "x-zupflow-callers": [ "console" ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "app", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/AppId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AppToolLevel" } }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "levels": { "type": "array", "items": { "type": "object", "properties": { "tool": { "type": "string" }, "level": { "type": "string", "enum": [ "allow", "approve", "deny" ] } }, "required": [ "tool", "level" ] } } }, "required": [ "levels" ] } } } } } }, "/v1/workspaces/{ws}/apps": { "get": { "operationId": "listWorkspaceApps", "summary": "The workspace's own apps", "security": [ { "consoleSession": [], "organization": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "ws", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/WorkspaceId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/App" } }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "createWorkspaceApp", "summary": "Add an app only this workspace can use", "security": [ { "consoleSession": [], "organization": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "ws", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/WorkspaceId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "$ref": "#/components/schemas/App" }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "mcp" ] }, "name": { "type": "string" }, "key": { "type": "string" }, "description": { "type": "string" }, "auth_type": { "type": "string", "enum": [ "oauth2", "mcp_oauth", "token" ] } }, "required": [ "kind", "name", "key", "description", "auth_type" ] } } } } } }, "/v1/workspaces/{ws}/apps/{app}": { "get": { "operationId": "getWorkspaceApp", "summary": "A workspace app", "security": [ { "consoleSession": [], "organization": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "ws", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/WorkspaceId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "app", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/AppId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "$ref": "#/components/schemas/App" }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } }, "patch": { "operationId": "updateWorkspaceApp", "summary": "Rename or describe a workspace app, or set how it authenticates", "security": [ { "consoleSession": [], "organization": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "ws", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/WorkspaceId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "app", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/AppId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "$ref": "#/components/schemas/App" }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "auth": { "$ref": "#/components/schemas/AuthTemplate" } } } } } } } }, "/v1/workspaces/{ws}/apps/{app}/configuration": { "get": { "operationId": "getWorkspaceAppConfiguration", "summary": "A workspace app's client configuration", "security": [ { "consoleSession": [], "organization": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "ws", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/WorkspaceId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "app", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/AppId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "$ref": "#/components/schemas/ClientConfiguration" }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } }, "put": { "operationId": "updateWorkspaceAppConfiguration", "summary": "Set a workspace app's client configuration", "security": [ { "consoleSession": [], "organization": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "ws", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/WorkspaceId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "app", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/AppId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "$ref": "#/components/schemas/ClientConfiguration" }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mcp_server_url": { "type": [ "string", "null" ] }, "oauth_client_id": { "type": [ "string", "null" ] }, "oauth_client_secret": { "type": "string" }, "oauth_scopes": { "type": "array", "items": { "type": "string" } } } } } } } } }, "/v1/workspaces/{ws}/available-apps": { "get": { "operationId": "listAvailableApps", "summary": "Apps ready to install in this workspace", "security": [ { "consoleSession": [], "organization": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "ws", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/WorkspaceId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AvailableApp" } }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/workspaces/{ws}/installations": { "get": { "operationId": "listInstallations", "summary": "Connected accounts in a workspace", "security": [ { "consoleSession": [], "organization": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "ws", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/WorkspaceId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Installation" } }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/workspaces/{ws}/installations/{inst}": { "get": { "operationId": "getInstallation", "summary": "An installation", "security": [ { "consoleSession": [], "organization": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "ws", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/WorkspaceId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "inst", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/InstallationId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "$ref": "#/components/schemas/Installation" }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } }, "patch": { "operationId": "updateInstallation", "summary": "Rename an installation", "security": [ { "consoleSession": [], "organization": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "ws", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/WorkspaceId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "inst", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/InstallationId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "$ref": "#/components/schemas/Installation" }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string" } }, "required": [ "label" ] } } } } }, "delete": { "operationId": "deleteInstallation", "summary": "Delete an installation, its credential and its grants", "security": [ { "consoleSession": [], "organization": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "ws", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/WorkspaceId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "inst", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/InstallationId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." } ], "responses": { "204": { "description": "Done" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/workspaces/{ws}/installations/{inst}/disconnect": { "post": { "operationId": "disconnectInstallation", "summary": "Stop using an installation; its grants are kept", "security": [ { "consoleSession": [], "organization": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "ws", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/WorkspaceId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "inst", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/InstallationId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "$ref": "#/components/schemas/Installation" }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/workspaces/{ws}/installations/{inst}/tools": { "get": { "operationId": "listInstallationTools", "summary": "Tools an installation's app listed, a page at a time by name", "security": [ { "consoleSession": [], "organization": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "ws", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/WorkspaceId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "inst", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/InstallationId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "description": "Page size, 1 to 100 (default 25); values outside are clamped, and a non-integer means the default.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/InstallationTool" } }, "meta": { "$ref": "#/components/schemas/Meta" }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/workspaces/{ws}/installations/{inst}/refresh-tools": { "post": { "operationId": "refreshInstallationTools", "summary": "List a connected installation's tools again", "security": [ { "consoleSession": [], "organization": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "ws", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/WorkspaceId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "inst", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/InstallationId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "$ref": "#/components/schemas/Installation" }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/workspaces/{ws}/installations/{inst}/accept-tool-change": { "post": { "operationId": "acceptToolChange", "summary": "Accept a changed tool's latest definition; owners and admins", "security": [ { "consoleSession": [], "organization": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "ws", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/WorkspaceId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "inst", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/InstallationId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "$ref": "#/components/schemas/InstallationTool" }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "latest_hash": { "type": "string" } }, "required": [ "name", "latest_hash" ] } } } } } }, "/v1/workspaces/{ws}/connect-sessions": { "get": { "operationId": "listConnectSessions", "summary": "A workspace's Connect sessions", "security": [ { "consoleSession": [], "organization": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "ws", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/WorkspaceId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ConnectSession" } }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "createConnectSession", "summary": "Start Connect; the response's url is the hosted page, shown once", "security": [ { "consoleSession": [], "organization": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "ws", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/WorkspaceId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "$ref": "#/components/schemas/CreatedConnectSession" }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-zupflow-shows-secret-once": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "app_id": { "$ref": "#/components/schemas/AppId" }, "intent": { "type": "string", "enum": [ "create", "reconnect" ] }, "label": { "type": "string" }, "installation_id": { "anyOf": [ { "$ref": "#/components/schemas/InstallationId" }, { "type": "null" } ] }, "return_url": { "type": [ "string", "null" ] } }, "required": [ "app_id", "intent", "label", "installation_id", "return_url" ] }, { "type": "object", "properties": { "target": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "channel_app_manager" }, "provider": { "$ref": "#/components/schemas/ChannelProvider" } }, "required": [ "kind", "provider" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "channel_app" }, "app": { "$ref": "#/components/schemas/ChannelAppId" } }, "required": [ "kind", "app" ] } ] }, "return_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] } }, "required": [ "target", "return_url" ] } ] } } } } } }, "/v1/workspaces/{ws}/connect-sessions/{session}": { "get": { "operationId": "getConnectSession", "summary": "A Connect session, for polling its outcome", "security": [ { "consoleSession": [], "organization": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "ws", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/WorkspaceId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "session", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ConnectSessionId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "$ref": "#/components/schemas/ConnectSession" }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/connect/sessions/{reference}": { "get": { "operationId": "getHostedConnect", "summary": "The hosted Connect page's session, by reference", "security": [ {} ], "x-zupflow-callers": [ "connect" ], "parameters": [ { "name": "reference", "in": "path", "required": true, "schema": { "type": "string", "description": "The session's reference: the random token at the end of its `url`. Possession authorizes the page." } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "$ref": "#/components/schemas/ConnectSession" }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/connect/sessions/{reference}/credentials": { "post": { "operationId": "submitConnectCredentials", "summary": "Submit a token app's credentials", "security": [ {} ], "x-zupflow-callers": [ "connect" ], "parameters": [ { "name": "reference", "in": "path", "required": true, "schema": { "type": "string", "description": "The session's reference: the random token at the end of its `url`. Possession authorizes the page." } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "$ref": "#/components/schemas/ConnectResult" }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "values": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } } }, "required": [ "values" ] } } } } } }, "/v1/connect/sessions/{reference}/authorize": { "post": { "operationId": "authorizeConnect", "summary": "Start an OAuth app's consent", "security": [ {} ], "x-zupflow-callers": [ "connect" ], "parameters": [ { "name": "reference", "in": "path", "required": true, "schema": { "type": "string", "description": "The session's reference: the random token at the end of its `url`. Possession authorizes the page." } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "$ref": "#/components/schemas/AuthorizeConnectResult" }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-zupflow-shows-secret-once": true } }, "/v1/connect/sessions/{reference}/cancel": { "post": { "operationId": "cancelConnect", "summary": "Cancel a Connect session", "security": [ {} ], "x-zupflow-callers": [ "connect" ], "parameters": [ { "name": "reference", "in": "path", "required": true, "schema": { "type": "string", "description": "The session's reference: the random token at the end of its `url`. Possession authorizes the page." } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "$ref": "#/components/schemas/ConnectSession" }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/workspaces/{ws}/agents": { "get": { "operationId": "listAgents", "summary": "A workspace's agents", "security": [ { "consoleSession": [], "organization": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "ws", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/WorkspaceId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Agent" } }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "createAgent", "summary": "Create an agent", "security": [ { "consoleSession": [], "organization": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "ws", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/WorkspaceId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "$ref": "#/components/schemas/Agent" }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "model_id": { "anyOf": [ { "$ref": "#/components/schemas/ModelId" }, { "type": "null" } ] }, "instructions": { "type": "string" } }, "required": [ "name", "description", "instructions" ] } } } } } }, "/v1/workspaces/{ws}/agents/{agent}": { "get": { "operationId": "getAgent", "summary": "An agent", "security": [ { "consoleSession": [], "organization": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "ws", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/WorkspaceId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "agent", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/AgentId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "$ref": "#/components/schemas/Agent" }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } }, "patch": { "operationId": "updateAgent", "summary": "Change an agent, or pause it", "security": [ { "consoleSession": [], "organization": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "ws", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/WorkspaceId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "agent", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/AgentId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "$ref": "#/components/schemas/Agent" }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "model_id": { "anyOf": [ { "$ref": "#/components/schemas/ModelId" }, { "type": "null" } ] }, "instructions": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "paused" ] } } } } } } }, "delete": { "operationId": "deleteAgent", "summary": "Delete an agent and its grants", "security": [ { "consoleSession": [], "organization": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "ws", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/WorkspaceId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "agent", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/AgentId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." } ], "responses": { "204": { "description": "Done" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/workspaces/{ws}/agents/{agent}/grants": { "get": { "operationId": "listGrants", "summary": "An agent's grants", "security": [ { "consoleSession": [], "organization": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "ws", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/WorkspaceId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "agent", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/AgentId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Grant" } }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "createGrant", "summary": "Grant an agent tools of one installation", "security": [ { "consoleSession": [], "organization": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "ws", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/WorkspaceId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "agent", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/AgentId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "$ref": "#/components/schemas/Grant" }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "installation_id": { "$ref": "#/components/schemas/InstallationId" }, "tools": { "type": "array", "items": { "type": "string" } }, "approval_required": { "type": "array", "items": { "type": "string" } } }, "required": [ "installation_id", "tools", "approval_required" ] } } } } } }, "/v1/workspaces/{ws}/agents/{agent}/grants/{grant}": { "patch": { "operationId": "updateGrant", "summary": "Change a grant's tools and approvals", "security": [ { "consoleSession": [], "organization": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "ws", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/WorkspaceId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "agent", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/AgentId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "grant", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/GrantId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "$ref": "#/components/schemas/Grant" }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tools": { "type": "array", "items": { "type": "string" } }, "approval_required": { "type": "array", "items": { "type": "string" } } }, "required": [ "tools", "approval_required" ] } } } } }, "delete": { "operationId": "deleteGrant", "summary": "Revoke a grant", "security": [ { "consoleSession": [], "organization": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "ws", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/WorkspaceId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "agent", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/AgentId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "grant", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/GrantId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." } ], "responses": { "204": { "description": "Done" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/workspaces/{ws}/agents/{agent}/runs": { "post": { "operationId": "startRun", "summary": "Start a run on the agent's model, or its environment's default. With neither, `422 model_not_configured`", "security": [ { "consoleSession": [], "organization": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "ws", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/WorkspaceId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "agent", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/AgentId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "$ref": "#/components/schemas/Run" }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "input": { "type": "string" } }, "required": [ "input" ] } } } } } }, "/v1/workspaces/{ws}/runs": { "get": { "operationId": "listRuns", "summary": "A workspace's runs, newest first", "security": [ { "consoleSession": [], "organization": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "ws", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/WorkspaceId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "agent_id", "in": "query", "required": false, "schema": { "description": "Only this agent's runs. A malformed or unknown ID matches nothing.", "$ref": "#/components/schemas/AgentId" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "queued", "running", "waiting_for_approval", "completed", "failed", "cancelled" ] } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "description": "Page size, 1 to 100 (default 25); values outside are clamped, and a non-integer means the default.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Run" } }, "meta": { "$ref": "#/components/schemas/Meta" }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/workspaces/{ws}/runs/{run}": { "get": { "operationId": "getRun", "summary": "A run", "security": [ { "consoleSession": [], "organization": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "ws", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/WorkspaceId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "run", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/RunId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "$ref": "#/components/schemas/Run" }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/workspaces/{ws}/runs/{run}/events": { "get": { "operationId": "listRunEvents", "summary": "A run's timeline, in order", "security": [ { "consoleSession": [], "organization": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "ws", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/WorkspaceId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "run", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/RunId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RunEvent" } }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/workspaces/{ws}/runs/{run}/cancel": { "post": { "operationId": "cancelRun", "summary": "Cancel a run", "security": [ { "consoleSession": [], "organization": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "ws", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/WorkspaceId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "run", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/RunId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "$ref": "#/components/schemas/Run" }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/workspaces/{ws}/runs/{run}/approvals": { "post": { "operationId": "resolveApproval", "summary": "Record a decision your product made; API keys only", "security": [ { "apiKey": [] } ], "x-zupflow-callers": [ "api_key" ], "parameters": [ { "name": "ws", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/WorkspaceId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "run", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/RunId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "$ref": "#/components/schemas/Run" }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "call_id": { "$ref": "#/components/schemas/ToolCallId" }, "decision": { "type": "string", "enum": [ "approved", "denied" ] }, "reason": { "type": "string", "maxLength": 500 } }, "required": [ "call_id", "decision" ] } } } } } }, "/v1/organizations/{org}/model-connections": { "get": { "operationId": "listModelConnections", "summary": "The organization's model provider connections, oldest first", "security": [ { "consoleSession": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "environment", "in": "query", "required": false, "schema": { "description": "Only this environment's connections. An API key reads its own environment's; naming another is `422 environment_mismatch`.", "$ref": "#/components/schemas/Environment" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ModelConnection" } }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "createModelConnection", "summary": "Connect a model provider in one environment with an API key, checked with the provider first (`422 invalid_api_key`; `501 model_providers_not_configured` when the deployment reaches no model providers)", "security": [ { "consoleSession": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "$ref": "#/components/schemas/ModelConnection" }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "environment": { "$ref": "#/components/schemas/Environment" }, "kind": { "$ref": "#/components/schemas/ModelProviderKind" }, "label": { "type": "string" }, "api_key": { "type": "string" } }, "required": [ "environment", "kind", "label", "api_key" ] } } } } } }, "/v1/organizations/{org}/model-connections/{connection}": { "get": { "operationId": "getModelConnection", "summary": "A model provider connection", "security": [ { "consoleSession": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "connection", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ModelConnectionId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "$ref": "#/components/schemas/ModelConnection" }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } }, "patch": { "operationId": "updateModelConnection", "summary": "Rename a model provider connection", "security": [ { "consoleSession": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "connection", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ModelConnectionId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "$ref": "#/components/schemas/ModelConnection" }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string" } }, "required": [ "label" ] } } } } }, "delete": { "operationId": "deleteModelConnection", "summary": "Delete a connection, its key and its models. Refused while one of its models is the environment's default or an agent's (`409 model_in_use`, naming them)", "security": [ { "consoleSession": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "connection", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ModelConnectionId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." } ], "responses": { "204": { "description": "Done" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/organizations/{org}/model-connections/{connection}/api-key": { "put": { "operationId": "replaceModelConnectionKey", "summary": "Replace a connection's API key with a new version, checked with the provider first (`422 invalid_api_key`, keeping the old one; `501 model_providers_not_configured` when the deployment reaches no model providers). `409 key_changed` when another request replaced the key meanwhile: nothing changes, and the connection shows the newer key", "security": [ { "consoleSession": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "connection", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ModelConnectionId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "$ref": "#/components/schemas/ModelConnection" }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "api_key": { "type": "string" } }, "required": [ "api_key" ] } } } } } }, "/v1/organizations/{org}/model-connections/{connection}/provider-models": { "get": { "operationId": "listProviderModels", "summary": "Search the models the connection's provider lists for its key, a page at a time. `422 invalid_api_key` when the provider refuses the key; `501 model_providers_not_configured` when the deployment reaches no model providers", "security": [ { "consoleSession": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "connection", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ModelConnectionId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "description": "Page size, 1 to 100 (default 25); values outside are clamped, and a non-integer means the default.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProviderModel" } }, "meta": { "$ref": "#/components/schemas/Meta" }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/organizations/{org}/models": { "get": { "operationId": "listModels", "summary": "Models the organization added, by name, searched and paged on the server", "security": [ { "consoleSession": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "description": "Page size, 1 to 100 (default 25); values outside are clamped, and a non-integer means the default.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, { "name": "environment", "in": "query", "required": false, "schema": { "description": "Only this environment's models. An API key reads its own environment's; naming another is `422 environment_mismatch`.", "$ref": "#/components/schemas/Environment" } }, { "name": "connection_id", "in": "query", "required": false, "schema": { "description": "Only this connection's models. A malformed or unknown ID matches nothing.", "$ref": "#/components/schemas/ModelConnectionId" } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Model" } }, "meta": { "$ref": "#/components/schemas/Meta" }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "createModel", "summary": "Add a model from a connection, in the connection's environment", "security": [ { "consoleSession": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "$ref": "#/components/schemas/Model" }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "connection_id": { "$ref": "#/components/schemas/ModelConnectionId" }, "provider_model_id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "connection_id", "provider_model_id" ] } } } } } }, "/v1/organizations/{org}/models/{model}": { "get": { "operationId": "getModel", "summary": "A model", "security": [ { "consoleSession": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "model", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ModelId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "$ref": "#/components/schemas/Model" }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } }, "patch": { "operationId": "updateModel", "summary": "Rename a model", "security": [ { "consoleSession": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "model", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ModelId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "$ref": "#/components/schemas/Model" }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] } } } } }, "delete": { "operationId": "deleteModel", "summary": "Remove a model. Refused while it is the environment's default or an agent's (`409 model_in_use`, naming them)", "security": [ { "consoleSession": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "model", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ModelId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." } ], "responses": { "204": { "description": "Done" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/organizations/{org}/default-models/{env}": { "get": { "operationId": "getDefaultModel", "summary": "The model agents in one environment run on unless they override it", "security": [ { "consoleSession": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "env", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Environment" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "$ref": "#/components/schemas/DefaultModel" }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } }, "put": { "operationId": "updateDefaultModel", "summary": "Choose an environment's default model, or none", "security": [ { "consoleSession": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "env", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Environment" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "$ref": "#/components/schemas/DefaultModel" }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model_id": { "anyOf": [ { "$ref": "#/components/schemas/ModelId" }, { "type": "null" } ] } }, "required": [ "model_id" ] } } } } } }, "/v1/organizations/{org}/connect-settings/{env}": { "get": { "operationId": "getConnectSettings", "summary": "Connect's return URLs and origins in one environment", "security": [ { "consoleSession": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "env", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Environment" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "$ref": "#/components/schemas/ConnectSettings" }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } }, "put": { "operationId": "updateConnectSettings", "summary": "Set Connect's return URLs and origins in one environment", "security": [ { "consoleSession": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "env", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Environment" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "$ref": "#/components/schemas/ConnectSettings" }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "return_urls": { "type": "array", "items": { "type": "string" } }, "allowed_origins": { "type": "array", "items": { "type": "string" } } }, "required": [ "return_urls", "allowed_origins" ] } } } } } }, "/v1/organizations/{org}/api-keys": { "get": { "operationId": "listApiKeys", "summary": "API keys", "security": [ { "consoleSession": [] } ], "x-zupflow-callers": [ "console" ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" } }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "createApiKey", "summary": "Create an API key; the secret is shown once", "security": [ { "consoleSession": [] } ], "x-zupflow-callers": [ "console" ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "$ref": "#/components/schemas/CreatedApiKey" }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-zupflow-shows-secret-once": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "environment": { "$ref": "#/components/schemas/Environment" } }, "required": [ "name", "environment" ] } } } } } }, "/v1/organizations/{org}/api-keys/{key}/revoke": { "post": { "operationId": "revokeApiKey", "summary": "Revoke an API key", "security": [ { "consoleSession": [] } ], "x-zupflow-callers": [ "console" ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "key", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ApiKeyId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "$ref": "#/components/schemas/ApiKey" }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/organizations/{org}/webhooks": { "get": { "operationId": "listWebhooks", "summary": "Webhook endpoints", "security": [ { "consoleSession": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpoint" } }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "createWebhook", "summary": "Add a webhook endpoint; the signing secret is shown once", "security": [ { "consoleSession": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "$ref": "#/components/schemas/CreatedWebhookEndpoint" }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-zupflow-shows-secret-once": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "environment": { "$ref": "#/components/schemas/Environment" }, "url": { "type": "string" }, "description": { "type": "string" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "installation.connected", "installation.reconnect_required", "installation.disconnected", "connect_session.completed", "connect_session.failed", "run.completed", "run.failed", "run.waiting_for_approval", "run.cancelled", "app.tools_changed", "channel_message.received", "channel_message.sent", "channel_app_manager.status_changed", "channel_app.status_changed", "channel_connection.status_changed", "channel_conversation.paused" ] } } }, "required": [ "environment", "url", "description", "events" ] } } } } } }, "/v1/organizations/{org}/webhooks/{hook}": { "patch": { "operationId": "updateWebhook", "summary": "Change a webhook endpoint", "security": [ { "consoleSession": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "hook", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/WebhookEndpointId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "$ref": "#/components/schemas/WebhookEndpoint" }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "description": { "type": "string" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "installation.connected", "installation.reconnect_required", "installation.disconnected", "connect_session.completed", "connect_session.failed", "run.completed", "run.failed", "run.waiting_for_approval", "run.cancelled", "app.tools_changed", "channel_message.received", "channel_message.sent", "channel_app_manager.status_changed", "channel_app.status_changed", "channel_connection.status_changed", "channel_conversation.paused" ] } }, "enabled": { "type": "boolean" } } } } } } }, "delete": { "operationId": "deleteWebhook", "summary": "Delete a webhook endpoint", "security": [ { "consoleSession": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "hook", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/WebhookEndpointId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." } ], "responses": { "204": { "description": "Done" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/organizations/{org}/webhooks/{hook}/roll-secret": { "post": { "operationId": "rollWebhookSecret", "summary": "Roll an endpoint's signing secret, returning the new secret once. Owners, admins and an API key for the endpoint's environment may roll, including disabled endpoints and Production. The previous secret remains valid for 24 hours; deliveries carry signatures for both secrets over the same timestamp and body until then. previous_signing_secret_expires_at is null at or after the deadline. A second roll during overlap is `409 rotation_in_progress`, even with a fresh idempotency key. Replaying a successful key is `409 idempotency_key_completed` and never returns the secret again. A missing or foreign endpoint is `404`. Records webhook.secret_rolled against the existing webhook endpoint, with no workspace and the endpoint's environment.", "security": [ { "consoleSession": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "hook", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/WebhookEndpointId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "$ref": "#/components/schemas/CreatedWebhookEndpoint" }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-zupflow-shows-secret-once": true } }, "/v1/organizations/{org}/webhooks/{hook}/deliveries": { "get": { "operationId": "listWebhookDeliveries", "summary": "An endpoint's deliveries, newest first by creation time and ID. Every member may read; an API key reads only its environment. Unknown state/event_type or a missing, foreign or other-environment workspace filter matches nothing. A malformed cursor, or one from another endpoint or set of filters, is `400 validation_failed`.", "security": [ { "consoleSession": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "hook", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/WebhookEndpointId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "description": "Page size, 1 to 100 (default 25); values outside are clamped, and a non-integer means the default.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, { "name": "workspace_id", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/WorkspaceId" } }, { "name": "state", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "succeeded", "failed", "skipped" ] } }, { "name": "event_type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "installation.connected", "installation.reconnect_required", "installation.disconnected", "connect_session.completed", "connect_session.failed", "run.completed", "run.failed", "run.waiting_for_approval", "run.cancelled", "app.tools_changed", "channel_message.received", "channel_message.sent", "channel_app_manager.status_changed", "channel_app.status_changed", "channel_connection.status_changed", "channel_conversation.paused", "webhook.test" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDeliverySummary" } }, "meta": { "$ref": "#/components/schemas/Meta" }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/organizations/{org}/webhooks/{hook}/deliveries/{delivery}": { "get": { "operationId": "getWebhookDelivery", "summary": "A delivery and its lean event. A missing, foreign or wrong-endpoint delivery is `404`. Older deliveries may have incomplete attempt history; response bodies, request headers and signatures are never returned.", "security": [ { "consoleSession": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "hook", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/WebhookEndpointId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "delivery", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/WebhookDeliveryId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "$ref": "#/components/schemas/WebhookDeliveryDetail" }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/organizations/{org}/webhooks/{hook}/deliveries/{delivery}/attempts": { "get": { "operationId": "listWebhookDeliveryAttempts", "summary": "A delivery's recorded attempts, oldest first by number. A malformed cursor or one from another delivery is `400 validation_failed`. Historical summary-only attempts are not fabricated.", "security": [ { "consoleSession": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "hook", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/WebhookEndpointId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "delivery", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/WebhookDeliveryId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "description": "Page size, 1 to 100 (default 25); values outside are clamped, and a non-integer means the default.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDeliveryAttempt" } }, "meta": { "$ref": "#/components/schemas/Meta" }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/organizations/{org}/webhooks/{hook}/deliveries/{delivery}/resend": { "post": { "operationId": "resendWebhookDelivery", "summary": "Queue a new pending delivery of the original event, preserving its ID and body and leaving the source history unchanged. Owners, admins and an API key for the endpoint's environment may resend, including in Production. The new delivery starts with zero attempts and the normal retry budget. A pending source (including an in-flight send) is `409 delivery_pending`, a disabled endpoint `409 webhook_disabled`, and one no longer subscribed `409 webhook_not_subscribed`; webhook.test is exempt from subscriptions. A missing, foreign or wrong-endpoint delivery is `404`. Normal POST idempotency applies. Records webhook.delivery_resent against the new webhook_delivery, attributed to the event's workspace and environment.", "security": [ { "consoleSession": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "hook", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/WebhookEndpointId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "delivery", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/WebhookDeliveryId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "$ref": "#/components/schemas/WebhookDeliverySummary" }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/organizations/{org}/webhooks/{hook}/test": { "post": { "operationId": "testWebhook", "summary": "Send a test delivery", "security": [ { "consoleSession": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "hook", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/WebhookEndpointId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "$ref": "#/components/schemas/WebhookDelivery" }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/workspaces/{ws}/channel-app-managers": { "get": { "operationId": "listChannelAppManagers", "summary": "The workspace's linked teams, newest first", "security": [ { "consoleSession": [], "organization": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "ws", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/WorkspaceId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "description": "Page size, 1 to 100 (default 25); values outside are clamped, and a non-integer means the default.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ChannelAppManager" } }, "meta": { "$ref": "#/components/schemas/Meta" }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "createChannelAppManager", "summary": "Link a team with a configuration token, so Zupflow can create apps for the workspace's agents there. Developers and API keys; the Console can't in Production (`403 console_read_only_in_production`). A token the provider refuses is `422 invalid_configuration_token`", "security": [ { "consoleSession": [], "organization": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "ws", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/WorkspaceId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "$ref": "#/components/schemas/ChannelAppManager" }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "provider": { "$ref": "#/components/schemas/ChannelProvider" }, "method": { "type": "string", "enum": [ "configuration_token" ] }, "configuration_token": { "type": "string", "minLength": 1, "maxLength": 4096 }, "refresh_token": { "type": "string", "minLength": 1, "maxLength": 4096 } }, "required": [ "provider", "method", "configuration_token", "refresh_token" ] } } } } } }, "/v1/workspaces/{ws}/channel-app-managers/{manager}": { "get": { "operationId": "getChannelAppManager", "summary": "A linked team", "security": [ { "consoleSession": [], "organization": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "ws", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/WorkspaceId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "manager", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ChannelAppManagerId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "$ref": "#/components/schemas/ChannelAppManager" }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } }, "patch": { "operationId": "updateChannelAppManager", "summary": "Replace a linked team's tokens; it's `active` again. Developers and API keys; the Console can't in Production", "security": [ { "consoleSession": [], "organization": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "ws", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/WorkspaceId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "manager", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ChannelAppManagerId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "$ref": "#/components/schemas/ChannelAppManager" }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "configuration_token": { "type": "string", "minLength": 1, "maxLength": 4096 }, "refresh_token": { "type": "string", "minLength": 1, "maxLength": 4096 } }, "required": [ "configuration_token", "refresh_token" ] } } } } }, "delete": { "operationId": "deleteChannelAppManager", "summary": "Unlink a team and forget its tokens. Refused while it has apps that aren't deleted, or deleted apps not yet removed at the provider (its tokens remove them; pasting new ones retries): `409 in_use`", "security": [ { "consoleSession": [], "organization": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "ws", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/WorkspaceId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "manager", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ChannelAppManagerId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." } ], "responses": { "204": { "description": "Done" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/workspaces/{ws}/channel-apps": { "get": { "operationId": "listChannelApps", "summary": "The workspace's generated apps, newest first; deleted ones aren't listed", "security": [ { "consoleSession": [], "organization": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "ws", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/WorkspaceId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "description": "Page size, 1 to 100 (default 25); values outside are clamped, and a non-integer means the default.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, { "name": "agent_id", "in": "query", "required": false, "schema": { "description": "Only this agent's apps. A malformed or unknown ID matches nothing.", "$ref": "#/components/schemas/AgentId" } }, { "name": "manager_id", "in": "query", "required": false, "schema": { "description": "Only this manager's apps. A malformed or unknown ID matches nothing.", "$ref": "#/components/schemas/ChannelAppManagerId" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ChannelApp" } }, "meta": { "$ref": "#/components/schemas/Meta" }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "createChannelApp", "summary": "Make an agent's own app in a linked team. Answers `202` with the app `creating`; a job makes it with the provider. Developers and API keys; the Console can't in Production", "security": [ { "consoleSession": [], "organization": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "ws", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/WorkspaceId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "202": { "description": "Accepted: a job finishes it", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "$ref": "#/components/schemas/ChannelApp" }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_id": { "$ref": "#/components/schemas/AgentId" }, "manager_id": { "$ref": "#/components/schemas/ChannelAppManagerId" } }, "required": [ "agent_id", "manager_id" ] } } } } } }, "/v1/workspaces/{ws}/channel-apps/{app}": { "get": { "operationId": "getChannelApp", "summary": "A generated app; a deleted one is `404`", "security": [ { "consoleSession": [], "organization": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "ws", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/WorkspaceId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "app", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ChannelAppId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "$ref": "#/components/schemas/ChannelApp" }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } }, "delete": { "operationId": "deleteChannelApp", "summary": "Remove an agent's app: its token is revoked and the provider's app deleted, its connection disconnected and the agent's channel on it removed", "security": [ { "consoleSession": [], "organization": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "ws", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/WorkspaceId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "app", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ChannelAppId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." } ], "responses": { "204": { "description": "Done" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/workspaces/{ws}/channel-connections": { "get": { "operationId": "listChannelConnections", "summary": "The workspace's channel connections, newest first", "security": [ { "consoleSession": [], "organization": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "ws", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/WorkspaceId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "description": "Page size, 1 to 100 (default 25); values outside are clamped, and a non-integer means the default.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, { "name": "agent_id", "in": "query", "required": false, "schema": { "description": "Only this agent's connections. A malformed or unknown ID matches nothing.", "$ref": "#/components/schemas/AgentId" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ChannelConnection" } }, "meta": { "$ref": "#/components/schemas/Meta" }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/workspaces/{ws}/channel-connections/{channel_connection}": { "get": { "operationId": "getChannelConnection", "summary": "A channel connection", "security": [ { "consoleSession": [], "organization": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "ws", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/WorkspaceId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "channel_connection", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ChannelConnectionId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "$ref": "#/components/schemas/ChannelConnection" }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } }, "patch": { "operationId": "updateChannelConnection", "summary": "Rename a channel connection, or set its handler", "security": [ { "consoleSession": [], "organization": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "ws", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/WorkspaceId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "channel_connection", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ChannelConnectionId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "$ref": "#/components/schemas/ChannelConnection" }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 40 }, "handler": { "type": "string", "enum": [ "mention" ] } } } } } } }, "delete": { "operationId": "deleteChannelConnection", "summary": "Disconnect: the token is revoked, and the connection, its conversations, messages and agent channel removed. Its app waits for a new install", "security": [ { "consoleSession": [], "organization": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "ws", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/WorkspaceId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "channel_connection", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ChannelConnectionId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." } ], "responses": { "204": { "description": "Done" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/workspaces/{ws}/channel-connections/{channel_connection}/conversations": { "get": { "operationId": "listChannelConversations", "summary": "The conversations a connection has seen messages in, most recent first; `q` searches names", "security": [ { "consoleSession": [], "organization": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "ws", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/WorkspaceId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "channel_connection", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ChannelConnectionId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "description": "Page size, 1 to 100 (default 25); values outside are clamped, and a non-integer means the default.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "kind", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "channel", "private_channel", "dm", "group_dm" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ChannelConversation" } }, "meta": { "$ref": "#/components/schemas/Meta" }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/workspaces/{ws}/channel-connections/{channel_connection}/conversations/{conversation}/messages": { "get": { "operationId": "listChannelMessages", "summary": "A conversation's messages, newest first; `thread` keeps one thread's", "security": [ { "consoleSession": [], "organization": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "ws", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/WorkspaceId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "channel_connection", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ChannelConnectionId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "conversation", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ChannelConversationId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "description": "Page size, 1 to 100 (default 25); values outside are clamped, and a non-integer means the default.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, { "name": "thread", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ChannelMessage" } }, "meta": { "$ref": "#/components/schemas/Meta" }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/workspaces/{ws}/agents/{agent}/channels": { "get": { "operationId": "listAgentChannels", "summary": "An agent's channels: one per connection of its own apps", "security": [ { "consoleSession": [], "organization": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "ws", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/WorkspaceId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "agent", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/AgentId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AgentChannel" } }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/workspaces/{ws}/agents/{agent}/channels/{channel_connection}": { "put": { "operationId": "putAgentChannel", "summary": "Set an agent's channel on one of its own connections, creating it if it isn't there", "security": [ { "consoleSession": [], "organization": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "ws", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/WorkspaceId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "agent", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/AgentId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "channel_connection", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ChannelConnectionId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "$ref": "#/components/schemas/AgentChannel" }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tools": { "type": "array", "items": { "type": "string" } }, "approval_required": { "type": "array", "items": { "type": "string" } }, "audience": { "type": "string", "enum": [ "origin", "listed", "anywhere" ] }, "audience_conversations": { "type": "array", "items": { "$ref": "#/components/schemas/ChannelConversationId" } }, "persona": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "avatar_url": { "anyOf": [ { "type": "string", "pattern": "^https:\\/\\/\\S+$" }, { "type": "null" } ] } }, "required": [ "name", "avatar_url" ] }, { "type": "null" } ] }, "answers_dms": { "type": "boolean" }, "answers_mentions": { "type": "boolean" }, "thread_follow_up": { "type": "string", "enum": [ "off", "when_last_addressed", "always" ] }, "agent_messages": { "type": "string", "enum": [ "ignore", "mentions" ] }, "max_agent_hops": { "type": "integer", "minimum": 1, "maximum": 5 }, "mid_run": { "type": "string", "enum": [ "steer", "collect" ] }, "senders": { "type": "string", "enum": [ "anyone", "listed" ] }, "sender_list": { "maxItems": 500, "type": "array", "items": { "type": "string", "maxLength": 320, "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" } }, "allow_automated": { "type": "boolean" }, "allow_external": { "type": "boolean" }, "reply_with_output": { "type": "boolean" } }, "required": [ "tools", "approval_required", "audience", "audience_conversations", "persona", "answers_dms", "answers_mentions", "thread_follow_up", "agent_messages", "max_agent_hops", "mid_run", "senders", "sender_list", "allow_automated", "allow_external", "reply_with_output" ] } } } } }, "delete": { "operationId": "deleteAgentChannel", "summary": "Stop an agent answering on a connection; the connection stays", "security": [ { "consoleSession": [], "organization": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "ws", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/WorkspaceId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "agent", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/AgentId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." }, { "name": "channel_connection", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ChannelConnectionId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." } ], "responses": { "204": { "description": "Done" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/organizations/{org}/channel-tool-levels": { "get": { "operationId": "listChannelToolLevels", "summary": "The organization's level for every channel tool, by provider", "security": [ { "consoleSession": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ChannelToolLevel" } }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } }, "put": { "operationId": "updateChannelToolLevels", "summary": "Set channel tool levels: owners and admins, from the Console", "security": [ { "consoleSession": [] } ], "x-zupflow-callers": [ "console" ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ChannelToolLevel" } }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "provider": { "$ref": "#/components/schemas/ChannelProvider" }, "levels": { "minItems": 1, "maxItems": 14, "type": "array", "items": { "type": "object", "properties": { "tool": { "type": "string" }, "level": { "type": "string", "enum": [ "allow", "approve", "deny" ] } }, "required": [ "tool", "level" ] } } }, "required": [ "provider", "levels" ] } } } } } }, "/v1/organizations/{org}/channel-settings": { "get": { "operationId": "getChannelSettings", "summary": "The organization's conversation breaker and message retention", "security": [ { "consoleSession": [] }, { "apiKey": [] } ], "x-zupflow-callers": [ "console", "api_key" ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "$ref": "#/components/schemas/ChannelSettings" }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } }, "put": { "operationId": "updateChannelSettings", "summary": "Set the conversation breaker and message retention: owners and admins, from the Console", "security": [ { "consoleSession": [] } ], "x-zupflow-callers": [ "console" ], "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationId" }, "description": "A malformed ID, or an ID of another type, answers 404 like a missing one." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "error" ], "properties": { "data": { "$ref": "#/components/schemas/ChannelSettings" }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "null" } ] }, "error": { "type": "null" } } } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "breaker_runs": { "type": "integer", "minimum": 1, "maximum": 200 }, "breaker_window_minutes": { "type": "integer", "minimum": 1, "maximum": 1440 }, "breaker_pause_minutes": { "type": "integer", "minimum": 1, "maximum": 1440 }, "message_retention_days": { "type": "integer", "minimum": 1, "maximum": 365 } }, "required": [ "breaker_runs", "breaker_window_minutes", "breaker_pause_minutes", "message_retention_days" ] } } } } } }, "/channels/inbound/{inbound_ref}": { "post": { "operationId": "receiveChannelEvent", "summary": "Where a provider delivers one app's events. Slack signs each request (`X-Slack-Signature`, `X-Slack-Request-Timestamp`) with the app's signing secret: an unknown reference, a bad signature or a timestamp more than five minutes off is `401`, before anything is stored. A delivery seen before (by its event ID) is answered again without effect. Not idempotency-keyed: the provider's event ID is the key", "security": [ {} ], "x-zupflow-callers": [ "provider" ], "parameters": [ { "name": "inbound_ref", "in": "path", "required": true, "schema": { "type": "string", "description": "The app's inbound reference: 32 random characters, set when the app is made. Not an ID." } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelInboundAnswer" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-zupflow-unwrapped": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {} } } } } } } }, "webhooks": { "installation.connected": { "post": { "operationId": "webhook_installation_connected", "summary": "`installation.connected`", "parameters": [ { "name": "Zupflow-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "`t=,v1=` over `\".\"` with the endpoint's signing secret; two `v1` values during a rotation. Verify against the raw body in constant time and reject a timestamp more than 300 seconds from your clock. The SDK's `verifyWebhook` does all of it." }, { "name": "Zupflow-Event-Id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The event's `id`: the same on every attempt and resend. Skip IDs you've already handled." }, { "name": "Zupflow-Delivery-Attempt", "in": "header", "required": true, "schema": { "type": "integer", "minimum": 1 } }, { "name": "User-Agent", "in": "header", "required": true, "schema": { "type": "string", "const": "Zupflow-Webhooks/1" } }, { "name": "Zupflow-Event-Type", "in": "header", "required": true, "schema": { "type": "string", "const": "installation.connected" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstallationConnectedWebhookEvent" } } } }, "responses": { "2XX": { "description": "Received. Answer within 10 seconds, then fetch current state; any other answer or a timeout is retried." } } } }, "installation.reconnect_required": { "post": { "operationId": "webhook_installation_reconnect_required", "summary": "`installation.reconnect_required`", "parameters": [ { "name": "Zupflow-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "`t=,v1=` over `\".\"` with the endpoint's signing secret; two `v1` values during a rotation. Verify against the raw body in constant time and reject a timestamp more than 300 seconds from your clock. The SDK's `verifyWebhook` does all of it." }, { "name": "Zupflow-Event-Id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The event's `id`: the same on every attempt and resend. Skip IDs you've already handled." }, { "name": "Zupflow-Delivery-Attempt", "in": "header", "required": true, "schema": { "type": "integer", "minimum": 1 } }, { "name": "User-Agent", "in": "header", "required": true, "schema": { "type": "string", "const": "Zupflow-Webhooks/1" } }, { "name": "Zupflow-Event-Type", "in": "header", "required": true, "schema": { "type": "string", "const": "installation.reconnect_required" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstallationReconnectRequiredWebhookEvent" } } } }, "responses": { "2XX": { "description": "Received. Answer within 10 seconds, then fetch current state; any other answer or a timeout is retried." } } } }, "installation.disconnected": { "post": { "operationId": "webhook_installation_disconnected", "summary": "`installation.disconnected`", "parameters": [ { "name": "Zupflow-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "`t=,v1=` over `\".\"` with the endpoint's signing secret; two `v1` values during a rotation. Verify against the raw body in constant time and reject a timestamp more than 300 seconds from your clock. The SDK's `verifyWebhook` does all of it." }, { "name": "Zupflow-Event-Id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The event's `id`: the same on every attempt and resend. Skip IDs you've already handled." }, { "name": "Zupflow-Delivery-Attempt", "in": "header", "required": true, "schema": { "type": "integer", "minimum": 1 } }, { "name": "User-Agent", "in": "header", "required": true, "schema": { "type": "string", "const": "Zupflow-Webhooks/1" } }, { "name": "Zupflow-Event-Type", "in": "header", "required": true, "schema": { "type": "string", "const": "installation.disconnected" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstallationDisconnectedWebhookEvent" } } } }, "responses": { "2XX": { "description": "Received. Answer within 10 seconds, then fetch current state; any other answer or a timeout is retried." } } } }, "connect_session.completed": { "post": { "operationId": "webhook_connect_session_completed", "summary": "`connect_session.completed`", "parameters": [ { "name": "Zupflow-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "`t=,v1=` over `\".\"` with the endpoint's signing secret; two `v1` values during a rotation. Verify against the raw body in constant time and reject a timestamp more than 300 seconds from your clock. The SDK's `verifyWebhook` does all of it." }, { "name": "Zupflow-Event-Id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The event's `id`: the same on every attempt and resend. Skip IDs you've already handled." }, { "name": "Zupflow-Delivery-Attempt", "in": "header", "required": true, "schema": { "type": "integer", "minimum": 1 } }, { "name": "User-Agent", "in": "header", "required": true, "schema": { "type": "string", "const": "Zupflow-Webhooks/1" } }, { "name": "Zupflow-Event-Type", "in": "header", "required": true, "schema": { "type": "string", "const": "connect_session.completed" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectSessionCompletedWebhookEvent" } } } }, "responses": { "2XX": { "description": "Received. Answer within 10 seconds, then fetch current state; any other answer or a timeout is retried." } } } }, "connect_session.failed": { "post": { "operationId": "webhook_connect_session_failed", "summary": "`connect_session.failed`", "parameters": [ { "name": "Zupflow-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "`t=,v1=` over `\".\"` with the endpoint's signing secret; two `v1` values during a rotation. Verify against the raw body in constant time and reject a timestamp more than 300 seconds from your clock. The SDK's `verifyWebhook` does all of it." }, { "name": "Zupflow-Event-Id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The event's `id`: the same on every attempt and resend. Skip IDs you've already handled." }, { "name": "Zupflow-Delivery-Attempt", "in": "header", "required": true, "schema": { "type": "integer", "minimum": 1 } }, { "name": "User-Agent", "in": "header", "required": true, "schema": { "type": "string", "const": "Zupflow-Webhooks/1" } }, { "name": "Zupflow-Event-Type", "in": "header", "required": true, "schema": { "type": "string", "const": "connect_session.failed" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectSessionFailedWebhookEvent" } } } }, "responses": { "2XX": { "description": "Received. Answer within 10 seconds, then fetch current state; any other answer or a timeout is retried." } } } }, "run.completed": { "post": { "operationId": "webhook_run_completed", "summary": "`run.completed`", "parameters": [ { "name": "Zupflow-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "`t=,v1=` over `\".\"` with the endpoint's signing secret; two `v1` values during a rotation. Verify against the raw body in constant time and reject a timestamp more than 300 seconds from your clock. The SDK's `verifyWebhook` does all of it." }, { "name": "Zupflow-Event-Id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The event's `id`: the same on every attempt and resend. Skip IDs you've already handled." }, { "name": "Zupflow-Delivery-Attempt", "in": "header", "required": true, "schema": { "type": "integer", "minimum": 1 } }, { "name": "User-Agent", "in": "header", "required": true, "schema": { "type": "string", "const": "Zupflow-Webhooks/1" } }, { "name": "Zupflow-Event-Type", "in": "header", "required": true, "schema": { "type": "string", "const": "run.completed" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunCompletedWebhookEvent" } } } }, "responses": { "2XX": { "description": "Received. Answer within 10 seconds, then fetch current state; any other answer or a timeout is retried." } } } }, "run.failed": { "post": { "operationId": "webhook_run_failed", "summary": "`run.failed`", "parameters": [ { "name": "Zupflow-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "`t=,v1=` over `\".\"` with the endpoint's signing secret; two `v1` values during a rotation. Verify against the raw body in constant time and reject a timestamp more than 300 seconds from your clock. The SDK's `verifyWebhook` does all of it." }, { "name": "Zupflow-Event-Id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The event's `id`: the same on every attempt and resend. Skip IDs you've already handled." }, { "name": "Zupflow-Delivery-Attempt", "in": "header", "required": true, "schema": { "type": "integer", "minimum": 1 } }, { "name": "User-Agent", "in": "header", "required": true, "schema": { "type": "string", "const": "Zupflow-Webhooks/1" } }, { "name": "Zupflow-Event-Type", "in": "header", "required": true, "schema": { "type": "string", "const": "run.failed" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunFailedWebhookEvent" } } } }, "responses": { "2XX": { "description": "Received. Answer within 10 seconds, then fetch current state; any other answer or a timeout is retried." } } } }, "run.waiting_for_approval": { "post": { "operationId": "webhook_run_waiting_for_approval", "summary": "`run.waiting_for_approval`", "parameters": [ { "name": "Zupflow-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "`t=,v1=` over `\".\"` with the endpoint's signing secret; two `v1` values during a rotation. Verify against the raw body in constant time and reject a timestamp more than 300 seconds from your clock. The SDK's `verifyWebhook` does all of it." }, { "name": "Zupflow-Event-Id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The event's `id`: the same on every attempt and resend. Skip IDs you've already handled." }, { "name": "Zupflow-Delivery-Attempt", "in": "header", "required": true, "schema": { "type": "integer", "minimum": 1 } }, { "name": "User-Agent", "in": "header", "required": true, "schema": { "type": "string", "const": "Zupflow-Webhooks/1" } }, { "name": "Zupflow-Event-Type", "in": "header", "required": true, "schema": { "type": "string", "const": "run.waiting_for_approval" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunWaitingForApprovalWebhookEvent" } } } }, "responses": { "2XX": { "description": "Received. Answer within 10 seconds, then fetch current state; any other answer or a timeout is retried." } } } }, "run.cancelled": { "post": { "operationId": "webhook_run_cancelled", "summary": "`run.cancelled`", "parameters": [ { "name": "Zupflow-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "`t=,v1=` over `\".\"` with the endpoint's signing secret; two `v1` values during a rotation. Verify against the raw body in constant time and reject a timestamp more than 300 seconds from your clock. The SDK's `verifyWebhook` does all of it." }, { "name": "Zupflow-Event-Id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The event's `id`: the same on every attempt and resend. Skip IDs you've already handled." }, { "name": "Zupflow-Delivery-Attempt", "in": "header", "required": true, "schema": { "type": "integer", "minimum": 1 } }, { "name": "User-Agent", "in": "header", "required": true, "schema": { "type": "string", "const": "Zupflow-Webhooks/1" } }, { "name": "Zupflow-Event-Type", "in": "header", "required": true, "schema": { "type": "string", "const": "run.cancelled" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunCancelledWebhookEvent" } } } }, "responses": { "2XX": { "description": "Received. Answer within 10 seconds, then fetch current state; any other answer or a timeout is retried." } } } }, "app.tools_changed": { "post": { "operationId": "webhook_app_tools_changed", "summary": "`app.tools_changed`", "parameters": [ { "name": "Zupflow-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "`t=,v1=` over `\".\"` with the endpoint's signing secret; two `v1` values during a rotation. Verify against the raw body in constant time and reject a timestamp more than 300 seconds from your clock. The SDK's `verifyWebhook` does all of it." }, { "name": "Zupflow-Event-Id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The event's `id`: the same on every attempt and resend. Skip IDs you've already handled." }, { "name": "Zupflow-Delivery-Attempt", "in": "header", "required": true, "schema": { "type": "integer", "minimum": 1 } }, { "name": "User-Agent", "in": "header", "required": true, "schema": { "type": "string", "const": "Zupflow-Webhooks/1" } }, { "name": "Zupflow-Event-Type", "in": "header", "required": true, "schema": { "type": "string", "const": "app.tools_changed" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppToolsChangedWebhookEvent" } } } }, "responses": { "2XX": { "description": "Received. Answer within 10 seconds, then fetch current state; any other answer or a timeout is retried." } } } }, "channel_message.received": { "post": { "operationId": "webhook_channel_message_received", "summary": "`channel_message.received`", "parameters": [ { "name": "Zupflow-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "`t=,v1=` over `\".\"` with the endpoint's signing secret; two `v1` values during a rotation. Verify against the raw body in constant time and reject a timestamp more than 300 seconds from your clock. The SDK's `verifyWebhook` does all of it." }, { "name": "Zupflow-Event-Id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The event's `id`: the same on every attempt and resend. Skip IDs you've already handled." }, { "name": "Zupflow-Delivery-Attempt", "in": "header", "required": true, "schema": { "type": "integer", "minimum": 1 } }, { "name": "User-Agent", "in": "header", "required": true, "schema": { "type": "string", "const": "Zupflow-Webhooks/1" } }, { "name": "Zupflow-Event-Type", "in": "header", "required": true, "schema": { "type": "string", "const": "channel_message.received" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelMessageReceivedWebhookEvent" } } } }, "responses": { "2XX": { "description": "Received. Answer within 10 seconds, then fetch current state; any other answer or a timeout is retried." } } } }, "channel_message.sent": { "post": { "operationId": "webhook_channel_message_sent", "summary": "`channel_message.sent`", "parameters": [ { "name": "Zupflow-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "`t=,v1=` over `\".\"` with the endpoint's signing secret; two `v1` values during a rotation. Verify against the raw body in constant time and reject a timestamp more than 300 seconds from your clock. The SDK's `verifyWebhook` does all of it." }, { "name": "Zupflow-Event-Id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The event's `id`: the same on every attempt and resend. Skip IDs you've already handled." }, { "name": "Zupflow-Delivery-Attempt", "in": "header", "required": true, "schema": { "type": "integer", "minimum": 1 } }, { "name": "User-Agent", "in": "header", "required": true, "schema": { "type": "string", "const": "Zupflow-Webhooks/1" } }, { "name": "Zupflow-Event-Type", "in": "header", "required": true, "schema": { "type": "string", "const": "channel_message.sent" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelMessageSentWebhookEvent" } } } }, "responses": { "2XX": { "description": "Received. Answer within 10 seconds, then fetch current state; any other answer or a timeout is retried." } } } }, "channel_app_manager.status_changed": { "post": { "operationId": "webhook_channel_app_manager_status_changed", "summary": "`channel_app_manager.status_changed`", "parameters": [ { "name": "Zupflow-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "`t=,v1=` over `\".\"` with the endpoint's signing secret; two `v1` values during a rotation. Verify against the raw body in constant time and reject a timestamp more than 300 seconds from your clock. The SDK's `verifyWebhook` does all of it." }, { "name": "Zupflow-Event-Id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The event's `id`: the same on every attempt and resend. Skip IDs you've already handled." }, { "name": "Zupflow-Delivery-Attempt", "in": "header", "required": true, "schema": { "type": "integer", "minimum": 1 } }, { "name": "User-Agent", "in": "header", "required": true, "schema": { "type": "string", "const": "Zupflow-Webhooks/1" } }, { "name": "Zupflow-Event-Type", "in": "header", "required": true, "schema": { "type": "string", "const": "channel_app_manager.status_changed" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelAppManagerStatusChangedWebhookEvent" } } } }, "responses": { "2XX": { "description": "Received. Answer within 10 seconds, then fetch current state; any other answer or a timeout is retried." } } } }, "channel_app.status_changed": { "post": { "operationId": "webhook_channel_app_status_changed", "summary": "`channel_app.status_changed`", "parameters": [ { "name": "Zupflow-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "`t=,v1=` over `\".\"` with the endpoint's signing secret; two `v1` values during a rotation. Verify against the raw body in constant time and reject a timestamp more than 300 seconds from your clock. The SDK's `verifyWebhook` does all of it." }, { "name": "Zupflow-Event-Id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The event's `id`: the same on every attempt and resend. Skip IDs you've already handled." }, { "name": "Zupflow-Delivery-Attempt", "in": "header", "required": true, "schema": { "type": "integer", "minimum": 1 } }, { "name": "User-Agent", "in": "header", "required": true, "schema": { "type": "string", "const": "Zupflow-Webhooks/1" } }, { "name": "Zupflow-Event-Type", "in": "header", "required": true, "schema": { "type": "string", "const": "channel_app.status_changed" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelAppStatusChangedWebhookEvent" } } } }, "responses": { "2XX": { "description": "Received. Answer within 10 seconds, then fetch current state; any other answer or a timeout is retried." } } } }, "channel_connection.status_changed": { "post": { "operationId": "webhook_channel_connection_status_changed", "summary": "`channel_connection.status_changed`", "parameters": [ { "name": "Zupflow-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "`t=,v1=` over `\".\"` with the endpoint's signing secret; two `v1` values during a rotation. Verify against the raw body in constant time and reject a timestamp more than 300 seconds from your clock. The SDK's `verifyWebhook` does all of it." }, { "name": "Zupflow-Event-Id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The event's `id`: the same on every attempt and resend. Skip IDs you've already handled." }, { "name": "Zupflow-Delivery-Attempt", "in": "header", "required": true, "schema": { "type": "integer", "minimum": 1 } }, { "name": "User-Agent", "in": "header", "required": true, "schema": { "type": "string", "const": "Zupflow-Webhooks/1" } }, { "name": "Zupflow-Event-Type", "in": "header", "required": true, "schema": { "type": "string", "const": "channel_connection.status_changed" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelConnectionStatusChangedWebhookEvent" } } } }, "responses": { "2XX": { "description": "Received. Answer within 10 seconds, then fetch current state; any other answer or a timeout is retried." } } } }, "channel_conversation.paused": { "post": { "operationId": "webhook_channel_conversation_paused", "summary": "`channel_conversation.paused`", "parameters": [ { "name": "Zupflow-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "`t=,v1=` over `\".\"` with the endpoint's signing secret; two `v1` values during a rotation. Verify against the raw body in constant time and reject a timestamp more than 300 seconds from your clock. The SDK's `verifyWebhook` does all of it." }, { "name": "Zupflow-Event-Id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The event's `id`: the same on every attempt and resend. Skip IDs you've already handled." }, { "name": "Zupflow-Delivery-Attempt", "in": "header", "required": true, "schema": { "type": "integer", "minimum": 1 } }, { "name": "User-Agent", "in": "header", "required": true, "schema": { "type": "string", "const": "Zupflow-Webhooks/1" } }, { "name": "Zupflow-Event-Type", "in": "header", "required": true, "schema": { "type": "string", "const": "channel_conversation.paused" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelConversationPausedWebhookEvent" } } } }, "responses": { "2XX": { "description": "Received. Answer within 10 seconds, then fetch current state; any other answer or a timeout is retried." } } } }, "webhook.test": { "post": { "operationId": "webhook_webhook_test", "summary": "Sent by the test button; can't be subscribed to", "parameters": [ { "name": "Zupflow-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "`t=,v1=` over `\".\"` with the endpoint's signing secret; two `v1` values during a rotation. Verify against the raw body in constant time and reject a timestamp more than 300 seconds from your clock. The SDK's `verifyWebhook` does all of it." }, { "name": "Zupflow-Event-Id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The event's `id`: the same on every attempt and resend. Skip IDs you've already handled." }, { "name": "Zupflow-Delivery-Attempt", "in": "header", "required": true, "schema": { "type": "integer", "minimum": 1 } }, { "name": "User-Agent", "in": "header", "required": true, "schema": { "type": "string", "const": "Zupflow-Webhooks/1" } }, { "name": "Zupflow-Event-Type", "in": "header", "required": true, "schema": { "type": "string", "const": "webhook.test" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookTestWebhookEvent" } } } }, "responses": { "2XX": { "description": "Received. Answer within 10 seconds, then fetch current state; any other answer or a timeout is retried." } } } } } }