{ "openapi": "3.1.0", "info": { "title": "DryKraft current API", "version": "2026-10-02", "description": "Current session-cookie API. No API key or service-account authentication is available. General JSON limit 512 KB; rate limits 300/minute, auth/hooks 30/15min, signed provider hooks 120/minute. Response shapes with open metadata are described rather than guaranteed as a stable external integration contract." }, "servers": [ { "url": "https://app.drykraft.com" } ], "tags": [ { "name": "Authentication & sessions" }, { "name": "Objects & CRM records" }, { "name": "Imports & smart lists" }, { "name": "Sales & dashboards" }, { "name": "Workspace settings" }, { "name": "Team & invitations" }, { "name": "Account security" }, { "name": "Finance" }, { "name": "Subscription billing" }, { "name": "Automation" }, { "name": "Outreach connections" }, { "name": "Campaigns & sequences" }, { "name": "Webhooks & callbacks" } ], "paths": { "/api/health": { "get": { "operationId": "get-health", "tags": [ "Authentication & sessions" ], "summary": "Check service health", "description": "Checks PostgreSQL and Redis connectivity. Access: Public.", "security": [], "parameters": [], "responses": { "200": { "description": "Check service health", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "ok" }, "database": { "const": "connected" }, "redis": { "const": "connected" } }, "required": [] } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/meta": { "get": { "operationId": "get-meta", "tags": [ "Authentication & sessions" ], "summary": "Read public configuration", "description": "Supported currencies include their code, name, symbol and decimal precision. Demo is false in production. Access: Public.", "security": [], "parameters": [], "responses": { "200": { "description": "Read public configuration", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "DryKraft" }, "domain": { "type": "string", "description": "Workspace domain" }, "currency_options": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Code" }, "name": { "type": "string", "description": "Name" }, "symbol": { "type": "string", "description": "Symbol" }, "digits": { "type": "integer", "description": "Decimal places" } }, "required": [] } }, "demo": { "type": "boolean", "description": "Local sample enabled" } }, "required": [] } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/auth/subdomain": { "get": { "operationId": "get-auth-subdomain", "tags": [ "Authentication & sessions" ], "summary": "Check workspace address", "description": "Reserved and occupied names are unavailable. This does not reserve an address. Access: Public.", "security": [], "parameters": [ { "name": "slug", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[a-z][a-z0-9-]{2,39}$", "description": "Required; 3-40 characters." } } ], "responses": { "200": { "description": "Check workspace address", "content": { "application/json": { "schema": { "type": "object", "properties": { "available": { "type": "boolean", "description": "Availability" } }, "required": [] } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/auth/signup": { "post": { "operationId": "post-auth-signup", "tags": [ "Authentication & sessions" ], "summary": "Create account", "description": "Use the central application address, not a workspace host. Sets the session cookie; workspace setup follows. Access: Public.", "security": [], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name", "maxLength": 100, "minLength": 2 }, "email": { "type": "string", "format": "email", "maxLength": 200 }, "password": { "type": "string", "minLength": 10, "maxLength": 128, "writeOnly": true } }, "required": [ "name", "email", "password" ] } } } }, "responses": { "201": { "description": "Create account", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "onboarding": { "const": true } }, "required": [] } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/auth/onboarding": { "post": { "operationId": "post-auth-onboarding", "tags": [ "Authentication & sessions" ], "summary": "Create first workspace", "description": "Central application only. Retries reuse the account’s first completed workspace. Starts the 15-day trial. Access: Account session.", "security": [ { "sessionCookie": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "workspace": { "type": "string", "description": "Company name", "maxLength": 100, "minLength": 2 }, "slug": { "type": "string", "pattern": "^[a-z][a-z0-9-]{2,39}$" }, "currency": { "type": "string", "description": "Supported currency code, e.g. USD, INR, EUR or KWD. Default USD." }, "currencies": { "type": "array", "items": { "type": "string", "description": "Supported currency code" }, "minItems": 1, "maxItems": 180 } }, "required": [ "workspace", "slug" ] } } } }, "responses": { "201": { "description": "Create first workspace", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" } }, "required": [] } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/auth/login": { "post": { "operationId": "post-auth-login", "tags": [ "Authentication & sessions" ], "summary": "Sign in", "description": "Sets a seven-day session cookie. On a workspace hostname membership is required. Access: Public.", "security": [], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "maxLength": 200 }, "password": { "type": "string", "minLength": 10, "maxLength": 128, "writeOnly": true } }, "required": [ "email", "password" ] } } } }, "responses": { "200": { "description": "Sign in", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OK" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/auth/demo": { "post": { "operationId": "post-auth-demo", "tags": [ "Authentication & sessions" ], "summary": "Open local sample", "description": "Local development only when enabled; production returns 404. Access: Public.", "security": [], "parameters": [], "responses": { "200": { "description": "Open local sample", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OK" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/auth/logout": { "post": { "operationId": "post-auth-logout", "tags": [ "Authentication & sessions" ], "summary": "Sign out", "description": "Revokes this cookie session and clears the cookie. Safe when already signed out. Access: Public.", "security": [], "parameters": [], "responses": { "200": { "description": "Sign out", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OK" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/session": { "get": { "operationId": "get-session", "tags": [ "Authentication & sessions" ], "summary": "Read account and workspace", "description": "Returns accessible workspaces, selected workspace/role, public user and supported currencies. Before onboarding workspace and role are null. Access: Account session.", "security": [ { "sessionCookie": [] } ], "parameters": [], "responses": { "200": { "description": "Read account and workspace", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "description": "Name" }, "email": { "type": "string", "format": "email", "maxLength": 200 } }, "required": [] }, "workspace": { "type": [ "object", "null" ] }, "role": { "type": [ "string", "null" ] }, "workspaces": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "description": "Name" }, "slug": { "type": "string", "description": "Address" }, "role": { "type": "string", "description": "Role" } }, "required": [] } }, "currency_options": { "type": "array", "items": { "type": "object" } }, "domain": { "type": "string", "description": "Domain" }, "subdomain_routing": { "type": "boolean", "description": "Wildcard routing enabled" } }, "required": [] } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/session/workspace": { "post": { "operationId": "post-session-workspace", "tags": [ "Authentication & sessions" ], "summary": "Switch workspace", "description": "Membership is checked. Workspace hostname restrictions still apply to subsequent requests. Access: Workspace member.", "security": [ { "sessionCookie": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" } }, "required": [ "id" ] } } } }, "responses": { "200": { "description": "Switch workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OK" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/auth/invitations/preview": { "post": { "operationId": "post-auth-invitations-preview", "tags": [ "Team & invitations" ], "summary": "Preview invitation", "description": "Email-bound invitation; wrong workspace hostname or expired/revoked links return 410. Does not accept access. Access: Public.", "security": [], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "token" ] } } } }, "responses": { "200": { "description": "Preview invitation", "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "maxLength": 200 }, "role": { "type": "string", "enum": [ "admin", "member", "viewer" ], "description": "Owner cannot be assigned or changed here. Only owners manage administrators." }, "expires_at": { "type": "string", "description": "Timestamp" }, "accepted": { "type": "boolean", "description": "Already accepted" }, "workspace": { "type": "object", "properties": { "name": { "type": "string", "description": "Name" }, "slug": { "type": "string", "description": "Address" } }, "required": [] } }, "required": [] } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/auth/invitations/accept": { "post": { "operationId": "post-auth-invitations-accept", "tags": [ "Team & invitations" ], "summary": "Accept invitation", "description": "Checks invited account password, available billing seat and inviter authority. New account needs name. Sets a session directly in the invited workspace. Access: Public.", "security": [], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "password": { "type": "string", "minLength": 10, "maxLength": 128, "writeOnly": true }, "mode": { "type": "string", "enum": [ "login", "signup" ], "description": "Account choice" }, "name": { "type": "string", "description": "New account name", "maxLength": 100, "minLength": 2 } }, "required": [ "token", "password", "mode" ] } } } }, "responses": { "200": { "description": "Accept invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OK" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/settings/members": { "get": { "operationId": "get-settings-members", "tags": [ "Team & invitations" ], "summary": "List workspace members", "description": "25 members per page, ordered by email. Pass next_cursor unchanged. Access: Workspace member.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "format": "email", "maxLength": 200, "description": "Optional next_cursor email" } } ], "responses": { "200": { "description": "List workspace members", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "description": "Name" }, "email": { "type": "string", "format": "email", "maxLength": 200 }, "role": { "type": "string", "description": "Role" }, "version": { "type": "integer", "description": "Positive optimistic version returned by the latest read. Refresh on 409; do not overwrite stale changes.", "minimum": 1 } }, "required": [] } }, "total": { "type": "integer", "description": "Total" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [] } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/settings/members/{id}": { "put": { "operationId": "put-settings-members-id", "tags": [ "Team & invitations" ], "summary": "Change member role", "description": "Owner is protected; admins cannot manage another administrator or grant admin. Refresh on stale version. Access: Owner or admin.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "admin", "member", "viewer" ], "description": "Owner cannot be assigned or changed here. Only owners manage administrators." }, "version": { "type": "integer", "description": "Positive optimistic version returned by the latest read. Refresh on 409; do not overwrite stale changes.", "minimum": 1 } }, "required": [ "role", "version" ] } } } }, "responses": { "200": { "description": "Change member role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OK" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "delete-settings-members-id", "tags": [ "Team & invitations" ], "summary": "Remove member", "description": "Revokes this workspace’s sessions, keeps business records and revokes pending invitations sent by the member. Owner/admin protections apply. Available even after trial expiration. Access: Owner or admin.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "version", "in": "query", "required": true, "schema": { "type": "integer", "description": "Required current member version", "minimum": 1 } } ], "responses": { "200": { "description": "Remove member", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OK" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/settings/invitations": { "get": { "operationId": "get-settings-invitations", "tags": [ "Team & invitations" ], "summary": "List pending invitations", "description": "25 per page; includes expired, nonrevoked pending invitations with active flag. Access: Owner or admin.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "List pending invitations", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email", "maxLength": 200 }, "role": { "type": "string", "enum": [ "admin", "member", "viewer" ], "description": "Owner cannot be assigned or changed here. Only owners manage administrators." }, "created_at": { "type": "string", "description": "Timestamp" }, "expires_at": { "type": "string", "description": "Timestamp" }, "active": { "type": "boolean", "description": "Not expired" } }, "required": [] } }, "total": { "type": "integer", "description": "Total" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [] } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "post-settings-invitations", "tags": [ "Team & invitations" ], "summary": "Create invitation link", "description": "Valid seven days; replacing the same email revokes the old link. Only owner grants admin. No invitation email is sent. Keep the one-time response token private. Access: Owner or admin.", "security": [ { "sessionCookie": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "maxLength": 200 }, "role": { "type": "string", "enum": [ "admin", "member", "viewer" ], "description": "Owner cannot be assigned or changed here. Only owners manage administrators." } }, "required": [ "email", "role" ] } } } }, "responses": { "201": { "description": "Create invitation link", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email", "maxLength": 200 }, "role": { "type": "string", "enum": [ "admin", "member", "viewer" ], "description": "Owner cannot be assigned or changed here. Only owners manage administrators." }, "expires_at": { "type": "string", "description": "Timestamp" }, "token": { "type": "string", "description": "Private invitation token" } }, "required": [] } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/settings/invitations/{id}": { "delete": { "operationId": "delete-settings-invitations-id", "tags": [ "Team & invitations" ], "summary": "Revoke invitation", "description": "Already accepted invitations return 409; use member access instead. Repeated revocation is safe. Access: Owner or admin.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Revoke invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OK" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/account/security": { "get": { "operationId": "get-account-security", "tags": [ "Account security" ], "summary": "Read account security", "description": "Across all workspaces. 25 other sessions per page plus current session and latest 20 private security events. Browser labels are approximate, activity updates about every five minutes. Access: Account session.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Read account security", "content": { "application/json": { "schema": { "type": "object", "properties": { "current": { "type": "object", "description": "id, device, created_at, last_seen_at, expires_at" }, "others": { "type": "object", "description": "items, total, next_cursor" }, "password_changed_at": { "type": [ "string", "null" ] }, "shared_demo": { "type": "boolean", "description": "Shared sample" }, "history": { "type": "array", "items": { "type": "object", "description": "id, action, count, created_at" } } }, "required": [] } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/account/sessions": { "delete": { "operationId": "delete-account-sessions", "tags": [ "Account security" ], "summary": "End other sessions", "description": "Keeps this session and revokes all other active sessions across workspaces. Access: Account session.", "security": [ { "sessionCookie": [] } ], "parameters": [], "responses": { "200": { "description": "End other sessions", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer", "description": "Sessions ended" } }, "required": [] } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/account/sessions/{id}": { "delete": { "operationId": "delete-account-sessions-id", "tags": [ "Account security" ], "summary": "End a session", "description": "Ending this session clears its cookie. Missing/already-ended session returns 404. Access: Account session.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "End a session", "content": { "application/json": { "schema": { "type": "object", "properties": { "current": { "type": "boolean", "description": "Whether this session ended" } }, "required": [] } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/account/password": { "post": { "operationId": "post-account-password", "tags": [ "Account security" ], "summary": "Change password", "description": "Current password is required; new and confirmation must match and differ from current. Rotates this session, ends all others. Shared sample account is blocked. 10 attempts per account per 15 minutes. Access: Account session.", "security": [ { "sessionCookie": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "current_password": { "type": "string", "minLength": 10, "maxLength": 128, "writeOnly": true }, "new_password": { "type": "string", "minLength": 10, "maxLength": 128, "writeOnly": true }, "confirm_password": { "type": "string", "minLength": 10, "maxLength": 128, "writeOnly": true } }, "required": [ "current_password", "new_password", "confirm_password" ] } } } }, "responses": { "200": { "description": "Change password", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OK" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/objects": { "get": { "operationId": "get-objects", "tags": [ "Objects & CRM records" ], "summary": "List object definitions", "description": "Built-in and custom definitions, including field schemas. Access: Workspace member.", "security": [ { "sessionCookie": [] } ], "parameters": [], "responses": { "200": { "description": "List object definitions", "content": { "application/json": { "schema": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/Object" } ], "description": "Also tenant_id, built_in and timestamps" } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "post-objects", "tags": [ "Objects & CRM records" ], "summary": "Create custom object", "description": "Unique key and field keys. Currency fields require a text currency-code field; one is added automatically if absent. Maximum 100 fields including currency. Access: Owner or admin.", "security": [ { "sessionCookie": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Object" } } } }, "responses": { "201": { "description": "Create custom object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Object" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/objects/{key}/fields": { "post": { "operationId": "post-objects-key-fields", "tags": [ "Objects & CRM records" ], "summary": "Add object field", "description": "Duplicate key is 409. Required fields cannot be added when records already exist. This release has no field-edit/delete route. Access: Owner or admin.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Field" } } } }, "responses": { "200": { "description": "Add object field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Object" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/records/{key}": { "get": { "operationId": "get-records-key", "tags": [ "Objects & CRM records" ], "summary": "List records", "description": "Latest created first. Saved list/filter intersects search/status. Financial records can be read here, but must be mutated through Finance. Access: Workspace member.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "description": "Optional search in name/email/company/customer/vendor/invoice number, max 200" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "description": "Default 50", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "Opaque next_cursor, max 500" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "description": "Exact status, max 80" } }, { "name": "list", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "description": "Optional saved smart-list ID" } }, { "name": "filter", "in": "query", "required": false, "schema": { "type": "string", "description": "Optional JSON-encoded Filter; mutually exclusive with list, max 10,000" } } ], "responses": { "200": { "description": "List records", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordPage" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "post-records-key", "tags": [ "Objects & CRM records" ], "summary": "Create record", "description": "Nonfinancial objects only. Field types, required values, relations and currencies are validated. Access: Owner, admin or member.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true, "description": "Object field values. Only keys in the workspace object definition are allowed; required fields and field types are validated." } }, "required": [ "data" ] } } } }, "responses": { "201": { "description": "Create record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/records/{key}/{id}": { "get": { "operationId": "get-records-key-id", "tags": [ "Objects & CRM records" ], "summary": "Get record", "description": "404 for a missing record in the selected workspace. Merged People IDs resolve to the remaining canonical contact; returned id can differ from the requested id. Access: Workspace member.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Get record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "put-records-key-id", "tags": [ "Objects & CRM records" ], "summary": "Replace record data", "description": "Supply the complete desired field data and latest version. This is not a partial patch. Nonfinancial objects only. Access: Owner, admin or member.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true, "description": "Object field values. Only keys in the workspace object definition are allowed; required fields and field types are validated." }, "version": { "type": "integer", "description": "Positive optimistic version returned by the latest read. Refresh on 409; do not overwrite stale changes.", "minimum": 1 } }, "required": [ "data", "version" ] } } } }, "responses": { "200": { "description": "Replace record data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "delete-records-key-id", "tags": [ "Objects & CRM records" ], "summary": "Delete record", "description": "Nonfinancial only. Related records can prevent deletion. Supply version to protect against concurrent edits. Access: Owner, admin or member.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "version", "in": "query", "required": false, "schema": { "type": "integer", "description": "Positive optimistic version returned by the latest read. Refresh on 409; do not overwrite stale changes.", "minimum": 1 } } ], "responses": { "200": { "description": "Delete record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OK" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/leads/{id}/convert": { "post": { "operationId": "post-leads-id-convert", "tags": [ "Objects & CRM records" ], "summary": "Convert lead to person", "description": "Creates a person or reuses a matching email, sets lead Converted and adds converted_to link. Does not create a deal. Already converted returns 409. Access: Owner, admin or member.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Convert lead to person", "content": { "application/json": { "schema": { "type": "object", "properties": { "person": { "$ref": "#/components/schemas/Record" } }, "required": [] } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/activities": { "get": { "operationId": "get-activities", "tags": [ "Objects & CRM records" ], "summary": "List recent activities", "description": "Latest 50 with actor and record labels. Access: Workspace member.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "record_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "List recent activities", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "description": "id, record_id, actor_id, actor_name, record_name, object_key, type, body, created_at" } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "post-activities", "tags": [ "Objects & CRM records" ], "summary": "Add record activity", "description": "Notes/call/email/meeting entries record activity; they do not send a message or place a call. Access: Owner, admin or member.", "security": [ { "sessionCookie": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "record_id": { "type": "string", "format": "uuid" }, "body": { "type": "string", "description": "Nonblank note", "maxLength": 10000, "minLength": 1 }, "type": { "type": "string", "enum": [ "note", "call", "email", "meeting" ], "description": "Defaults note" } }, "required": [ "record_id", "body" ] } } } }, "responses": { "201": { "description": "Add record activity", "content": { "application/json": { "schema": { "type": "object", "description": "Saved activity row" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/search": { "get": { "operationId": "get-search", "tags": [ "Objects & CRM records" ], "summary": "Search records", "description": "Matches record name, latest updated first, maximum 20 results. Access: Workspace member.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "description": "Required query", "maxLength": 100, "minLength": 1 } } ], "responses": { "200": { "description": "Search records", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "object_key": { "type": "string", "pattern": "^[a-z][a-z0-9_]{1,39}$" }, "name": { "type": "string", "description": "Name" }, "email": { "type": "string", "format": "email", "maxLength": 200 } }, "required": [] } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/record-tools/{key}/import/preview": { "post": { "operationId": "post-record-tools-key-import-preview", "tags": [ "Imports & smart lists" ], "summary": "Preview CSV import", "description": "Nonfinancial objects only. Validates all rows without writing business records. First 20 errors and first five planned rows are returned. Access: Owner, admin or member.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Import" } } } }, "responses": { "200": { "description": "Preview CSV import", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportReport" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/record-tools/{key}/import/commit": { "post": { "operationId": "post-record-tools-key-import-commit", "tags": [ "Imports & smart lists" ], "summary": "Apply CSV import", "description": "Whole import is transactional. Reuse the same UUID with identical CSV/mapping/policy to safely retry; different content with that UUID is 409. Preview is advisory: commit revalidates current records. Access: Owner, admin or member.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "csv": { "type": "string", "description": "UTF-8 CSV content, not a file path. Header required; <=500 data rows.", "maxLength": 300000 }, "mapping": { "type": "array", "items": { "type": [ "string", "null" ], "description": "Field key per CSV column, null skips a column. Omit to match field keys/labels." }, "minItems": 0, "maxItems": 100 }, "duplicates": { "type": "string", "enum": [ "skip", "update", "error" ], "description": "People email duplicate policy, default skip. Blank update cells preserve existing values." }, "id": { "type": "string", "format": "uuid" } }, "required": [ "csv", "id" ] } } } }, "responses": { "200": { "description": "Apply CSV import", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "created": { "type": "integer", "description": "Created" }, "updated": { "type": "integer", "description": "Updated" }, "skipped": { "type": "integer", "description": "Skipped" }, "rows": { "type": "integer", "description": "Rows" } }, "required": [] } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/record-tools/{key}/bulk": { "post": { "operationId": "post-record-tools-key-bulk", "tags": [ "Imports & smart lists" ], "summary": "Change selected records", "description": "1-100 unique IDs and versions. Updates merge provided fields with existing data; deletes respect relation protection. Atomic: a changed/missing record rejects the whole operation. Nonfinancial only. Access: Owner, admin or member.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "records": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "version": { "type": "integer", "description": "Positive optimistic version returned by the latest read. Refresh on 409; do not overwrite stale changes.", "minimum": 1 } }, "required": [ "id", "version" ] }, "minItems": 1, "maxItems": 100 }, "action": { "type": "string", "enum": [ "update", "delete" ], "description": "Bulk operation" }, "data": { "type": "object", "additionalProperties": true, "description": "Object field values. Only keys in the workspace object definition are allowed; required fields and field types are validated." } }, "required": [ "records", "action" ] } } } }, "responses": { "200": { "description": "Change selected records", "content": { "application/json": { "schema": { "type": "object", "properties": { "changed": { "type": "integer", "description": "Affected records" } }, "required": [] } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/record-tools/people/merge/preview": { "post": { "operationId": "post-record-tools-people-merge-preview", "tags": [ "Imports & smart lists" ], "summary": "Review contact merge", "description": "No business record changes. Reviews the remaining values, source notes/relationships, frozen financial history and active source follow-ups. Retain the exact input and review token for confirmation. Contact or related changes require another review. Access: Owner or admin.", "security": [ { "sessionCookie": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactMerge" } } } }, "responses": { "200": { "description": "Review contact merge", "content": { "application/json": { "schema": { "type": "object", "properties": { "contacts": { "type": "array", "items": { "$ref": "#/components/schemas/Record" }, "minItems": 2, "maxItems": 2 }, "data": { "type": "object", "additionalProperties": true, "description": "Object field values. Only keys in the workspace object definition are allowed; required fields and field types are validated." }, "effects": { "$ref": "#/components/schemas/MergeEffects" }, "review_token": { "type": "string", "description": "SHA-256 review token; tied to current definitions, contacts and related state" } }, "required": [ "contacts", "data", "effects", "review_token" ] } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/record-tools/people/merge/commit": { "post": { "operationId": "post-record-tools-people-merge-commit", "tags": [ "Imports & smart lists" ], "summary": "Confirm contact merge", "description": "Atomic and retry-safe: repeat the exact input, UUID and review token after an ambiguous response. Changed content with that UUID is 409. Archive the source, move notes and declared relations, preserve non-draft financial snapshots/payments, cancel active source follow-ups and retain immutable merge history. There is no restore route. Submitted provider requests can finish. Archived/remaining contacts preserving merge history cannot be deleted. Future relation/activity writes using an alias resolve to the canonical contact. Access: Owner or admin.", "security": [ { "sessionCookie": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contacts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "version": { "type": "integer", "description": "Positive optimistic version returned by the latest read. Refresh on 409; do not overwrite stale changes.", "minimum": 1 } }, "required": [ "id", "version" ] }, "minItems": 2, "maxItems": 2 }, "target_id": { "type": "string", "format": "uuid" }, "take_source": { "type": "array", "items": { "type": "string", "pattern": "^[a-z][a-z0-9_]{1,39}$" }, "minItems": 0, "maxItems": 100 }, "id": { "type": "string", "format": "uuid" }, "review_token": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "confirmed": { "const": true } }, "required": [ "contacts", "target_id", "id", "review_token", "confirmed" ] } } } }, "responses": { "200": { "description": "Confirm contact merge", "content": { "application/json": { "schema": { "type": "object", "properties": { "record": { "$ref": "#/components/schemas/Record" }, "merged_id": { "type": "string", "format": "uuid" }, "merge_id": { "type": "string", "format": "uuid" }, "effects": { "$ref": "#/components/schemas/MergeEffects" } }, "required": [ "record", "merged_id", "merge_id", "effects" ] } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/record-lists/{key}": { "get": { "operationId": "get-record-lists-key", "tags": [ "Imports & smart lists" ], "summary": "List smart lists", "description": "Nonfinancial object only; alphabetical names. Access: Workspace member.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List smart lists", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SmartList" } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "post-record-lists-key", "tags": [ "Imports & smart lists" ], "summary": "Create smart list", "description": "Maximum 100 lists per object. Currency amount comparisons require match=all and currency eq rule. Dynamic rules do not copy records. Access: Owner, admin or member.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListInput" } } } }, "responses": { "201": { "description": "Create smart list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SmartList" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/record-lists/{key}/{id}": { "put": { "operationId": "put-record-lists-key-id", "tags": [ "Imports & smart lists" ], "summary": "Update smart list", "description": "Current version required. Duplicate name or stale change returns 409. Access: Owner, admin or member.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Nonblank list name", "maxLength": 80 }, "filter": { "$ref": "#/components/schemas/Filter" }, "version": { "type": "integer", "description": "Positive optimistic version returned by the latest read. Refresh on 409; do not overwrite stale changes.", "minimum": 1 } }, "required": [ "name", "filter", "version" ] } } } }, "responses": { "200": { "description": "Update smart list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SmartList" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "delete-record-lists-key-id", "tags": [ "Imports & smart lists" ], "summary": "Delete smart list", "description": "Removes rules, retains records. Current version is required. Access: Owner, admin or member.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "version", "in": "query", "required": true, "schema": { "type": "integer", "description": "Required current list version", "minimum": 1 } } ], "responses": { "200": { "description": "Delete smart list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OK" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/pipelines": { "get": { "operationId": "get-pipelines", "tags": [ "Sales & dashboards" ], "summary": "List sales pipelines", "description": "Returns saved stages, IDs and timestamps. Access: Workspace member.", "security": [ { "sessionCookie": [] } ], "parameters": [], "responses": { "200": { "description": "List sales pipelines", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Pipeline" } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "post-pipelines", "tags": [ "Sales & dashboards" ], "summary": "Create pipeline", "description": "Stage IDs must be unique. Access: Owner or admin.", "security": [ { "sessionCookie": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pipeline" } } } }, "responses": { "201": { "description": "Create pipeline", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pipeline" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/pipelines/{id}": { "put": { "operationId": "put-pipelines-id", "tags": [ "Sales & dashboards" ], "summary": "Update pipeline", "description": "Move deals before removing a stage they use. Returns 404 when missing. Access: Owner or admin.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pipeline" } } } }, "responses": { "200": { "description": "Update pipeline", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pipeline" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/dashboards": { "get": { "operationId": "get-dashboards", "tags": [ "Sales & dashboards" ], "summary": "List dashboards", "description": "Saved dashboard rows include id, name, widgets and version. Access: Workspace member.", "security": [ { "sessionCookie": [] } ], "parameters": [], "responses": { "200": { "description": "List dashboards", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "description": "id, tenant_id, name, widgets (Widget[]), version, created_at" } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "post-dashboards", "tags": [ "Sales & dashboards" ], "summary": "Create dashboard", "description": "Creates an empty dashboard. Access: Owner, admin or member.", "security": [ { "sessionCookie": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name", "maxLength": 100, "minLength": 1 } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Create dashboard", "content": { "application/json": { "schema": { "type": "object", "description": "Dashboard row" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/dashboards/{id}": { "put": { "operationId": "put-dashboards-id", "tags": [ "Sales & dashboards" ], "summary": "Save dashboard", "description": "Up to 30 unique widget IDs. Validates aggregations against workspace objects and fields. Optimistic version is required. Access: Owner, admin or member.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name", "maxLength": 100, "minLength": 1 }, "widgets": { "type": "array", "items": { "$ref": "#/components/schemas/Widget" }, "minItems": 0, "maxItems": 30 }, "version": { "type": "integer", "description": "Positive optimistic version returned by the latest read. Refresh on 409; do not overwrite stale changes.", "minimum": 1 } }, "required": [ "name", "widgets", "version" ] } } } }, "responses": { "200": { "description": "Save dashboard", "content": { "application/json": { "schema": { "type": "object", "description": "Updated dashboard with incremented version" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/analytics/query": { "post": { "operationId": "post-analytics-query", "tags": [ "Sales & dashboards" ], "summary": "Query KPIs", "description": "Counts, sum or average; optional exact filter and grouping. Monetary totals remain in one currency. Financial sums/averages need explicit currency or currency filter. <=100 groups per widget. Access: Workspace member.", "security": [ { "sessionCookie": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "widgets": { "type": "array", "items": { "$ref": "#/components/schemas/Widget" }, "minItems": 0, "maxItems": 30 } }, "required": [ "widgets" ] } } } }, "responses": { "200": { "description": "Query KPIs", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "description": "Group" }, "value": { "type": "number" } }, "required": [] } }, "description": "Result map keyed by widget ID" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/settings/workspace": { "put": { "operationId": "put-settings-workspace", "tags": [ "Workspace settings" ], "summary": "Update workspace settings", "description": "Valid IANA timezone. Default/enabled currencies do not convert historical records. Slug is not editable here. If currencies omitted, existing codes plus new default are retained. Access: Owner or admin.", "security": [ { "sessionCookie": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name", "maxLength": 100, "minLength": 2 }, "timezone": { "type": "string", "description": "Timezone", "maxLength": 80 }, "currency": { "type": "string", "description": "Supported currency code, e.g. USD, INR, EUR or KWD. Default USD." }, "currencies": { "type": "array", "items": { "type": "string", "description": "Supported currency code" }, "minItems": 1, "maxItems": 180 } }, "required": [ "name", "timezone" ] } } } }, "responses": { "200": { "description": "Update workspace settings", "content": { "application/json": { "schema": { "type": "object", "description": "Workspace row with id, name, slug and settings" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/settings/audit": { "get": { "operationId": "get-settings-audit", "tags": [ "Workspace settings" ], "summary": "Read business audit", "description": "Latest 100 supported business events, including actor_name. Account security history is separate. Access: Owner or admin.", "security": [ { "sessionCookie": [] } ], "parameters": [], "responses": { "200": { "description": "Read business audit", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "description": "Audit event row: id, tenant_id, actor_id, actor_name, action, object_key, record_id, data, created_at" } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/finance/profile": { "get": { "operationId": "get-finance-profile", "tags": [ "Finance" ], "summary": "Read issuer profile", "description": "Default profile uses workspace name until configured. Access: Workspace member.", "security": [ { "sessionCookie": [] } ], "parameters": [], "responses": { "200": { "description": "Read issuer profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FinanceProfile" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "put-finance-profile", "tags": [ "Finance" ], "summary": "Save issuer profile", "description": "Issued invoices keep their issuer snapshot. Access: Owner or admin.", "security": [ { "sessionCookie": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FinanceProfile" } } } }, "responses": { "200": { "description": "Save issuer profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FinanceProfile" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/finance/summary": { "get": { "operationId": "get-finance-summary", "tags": [ "Finance" ], "summary": "Read currency totals", "description": "One row per currency. Monetary totals are decimal strings of minor units; overdue uses workspace timezone. No exchange conversion. Access: Workspace member.", "security": [ { "sessionCookie": [] } ], "parameters": [], "responses": { "200": { "description": "Read currency totals", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "currency": { "type": "string", "description": "Code" }, "outstanding": { "type": "string", "description": "Minor units" }, "collected": { "type": "string", "description": "Minor units" }, "overdue": { "type": "string", "description": "Minor units" }, "expenses": { "type": "string", "description": "Paid expense minor units" }, "approvals": { "type": "integer", "description": "Submitted expenses" } }, "required": [] } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/finance/templates/{name}": { "post": { "operationId": "post-finance-templates-name", "tags": [ "Finance" ], "summary": "Create finance workflow draft", "description": "name: won-deal, expense-approval or invoice-paid. Creates an unpublished workflow; review then publish separately. Access: Owner, admin or member.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "Create finance workflow draft", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workflow" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/finance/{key}": { "post": { "operationId": "post-finance-key", "tags": [ "Finance" ], "summary": "Create finance draft", "description": "key: invoices or expenses. Wrap InvoiceData/ExpenseData in data. Draft is server-calculated and field-validated. Access: Owner, admin or member.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "oneOf": [ { "$ref": "#/components/schemas/InvoiceData" }, { "$ref": "#/components/schemas/ExpenseData" } ] } }, "required": [ "data" ] } } } }, "responses": { "201": { "description": "Create finance draft", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/finance/{key}/{id}": { "put": { "operationId": "put-finance-key-id", "tags": [ "Finance" ], "summary": "Replace finance draft", "description": "key: invoices or expenses. Only current Draft can be edited. Supply complete desired draft values. Access: Owner, admin or member.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "oneOf": [ { "$ref": "#/components/schemas/InvoiceData" }, { "$ref": "#/components/schemas/ExpenseData" } ] }, "version": { "type": "integer", "description": "Positive optimistic version returned by the latest read. Refresh on 409; do not overwrite stale changes.", "minimum": 1 } }, "required": [ "data", "version" ] } } } }, "responses": { "200": { "description": "Replace finance draft", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/finance/{key}/{id}/entries": { "get": { "operationId": "get-finance-key-id-entries", "tags": [ "Finance" ], "summary": "Read finance payment entries", "description": "Latest first. No endpoint deletes or edits payment entries. Access: Workspace member.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Read finance payment entries", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "description": "id, record_id, kind, amount_minor, currency, paid_on, method, reference, actor_id, actor_name, created_at" } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/finance/{key}/{id}/action": { "post": { "operationId": "post-finance-key-id-action", "tags": [ "Finance" ], "summary": "Move finance state", "description": "Invoices: Draft → issue → Issued; unpaid Draft/Issued → void (admin, reason required). Expenses: Draft → submit → Submitted → approve/reject (admin); Rejected → reopen → Draft. Reject needs reason. Issuing requires positive total and freezes issuer/number/details. Access: Owner, admin or member.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "issue", "void", "submit", "approve", "reject", "reopen" ], "description": "State transition" }, "version": { "type": "integer", "description": "Positive optimistic version returned by the latest read. Refresh on 409; do not overwrite stale changes.", "minimum": 1 }, "note": { "type": "string", "description": "Reason or note, default empty", "maxLength": 2000 } }, "required": [ "action", "version" ] } } } }, "responses": { "200": { "description": "Move finance state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/finance/{key}/{id}/payments": { "post": { "operationId": "post-finance-key-id-payments", "tags": [ "Finance" ], "summary": "Record payment", "description": "Invoices: positive received amount <=balance, issued/partially paid only. Expenses: admin only, Approved, exact full amount. Date cannot be in future. UUID id supports identical retry; changed content returns 409. This does not charge or transfer money. Access: Owner, admin or member.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } } }, "responses": { "200": { "description": "Record payment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/finance/invoices/{id}/pdf": { "get": { "operationId": "get-finance-invoices-id-pdf", "tags": [ "Finance" ], "summary": "Download invoice PDF", "description": "Draft, issued and void documents reflect their state. Issued document uses frozen issuer. Private/no-store; attachment filename from invoice number. Access: Workspace member.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Download invoice PDF", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/billing/": { "get": { "operationId": "get-billing", "tags": [ "Subscription billing" ], "summary": "Read billing status", "description": "$1 USD/user/month, 100 minor units. 15-day trial starts at workspace creation. Pending invitations excluded from members. Access: Workspace member.", "security": [ { "sessionCookie": [] } ], "parameters": [], "responses": { "200": { "description": "Read billing status", "content": { "application/json": { "schema": { "type": "object", "properties": { "plan": { "type": "string", "description": "sample or workspace" }, "access": { "type": "boolean", "description": "May mutate/run" }, "trial": { "type": "boolean", "description": "Trial active" }, "trial_started_at": { "type": "string", "description": "Timestamp" }, "trial_ends_at": { "type": "string", "description": "Timestamp" }, "status": { "type": [ "string", "null" ] }, "seats": { "type": [ "integer", "null" ] }, "members": { "type": "integer", "description": "Every member counts" }, "unit_price_minor": { "const": 100 }, "currency": { "const": "USD" }, "next_billing_date": { "type": [ "string", "null" ] }, "cancel_at_next_billing_date": { "type": "boolean", "description": "Cancellation scheduled" }, "synced_at": { "type": [ "string", "null" ] }, "subscribed": { "type": "boolean", "description": "Subscription exists" }, "checkout": { "type": [ "object", "null" ], "description": "Open checkout: seats, expires_at" }, "ready": { "type": "boolean", "description": "Billing configured" }, "enterprise_email": { "type": [ "string", "null" ] }, "enterprise_requested_at": { "type": [ "string", "null" ] } }, "required": [] } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/billing/checkout": { "post": { "operationId": "post-billing-checkout", "tags": [ "Subscription billing" ], "summary": "Open subscription checkout", "description": "Real hosted Dodo checkout. Seats >=members, 1-10,000. Preserves remaining trial rounded up. Ambiguous open checkout is reserved for 24 hours; do not create another purchase blindly. Access: Workspace owner.", "security": [ { "sessionCookie": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "seats": { "type": "integer", "description": "Seat quantity", "minimum": 1, "maximum": 10000 } }, "required": [ "seats" ] } } } }, "responses": { "200": { "description": "Open subscription checkout", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" } }, "required": [] } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/billing/refresh": { "post": { "operationId": "post-billing-refresh", "tags": [ "Subscription billing" ], "summary": "Refresh provider billing state", "description": "Uses canonical provider state. Return-page query/status does not grant access. Access: Workspace owner.", "security": [ { "sessionCookie": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "checkout": { "type": "string", "format": "uuid" } }, "required": [] } } } }, "responses": { "200": { "description": "Refresh provider billing state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OK" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/billing/portal": { "post": { "operationId": "post-billing-portal", "tags": [ "Subscription billing" ], "summary": "Open Dodo customer portal", "description": "Requires completed checkout. Portal manages payment methods, invoices and cancellation. Access: Workspace owner.", "security": [ { "sessionCookie": [] } ], "parameters": [], "responses": { "200": { "description": "Open Dodo customer portal", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" } }, "required": [] } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/billing/seats": { "post": { "operationId": "post-billing-seats", "tags": [ "Subscription billing" ], "summary": "Change subscription seats", "description": "Active subscription required; seats >=members. Change effective immediately, no immediate charge; next renewal uses new price. Access: Workspace owner.", "security": [ { "sessionCookie": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "seats": { "type": "integer", "description": "Seat quantity", "minimum": 1, "maximum": 10000 } }, "required": [ "seats" ] } } } }, "responses": { "200": { "description": "Change subscription seats", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OK" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/billing/enterprise": { "post": { "operationId": "post-billing-enterprise", "tags": [ "Subscription billing" ], "summary": "Save Enterprise requirements", "description": "Saves a request; does not activate a contract, extra features or plan. Contact support@drykraft.com. Access: Workspace owner.", "security": [ { "sessionCookie": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "requirements": { "type": "string", "description": "Organization requirements", "maxLength": 3000, "minLength": 20 } }, "required": [ "requirements" ] } } } }, "responses": { "200": { "description": "Save Enterprise requirements", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OK" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/billing/dodo/webhook": { "post": { "operationId": "post-billing-dodo-webhook", "tags": [ "Webhooks & callbacks" ], "summary": "Receive Dodo events", "description": "Raw JSON bytes. Required webhook-id, webhook-timestamp and webhook-signature headers. HMAC-SHA256 over id.timestamp.rawBody with decoded whsec key; v1,base64 signature, timestamp ±300 seconds. Dedupe webhook ID; fetch current subscription before changing access. Unrelated types/products acknowledged. Access: Dodo signature.", "security": [], "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "webhook-timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "webhook-signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "Event type" }, "data": { "type": "object", "additionalProperties": true } }, "required": [ "type", "data" ] } } } }, "responses": { "200": { "description": "Receive Dodo events", "content": { "application/json": { "schema": { "type": "object", "properties": { "received": { "const": true } }, "required": [] } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/automation/workflows": { "get": { "operationId": "get-automation-workflows", "tags": [ "Automation" ], "summary": "List general workflows", "description": "Managed outreach workflows are excluded. Returns execution counts. Access: Workspace member.", "security": [ { "sessionCookie": [] } ], "parameters": [], "responses": { "200": { "description": "List general workflows", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Workflow" } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "post-automation-workflows", "tags": [ "Automation" ], "summary": "Create workflow draft", "description": "Starts with a manual trigger. Access: Owner, admin or member.", "security": [ { "sessionCookie": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name", "maxLength": 100, "minLength": 1 }, "description": { "type": "string", "description": "Default empty", "maxLength": 1000 } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Create workflow draft", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workflow" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/automation/workflows/{id}": { "put": { "operationId": "put-automation-workflows-id", "tags": [ "Automation" ], "summary": "Save workflow draft", "description": "Draft shape validated here; publish performs graph validation. Managed outreach workflows cannot be changed here. Access: Owner, admin or member.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name", "maxLength": 100, "minLength": 1 }, "description": { "type": "string", "description": "Default empty", "maxLength": 1000 }, "draft": { "$ref": "#/components/schemas/Graph" } }, "required": [ "name", "draft" ] } } } }, "responses": { "200": { "description": "Save workflow draft", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workflow" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/automation/workflows/{id}/publish": { "post": { "operationId": "post-automation-workflows-id-publish", "tags": [ "Automation" ], "summary": "Publish immutable version", "description": "Exactly one trigger, unique nodes, connected acyclic graph. Only condition branches, unique true/false handles. Activates workflow; future runs use this version. Access: Owner or admin.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Publish immutable version", "content": { "application/json": { "schema": { "type": "object", "description": "id, workflow_id, version, graph, created_at" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/automation/workflows/{id}/status": { "post": { "operationId": "post-automation-workflows-id-status", "tags": [ "Automation" ], "summary": "Activate or pause workflow", "description": "Must already be published. Access: Owner or admin.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "active", "paused" ], "description": "Workflow status" } }, "required": [ "status" ] } } } }, "responses": { "200": { "description": "Activate or pause workflow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workflow" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/automation/workflows/{id}/versions": { "get": { "operationId": "get-automation-workflows-id-versions", "tags": [ "Automation" ], "summary": "Read published versions", "description": "Latest version first. Access: Workspace member.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Read published versions", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "description": "id, workflow_id, version, graph, created_at" } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/automation/workflows/{id}/webhook": { "get": { "operationId": "get-automation-workflows-id-webhook", "tags": [ "Automation" ], "summary": "Read workflow hook URL", "description": "URL is a secret capability; null before creation. Never expose in public docs/logs. Access: Owner or admin.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Read workflow hook URL", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": [ "string", "null" ], "format": "uri" } }, "required": [] } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "post-automation-workflows-id-webhook", "tags": [ "Automation" ], "summary": "Create or rotate hook URL", "description": "Old token immediately stops working. Publish an active webhook trigger before receiving runs. Access: Owner or admin.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Create or rotate hook URL", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" } }, "required": [] } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/automation/workflows/{id}/run": { "post": { "operationId": "post-automation-workflows-id-run", "tags": [ "Automation" ], "summary": "Run published version", "description": "Returns an accepted execution; inspect history for outcome. Published version required. Worker enforces billing access. Access: Owner, admin or member.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "input": { "type": "object", "additionalProperties": true, "description": "Object field values. Only keys in the workspace object definition are allowed; required fields and field types are validated.", "default": {} } }, "required": [] } } } }, "responses": { "202": { "description": "Run published version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Execution" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/automation/executions": { "get": { "operationId": "get-automation-executions", "tags": [ "Automation" ], "summary": "List recent executions", "description": "Latest 100, with workflow_name. Access: Workspace member.", "security": [ { "sessionCookie": [] } ], "parameters": [], "responses": { "200": { "description": "List recent executions", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Execution" } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/automation/executions/{id}": { "get": { "operationId": "get-automation-executions-id", "tags": [ "Automation" ], "summary": "Inspect execution", "description": "Includes ordered node execution attempts and their input/output/error/timestamps. Access: Workspace member.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Inspect execution", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Execution" } ], "properties": { "nodes": { "type": "array", "items": { "type": "object" } } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/automation/executions/{id}/cancel": { "post": { "operationId": "post-automation-executions-id-cancel", "tags": [ "Automation" ], "summary": "Cancel unfinished execution", "description": "Queued/running/waiting/retrying only. Cannot recall an external side effect already accepted. Access: Owner, admin or member.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Cancel unfinished execution", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Execution" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/automation/executions/{id}/retry": { "post": { "operationId": "post-automation-executions-id-retry", "tags": [ "Automation" ], "summary": "Retry failed execution", "description": "Only failed executions. Review external side effects before retrying. Outreach reservations prevent automatic ambiguous resend. Access: Owner, admin or member.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Retry failed execution", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Execution" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/automation/credentials": { "get": { "operationId": "get-automation-credentials", "tags": [ "Automation" ], "summary": "List HTTP credentials", "description": "Only id, name, provider and created_at are returned; value remains private. Access: Owner or admin.", "security": [ { "sessionCookie": [] } ], "parameters": [], "responses": { "200": { "description": "List HTTP credentials", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "description": "id, name, provider, created_at" } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "post-automation-credentials", "tags": [ "Automation" ], "summary": "Save HTTP credential", "description": "Encrypted per workspace; header is required when provider=header. Access: Owner or admin.", "security": [ { "sessionCookie": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name", "maxLength": 100, "minLength": 1 }, "provider": { "type": "string", "enum": [ "bearer", "basic", "header" ], "description": "Outbound HTTP authorization, not DryKraft API authentication" }, "value": { "type": "string", "description": "Private value", "maxLength": 5000, "minLength": 1 }, "header": { "type": "string", "pattern": "^[a-zA-Z0-9-]+$" } }, "required": [ "name", "provider", "value" ] } } } }, "responses": { "201": { "description": "Save HTTP credential", "content": { "application/json": { "schema": { "type": "object", "description": "id, name, provider, created_at" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/automation/credentials/{id}": { "delete": { "operationId": "delete-automation-credentials-id", "tags": [ "Automation" ], "summary": "Delete HTTP credential", "description": "Existing workflows using it will need another credential. Access: Owner or admin.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Delete HTTP credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OK" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/hooks/{token}": { "post": { "operationId": "post-hooks-token", "tags": [ "Webhooks & callbacks" ], "summary": "Trigger webhook workflow", "description": "64-character hex token. Active published webhook trigger and billing access required. Optional Idempotency-Key <=200 characters: repeated identical payload returns same execution; changed payload is 409. Access: Secret hook token.", "security": [], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "Object field values. Only keys in the workspace object definition are allowed; required fields and field types are validated." } } } }, "responses": { "202": { "description": "Trigger webhook workflow", "content": { "application/json": { "schema": { "type": "object", "properties": { "execution_id": { "type": "string", "format": "uuid" }, "state": { "type": "string", "description": "Execution state" } }, "required": [] } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/outreach/meta": { "get": { "operationId": "get-outreach-meta", "tags": [ "Outreach connections" ], "summary": "Read connector readiness", "description": "Reports configured Google/Outlook app credentials and callbacks; true is not proof of completed consent. QCall LLM needs no key. Access: Workspace member.", "security": [ { "sessionCookie": [] } ], "parameters": [], "responses": { "200": { "description": "Read connector readiness", "content": { "application/json": { "schema": { "type": "object", "properties": { "google": { "type": "boolean", "description": "App configured" }, "microsoft": { "type": "boolean", "description": "App configured" }, "llm": { "type": "object", "properties": { "provider": { "const": "QCall" }, "keyRequired": { "const": false } }, "required": [] }, "redirects": { "type": "object", "properties": { "google": { "type": "string", "description": "Callback" }, "microsoft": { "type": "string", "description": "Callback" } }, "required": [] } }, "required": [] } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/outreach/connections": { "get": { "operationId": "get-outreach-connections", "tags": [ "Outreach connections" ], "summary": "List private provider connections", "description": "Only public connection metadata is returned. Access: Workspace member.", "security": [ { "sessionCookie": [] } ], "parameters": [], "responses": { "200": { "description": "List private provider connections", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Connection" } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "post-outreach-connections", "tags": [ "Outreach connections" ], "summary": "Create provider connection", "description": "SMTP verifies mail/optional IMAP access, QCall reads assistants/dialers, WhatsApp verifies phone/WABA. SMS checks public destination/config only. No test message or call is sent. Shared sample blocked. Access: Owner or admin.", "security": [ { "sessionCookie": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionInput" } } } }, "responses": { "201": { "description": "Create provider connection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Connection" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/outreach/connections/parse": { "post": { "operationId": "post-outreach-connections-parse", "tags": [ "Outreach connections" ], "summary": "Inspect SMS cURL fields", "description": "Parses but never executes. Returns existing primitive JSON body paths; header values are not returned. Configuration check does not verify SMS credentials. Access: Owner or admin.", "security": [ { "sessionCookie": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "curl": { "type": "string", "description": "Literal cURL", "maxLength": 50000, "minLength": 10 } }, "required": [ "curl" ] } } } }, "responses": { "200": { "description": "Inspect SMS cURL fields", "content": { "application/json": { "schema": { "type": "object", "properties": { "host": { "type": "string", "description": "Provider host" }, "parameters": { "type": "array", "items": { "type": "string", "description": "Body path" } }, "recipientPath": { "type": "string", "description": "Suggested path" }, "messagePath": { "type": "string", "description": "Suggested path" } }, "required": [] } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/outreach/connections/{id}": { "put": { "operationId": "put-outreach-connections-id", "tags": [ "Outreach connections" ], "summary": "Update limits or AI replies", "description": "WhatsApp AI needs verified connection and nonblank instructions. Disabling connection also disables AI. Instructions/inbound text are sent to llm.qcall.ai without API key when AI is enabled. Access: Owner or admin.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name", "maxLength": 100, "minLength": 1 }, "enabled": { "type": "boolean", "description": "Enabled" }, "daily_limit": { "type": "integer", "description": "Rolling 24h", "minimum": 1, "maximum": 10000 }, "hourly_limit": { "type": "integer", "description": "Rolling 1h", "minimum": 1, "maximum": 2000 }, "aiEnabled": { "type": "boolean", "description": "WhatsApp only" }, "aiInstructions": { "type": "string", "description": "WhatsApp business instructions", "maxLength": 8000 } }, "required": [ "name", "enabled", "daily_limit", "hourly_limit" ] } } } }, "responses": { "200": { "description": "Update limits or AI replies", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Connection" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/outreach/connections/{id}/reconnect": { "post": { "operationId": "post-outreach-connections-id-reconnect", "tags": [ "Outreach connections" ], "summary": "Replace provider credentials", "description": "secret uses the same provider schema as connection creation. Google/Outlook must reconnect through native OAuth. WhatsApp preserves verify token and disables AI. Access: Owner or admin.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "secret": { "oneOf": [ { "$ref": "#/components/schemas/SMTPSecret" }, { "$ref": "#/components/schemas/SMSSecret" }, { "$ref": "#/components/schemas/VoiceSecret" }, { "$ref": "#/components/schemas/WhatsAppSecret" } ] } }, "required": [ "secret" ] } } } }, "responses": { "200": { "description": "Replace provider credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Connection" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/outreach/connections/{id}/options": { "get": { "operationId": "get-outreach-connections-id-options", "tags": [ "Outreach connections" ], "summary": "Read provider choices", "description": "QCall assistants/dialers, or approved WhatsApp templates. Disabled/unverified returns empty choices. Access: Owner, admin or member.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Read provider choices", "content": { "application/json": { "schema": { "type": "object", "properties": { "assistants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID" }, "name": { "type": "string", "description": "Name" } }, "required": [] } }, "dialers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID" }, "name": { "type": "string", "description": "Name" } }, "required": [] } }, "templates": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Name" }, "language": { "type": "string", "description": "Code" }, "components": { "type": "array", "items": { "type": "object" } } }, "required": [] } } }, "required": [] } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/outreach/connections/{id}/webhook": { "get": { "operationId": "get-outreach-connections-id-webhook", "tags": [ "Outreach connections" ], "summary": "Read Meta webhook setup", "description": "WhatsApp only. Keep verifyToken private; use it in Meta configuration. Access: Owner or admin.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Read Meta webhook setup", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "verifyToken": { "type": "string", "description": "Private token" } }, "required": [] } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/outreach/connections/{id}/sync": { "post": { "operationId": "post-outreach-connections-id-sync", "tags": [ "Outreach connections" ], "summary": "Sync mailbox replies", "description": "IMAP/Google/Outlook matching replies stop sequences. No outgoing mail is sent. Returns {checked}; unsupported provider is 400. Access: Owner or admin.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sync mailbox replies", "content": { "application/json": { "schema": { "type": "object", "properties": { "checked": { "type": "integer", "description": "Headers checked" }, "replies": { "type": "integer", "description": "Replies matched, may be absent when sync skipped" } }, "required": [] } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/outreach/connections/{id}/subscribe": { "post": { "operationId": "post-outreach-connections-id-subscribe", "tags": [ "Outreach connections" ], "summary": "Subscribe WABA to app", "description": "Calls Meta subscribed_apps for WhatsApp connection. Meta must confirm success; configure callback separately. Access: Owner or admin.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Subscribe WABA to app", "content": { "application/json": { "schema": { "type": "object", "properties": { "subscribed": { "const": true } }, "required": [] } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/outreach/ai/preview": { "post": { "operationId": "post-outreach-ai-preview", "tags": [ "Outreach connections" ], "summary": "Preview unsent AI reply", "description": "Sends instructions and synthetic/test message to keyless llm.qcall.ai. Returns generated text; never sends to WhatsApp. Access: Owner or admin.", "security": [ { "sessionCookie": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "instructions": { "type": "string", "description": "Business instructions", "maxLength": 8000, "minLength": 1 }, "message": { "type": "string", "description": "Test incoming message", "maxLength": 4000, "minLength": 1 } }, "required": [ "instructions", "message" ] } } } }, "responses": { "200": { "description": "Preview unsent AI reply", "content": { "application/json": { "schema": { "type": "object", "properties": { "reply": { "type": "string", "description": "Generated plain text" }, "sent": { "const": false } }, "required": [] } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/outreach/oauth/{provider}": { "post": { "operationId": "post-outreach-oauth-provider", "tags": [ "Outreach connections" ], "summary": "Start native mailbox consent", "description": "provider: google or microsoft. Opens a 10-minute PKCE state bound to current account/session/workspace. App credentials and registered redirect required. Access: Owner or admin.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Start native mailbox consent", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" } }, "required": [] } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/outreach/oauth/{provider}/callback": { "get": { "operationId": "get-outreach-oauth-provider-callback", "tags": [ "Webhooks & callbacks" ], "summary": "Complete mailbox consent", "description": "Provider callback, not a manual API call. Matching one-use state/session required; exchanges code and stores encrypted offline grant. Redirects to Outreach connections; cancellation also redirects. Access: Account session.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "state", "in": "query", "required": true, "schema": { "type": "string", "description": "Required OAuth state" } }, { "name": "code", "in": "query", "required": false, "schema": { "type": "string", "description": "Required when error is absent. Omit on provider denial/cancellation.", "maxLength": 4000 } }, { "name": "error", "in": "query", "required": false, "schema": { "type": "string", "description": "Provider denial/cancellation" } } ], "responses": { "302": { "description": "Complete mailbox consent", "headers": { "Location": { "schema": { "type": "string", "format": "uri" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/outreach/campaigns": { "get": { "operationId": "get-outreach-campaigns", "tags": [ "Campaigns & sequences" ], "summary": "List campaigns and sequences", "description": "Latest 100 with connection_name, enrolled and accepted counts. Accepted includes provider accepted/delivered/read/replied, not proof of delivery. Access: Workspace member.", "security": [ { "sessionCookie": [] } ], "parameters": [], "responses": { "200": { "description": "List campaigns and sequences", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Campaign" } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "post-outreach-campaigns", "tags": [ "Campaigns & sequences" ], "summary": "Create campaign or sequence draft", "description": "Nonfinancial audience <=500 source records. Connection channel must match; no enrollment/send until reviewed launch. Access: Owner, admin or member.", "security": [ { "sessionCookie": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignInput" } } } }, "responses": { "201": { "description": "Create campaign or sequence draft", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Campaign" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/outreach/campaigns/{id}": { "get": { "operationId": "get-outreach-campaigns-id", "tags": [ "Campaigns & sequences" ], "summary": "Inspect campaign", "description": "Includes <=500 enrollments with execution state/error and latest 100 deliveries. Access: Workspace member.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Inspect campaign", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Campaign" } ], "properties": { "enrollments": { "type": "array", "items": { "type": "object" } }, "deliveries": { "type": "array", "items": { "type": "object" } } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "put-outreach-campaigns-id", "tags": [ "Campaigns & sequences" ], "summary": "Save campaign draft", "description": "Only unchanged draft. Launched steps/audience are immutable; create a new draft to revise. Access: Owner, admin or member.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Nonblank name", "maxLength": 100 }, "kind": { "type": "string", "enum": [ "campaign", "sequence" ], "description": "A campaign has exactly one step; a sequence has 1-20." }, "channel": { "type": "string", "enum": [ "email", "sms", "voice", "whatsapp" ], "description": "One channel per campaign/sequence" }, "object_key": { "type": "string", "pattern": "^[a-z][a-z0-9_]{1,39}$", "default": "people" }, "list_id": { "type": [ "string", "null" ], "format": "uuid", "default": null }, "connection_id": { "type": "string", "format": "uuid" }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/Step" }, "minItems": 1, "maxItems": 20 }, "version": { "type": "integer", "description": "Positive optimistic version returned by the latest read. Refresh on 409; do not overwrite stale changes.", "minimum": 1 } }, "required": [ "name", "kind", "channel", "connection_id", "steps", "version" ] } } } }, "responses": { "200": { "description": "Save campaign draft", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Campaign" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/outreach/campaigns/{id}/preview": { "post": { "operationId": "post-outreach-campaigns-id-preview", "tags": [ "Campaigns & sequences" ], "summary": "Review eligible audience", "description": "Consent=true, valid email/international phone, unique addresses and no channel suppression. Returns latest version, SHA256 audience digest and up to 20 eligible contacts, plus skip reasons. Access: Owner, admin or member.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Review eligible audience", "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "integer", "description": "Positive optimistic version returned by the latest read. Refresh on 409; do not overwrite stale changes.", "minimum": 1 }, "audienceToken": { "type": "string", "description": "Reviewed audience digest" }, "total": { "type": "integer", "description": "Source contacts" }, "eligible": { "type": "integer", "description": "Eligible count" }, "skipped": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "description": "Name" }, "reason": { "type": "string", "description": "Skip reason" } }, "required": [] } }, "contacts": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Name" }, "recipient": { "type": "string", "description": "Email or phone" } }, "required": [] } }, "firstStep": { "$ref": "#/components/schemas/Step" } }, "required": [] } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/outreach/campaigns/{id}/launch": { "post": { "operationId": "post-outreach-campaigns-id-launch", "tags": [ "Campaigns & sequences" ], "summary": "Launch reviewed audience", "description": "This performs real outreach asynchronously. Fresh digest/version/confirmation required. Verified enabled connector; validates QCall choices or approved WhatsApp body template parameters. Recheck stale audience on 409. Shared sample blocked. Access: Owner or admin.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "integer", "description": "Positive optimistic version returned by the latest read. Refresh on 409; do not overwrite stale changes.", "minimum": 1 }, "audienceToken": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "confirmed": { "const": true } }, "required": [ "version", "audienceToken", "confirmed" ] } } } }, "responses": { "202": { "description": "Launch reviewed audience", "content": { "application/json": { "schema": { "type": "object", "properties": { "enrolled": { "type": "integer", "description": "Enrolled" }, "skipped": { "type": "integer", "description": "Skipped" } }, "required": [] } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/outreach/campaigns/{id}/status": { "post": { "operationId": "post-outreach-campaigns-id-status", "tags": [ "Campaigns & sequences" ], "summary": "Pause, resume or cancel", "description": "Cannot change draft/cancelled. Pause waits before future steps; cancel stops unfinished executions. Already accepted provider side effects cannot be recalled. Access: Owner or admin.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "active", "paused", "cancelled" ], "description": "Campaign state" } }, "required": [ "status" ] } } } }, "responses": { "200": { "description": "Pause, resume or cancel", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "New state" } }, "required": [] } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/outreach/campaigns/{id}/contacts/{record}/stop": { "post": { "operationId": "post-outreach-campaigns-id-contacts-record-stop", "tags": [ "Campaigns & sequences" ], "summary": "Stop one enrolled contact", "description": "Stops unfinished follow-ups for this campaign; does not permanently suppress other campaigns. Use Suppressions for that. Access: Owner, admin or member.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "record", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Stop one enrolled contact", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OK" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/outreach/activity": { "get": { "operationId": "get-outreach-activity", "tags": [ "Campaigns & sequences" ], "summary": "Read recent outreach activity", "description": "Latest 100 deliveries and 50 incoming messages, with connection names. Unknown means acceptance was ambiguous: check provider before a new attempt. Access: Workspace member.", "security": [ { "sessionCookie": [] } ], "parameters": [], "responses": { "200": { "description": "Read recent outreach activity", "content": { "application/json": { "schema": { "type": "object", "properties": { "deliveries": { "type": "array", "items": { "type": "object", "description": "id, connection_id/name, execution_id, node_id, recipient, provider_id, status, error, timestamps" } }, "messages": { "type": "array", "items": { "type": "object", "description": "connection_id/name, provider_id, sender, body, received_at, execution_id" } } }, "required": [] } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/outreach/suppressions": { "get": { "operationId": "get-outreach-suppressions", "tags": [ "Campaigns & sequences" ], "summary": "Read channel suppressions", "description": "Latest 100. Permanent per workspace/channel; no removal API in current release. Access: Workspace member.", "security": [ { "sessionCookie": [] } ], "parameters": [], "responses": { "200": { "description": "Read channel suppressions", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "description": "channel, recipient, reason, created_at" } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "post-outreach-suppressions", "tags": [ "Campaigns & sequences" ], "summary": "Suppress recipient", "description": "Normalizes email lowercase or international +phone; stops active sequences on this channel/workspace. Access: Owner, admin or member.", "security": [ { "sessionCookie": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "channel": { "type": "string", "enum": [ "email", "sms", "voice", "whatsapp" ], "description": "Channel" }, "recipient": { "type": "string", "description": "Email or international phone", "maxLength": 200 } }, "required": [ "channel", "recipient" ] } } } }, "responses": { "200": { "description": "Suppress recipient", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OK" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/outreach/whatsapp/{id}": { "get": { "operationId": "get-outreach-whatsapp-id", "tags": [ "Webhooks & callbacks" ], "summary": "Verify Meta callback", "description": "Connection-specific endpoint. hub.mode=subscribe and matching hub.verify_token required; returns challenge as plain text. Access: Meta verify token.", "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "hub.mode", "in": "query", "required": true, "schema": { "const": "subscribe" } }, { "name": "hub.verify_token", "in": "query", "required": true, "schema": { "type": "string", "description": "Private connection token" } }, { "name": "hub.challenge", "in": "query", "required": true, "schema": { "type": "string", "description": "Required challenge", "maxLength": 200 } } ], "responses": { "200": { "description": "Verify Meta callback", "content": { "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "post-outreach-whatsapp-id", "tags": [ "Webhooks & callbacks" ], "summary": "Receive Meta messages", "description": "Raw JSON bytes; X-Hub-Signature-256 = sha256=hex HMAC-SHA256(body, appSecret). Checks WABA and phone IDs, dedupes messages, updates delivery/read receipts. Incoming text stops follow-ups; STOP/unsubscribe/cancel/quit permanently suppresses. AI only for eligible inbound messages within 24 hours. Access: Meta signature.", "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Hub-Signature-256", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Meta whatsapp_business_account event with entry[].id, changes[].field=messages, value.metadata.phone_number_id and messages/statuses." } } } }, "responses": { "200": { "description": "Receive Meta messages", "content": { "application/json": { "schema": { "type": "object", "properties": { "received": { "const": true } }, "required": [] } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/outreach/unsubscribe/{token}": { "get": { "operationId": "get-outreach-unsubscribe-token", "tags": [ "Webhooks & callbacks" ], "summary": "Show unsubscribe confirmation", "description": "64-character hex token in email link. Branded HTML form; GET does not suppress. Access: Secret unsubscribe token.", "security": [], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Show unsubscribe confirmation", "content": { "text/html": { "schema": { "type": "string", "description": "HTML confirmation page" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "post-outreach-unsubscribe-token", "tags": [ "Webhooks & callbacks" ], "summary": "Confirm unsubscribe", "description": "No body required. Stops follow-ups and permanently suppresses the recipient for this workspace/channel. Supports one-click unsubscribe. Returns branded HTML success. Access: Secret unsubscribe token.", "security": [], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Confirm unsubscribe", "content": { "text/html": { "schema": { "type": "string", "description": "HTML success page" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign-in or signature required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Active plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 512 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "drykraft_session", "description": "HTTP-only session cookie created by signup/login, secure in production, same-site lax, seven-day lifetime." } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "description": "Recovery message" }, "request_id": { "type": "string", "description": "Request correlation ID; may be absent on a rate limit response" } }, "required": [ "message" ] } }, "required": [ "error" ] }, "OK": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true } }, "required": [ "ok" ] }, "Record": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "tenant_id": { "type": "string", "format": "uuid" }, "object_key": { "type": "string", "pattern": "^[a-z][a-z0-9_]{1,39}$" }, "data": { "type": "object", "additionalProperties": true, "description": "Object field values. Only keys in the workspace object definition are allowed; required fields and field types are validated." }, "version": { "type": "integer", "description": "Positive optimistic version returned by the latest read. Refresh on 409; do not overwrite stale changes.", "minimum": 1 }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "object_key", "data", "version" ] }, "RecordPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Record" } }, "total": { "type": "integer", "description": "Number matching the full query, before cursor" }, "next_cursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page; null ends pagination." } }, "required": [ "items", "total", "next_cursor" ] }, "Field": { "type": "object", "properties": { "key": { "type": "string", "pattern": "^[a-z][a-z0-9_]{1,39}$" }, "name": { "type": "string", "description": "Field label", "maxLength": 80 }, "type": { "type": "string", "enum": [ "text", "email", "phone", "number", "currency", "boolean", "date", "select", "multi_select", "relation", "json" ], "description": "Field type" }, "required": { "type": "boolean", "description": "Defaults false" }, "options": { "type": "array", "items": { "type": "string", "description": "Option", "maxLength": 80 }, "minItems": 0, "maxItems": 100 }, "object": { "type": "string", "pattern": "^[a-z][a-z0-9_]{1,39}$" } }, "required": [ "key", "name", "type" ] }, "Object": { "type": "object", "properties": { "key": { "type": "string", "pattern": "^[a-z][a-z0-9_]{1,39}$" }, "name": { "type": "string", "description": "Plural label", "maxLength": 80 }, "singular_name": { "type": "string", "description": "Singular label", "maxLength": 80 }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/Field" }, "minItems": 1, "maxItems": 100 } }, "required": [ "key", "name", "singular_name", "fields" ] }, "Filter": { "type": "object", "properties": { "match": { "type": "string", "enum": [ "all", "any" ], "description": "Combine conditions" }, "conditions": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "pattern": "^[a-z][a-z0-9_]{1,39}$" }, "operator": { "type": "string", "enum": [ "eq", "ne", "contains", "not_contains", "gt", "gte", "lt", "lte", "empty", "not_empty" ], "description": "Supported operators depend on field type. Relations and JSON are excluded." }, "value": { "type": [ "string", "number", "boolean" ], "description": "Typed comparison value; omit for empty/not_empty." } }, "required": [ "field", "operator" ] }, "minItems": 1, "maxItems": 12 } }, "required": [ "match", "conditions" ] }, "SmartList": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "object_key": { "type": "string", "pattern": "^[a-z][a-z0-9_]{1,39}$" }, "name": { "type": "string", "description": "Unique name per object", "maxLength": 80 }, "filter": { "$ref": "#/components/schemas/Filter" }, "version": { "type": "integer", "description": "Positive optimistic version returned by the latest read. Refresh on 409; do not overwrite stale changes.", "minimum": 1 } }, "required": [ "id", "name", "filter", "version" ] }, "ListInput": { "type": "object", "properties": { "name": { "type": "string", "description": "Nonblank list name", "maxLength": 80 }, "filter": { "$ref": "#/components/schemas/Filter" } }, "required": [ "name", "filter" ] }, "Import": { "type": "object", "properties": { "csv": { "type": "string", "description": "UTF-8 CSV content, not a file path. Header required; <=500 data rows.", "maxLength": 300000 }, "mapping": { "type": "array", "items": { "type": [ "string", "null" ], "description": "Field key per CSV column, null skips a column. Omit to match field keys/labels." }, "minItems": 0, "maxItems": 100 }, "duplicates": { "type": "string", "enum": [ "skip", "update", "error" ], "description": "People email duplicate policy, default skip. Blank update cells preserve existing values." } }, "required": [ "csv" ] }, "ImportReport": { "type": "object", "properties": { "headers": { "type": "array", "items": { "type": "string", "description": "CSV heading" } }, "mapping": { "type": "array", "items": { "type": [ "string", "null" ] } }, "rows": { "type": "integer", "description": "Data rows" }, "created": { "type": "integer", "description": "Planned creates" }, "updated": { "type": "integer", "description": "Planned updates" }, "skipped": { "type": "integer", "description": "Planned skips" }, "error_count": { "type": "integer", "description": "All errors" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "line": { "type": "integer", "description": "CSV line" }, "message": { "type": "string", "description": "Validation error" } }, "required": [] } }, "preview": { "type": "array", "items": { "type": "object", "properties": { "line": { "type": "integer", "description": "CSV line" }, "action": { "type": "string", "description": "create, update or skip" }, "data": { "type": "object", "additionalProperties": true, "description": "Object field values. Only keys in the workspace object definition are allowed; required fields and field types are validated." } }, "required": [] } }, "can_import": { "type": "boolean", "description": "True only if the whole import is valid" } }, "required": [] }, "ContactMerge": { "type": "object", "properties": { "contacts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "version": { "type": "integer", "description": "Positive optimistic version returned by the latest read. Refresh on 409; do not overwrite stale changes.", "minimum": 1 } }, "required": [ "id", "version" ] }, "minItems": 2, "maxItems": 2 }, "target_id": { "type": "string", "format": "uuid" }, "take_source": { "type": "array", "items": { "type": "string", "pattern": "^[a-z][a-z0-9_]{1,39}$" }, "minItems": 0, "maxItems": 100 } }, "required": [ "contacts", "target_id" ], "description": "Two distinct active People records, current versions and a remaining target. Omit take_source for remaining values with automatic filling of empty fields. Chosen source fields replace even empty values. Tags combine; consent is true only when both records explicitly consent. Different custom amount currencies must be aligned first." }, "MergeEffects": { "type": "object", "properties": { "notes": { "type": "integer", "description": "Source notes moved" }, "relationships": { "type": "integer", "description": "Related records updated, including financial drafts" }, "financial_history": { "type": "integer", "description": "Non-draft financial records retained unchanged" }, "links": { "type": "integer", "description": "Source links combined, duplicates collapse" }, "stopped_sequences": { "type": "integer", "description": "Active source enrollments cancelled" } }, "required": [] }, "Pipeline": { "type": "object", "properties": { "name": { "type": "string", "description": "Pipeline name", "maxLength": 100 }, "stages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z0-9_-]{1,40}$" }, "name": { "type": "string", "description": "Stage label", "maxLength": 80 }, "probability": { "type": "number", "minimum": 0, "maximum": 100 }, "color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" } }, "required": [ "id", "name", "probability", "color" ] }, "minItems": 1, "maxItems": 30 } }, "required": [ "name", "stages" ] }, "Widget": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique widget ID", "maxLength": 80 }, "title": { "type": "string", "description": "KPI title", "maxLength": 120 }, "object": { "type": "string", "pattern": "^[a-z][a-z0-9_]{1,39}$" }, "operation": { "type": "string", "enum": [ "count", "sum", "avg" ], "description": "Aggregation" }, "field": { "type": "string", "pattern": "^[a-z][a-z0-9_]{1,39}$" }, "group_by": { "type": "string", "pattern": "^[a-z][a-z0-9_]{1,39}$" }, "display": { "type": "string", "enum": [ "metric", "bar", "donut" ], "description": "Presentation" }, "currency": { "type": "string", "description": "Currency for monetary results" }, "filter": { "type": "object", "properties": { "field": { "type": "string", "pattern": "^[a-z][a-z0-9_]{1,39}$" }, "value": { "type": "string", "description": "Exact text comparison", "maxLength": 200 } }, "required": [ "field", "value" ] } }, "required": [ "id", "title", "object", "operation", "display" ] }, "FinanceProfile": { "type": "object", "properties": { "business_name": { "type": "string", "description": "Nonblank issuer name", "maxLength": 160 }, "email": { "oneOf": [ { "type": "string", "format": "email", "maxLength": 200 }, { "const": "" } ] }, "address": { "type": "string", "description": "Issuer address", "maxLength": 2000 }, "tax_id": { "type": "string", "description": "Tax reference", "maxLength": 100 }, "payment_instructions": { "type": "string", "description": "Payment instructions", "maxLength": 2000 }, "invoice_prefix": { "type": "string", "pattern": "^[A-Z0-9-]{1,12}$", "default": "INV" } }, "required": [ "business_name" ] }, "InvoiceData": { "type": "object", "properties": { "name": { "type": "string", "description": "Required title" }, "customer_name": { "type": "string", "description": "Required customer name" }, "customer_email": { "type": "string", "format": "email", "maxLength": 200 }, "billing_address": { "type": "string", "description": "Address" }, "contact_id": { "type": "string", "format": "uuid" }, "deal_id": { "type": "string", "format": "uuid" }, "currency": { "type": "string", "description": "Enabled currency code" }, "issue_date": { "type": "string", "format": "date", "description": "Valid calendar date, YYYY-MM-DD." }, "due_date": { "type": "string", "format": "date", "description": "Valid calendar date, YYYY-MM-DD." }, "items": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string", "description": "Nonblank description", "maxLength": 500 }, "quantity": { "oneOf": [ { "type": "string" }, { "type": "number" } ], "description": "Major currency units, nonnegative. Use decimal strings to retain precision. Currency-specific decimal places apply." }, "unit_price": { "oneOf": [ { "type": "string" }, { "type": "number" } ], "description": "Major currency units, nonnegative. Use decimal strings to retain precision. Currency-specific decimal places apply." }, "discount": { "oneOf": [ { "type": "string" }, { "type": "number" } ], "description": "Major currency units, nonnegative. Use decimal strings to retain precision. Currency-specific decimal places apply." }, "tax_rate": { "oneOf": [ { "type": "string" }, { "type": "number" } ], "description": "Major currency units, nonnegative. Use decimal strings to retain precision. Currency-specific decimal places apply." } }, "required": [ "description", "quantity", "unit_price" ] }, "minItems": 1, "maxItems": 100 }, "notes": { "type": "string", "description": "Notes" } }, "required": [ "name", "customer_name", "currency", "issue_date", "due_date", "items" ], "description": "Draft inputs; custom optional fields are allowed if defined. Quantity >0 to 1,000,000 with <=3 decimals. Discount is a line amount, tax_rate is 0-100 percent with <=2 decimals. Due date cannot precede issue date. Totals/status/issuer/number are server managed." }, "ExpenseData": { "type": "object", "properties": { "name": { "type": "string", "description": "Required title" }, "vendor": { "type": "string", "description": "Required vendor" }, "category": { "type": "string", "description": "Category" }, "spent_on": { "type": "string", "format": "date", "description": "Valid calendar date, YYYY-MM-DD." }, "currency": { "type": "string", "description": "Enabled currency code" }, "amount": { "oneOf": [ { "type": "string" }, { "type": "number" } ], "description": "Major currency units, nonnegative. Use decimal strings to retain precision. Currency-specific decimal places apply." }, "tax": { "oneOf": [ { "type": "string" }, { "type": "number" } ], "description": "Major currency units, nonnegative. Use decimal strings to retain precision. Currency-specific decimal places apply." }, "receipt_url": { "type": "string", "format": "uri", "description": "HTTP(S) reference; no receipt upload endpoint." }, "notes": { "type": "string", "description": "Notes" }, "deal_id": { "type": "string", "format": "uuid" } }, "required": [ "name", "vendor", "spent_on", "currency", "amount" ], "description": "Amount must be positive; tax is included in amount and cannot exceed it. Custom optional fields are allowed if defined. Status/approval/totals are server managed." }, "Payment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "version": { "type": "integer", "description": "Positive optimistic version returned by the latest read. Refresh on 409; do not overwrite stale changes.", "minimum": 1 }, "amount": { "oneOf": [ { "type": "string" }, { "type": "number" } ], "description": "Major currency units, nonnegative. Use decimal strings to retain precision. Currency-specific decimal places apply." }, "paid_on": { "type": "string", "format": "date", "description": "Valid calendar date, YYYY-MM-DD." }, "method": { "type": "string", "enum": [ "Bank transfer", "Cash", "Card", "Other" ], "description": "Payment handled outside DryKraft" }, "reference": { "type": "string", "description": "Nonblank payment reference", "maxLength": 200 } }, "required": [ "id", "version", "amount", "paid_on", "method", "reference" ] }, "NodeData": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "trigger.manual", "trigger.event", "trigger.schedule", "trigger.webhook", "condition", "wait", "set", "crm.create", "crm.update", "finance.create", "http", "log" ], "description": "Outreach kinds are managed and rejected by the general editor." }, "label": { "type": "string", "description": "Nonempty node label", "maxLength": 100 }, "event": { "type": "string", "description": "Required for trigger.event", "maxLength": 100 }, "intervalMinutes": { "type": "integer", "description": "Required for trigger.schedule", "minimum": 1, "maximum": 525600 }, "seconds": { "type": "integer", "description": "Required for wait", "minimum": 1, "maximum": 2592000 }, "object": { "type": "string", "pattern": "^[a-z][a-z0-9_]{1,39}$", "description": "Required for crm.create/update; finance.create only invoices or expenses" }, "values": { "type": "object", "additionalProperties": true, "description": "Required for set or record create/update; interpolated context values" }, "recordId": { "type": "string", "description": "Required for crm.update; UUID or context expression" }, "field": { "type": "string", "description": "Required context path for condition", "maxLength": 100 }, "operator": { "type": "string", "enum": [ "eq", "neq", "gte", "gt", "lte", "lt", "contains", "exists" ], "description": "Required for condition" }, "value": { "description": "Condition comparison value, interpolated", "type": [ "string", "number", "boolean", "object", "array", "null" ] }, "url": { "type": "string", "format": "uri", "description": "Required for http; public destination only" }, "method": { "type": "string", "enum": [ "GET", "POST", "PUT", "PATCH", "DELETE" ], "description": "http method, default GET" }, "credentialId": { "type": "string", "format": "uuid", "description": "Optional saved outbound credential. Headers are server-managed, not arbitrary draft headers." }, "body": { "description": "http body; interpolated", "type": [ "string", "object", "array", "null" ] }, "message": { "type": "string", "description": "log message; context expressions supported" } }, "required": [ "kind", "label" ], "description": "Fields are conditional on kind; publish enforces the required node settings. Extra runtime context fields may exist." }, "Graph": { "type": "object", "properties": { "nodes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique nonempty node ID", "maxLength": 80 }, "type": { "const": "workflow" }, "position": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" } }, "required": [ "x", "y" ] }, "data": { "$ref": "#/components/schemas/NodeData" } }, "required": [ "id", "type", "position", "data" ] }, "minItems": 1, "maxItems": 100 }, "edges": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Edge ID" }, "source": { "type": "string", "description": "Source node" }, "target": { "type": "string", "description": "Target node" }, "sourceHandle": { "type": [ "string", "null" ] }, "targetHandle": { "type": [ "string", "null" ] }, "label": { "type": "string", "description": "Optional label" } }, "required": [ "id", "source", "target" ] }, "minItems": 0, "maxItems": 150 } }, "required": [ "nodes", "edges" ] }, "Workflow": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "description": "Name" }, "description": { "type": "string", "description": "Description" }, "draft": { "$ref": "#/components/schemas/Graph" }, "status": { "type": "string", "description": "draft, active or paused" }, "published_version_id": { "type": [ "string", "null" ], "format": "uuid" }, "created_at": { "type": "string", "description": "Timestamp" }, "updated_at": { "type": "string", "description": "Timestamp" } }, "required": [] }, "Execution": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "workflow_id": { "type": "string", "format": "uuid" }, "version_id": { "type": "string", "format": "uuid" }, "state": { "type": "string", "description": "queued, running, waiting, retrying, succeeded, failed or cancelled" }, "input": { "type": "object", "additionalProperties": true, "description": "Object field values. Only keys in the workspace object definition are allowed; required fields and field types are validated." }, "context": { "type": "object", "additionalProperties": true, "description": "Object field values. Only keys in the workspace object definition are allowed; required fields and field types are validated." }, "current_node": { "type": [ "string", "null" ] }, "error": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "description": "Timestamp" }, "completed_at": { "type": [ "string", "null" ] } }, "required": [] }, "Connection": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "description": "Name" }, "channel": { "type": "string", "enum": [ "email", "sms", "voice", "whatsapp" ], "description": "Channel" }, "provider": { "type": "string", "enum": [ "smtp", "google", "microsoft", "curl", "qcall", "whatsapp" ], "description": "Provider" }, "config": { "type": "object", "description": "Public provider metadata; no private credentials" }, "enabled": { "type": "boolean", "description": "Connection enabled" }, "verified_at": { "type": [ "string", "null" ] }, "last_error": { "type": [ "string", "null" ] }, "daily_limit": { "type": "integer", "description": "Rolling daily allowance", "minimum": 1, "maximum": 10000 }, "hourly_limit": { "type": "integer", "description": "Rolling hourly allowance", "minimum": 1, "maximum": 2000 }, "created_at": { "type": "string", "description": "Timestamp" } }, "required": [] }, "SMTPSecret": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "maxLength": 200 }, "host": { "type": "string", "description": "Public SMTP hostname" }, "port": { "enum": [ 465, 587 ] }, "user": { "type": "string", "description": "Username" }, "password": { "type": "string", "description": "Password/app password" }, "imap": { "type": "object", "properties": { "host": { "type": "string", "description": "Public IMAP hostname; TLS port 993" }, "user": { "type": "string", "description": "Username" }, "password": { "type": "string", "description": "Password/app password" } }, "required": [ "host", "user", "password" ] } }, "required": [ "email", "host", "port", "user", "password" ] }, "SMSSecret": { "type": "object", "properties": { "curl": { "type": "string", "description": "One literal HTTPS:443 POST JSON cURL. No execution or file input.", "maxLength": 50000 }, "recipientPath": { "type": "string", "description": "Existing body path, e.g. recipients.0.mobiles", "maxLength": 150 }, "messagePath": { "type": "string", "description": "Optional message body path", "maxLength": 150 } }, "required": [ "curl", "recipientPath" ] }, "VoiceSecret": { "type": "object", "properties": { "apiKey": { "type": "string", "description": "Workspace QCall API key" } }, "required": [ "apiKey" ] }, "WhatsAppSecret": { "type": "object", "properties": { "accessToken": { "type": "string", "description": "Meta access token" }, "appSecret": { "type": "string", "description": "Meta app secret" }, "wabaId": { "type": "string", "pattern": "^\\d{5,40}$" }, "phoneId": { "type": "string", "pattern": "^\\d{5,40}$" }, "version": { "type": "string", "pattern": "^v\\d{2}\\.0$", "default": "v23.0" } }, "required": [ "accessToken", "appSecret", "wabaId", "phoneId" ] }, "ConnectionInput": { "type": "object", "properties": { "name": { "type": "string", "description": "Nonblank name", "maxLength": 100 }, "provider": { "type": "string", "enum": [ "smtp", "curl", "qcall", "whatsapp" ], "description": "Use native OAuth endpoints for Google/Outlook." }, "daily_limit": { "type": "integer", "description": "Defaults 100", "minimum": 1, "maximum": 10000 }, "hourly_limit": { "type": "integer", "description": "Defaults 20", "minimum": 1, "maximum": 2000 }, "secret": { "oneOf": [ { "$ref": "#/components/schemas/SMTPSecret" }, { "$ref": "#/components/schemas/SMSSecret" }, { "$ref": "#/components/schemas/VoiceSecret" }, { "$ref": "#/components/schemas/WhatsAppSecret" } ], "description": "Choose the schema matching provider. Secret is encrypted and never returned." } }, "required": [ "name", "provider", "secret" ] }, "Step": { "type": "object", "properties": { "waitHours": { "type": "integer", "description": "Wait before this step, default 0", "minimum": 0, "maximum": 720 }, "subject": { "type": "string", "description": "Email subject; nonblank for email", "maxLength": 300 }, "body": { "type": "string", "description": "Email/SMS body; email requires nonblank", "maxLength": 10000 }, "variables": { "type": "object", "additionalProperties": { "type": "string", "description": "SMS template variable, max 1,000 characters", "maxLength": 1000 }, "description": "Keys: 1-40 letters, digits or underscores" }, "template": { "type": "string", "description": "Approved WhatsApp template name", "maxLength": 100 }, "language": { "type": "string", "description": "WhatsApp language, default en", "maxLength": 20 }, "parameters": { "type": "array", "items": { "type": "string", "description": "WhatsApp body parameter", "maxLength": 1000 }, "minItems": 0, "maxItems": 20 }, "assistantId": { "type": "string", "description": "QCall assistant ID", "maxLength": 100 }, "dialerId": { "type": "string", "description": "QCall dialer ID", "maxLength": 100 } }, "required": [], "description": "All optional fields default to empty except language. Email requires subject/body; SMS needs body or variables; voice requires assistant/dialer; WhatsApp requires template/language. Interpolate {{record.data.name}} and other context paths." }, "CampaignInput": { "type": "object", "properties": { "name": { "type": "string", "description": "Nonblank name", "maxLength": 100 }, "kind": { "type": "string", "enum": [ "campaign", "sequence" ], "description": "A campaign has exactly one step; a sequence has 1-20." }, "channel": { "type": "string", "enum": [ "email", "sms", "voice", "whatsapp" ], "description": "One channel per campaign/sequence" }, "object_key": { "type": "string", "pattern": "^[a-z][a-z0-9_]{1,39}$", "default": "people" }, "list_id": { "type": [ "string", "null" ], "format": "uuid", "default": null }, "connection_id": { "type": "string", "format": "uuid" }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/Step" }, "minItems": 1, "maxItems": 20 } }, "required": [ "name", "kind", "channel", "connection_id", "steps" ] }, "Campaign": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "description": "Name" }, "kind": { "type": "string", "description": "campaign or sequence" }, "channel": { "type": "string", "description": "Channel" }, "object_key": { "type": "string", "pattern": "^[a-z][a-z0-9_]{1,39}$" }, "list_id": { "type": [ "string", "null" ] }, "connection_id": { "type": "string", "format": "uuid" }, "workflow_id": { "type": "string", "format": "uuid" }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/Step" } }, "status": { "type": "string", "description": "draft, active, paused or cancelled" }, "version": { "type": "integer", "description": "Positive optimistic version returned by the latest read. Refresh on 409; do not overwrite stale changes.", "minimum": 1 }, "created_at": { "type": "string", "description": "Timestamp" }, "updated_at": { "type": "string", "description": "Timestamp" } }, "required": [] } } } }