{ "openapi": "3.1.0", "info": { "title": "Amdahl Platform API", "version": "1.0.0", "description": "REST API for Amdahl, an eval harness for GTM outputs. Three surfaces: **Evals** grades what your agents write against your own customer conversations, **Search** answers questions over the same corpus in one synchronous call, and **Agents** runs async investigations (multi-turn Chat)." }, "servers": [ { "url": "/" } ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "tags": [ { "name": "assets", "description": "Artifacts - unified output storage with version history and hierarchy." }, { "name": "context", "description": "Business context, substrate intelligence, remembered evidence, and Q&A." }, { "name": "conversations", "description": "" }, { "name": "data", "description": "Data exploration - SQL queries, hybrid search, and ML clusters." }, { "name": "workflows", "description": "Workflow orchestration endpoints." } ], "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Platform API key (amdhl_...). Scopes are enforced per operation. The same key is also accepted as `Authorization: Bearer ` — one key works on both transports." }, "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Bearer credential: an API key (amdhl_-prefixed values are validated as API keys), an OAuth access token, or a Supabase JWT. Role + scope enforcement applies." }, "OAuth2": { "type": "oauth2", "description": "OAuth2 authorization code flow with scope granularity.", "flows": { "authorizationCode": { "authorizationUrl": "/oauth/authorize", "tokenUrl": "/oauth/token", "scopes": { "connections:delete": "Disconnect connections", "connections:read": "Read connections and the connector catalog", "connections:write": "Connect, reconnect, and configure connections", "conversations:read": "Read chats and their runs", "conversations:write": "Start, rename, and configure chats", "data:read": "Query and search data sources", "messages:execute": "Run the message optimizer on a draft message", "workflows:write": "Resume and cancel agent runs" } } } } }, "schemas": {}, "parameters": {} }, "paths": { "/api/platform/v1/agents/{session_id}/resume": { "post": { "operationId": "agentsResume", "summary": "Resume Agent Session", "description": "Resume an agent run that is paused on pending user input. Use when replying to an outline approval prompt, a clarification question, or a continue/finish decision. The input payload must match the run's `pending_input_schema`. After a successful resume the run transitions back to running and proceeds from where it paused.", "tags": [ "workflows" ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} } } } } }, "400": { "description": "Invalid input - failed schema validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - missing scope or role", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } }, "security": [ { "ApiKeyAuth": [ "workflows:write" ] }, { "BearerAuth": [ "workflows:write" ] } ], "x-scopes": [ "workflows:write" ], "x-stability": "stable", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "input": { "type": "object", "description": "The user's resume payload. Must match the run's persisted pending_input_schema.", "additionalProperties": true } }, "required": [ "input" ], "additionalProperties": false } } } } } }, "/api/platform/v1/agents/{session_id}/cancel": { "post": { "operationId": "agentsCancel", "summary": "Cancel Agent Session", "description": "Cancel an in-flight agent run. Use when the user wants to stop a running agent before it finishes, or abandon a run that has gone sideways. Cascades to any sub-agents spawned from this run via agents.delegate — every live descendant is cancelled atomically. The runner bails at the next iteration boundary after observing the status change. Already-completed runs cannot be canceled. Pass a reason to record WHY the run was aborted in the audit trail.", "tags": [ "workflows" ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} } } } } }, "400": { "description": "Invalid input - failed schema validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - missing scope or role", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } }, "security": [ { "ApiKeyAuth": [ "workflows:write" ] }, { "BearerAuth": [ "workflows:write" ] } ], "x-scopes": [ "workflows:write" ], "x-stability": "stable", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "maxLength": 500, "description": "Optional operator note describing why the run was canceled." } }, "additionalProperties": false } } } } } }, "/api/platform/v1/connections/catalog": { "get": { "operationId": "connectionsListCatalog", "summary": "List Connector Catalog", "description": "Read the catalog of integrations a workspace can hook up - CRM, calls, comms, docs, support, social, and actions (outbound) - with each entry's connect flow, ownership, and the data streams it brings in. Read when rendering the \"add a connection\" picker or answering which providers are supported. Describes what CAN be connected, not what is already connected. Optional kind / category filters narrow the menu.", "tags": [ "data" ], "parameters": [ { "name": "kind", "in": "query", "required": false, "description": "Filter to one ingestion stack. first_party (amdahl-data pullers) is the only stack today; use category=social to filter the social UI grouping.", "schema": { "type": "string", "enum": [ "first_party" ], "description": "Filter to one ingestion stack. first_party (amdahl-data pullers) is the only stack today; use category=social to filter the social UI grouping." } }, { "name": "category", "in": "query", "required": false, "description": "Filter to one UI category.", "schema": { "type": "string", "enum": [ "crm", "calls", "comms", "docs", "support", "social", "actions" ], "description": "Filter to one UI category." } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} } } } } }, "400": { "description": "Invalid input - failed schema validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - missing scope or role", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } }, "security": [ { "ApiKeyAuth": [ "connections:read" ] }, { "BearerAuth": [ "connections:read" ] } ], "x-scopes": [ "connections:read" ], "x-stability": "stable" } }, "/api/platform/v1/connections": { "get": { "operationId": "connectionsList", "summary": "List Established Connections", "description": "Read the integrations a workspace has actually established, newest first, merging first-party data sources and tracked social accounts into one normalized list with a uniform status, scope, and last-synced field. Read when rendering the connections inventory or answering which integrations are live for the tenant. Defaults to ACTIVE connections; pass include_inactive=true to also return disconnected and never-synced sources.", "tags": [ "data" ], "parameters": [ { "name": "include_inactive", "in": "query", "required": false, "description": "Include disconnected and never-synced (abandoned / in-flight) connections. Defaults to false, which returns only active connections (connected/syncing or ever-synced).", "schema": { "type": "boolean", "description": "Include disconnected and never-synced (abandoned / in-flight) connections. Defaults to false, which returns only active connections (connected/syncing or ever-synced)." } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} } } } } }, "400": { "description": "Invalid input - failed schema validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - missing scope or role", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } }, "security": [ { "ApiKeyAuth": [ "connections:read" ] }, { "BearerAuth": [ "connections:read" ] } ], "x-scopes": [ "connections:read" ], "x-stability": "stable" }, "post": { "operationId": "connectionsConnect", "summary": "Connect an Integration", "description": "Establish a new integration for a workspace, routing on the connector type: collect an API key, kick off an OAuth redirect, or track a social handle. Use when a user picks a provider from the catalog and wants it connected. Returns the created connection, or an OAuth authorize URL to redirect to. Creates and stores the connection without starting a sync.", "tags": [ "data" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} } } } } }, "400": { "description": "Invalid input - failed schema validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - missing scope or role", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } }, "security": [ { "ApiKeyAuth": [ "connections:write" ] }, { "BearerAuth": [ "connections:write" ] } ], "x-scopes": [ "connections:write" ], "x-stability": "stable", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "connector_type": { "type": "string", "description": "Catalog connector type to connect (e.g. hubspot, fathom, twitter)." }, "name": { "type": "string", "description": "Optional display label for this connection instance.", "maxLength": 200 }, "scope": { "type": "string", "enum": [ "business", "personal" ], "description": "Ownership: business (workspace-wide) or personal. Defaults from the catalog." }, "api_key": { "type": "string", "description": "For api_key connectors: the API key / token to store (encrypted).", "minLength": 1 }, "api_id": { "type": "string", "description": "For an api_key connector whose credential is a PAIR (today only Aircall, whose API is HTTP Basic): the non-secret id half, pasted alongside the token in api_key. Read connections.list_catalog to see whether a connector asks for it.", "minLength": 1 }, "base_url": { "type": "string", "description": "For the computer_agent connector: its deployment base URL (http/https).", "minLength": 1 }, "account_handle": { "type": "string", "description": "For social (handle) connectors: the resolved bare account handle.", "maxLength": 200 }, "external_account_id": { "type": "string", "description": "For social (handle) connectors: the provider's stable account id.", "maxLength": 200 }, "display_name": { "type": "string", "description": "For social (handle) connectors: display name snapshot.", "maxLength": 200 }, "avatar_url": { "type": "string", "description": "For social (handle) connectors: avatar image URL snapshot." }, "followers": { "type": "integer", "description": "For social (handle) connectors: follower count snapshot." }, "return_to": { "type": "string", "description": "For oauth connectors: console URL to redirect back to after the handshake (first-party origins only)." }, "call_filters": { "type": "object", "description": "For an api_key CALLS connector (e.g. Fireflies): an optional atomic pre-sync call filter applied in the SAME request, so the source connects AND its filter decision lands together (an enabled filter syncs filtered; { enabled: false } is the \"ingest all\" opt-out). Omit to leave the calls source paused until a filter is set later. Own domains are stamped server-side. Requires workspace admin.", "properties": { "enabled": { "type": "boolean", "description": "Whether the filter is active. false = the \"ingest all calls\" opt-out." }, "require_external": { "type": "boolean", "description": "Ingest only calls with at least one external attendee." }, "require_participants": { "type": "array", "items": { "type": "string" }, "description": "Ingest only calls including at least one of these participant emails." }, "exclude_participants": { "type": "array", "items": { "type": "string" }, "description": "NEVER ingest a call one of these emails attended or hosted (exclusion wins over the include rules)." }, "exclude_domains": { "type": "array", "items": { "type": "string" }, "description": "NEVER ingest a call with an attendee/host on one of these domains (suffix-aware; exclusion wins)." }, "internal_domains": { "type": "array", "items": { "type": "string" }, "description": "Optional extra internal domains; the tenant own domains are merged in." }, "bot_domains": { "type": "array", "items": { "type": "string" }, "description": "Meeting-bot email domains to disregard when computing the roster." }, "mode": { "type": "string", "enum": [ "strict" ], "description": "Fail-closed posture; only \"strict\"." }, "on_ambiguous": { "type": "string", "enum": [ "exclude" ], "description": "Ambiguity resolution; only \"exclude\"." } }, "additionalProperties": false }, "crm_recency": { "type": "object", "description": "For a CRM connector (Salesforce / HubSpot / Pipedrive): how much activity/comms history (emails, meetings, calls, notes, tasks) the first sync imports. window_months (1–120) OR all_history. Reference records (accounts, contacts, deals) always land in full. Omit for the 12-month default.", "properties": { "window_months": { "type": "integer", "minimum": 1, "maximum": 120, "description": "Import the last N months of CRM activity/comms." }, "all_history": { "type": "boolean", "description": "Import ALL activity history (unbounded). Mutually exclusive with window_months." } }, "additionalProperties": false }, "comms_filter": { "type": "object", "description": "For a connector that supports it (HubSpot and Salesforce emails; Zero meetings, whose transcripts follow their meeting): a SOFT filter over which comms records (e.g. emails or meetings) the first sync imports — keep only external / rep-involved messages, dropping internal-only or irrelevant ones before they land. Applies only to the named comms streams; account/contact/deal records are untouched. Own domains stamped server-side. Omit to import comms unfiltered.", "properties": { "enabled": { "type": "boolean", "description": "Whether the filter is active." }, "streams": { "type": "array", "items": { "type": "string" }, "description": "Which comms streams to filter (e.g. [\"emails\"])." }, "require_external": { "type": "boolean", "description": "Keep only records with at least one external party." }, "require_participants": { "type": "array", "items": { "type": "string" }, "description": "Keep only records including at least one of these rep emails." }, "exclude_participants": { "type": "array", "items": { "type": "string" }, "description": "Always drop a record where one of these emails is a party." }, "exclude_domains": { "type": "array", "items": { "type": "string" }, "description": "Always drop a record with a party on one of these domains." }, "internal_domains": { "type": "array", "items": { "type": "string" }, "description": "Optional extra internal domains; the tenant own domains are merged in." }, "on_ambiguous": { "type": "string", "enum": [ "include", "exclude" ], "description": "Ambiguity resolution; \"include\" (default) keeps a record when it cannot be judged." } }, "additionalProperties": false } }, "required": [ "connector_type" ], "additionalProperties": false } } } } } }, "/api/platform/v1/connections/{id}": { "get": { "operationId": "connectionsGet", "summary": "Get Connection By Id", "description": "Fetch one established integration by its id, scoped to the caller's workspace, with its newest successful provider check (warnings such as a key that lacks a scope; checked_at gives its age). Read when opening a connection detail view, confirming a specific integration's configuration, or finding why part of its data does not sync. Returns the normalized record, or null when the id belongs to another tenant or does not exist - a not-found that never reveals existence.", "tags": [ "data" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "UUID of the connection to read.", "schema": { "type": "string", "description": "UUID of the connection to read." } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} } } } } }, "400": { "description": "Invalid input - failed schema validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - missing scope or role", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } }, "security": [ { "ApiKeyAuth": [ "connections:read" ] }, { "BearerAuth": [ "connections:read" ] } ], "x-scopes": [ "connections:read" ], "x-stability": "stable" }, "delete": { "operationId": "connectionsDisconnect", "summary": "Disconnect an Integration", "description": "Disconnect one established integration by its id, scoped to the workspace. Use when a user wants to stop an integration: the source (a CRM / calls / docs connector or a tracked X / LinkedIn account) is marked disconnected. Retains the row for re-connect; a non-existent or cross-tenant id is a clean not-found that never reveals another workspace.", "tags": [ "data" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "UUID of the connection to disconnect.", "schema": { "type": "string", "description": "UUID of the connection to disconnect." } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} } } } } }, "400": { "description": "Invalid input - failed schema validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - missing scope or role", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } }, "security": [ { "ApiKeyAuth": [ "connections:delete" ] }, { "BearerAuth": [ "connections:delete" ] } ], "x-scopes": [ "connections:delete" ], "x-stability": "stable" }, "patch": { "operationId": "connectionsUpdate", "summary": "Update a Connection", "description": "Rename an established connection, or set/clear its owner - the workspace member a personal source (e.g. Gmail, Outlook) belongs to. Use when a user wants to relabel a connection to tell multiple instances apart, attribute a personal connection to a teammate, or clear that attribution. Owner applies to personal connectors only; returns the updated connection. A non-existent or cross-tenant id is a clean not-found.", "tags": [ "data" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "UUID of the connection to update.", "schema": { "type": "string", "description": "UUID of the connection to update." } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} } } } } }, "400": { "description": "Invalid input - failed schema validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - missing scope or role", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } }, "security": [ { "ApiKeyAuth": [ "connections:write" ] }, { "BearerAuth": [ "connections:write" ] } ], "x-scopes": [ "connections:write" ], "x-stability": "stable", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "New display label for this connection instance (trimmed; must be non-empty). Renames any connection so multiple instances of the same connector type can be told apart." }, "owner_user_id": { "type": [ "string", "null" ], "description": "The workspace member (auth user id) this personal connection belongs to. Pass null to clear the owner. Only valid for personal connectors (Gmail, Outlook)." } }, "additionalProperties": false } } } } } }, "/api/platform/v1/connections/{id}/status": { "get": { "operationId": "connectionsGetStatus", "summary": "Get Connection Sync State", "description": "Fetch the live sync state of one integration - its normalized health, the in-flight syncing flag, the last good sync time, and any last error - without pulling the whole record. Read when polling a connecting / syncing badge after a connect or refresh kicks off. Resolved across both stacks and scoped to the workspace; null when the id is not in the tenant.", "tags": [ "data" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "UUID of the connection to read the sync state for.", "schema": { "type": "string", "description": "UUID of the connection to read the sync state for." } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} } } } } }, "400": { "description": "Invalid input - failed schema validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - missing scope or role", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } }, "security": [ { "ApiKeyAuth": [ "connections:read" ] }, { "BearerAuth": [ "connections:read" ] } ], "x-scopes": [ "connections:read" ], "x-stability": "stable" } }, "/api/platform/v1/connections/{id}/runs": { "get": { "operationId": "connectionsListRuns", "summary": "List Connection Sync Runs", "description": "Read the recent sync-run history of one integration - each run's outcome, what triggered it, when it started and finished, how many streams ran or failed, the rows written, and a bucketed failure reason. Read when showing a connection activity log or diagnosing why data is not flowing. Scoped to the workspace; an id outside the tenant returns an empty list.", "tags": [ "data" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "UUID of the connection to list sync runs for.", "schema": { "type": "string", "description": "UUID of the connection to list sync runs for." } }, { "name": "limit", "in": "query", "required": false, "description": "Max runs to return, newest first (default 25, capped at 100).", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Max runs to return, newest first (default 25, capped at 100)." } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} } } } } }, "400": { "description": "Invalid input - failed schema validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - missing scope or role", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } }, "security": [ { "ApiKeyAuth": [ "connections:read" ] }, { "BearerAuth": [ "connections:read" ] } ], "x-scopes": [ "connections:read" ], "x-stability": "stable" } }, "/api/platform/v1/connections/{id}/summary": { "get": { "operationId": "connectionsGetSummary", "summary": "Get Connection Data Summary", "description": "Read a glanceable snapshot of one integration's own synced data - per-connector counts and totals (deals and pipeline value, meetings, messages, tickets), the most recent items, and a weekly activity sparkline - computed live from the raw tables its puller writes. Read when opening a connection detail to show what has actually flowed in, beyond status. Scoped to the workspace; null when the id is not in the tenant.", "tags": [ "data" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "UUID of the connection to summarize.", "schema": { "type": "string", "description": "UUID of the connection to summarize." } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} } } } } }, "400": { "description": "Invalid input - failed schema validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - missing scope or role", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } }, "security": [ { "ApiKeyAuth": [ "connections:read" ] }, { "BearerAuth": [ "connections:read" ] } ], "x-scopes": [ "connections:read" ], "x-stability": "stable" } }, "/api/platform/v1/connections/{id}/reconnect": { "post": { "operationId": "connectionsReconnect", "summary": "Reconnect an Integration", "description": "Restore a connection stuck in an error or needs-reauth state, in place on the existing data source so its sync history and id survive (no duplicate row). Use when a user clicks reconnect on a broken connection: an OAuth provider returns a fresh authorize URL to redirect through, an api_key connector takes a replacement key, and a tracked social handle simply re-triggers its sync. A non-existent or cross-tenant id is a clean not-found.", "tags": [ "data" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "UUID of the connection to reconnect.", "schema": { "type": "string", "description": "UUID of the connection to reconnect." } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} } } } } }, "400": { "description": "Invalid input - failed schema validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - missing scope or role", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } }, "security": [ { "ApiKeyAuth": [ "connections:write" ] }, { "BearerAuth": [ "connections:write" ] } ], "x-scopes": [ "connections:write" ], "x-stability": "stable", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "api_key": { "type": "string", "description": "For api_key connectors: the replacement API key / token to store (encrypted) on the existing source. Ignored for oauth and social-handle connectors.", "minLength": 1 }, "api_id": { "type": "string", "description": "For an api_key connector whose credential is a PAIR (today only Aircall): the non-secret id half, re-stored alongside the replacement token. Required when the catalog entry asks for it.", "minLength": 1 }, "return_to": { "type": "string", "description": "For oauth connectors: console URL to redirect back to after the re-handshake (first-party origins only)." } }, "additionalProperties": false } } } } } }, "/api/platform/v1/connections/{id}/call-filters": { "patch": { "operationId": "connectionsSetCallFilters", "summary": "Set Call Filters", "description": "Configure the pre-sync call filter on a supported calls connection (Fathom, Fireflies, Gong, Grain) so only external and rep-attended calls are ever ingested — non-qualifying transcripts are never fetched. Use when a compliance-sensitive workspace must keep such call content from reaching Amdahl. Stamps the tenant own domains, validates against what the connector can enforce, and starts sync once an enabled filter is saved. Workspace admin only.", "tags": [ "data" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "UUID of the calls connection to configure.", "schema": { "type": "string", "description": "UUID of the calls connection to configure." } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} } } } } }, "400": { "description": "Invalid input - failed schema validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - missing scope or role", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } }, "security": [ { "ApiKeyAuth": [ "connections:write" ] }, { "BearerAuth": [ "connections:write" ] } ], "x-scopes": [ "connections:write" ], "x-stability": "stable", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "config": { "type": "object", "description": "The call-filter config (inclusion polarity). Own domains are stamped server-side.", "properties": { "enabled": { "type": "boolean", "description": "Whether the filter is active. Only an enabled filter starts sync." }, "mode": { "type": "string", "enum": [ "strict" ], "description": "Fail-closed posture marker; only \"strict\"." }, "require_external": { "type": "boolean", "description": "Ingest only calls with at least one external attendee." }, "require_participants": { "type": "array", "items": { "type": "string" }, "description": "Ingest only calls including at least one of these participant emails." }, "exclude_participants": { "type": "array", "items": { "type": "string" }, "description": "NEVER ingest a call one of these emails attended or hosted (exclusion wins over the include rules)." }, "exclude_domains": { "type": "array", "items": { "type": "string" }, "description": "NEVER ingest a call with an attendee/host on one of these domains (suffix-aware; exclusion wins)." }, "internal_domains": { "type": "array", "items": { "type": "string" }, "description": "Optional extra internal domains; the tenant own domains are merged in." }, "bot_domains": { "type": "array", "items": { "type": "string" }, "description": "Meeting-bot email domains to disregard when computing the roster." }, "on_ambiguous": { "type": "string", "enum": [ "exclude" ], "description": "Ambiguity resolution; only \"exclude\" (fail-closed)." } }, "additionalProperties": false } }, "required": [ "config" ], "additionalProperties": false } } } } } }, "/api/platform/v1/connections/{id}/crm-recency": { "patch": { "operationId": "connectionsSetCrmRecency", "summary": "Set CRM Recency Window", "description": "Set how much CRM activity history (emails, meetings, calls, notes, tasks) a Salesforce / HubSpot / Pipedrive connection imports on first sync — a month window or all-history — while account, contact and deal records always land in full. Use when a workspace wants to bound (or widen) how far back CRM communications are pulled; editing it re-pulls only the affected activity streams.", "tags": [ "data" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "UUID of the CRM connection to configure.", "schema": { "type": "string", "description": "UUID of the CRM connection to configure." } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} } } } } }, "400": { "description": "Invalid input - failed schema validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - missing scope or role", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } }, "security": [ { "ApiKeyAuth": [ "connections:write" ] }, { "BearerAuth": [ "connections:write" ] } ], "x-scopes": [ "connections:write" ], "x-stability": "stable", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "config": { "type": "object", "description": "The recency window: window_months (1–120) OR all_history. Omit both for the 12-month default.", "properties": { "window_months": { "type": "integer", "minimum": 1, "maximum": 120, "description": "Import the last N months of CRM activity/comms." }, "all_history": { "type": "boolean", "description": "Import ALL activity history (unbounded). Mutually exclusive with window_months." } }, "additionalProperties": false } }, "required": [ "config" ], "additionalProperties": false } } } } } }, "/api/platform/v1/connections/{id}/comms-filter": { "patch": { "operationId": "connectionsSetCommsFilter", "summary": "Set CRM Comms Filter", "description": "Filter which CRM activity records (today HubSpot and Salesforce emails, and Zero meetings with their transcripts) are imported to only external / rep-involved communications — internal-only or irrelevant messages are dropped before they land, while account, contact and deal records are untouched. Use when a workspace wants to keep internal or off-topic CRM comms out of Amdahl; it applies to new activity going forward (set it at connect to filter from the first sync).", "tags": [ "data" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "UUID of the CRM connection to configure.", "schema": { "type": "string", "description": "UUID of the CRM connection to configure." } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} } } } } }, "400": { "description": "Invalid input - failed schema validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - missing scope or role", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } }, "security": [ { "ApiKeyAuth": [ "connections:write" ] }, { "BearerAuth": [ "connections:write" ] } ], "x-scopes": [ "connections:write" ], "x-stability": "stable", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "config": { "type": "object", "description": "The comms filter: which streams + predicates. Own domains are stamped server-side.", "properties": { "enabled": { "type": "boolean", "description": "Whether the filter is active." }, "streams": { "type": "array", "items": { "type": "string" }, "description": "Which comms streams to filter (e.g. [\"emails\"])." }, "require_external": { "type": "boolean", "description": "Keep only records with at least one external party." }, "require_participants": { "type": "array", "items": { "type": "string" }, "description": "Keep only records including at least one of these rep emails." }, "exclude_participants": { "type": "array", "items": { "type": "string" }, "description": "Always drop a record where one of these emails is a party." }, "exclude_domains": { "type": "array", "items": { "type": "string" }, "description": "Always drop a record with a party on one of these domains." }, "internal_domains": { "type": "array", "items": { "type": "string" }, "description": "Optional extra internal domains; the tenant own domains are merged in." }, "on_ambiguous": { "type": "string", "enum": [ "include", "exclude" ], "description": "Ambiguity resolution; \"include\" (default) keeps a record when it cannot be judged." } }, "additionalProperties": false } }, "required": [ "config" ], "additionalProperties": false } } } } } }, "/api/platform/v1/chat": { "post": { "operationId": "chatStart", "summary": "Chat", "description": "Ask the workspace anything: opens or continues a named Chat and enqueues one Master agent turn. Use when starting an investigation over company data and connected sources. Always returns handles immediately (chat_id, run_id, stream/read/resume URLs) - subscribe to stream_url or poll read_url with wait_ms for the answer; never blocks.", "tags": [ "conversations" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} } } } } }, "400": { "description": "Invalid input - failed schema validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - missing scope or role", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } }, "security": [ { "ApiKeyAuth": [ "conversations:write" ] }, { "BearerAuth": [ "conversations:write" ] } ], "x-scopes": [ "conversations:write" ], "x-stability": "stable", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "input": { "type": "string", "minLength": 1, "maxLength": 32000, "description": "The ask, in plain language. Becomes the Master turn user message." }, "chat_id": { "type": "string", "format": "uuid", "description": "Continue an existing Chat. Omit to open a new one." }, "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Name for a NEW Chat. Omitted: auto-titled from the input." }, "agent": { "type": "string", "maxLength": 200, "description": "Optional agent pin: an Amdahl library slug/uuid or workspace agent id/slug the Master turn runs as (Master privileges; the agent prompt is the specialization)." }, "config": { "type": "object", "properties": { "depth": { "type": "string", "enum": [ "quick", "standard", "deep" ] }, "actions_allowed": { "type": "array", "items": { "type": "string" }, "maxItems": 20, "description": "Outbound actions this run may invoke. Absent = ALL cataloged actions (default ON); pass a list to narrow, [] to disable." }, "on_question": { "type": "string", "enum": [ "pause", "auto", "none" ], "description": "ask_a_human behavior: pause (interactive), auto (default), none (headless)." }, "external_search": { "type": "boolean", "description": "Allow market fan-outs (external_search.execute stays in the kit). Default false; deep depth forces true." }, "include_divergence": { "type": "boolean", "description": "Fuse the divergence map on external_search.execute (else mode:evidence). Default false; deep depth forces true." } }, "additionalProperties": false, "description": "The only knobs. No model, temperature, or stream fields exist." } }, "required": [ "input" ], "additionalProperties": false } } } } } }, "/api/platform/v1/chats": { "get": { "operationId": "chatList", "summary": "List Chats", "description": "List Chats for this workspace, newest activity first. Read when picking a Chat to continue, rendering a recents rail, or reviewing what one agent has been doing. Each entry is a lean snapshot (name, status, turn count, last activity, and how it was triggered); scope by agent_ref, filter by status, page via limit and offset.", "tags": [ "conversations" ], "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "active", "archived" ] } }, { "name": "agent_ref", "in": "query", "required": false, "description": "Keep only Chats this agent drove (slug or uuid — both forms of the same agent match).", "schema": { "type": "string", "description": "Keep only Chats this agent drove (slug or uuid — both forms of the same agent match)." } }, { "name": "routine_id", "in": "query", "required": false, "description": "Keep only Chats this routine fired.", "schema": { "type": "string", "description": "Keep only Chats this routine fired." } }, { "name": "subscription_id", "in": "query", "required": false, "description": "Keep only Chats this subscription fired.", "schema": { "type": "string", "description": "Keep only Chats this subscription fired." } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} } } } } }, "400": { "description": "Invalid input - failed schema validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - missing scope or role", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } }, "security": [ { "ApiKeyAuth": [ "conversations:read" ] }, { "BearerAuth": [ "conversations:read" ] } ], "x-scopes": [ "conversations:read" ], "x-stability": "stable" } }, "/api/platform/v1/chats/{id}": { "get": { "operationId": "chatGet", "summary": "Get Chat", "description": "Fetch one Chat snapshot: name, status, its runs (with read handles), which runs are still in flight, and any pending human asks with their resume URLs. Read when rendering a Chat view, deciding whether to continue it, or surfacing an awaiting question to the human. Returns null for unknown or cross-workspace ids.", "tags": [ "conversations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} } } } } }, "400": { "description": "Invalid input - failed schema validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - missing scope or role", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } }, "security": [ { "ApiKeyAuth": [ "conversations:read" ] }, { "BearerAuth": [ "conversations:read" ] } ], "x-scopes": [ "conversations:read" ], "x-stability": "stable" }, "patch": { "operationId": "chatRename", "summary": "Rename Chat", "description": "Rename one Chat so the thread is findable later. Use when a chat was auto-titled from its first ask and deserves a human name, or when its focus shifted. Renames the underlying conversation title in place; runs, substrate, and handles are untouched. Returns the updated chat snapshot.", "tags": [ "conversations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Chat UUID.", "schema": { "type": "string", "format": "uuid", "description": "Chat UUID." } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} } } } } }, "400": { "description": "Invalid input - failed schema validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - missing scope or role", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } }, "security": [ { "ApiKeyAuth": [ "conversations:write" ] }, { "BearerAuth": [ "conversations:write" ] } ], "x-scopes": [ "conversations:write" ], "x-stability": "stable", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The new chat name." } }, "required": [ "name" ], "additionalProperties": false } } } } } }, "/api/platform/v1/chats/{id}/runs/{run_id}": { "get": { "operationId": "chatGetRun", "summary": "Get Chat Run", "description": "Read one Chat run snapshot: status, pause payload when awaiting input, the answer envelope (answer_text plus the ordered content_blocks with query and snapshot data), answered asks, and usage. Read when polling a started Chat for its result; pass wait_ms (max 45000) to long-poll until the run settles instead of tight-looping. Pass include=events to also get the persisted activity trace for transcript replay.", "tags": [ "conversations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Chat (conversation) UUID.", "schema": { "type": "string", "description": "Chat (conversation) UUID." } }, { "name": "run_id", "in": "path", "required": true, "description": "Run (turn) UUID from the START response.", "schema": { "type": "string", "description": "Run (turn) UUID from the START response." } }, { "name": "wait_ms", "in": "query", "required": false, "description": "Optional long-poll budget in ms; hard-capped at 45000.", "schema": { "type": "integer", "description": "Optional long-poll budget in ms; hard-capped at 45000." } }, { "name": "include", "in": "query", "required": false, "description": "Optional: 'events' includes the persisted activity trace (parent + sub-agent tool calls, capped) so a reloaded transcript can replay what the run did.", "schema": { "type": "string", "description": "Optional: 'events' includes the persisted activity trace (parent + sub-agent tool calls, capped) so a reloaded transcript can replay what the run did." } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} } } } } }, "400": { "description": "Invalid input - failed schema validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - missing scope or role", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } }, "security": [ { "ApiKeyAuth": [ "conversations:read" ] }, { "BearerAuth": [ "conversations:read" ] } ], "x-scopes": [ "conversations:read" ], "x-stability": "stable" } }, "/api/platform/v1/chat/preferences": { "get": { "operationId": "chatGetPreferences", "summary": "Get Chat Preferences", "description": "Fetch the calling user's saved Chat settings for this workspace: their default run-config knobs (depth, on_question, external_search, include_divergence, actions_allowed) and their agent block list. Read when opening the Chat settings surface to seed its controls. Returns defaults when nothing is saved yet.", "tags": [ "conversations" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} } } } } }, "400": { "description": "Invalid input - failed schema validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - missing scope or role", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } }, "security": [ { "ApiKeyAuth": [ "conversations:read" ] }, { "BearerAuth": [ "conversations:read" ] } ], "x-scopes": [ "conversations:read" ], "x-stability": "stable" }, "patch": { "operationId": "chatUpdatePreferences", "summary": "Update Chat Preferences", "description": "Save the calling user's Chat settings for this workspace: their default run-config knobs and/or their agent block list (the agents the Master may not delegate to). Use when the user changes a control in the Chat settings surface. A top-level PATCH — only the keys you send change; the block list applies to new Chat turns server-side.", "tags": [ "conversations" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} } } } } }, "400": { "description": "Invalid input - failed schema validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - missing scope or role", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } }, "security": [ { "ApiKeyAuth": [ "conversations:write" ] }, { "BearerAuth": [ "conversations:write" ] } ], "x-scopes": [ "conversations:write" ], "x-stability": "stable", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "run_config": { "type": "object", "properties": { "depth": { "type": "string", "enum": [ "quick", "standard", "deep" ] }, "actions_allowed": { "type": "array", "items": { "type": "string" }, "maxItems": 20 }, "on_question": { "type": "string", "enum": [ "pause", "auto", "none" ] }, "external_search": { "type": "boolean" }, "include_divergence": { "type": "boolean" } }, "additionalProperties": false, "description": "Default Chat run knobs. Replaces the stored run_config wholesale when sent." }, "blocked_agents": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "maxItems": 200, "description": "Agent slugs / refs the Master may NOT delegate to for this user. Empty = every agent usable." } }, "additionalProperties": false } } } } } }, "/api/platform/v1/search/query": { "post": { "operationId": "searchQuery", "summary": "Routed Warehouse Search", "description": "One routed door over tenant warehouse data: each ask lands on typed filters, NL-to-SQL, vector similarity, or a research handoff for a statistical ask (route), which may start a job. Use when you hold a plain question OR typed predicates and want the cheapest lane picked automatically (force via mode/route). Returns the lane, rows, compiled SQL and retry_guidance. research_id polls a started job (needs conversations:read). Lanes read different stores at different grains — read corpus.", "tags": [ "data" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "success": { "type": "boolean" }, "mode_ran": { "type": "string" }, "results": { "type": "array" }, "compiled": { "type": "object" }, "freshness": { "type": "object" }, "corpus": { "type": "object" }, "timing": { "type": "object" }, "cached": { "type": "boolean" }, "detail": { "type": "object" }, "job": { "type": "object" }, "notes": { "type": "array", "items": { "type": "string" } }, "limit_clamped": { "type": "object" }, "rerouted_from": { "type": "string" }, "setup_needed": { "type": "object", "description": "Present only when this workspace has no connected data source, so there is nothing to read. reason is no_sources_connected; message says so in plain words for the user; connect_url is the Connections page in the console. Give the user the message and the link. Absent when a source is connected.", "properties": { "reason": { "type": "string", "enum": [ "no_sources_connected" ] }, "message": { "type": "string" }, "connect_url": { "type": "string" } }, "required": [ "reason", "message", "connect_url" ], "additionalProperties": false }, "data_freshness": { "type": "object", "description": "Present on an empty answer (no rows, or one aggregate row of zeros): one plain line (message) with the date of the newest conversation in the workspace data and the time of the last sync, so an answer that is empty because the data has not arrived yet reads differently from one with no match. latest_conversation_at and last_synced_at are the ISO-8601 instants behind it, null when unknown. Absent when rows came back, and where the age of the conversation data cannot explain the empty answer: an as_of read, a read of deals or deal_qualification, and a read the data scope emptied.", "properties": { "message": { "type": "string" }, "latest_conversation_at": { "type": [ "string", "null" ] }, "last_synced_at": { "type": [ "string", "null" ] } }, "required": [ "message" ], "additionalProperties": false }, "research": { "type": "object" }, "statistical_gap": { "type": "object" }, "research_route": { "type": "object" }, "error": { "type": "object" } }, "required": [ "success" ], "additionalProperties": false } }, "required": [ "data" ] } } } }, "400": { "description": "Invalid input - failed schema validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - missing scope or role", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } }, "security": [ { "ApiKeyAuth": [ "data:read" ] }, { "BearerAuth": [ "data:read" ] } ], "x-scopes": [ "data:read" ], "x-stability": "beta", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "maxLength": 2000, "description": "Free-text ask. Meaning-shaped wording (\"what do customers say about…\") routes to the semantic lane; other questions route to the NL-to-SQL fuzzy lane." }, "max_subqueries": { "type": "integer", "minimum": 1, "maximum": 12, "description": "How many independent sub-questions a multi-part ask may fan out into. Default 3; up to 5 synchronously and 12 with async:true. RAISE THIS when a reply comes back with retry_guidance.action = \"raise_max_subqueries\" — it means parts of your question were cut by this cap, and retry_guidance.suggested_params carries the value to use." }, "async": { "type": "boolean", "description": "Run as a background job instead of blocking. Returns {job:{job_id,status}} straight away; collect it by calling this verb again with that job_id and no query. USE THIS when a reply comes back with retry_guidance.action = \"run_async\" — the synchronous path is bounded at ~15s and your ask needs longer, and the async path also allows a higher max_subqueries. Fuzzy lane only; others name it in corpus.ignored_params." }, "job_id": { "type": "string", "description": "Collect a job started with async:true. Send this ALONE (no query). While status is \"queued\"/\"running\", poll again; on \"complete\" the full envelope is on detail." }, "research_id": { "type": "string", "format": "uuid", "description": "Poll a research job started by route or research.start/start_research. Send this ALONE (no query). Returns the same status/answer/partials as research.get: running, needs_input, complete, failed or canceled, the cited answer once complete, and partial_findings on a failure. Needs conversations:read (not just data:read)." }, "mode": { "type": "string", "enum": [ "auto", "filter", "fuzzy", "semantic" ], "description": "Lane override. Default auto: filters-with-no-query → filter; meaning-shaped query → semantic; else fuzzy. Lanes read DIFFERENT stores at different grains — read `corpus` on the response to see which one answered." }, "route": { "type": "string", "enum": [ "auto", "search", "research" ], "description": "Statistical/outcome routing (workspace opt-in). auto (default): hand off to a research job when the ask reads as a phrase-to-outcome or significance question (\"which phrase predicts a win\", \"is this lift significant\") — no search lane can join a phrase to an outcome in one call. research: force the handoff. search: stay on a search lane regardless. On a workspace without routing enabled this has no effect, and a statistical ask that stays in search gets statistical_gap on the response instead of a silent drop. A handoff (and route:\"auto\"'s one-hop escalation, which fires only when that gap is itself statistical_gap — an ordinary empty or narrow result never escalates) returns {research:{research_id,chat_id,status,poll}}; poll with research_id for the full answer. Same on MCP: search_customers may start the job too." }, "surface": { "type": "string", "enum": [ "interactions", "deals", "deal_qualification" ], "description": "Warehouse surface for the filter lane. Default interactions. Ignored by the fuzzy and semantic lanes, which report it back in corpus.ignored_params when you pass it." }, "audience": { "type": "string", "enum": [ "all", "customer_voice" ], "description": "Who counts as the voice you want. Default \"all\". Use \"customer_voice\" to keep only genuine customer / prospect speech and drop investor, advisor, media, partner, vendor and competitor chatter that merely shares an account record — while STILL keeping a real buyer on such an account (someone on a live opportunity, or a scored champion / economic buyer). This applies the platform's own canonical rule server-side; it is a disjunction you cannot express with `filters`, which are ANDed. interactions only. Applied on the filter lane, and on the semantic lane with hydrate (turned on for you unless you send hydrate:false). A request that would land on the fuzzy lane, which writes its own SQL, is rerouted to semantic with hydrate and says so in rerouted_from and notes. Refused on the lexical lane, which matches exact terms." }, "hydrate": { "type": "boolean", "description": "Semantic lane only. Semantic matches carry a truncated preview and no labels, so they cannot be quoted or attributed. Set true to bridge each match back to its full warehouse row — full `content` plus company, speaker title, pushback and buyer-signal columns. One row per match, containing the matched utterance, so a hit is citable. SPEAKER comes from the ATOMIC utterance that matched, not from the turn stamp: read speaker_attribution on each row. \"utterance\" = verified from the atomic source. \"ambiguous\" = two matched utterances share this row and disagree on speaker, so the speaker fields are NULL and nobody is named — check turn_speakers for who is in play. \"turn\" = the atomic source had no row, so the fields are the turn's FIRST member and are NOT verified. Separately, speaker_ambiguous says the row's TEXT spans more than one speaker (13.58% of turns on the tenant measured 2026-08-15) — a row can be cleanly attributed AND span two voices, so quoting the whole content as one person is still wrong there. Both fields ship on every turn-grain row including the clean ones; corpus.speaker_ambiguous_rows / corpus.speaker_unattributable_rows are the rates. speaker_ambiguous_source says where that verdict came from: \"stamped\" = read from the column the pipeline writes on the turn itself, \"overlay\" = reconstructed at read time because the pipeline recorded none for that turn. A missing record is NOT \"one speaker\" — permanently-excluded interactions never get one — so an unrecorded turn falls back rather than being reported unambiguous, and a \"stamped\" row also carries speaker_count. corpus.speaker_stamped_rows / corpus.speaker_fallback_rows are the split. Stakeholder columns (role_level, is_champion, is_economic_buyer, champion_score, inferred_persona) are derived from the turn stamp, so they are NULLED when the row is re-attributed to a different speaker rather than left describing someone else. Slower — two reads. Check corpus.hydrated_grain: \"turn\" is that row-per-match answer; \"call\" means the turn lookup failed and the rows are arbitrary turns from the right conversations (context, not the matches; also flagged corpus.degraded). Matches whose utterance belongs to no turn have no warehouse row and are counted in corpus.unresolved_matches; matches sharing one turn are corpus.collapsed_matches. Read those two directly rather than inferring a gap from a match_count/row_count delta — corpus.match_count is how many nearest neighbours the lane pulled and is BOUNDED BY limit, not a count of how many things genuinely matched. Caps at 200 distinct ids, reported as corpus.truncated." }, "coverage": { "type": "boolean", "description": "Opt into gap detection on corpus.coverage. Every response ALREADY carries corpus.coverage with max_timestamp / min_timestamp and an age histogram, computed free from the rows returned. This flag adds `gaps`: windows where the corpus HELD rows and this result set had none — the \"your evidence has a hole in it\" signal, as opposed to the ordinary quiet periods a plain empty-bucket scan would flag. Costs one extra bucketed read, so it is off by default. Read coverage.basis first: \"matched_set\" means the numbers describe your whole match set, \"returned_rows\" means they describe a truncated slice, and \"unavailable\" means coverage could not be measured — never read that as zero." }, "filters": { "type": "array", "maxItems": 32, "items": { "type": "object", "properties": { "field": { "type": "string", "description": "A field from search_field://list." }, "op": { "type": "string", "enum": [ "eq", "neq", "in", "not_in", "contains", "gt", "gte", "lt", "lte", "between", "is_null", "not_null" ] }, "value": { "description": "Scalar for eq/neq/gt/gte/lt/lte/contains; array for in/not_in; [low, high] for between; omitted for is_null/not_null." } }, "required": [ "field", "op" ], "additionalProperties": false }, "description": "Typed predicates (ANDed — there is no OR; for the customer-voice disjunction use `audience`). Semantic mode supports only company_id / occurred_at / speaker_type, and cannot apply any of them on its theme-index fallback — check corpus.filters_applied. The filter lane supports every field the catalog advertises." }, "order_by": { "type": "object", "properties": { "field": { "type": "string" }, "dir": { "type": "string", "enum": [ "asc", "desc" ] } }, "required": [ "field", "dir" ], "additionalProperties": false, "description": "Filter lane: order by a vocabulary field or a metric alias (e.g. \"count\")." }, "limit": { "type": "integer", "minimum": 1, "description": "Row / match cap; max 1000. A larger value is clamped to 1000 rather than refused, and the response reports it on limit_clamped and in notes. Default is lane-dependent: 100 on the filter and semantic lanes, 50 on the fuzzy lane (where an unforced plain-language question usually lands), so pass it explicitly when the row count matters." }, "group_by": { "type": "array", "items": { "type": "string" }, "maxItems": 8, "description": "Filter lane: group fields (requires at least one metric)." }, "metrics": { "type": "array", "maxItems": 8, "items": { "type": "object", "properties": { "fn": { "type": "string", "enum": [ "count", "count_distinct", "sum", "avg", "min", "max" ] }, "field": { "type": "string", "description": "Required for every fn except count." } }, "required": [ "fn" ], "additionalProperties": false }, "description": "Filter lane: aggregations (sum/avg need a numeric field)." } }, "additionalProperties": false } } } } } }, "/api/platform/v1/search/fields": { "get": { "operationId": "searchFields", "summary": "Search Filter Fields", "description": "Read when composing typed predicates for the routed search verb: the per-surface field catalog (interactions, deals, deal_qualification) listing each field with its type, description, and the comparison operators it admits. Derived live from the warehouse schema catalog - exactly what the filter compiler validates against, so it can never drift from the accepted vocabulary.", "tags": [ "data" ], "parameters": [ { "name": "surface", "in": "query", "required": false, "description": "List only this surface. Omit for every surface.", "schema": { "type": "string", "enum": [ "interactions", "deals", "deal_qualification" ], "description": "List only this surface. Omit for every surface." } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} } } } } }, "400": { "description": "Invalid input - failed schema validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - missing scope or role", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } }, "security": [ { "ApiKeyAuth": [ "data:read" ] }, { "BearerAuth": [ "data:read" ] } ], "x-scopes": [ "data:read" ], "x-stability": "beta" } }, "/api/platform/v1/search/overview": { "get": { "operationId": "searchOverview", "summary": "Workspace Data Overview", "description": "Read when orienting on what a workspace holds before composing a search: live row counts and time spans for each queryable warehouse surface (conversations, CRM deals, per-company deal qualification), computed through the governed query gate. A surface whose read fails reports null rather than zero, so an outage is never mistaken for an empty corpus.", "tags": [ "data" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} } } } } }, "400": { "description": "Invalid input - failed schema validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - missing scope or role", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } }, "security": [ { "ApiKeyAuth": [ "data:read" ] }, { "BearerAuth": [ "data:read" ] } ], "x-scopes": [ "data:read" ], "x-stability": "beta" } }, "/api/platform/v1/messages/optimize": { "post": { "operationId": "messagesOptimize", "summary": "Optimize Outbound Message", "description": "Write one outbound email or LinkedIn message in the sender's own voice from context (facts, rules, voice_examples) and return it with a line on what changed. Use when an outbound message needs writing or improving before it is sent. message (a draft) is optional; sent with facts or rules, it is the base. What the input cannot back is left out and listed in omitted (on_missing_input ask returns questions instead). evidence: \"workspace\" grades against synced conversations (slower). Sends nothing.", "tags": [ "assets" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} } } } } }, "400": { "description": "Invalid input - failed schema validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - missing scope or role", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } }, "security": [ { "ApiKeyAuth": [ "messages:execute" ] }, { "BearerAuth": [ "messages:execute" ] } ], "x-scopes": [ "messages:execute" ], "x-stability": "experimental", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "context": { "type": "object", "description": "What the message is written FROM, and the quality of the message follows the quality of this. facts are what the sender knows first-hand about the recipient: who they are, why write now, what is offered, the proof that may be cited. rules are what the message must and must not do, including the ask. voice_examples are the sender’s own messages, matched and never copied. keep_cta, max_words, banned_phrases and banned_punctuation are checked exactly. If all you have is the user’s own request, pass it as a fact rather than sending nothing. Blank entries are dropped and any other key is refused.", "properties": { "rules": { "type": "array", "items": { "type": "string" }, "description": "Hard constraints on the rewrite, such as \"no pricing\". They steer the rewrite and are not rewritten or quoted in the message. Up to 20, each up to 500 characters once trimmed." }, "voice_examples": { "type": "array", "items": { "type": "string" }, "description": "Messages the sender wrote themselves. The rewrite matches the sender's voice and does not copy their words. Up to 5, each up to 4000 characters once trimmed." }, "facts": { "type": "array", "items": { "type": "string" }, "description": "What you know first-hand about the recipient or situation that no call recording holds, one fact per entry, such as \"Met Priya at the GTM dinner on Sep 24; she said her SDRs rewrite every AI draft\". Graded as caller-supplied evidence (tier CALLER, not a customer quote): a claim a fact states is not marked fabricated, a claim that inflates one still is. Up to 10, each up to 1000 characters once trimmed." }, "keep_cta": { "type": "boolean", "description": "true to keep the draft's closing ask (its last sentence that asks for something) word for word. Checked exactly on every rewrite; the rewrite works on the rest of the message." }, "max_words": { "type": "integer", "minimum": 10, "maximum": 1000, "description": "The most words the returned message may have, checked exactly on every rewrite. 10 to 1000." }, "banned_phrases": { "type": "array", "items": { "type": "string" }, "description": "Words or phrases the rewrite leaves out, such as \"just\" or \"reaching out\", matched as whole words in any case and checked exactly on every rewrite. Up to 30, each up to 60 characters once trimmed." }, "banned_punctuation": { "type": "array", "items": { "type": "string", "enum": [ "colon", "semicolon", "exclamation" ] }, "description": "Punctuation the rewrite leaves out: any of colon, semicolon, exclamation. Checked exactly on every rewrite; a colon in a time like 2:30pm or in a link does not count." } }, "additionalProperties": false }, "message": { "type": "string", "description": "Optional. A draft, verbatim. Sent with context.facts, context.rules or a recipient, it is the starting point of the message. It is the sender's own word, so what it states may be stated, and its substance, order, layout and voice are kept. Facts add to it and rules shape it. A rule that needs a fact neither the draft nor a fact gives is listed in omitted, or asked as a question with on_missing_input ask. A draft sent with no facts, no rules and no recipient is improved instead, with a draft_improved_no_context note. Put what you know in context.", "maxLength": 10000 }, "mode": { "type": "string", "enum": [ "improve", "grade" ], "default": "improve", "description": "improve (the default) writes or rewrites the message. grade grades the draft in message with Amdahl's independent judge and writes nothing: the result has no message, only grade (five rubric lines, a 1-5 score with passed and total beside it) and disclosures. grade needs message, and is billed as a grade. The grade measures the message against your evidence and this rubric; it does not predict replies." }, "grade_nonce": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9_.:-]{1,64}$", "description": "Only with mode grade. A grade of the same request returns the same stored grading; a different grade_nonce (1-64 of A-Z a-z 0-9 _ . : -) makes the request distinct, so the same text is graded fresh. No judge sees it. Used to measure how far the judge moves on a repeat." }, "channel": { "type": "string", "enum": [ "email", "linkedin" ], "description": "Where the message will be sent. Send it: with no draft there is nothing to infer it from, and the channel sets the length and format the message is written and judged against. linkedin means a connection note, which carries no sign-off." }, "on_unsupported": { "type": "string", "enum": [ "flag", "remove" ], "description": "What to do with a claim in the draft that nothing in the workspace conversations backs. \"flag\" (the default) keeps it and lists it in unsupported_claims; \"remove\" lets the rewrite soften or cut it. Only checked when the workspace has connected conversations." }, "evidence": { "type": "string", "enum": [ "workspace", "off" ], "default": "off", "description": "Optional, default off. workspace grades the draft against what this workspace's customers said in its synced conversations (positioning, grounding, specifics, differentiation), which is slower; off is a fast style pass. Where no conversations can be read the run is graded as off and evidence.reason says why." }, "on_missing_input": { "type": "string", "enum": [ "best_effort", "ask" ], "default": "best_effort", "description": "What to do when the input cannot back everything the message should say. \"best_effort\" (the default) writes the best message the input supports and lists what it could not do in omitted, each with why; nothing is invented. \"ask\" writes nothing it would have to guess and returns outcome needs_input with ask, the questions only the sender can answer." }, "include_tries": { "type": "boolean", "default": false, "description": "Optional, default false. When true, the result also carries `tries`: every version the run scored or checked, the draft first, each with its text, the optimizer's own score and human_tone (1 to 5), the dimensions it aimed at, and which one was returned. It shows how the draft progressed. Those scores come from the judge the rewrites were optimized against, so `lift`, not them, is the before-and-after. A version written from context is checked, not scored: its score can be null, and `checks_open` counts the checks it still fails." }, "recipient": { "type": "object", "description": "Who the message is for. Send email, name and company when known: Amdahl finds the person in the workspace's CRM and calls by email, else by name and company, and reads the role from the title the CRM or the calls hold (from attributes.title only where the workspace has live intake on). linkedin_url is kept as a fact but finds no one. Takes any of email (up to 320 characters), name and company (up to 200 each), domain (up to 253), linkedin_url (up to 300) and attributes. attributes is a flat map of text, number, true/false or null values, such as a whole Clay or CSV row: up to 100 keys of 100 characters, each text value up to 1000 characters. Any other key is refused, and so is an attribute key that names a business, user, tenant or workspace id.", "properties": { "email": { "type": "string", "maxLength": 320 }, "name": { "type": "string", "maxLength": 200 }, "company": { "type": "string", "maxLength": 200 }, "domain": { "type": "string", "maxLength": 253 }, "linkedin_url": { "type": "string", "maxLength": 300 }, "attributes": { "type": "object", "maxProperties": 100, "additionalProperties": { "type": [ "string", "number", "boolean", "null" ], "maxLength": 1000 } } }, "additionalProperties": false }, "recipient_notes": { "type": "string", "maxLength": 10000, "description": "Free text about the recipient, such as your own research or a pasted CRM note. Up to 10000 characters." }, "message_type": { "type": "string", "enum": [ "cold", "re-engage", "follow-up", "deal" ], "description": "The kind of message: cold, re-engage, follow-up, deal. follow-up is a reply in a thread that is in progress." }, "content_spec": { "type": "object", "description": "Beta, per workspace: ignored, and listed in ignored_params, unless the workspace has quality v2 on. What is being written, as fields: channel, format (message, connection_note, inmail, post, recap), stage (cold, engaged, active_deal, customer, closed_lost), sequence (step from 1 to 100, prior_touches, days_since_last_touch), objective (reply, meeting, intro, re_engage, next_step, awareness), audience (persona, industry, firmographic_segment, for writing to a segment with no recipient), campaign_id and planned_send_at (ISO-8601 UTC). Every field is optional: a field not sent comes from message_type, channel, the recipient or a default. The result names the message type in message_type, with where each field came from in message_type.derived. Any other key is refused.", "properties": { "channel": { "type": "string", "enum": [ "email", "linkedin" ] }, "format": { "type": "string", "enum": [ "message", "connection_note", "inmail", "post", "recap" ] }, "stage": { "type": "string", "enum": [ "cold", "engaged", "active_deal", "customer", "closed_lost" ] }, "sequence": { "type": "object", "properties": { "step": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 }, "prior_touches": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 99 }, "days_since_last_touch": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 3650 } }, "additionalProperties": false }, "objective": { "type": "string", "enum": [ "reply", "meeting", "intro", "re_engage", "next_step", "awareness" ] }, "audience": { "type": [ "object", "null" ], "properties": { "persona": { "type": [ "string", "null" ], "maxLength": 200 }, "industry": { "type": [ "string", "null" ], "maxLength": 200 }, "firmographic_segment": { "type": [ "string", "null" ], "maxLength": 200 } }, "additionalProperties": false }, "campaign_id": { "type": [ "string", "null" ], "maxLength": 200 }, "planned_send_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": false } }, "additionalProperties": false } } } } } }, "/api/platform/v1/messages/optimize/batch": { "post": { "operationId": "messagesOptimizeBatch", "summary": "Optimize Outbound Messages In A Batch", "description": "Queue many outbound drafts for the optimizer in one request and get a batch_id back at once. Use when a campaign has more drafts than the per-workspace limits on single optimizes allow, or nobody is waiting on each result. Items run later on spare capacity, behind interactive calls, and are never refused as busy. Poll the batch for counts, an estimated finish time and each result. Only items that succeed count as usage.", "tags": [ "assets" ], "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} } } } } }, "400": { "description": "Invalid input - failed schema validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - missing scope or role", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } }, "security": [ { "ApiKeyAuth": [ "messages:execute" ] }, { "BearerAuth": [ "messages:execute" ] } ], "x-scopes": [ "messages:execute" ], "x-stability": "experimental", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "minItems": 1, "maxItems": 500, "description": "The drafts, up to 500. Each is the body of one single optimize, with every field it takes and the same rules (context, message, channel, evidence, on_unsupported, on_missing_input, include_tries and the recipient, recipient_notes and message_type), plus an optional item_id of your own. Results come back in this order.", "items": { "type": "object", "properties": { "item_id": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Your own id for this draft, returned with its result. Unique within the batch." }, "context": { "type": "object", "description": "What the message is written FROM, and the quality of the message follows the quality of this. facts are what the sender knows first-hand about the recipient: who they are, why write now, what is offered, the proof that may be cited. rules are what the message must and must not do, including the ask. voice_examples are the sender’s own messages, matched and never copied. keep_cta, max_words, banned_phrases and banned_punctuation are checked exactly. If all you have is the user’s own request, pass it as a fact rather than sending nothing. Blank entries are dropped and any other key is refused.", "properties": { "rules": { "type": "array", "items": { "type": "string" }, "description": "Hard constraints on the rewrite, such as \"no pricing\". They steer the rewrite and are not rewritten or quoted in the message. Up to 20, each up to 500 characters once trimmed." }, "voice_examples": { "type": "array", "items": { "type": "string" }, "description": "Messages the sender wrote themselves. The rewrite matches the sender's voice and does not copy their words. Up to 5, each up to 4000 characters once trimmed." }, "facts": { "type": "array", "items": { "type": "string" }, "description": "What you know first-hand about the recipient or situation that no call recording holds, one fact per entry, such as \"Met Priya at the GTM dinner on Sep 24; she said her SDRs rewrite every AI draft\". Graded as caller-supplied evidence (tier CALLER, not a customer quote): a claim a fact states is not marked fabricated, a claim that inflates one still is. Up to 10, each up to 1000 characters once trimmed." }, "keep_cta": { "type": "boolean", "description": "true to keep the draft's closing ask (its last sentence that asks for something) word for word. Checked exactly on every rewrite; the rewrite works on the rest of the message." }, "max_words": { "type": "integer", "minimum": 10, "maximum": 1000, "description": "The most words the returned message may have, checked exactly on every rewrite. 10 to 1000." }, "banned_phrases": { "type": "array", "items": { "type": "string" }, "description": "Words or phrases the rewrite leaves out, such as \"just\" or \"reaching out\", matched as whole words in any case and checked exactly on every rewrite. Up to 30, each up to 60 characters once trimmed." }, "banned_punctuation": { "type": "array", "items": { "type": "string", "enum": [ "colon", "semicolon", "exclamation" ] }, "description": "Punctuation the rewrite leaves out: any of colon, semicolon, exclamation. Checked exactly on every rewrite; a colon in a time like 2:30pm or in a link does not count." } }, "additionalProperties": false }, "message": { "type": "string", "description": "Optional. A draft, verbatim. Sent with context.facts, context.rules or a recipient, it is the starting point of the message. It is the sender's own word, so what it states may be stated, and its substance, order, layout and voice are kept. Facts add to it and rules shape it. A rule that needs a fact neither the draft nor a fact gives is listed in omitted, or asked as a question with on_missing_input ask. A draft sent with no facts, no rules and no recipient is improved instead, with a draft_improved_no_context note. Put what you know in context.", "maxLength": 10000 }, "mode": { "type": "string", "enum": [ "improve", "grade" ], "default": "improve", "description": "improve (the default) writes or rewrites the message. grade grades the draft in message with Amdahl's independent judge and writes nothing: the result has no message, only grade (five rubric lines, a 1-5 score with passed and total beside it) and disclosures. grade needs message, and is billed as a grade. The grade measures the message against your evidence and this rubric; it does not predict replies." }, "grade_nonce": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9_.:-]{1,64}$", "description": "Only with mode grade. A grade of the same request returns the same stored grading; a different grade_nonce (1-64 of A-Z a-z 0-9 _ . : -) makes the request distinct, so the same text is graded fresh. No judge sees it. Used to measure how far the judge moves on a repeat." }, "channel": { "type": "string", "enum": [ "email", "linkedin" ], "description": "Where the message will be sent. Send it: with no draft there is nothing to infer it from, and the channel sets the length and format the message is written and judged against. linkedin means a connection note, which carries no sign-off." }, "on_unsupported": { "type": "string", "enum": [ "flag", "remove" ], "description": "What to do with a claim in the draft that nothing in the workspace conversations backs. \"flag\" (the default) keeps it and lists it in unsupported_claims; \"remove\" lets the rewrite soften or cut it. Only checked when the workspace has connected conversations." }, "evidence": { "type": "string", "enum": [ "workspace", "off" ], "default": "off", "description": "Optional, default off. workspace grades the draft against what this workspace's customers said in its synced conversations (positioning, grounding, specifics, differentiation), which is slower; off is a fast style pass. Where no conversations can be read the run is graded as off and evidence.reason says why." }, "on_missing_input": { "type": "string", "enum": [ "best_effort", "ask" ], "default": "best_effort", "description": "What to do when the input cannot back everything the message should say. \"best_effort\" (the default) writes the best message the input supports and lists what it could not do in omitted, each with why; nothing is invented. \"ask\" writes nothing it would have to guess and returns outcome needs_input with ask, the questions only the sender can answer." }, "include_tries": { "type": "boolean", "default": false, "description": "Optional, default false. When true, the result also carries `tries`: every version the run scored or checked, the draft first, each with its text, the optimizer's own score and human_tone (1 to 5), the dimensions it aimed at, and which one was returned. It shows how the draft progressed. Those scores come from the judge the rewrites were optimized against, so `lift`, not them, is the before-and-after. A version written from context is checked, not scored: its score can be null, and `checks_open` counts the checks it still fails." }, "recipient": { "type": "object", "description": "Who the message is for. Send email, name and company when known: Amdahl finds the person in the workspace's CRM and calls by email, else by name and company, and reads the role from the title the CRM or the calls hold (from attributes.title only where the workspace has live intake on). linkedin_url is kept as a fact but finds no one. Takes any of email (up to 320 characters), name and company (up to 200 each), domain (up to 253), linkedin_url (up to 300) and attributes. attributes is a flat map of text, number, true/false or null values, such as a whole Clay or CSV row: up to 100 keys of 100 characters, each text value up to 1000 characters. Any other key is refused, and so is an attribute key that names a business, user, tenant or workspace id.", "properties": { "email": { "type": "string", "maxLength": 320 }, "name": { "type": "string", "maxLength": 200 }, "company": { "type": "string", "maxLength": 200 }, "domain": { "type": "string", "maxLength": 253 }, "linkedin_url": { "type": "string", "maxLength": 300 }, "attributes": { "type": "object", "maxProperties": 100, "additionalProperties": { "type": [ "string", "number", "boolean", "null" ], "maxLength": 1000 } } }, "additionalProperties": false }, "recipient_notes": { "type": "string", "maxLength": 10000, "description": "Free text about the recipient, such as your own research or a pasted CRM note. Up to 10000 characters." }, "message_type": { "type": "string", "enum": [ "cold", "re-engage", "follow-up", "deal" ], "description": "The kind of message: cold, re-engage, follow-up, deal. follow-up is a reply in a thread that is in progress." } }, "additionalProperties": false } }, "webhook_url": { "type": "string", "maxLength": 2048, "description": "Optional. An https URL that gets one signed POST when the batch completes, carrying the batch id and its counts, never a draft or a rewrite." }, "idempotency_key": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Optional. Send the same key to retry a submit safely: the same key and body return the first batch and queue nothing new." } }, "required": [ "items" ], "additionalProperties": false } } } } } }, "/api/platform/v1/messages/optimize/batches/{id}": { "get": { "operationId": "messagesBatchStatus", "summary": "Get Optimize Batch", "description": "Read one optimize batch you submitted: counts by state, its place in the queue, an estimated finish, and a page of items, each with the result a single optimize returns. Use when polling a batch_id: wait_ms (max 45000) holds the read until the batch completes, so one read replaces a polling loop. Page with limit and cursor, or pass only_finished=true, then finished_since (the last read's finished_cursor) for only items finished after it.", "tags": [ "assets" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The batch_id the batch submit returned.", "schema": { "type": "string", "format": "uuid", "description": "The batch_id the batch submit returned." } }, { "name": "limit", "in": "query", "required": false, "description": "Items per page, up to 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Items per page, up to 100." } }, { "name": "cursor", "in": "query", "required": false, "description": "The next_cursor of the previous page. Omit for the first page.", "schema": { "type": "string", "description": "The next_cursor of the previous page. Omit for the first page." } }, { "name": "status", "in": "query", "required": false, "description": "Return only items in this state. Omit for every item, in submitted order.", "schema": { "type": "string", "enum": [ "queued", "running", "done", "failed" ], "description": "Return only items in this state. Omit for every item, in submitted order." } }, { "name": "wait_ms", "in": "query", "required": false, "description": "Optional long-poll budget in ms, hard-capped at 45000. Holds the read until the batch is completed, then returns the same body.", "schema": { "type": "integer", "description": "Optional long-poll budget in ms, hard-capped at 45000. Holds the read until the batch is completed, then returns the same body." } }, { "name": "only_finished", "in": "query", "required": false, "description": "Return only done and failed items, with finished_cursor and finished_remaining. limit applies; cursor and status are ignored.", "schema": { "type": "boolean", "description": "Return only done and failed items, with finished_cursor and finished_remaining. limit applies; cursor and status are ignored." } }, { "name": "finished_since", "in": "query", "required": false, "description": "The finished_cursor of an earlier read: return only items that finished after it. Implies only_finished.", "schema": { "type": "string", "description": "The finished_cursor of an earlier read: return only items that finished after it. Implies only_finished." } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "batch_id": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "running", "completed" ] }, "created_at": { "type": "string" }, "completed_at": { "type": [ "string", "null" ] }, "counts": { "type": "object", "description": "total, queued, running, done, failed." }, "queue_position": { "type": "integer", "description": "An estimate: queued items, in any workspace, expected to start before this batch's next one. 0 when none of its items is waiting." }, "eta": { "type": [ "object", "null" ], "description": "An estimate, null once nothing is left to run: seconds, estimate (always true), items_ahead, median_run_seconds, slots." }, "webhook": { "type": "object" }, "items": { "type": "array", "description": "index, item_id, status, and result: the single-optimize result, null until settled." }, "next_cursor": { "type": [ "string", "null" ] }, "finished_cursor": { "type": "string", "description": "With only_finished: every finished item returned so far. Pass as finished_since." }, "wait_note": { "type": "string", "description": "Set when the server could not hold this read." }, "finished_remaining": { "type": "integer", "description": "With only_finished: finished items not yet returned (past limit)." } }, "required": [ "batch_id", "status", "counts", "items" ], "additionalProperties": false } }, "required": [ "data" ] } } } }, "400": { "description": "Invalid input - failed schema validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - missing scope or role", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } }, "security": [ { "ApiKeyAuth": [ "messages:execute" ] }, { "BearerAuth": [ "messages:execute" ] } ], "x-scopes": [ "messages:execute" ], "x-stability": "experimental" } }, "/api/platform/v1/messages/optimize/runs/{id}": { "get": { "operationId": "messagesGetRun", "summary": "Get Optimize Run", "description": "Read one optimize run you made: the draft you sent in message, the context you sent, and the message Amdahl returned, so the two versions can be compared. Read when you need to show a past run again; pass the run_id an optimize returned.", "tags": [ "assets" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The run_id an optimize returned.", "schema": { "type": "string", "format": "uuid", "description": "The run_id an optimize returned." } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "run_id": { "type": "string" }, "draft": { "type": [ "string", "null" ], "description": "Your own version, as you sent it in message. null when you sent none." }, "context": { "type": [ "object", "null" ], "description": "The context you sent: facts, rules, voice_examples and limits." }, "message": { "type": [ "string", "null" ], "description": "The message Amdahl returned. null when nothing was written." }, "created_at": { "type": [ "string", "null" ] } }, "required": [ "run_id", "draft", "context", "message", "created_at" ], "additionalProperties": false } }, "required": [ "data" ] } } } }, "400": { "description": "Invalid input - failed schema validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - missing scope or role", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } }, "security": [ { "ApiKeyAuth": [ "messages:execute" ] }, { "BearerAuth": [ "messages:execute" ] } ], "x-scopes": [ "messages:execute" ], "x-stability": "experimental" } }, "/api/platform/v1/messages/optimize/runs/{id}/feedback": { "post": { "operationId": "messagesRecordFeedback", "summary": "Record Message Feedback", "description": "Use when the sender has used, edited or rejected a message an optimize run returned. Pass the run_id the optimize returned, plus the text they actually sent (sent_text), their own words about it (comment), or outcome, and evidence (how you know). The optimizer stores the event and learns the sender's preferences from an edit, unless evidence is inferred. Each call adds an event, so a retry stores it twice.", "tags": [ "assets" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Alias for run_id, carrying the REST path segment of POST /messages/optimize/runs/:id/feedback.", "schema": { "type": "string", "description": "Alias for run_id, carrying the REST path segment of POST /messages/optimize/runs/:id/feedback." } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "success": { "type": "boolean" }, "feedback_id": { "type": "string", "description": "The id of the stored feedback event." }, "run_id": { "type": "string" }, "rubric_miss": { "type": [ "boolean", "null" ], "description": "True when the current judge scored sent_text below the message the run returned. null with no sent_text." }, "outcome": { "type": [ "string", "null" ] }, "evidence": { "type": [ "string", "null" ] } }, "required": [ "success" ], "additionalProperties": false } }, "required": [ "data" ] } } } }, "400": { "description": "Invalid input - failed schema validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - missing scope or role", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } }, "security": [ { "ApiKeyAuth": [ "messages:execute" ] }, { "BearerAuth": [ "messages:execute" ] } ], "x-scopes": [ "messages:execute" ], "x-stability": "experimental", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "run_id": { "type": "string", "format": "uuid", "description": "The run_id an optimize returned." }, "sent_text": { "type": "string", "maxLength": 10000, "description": "The message as the sender actually sent it, verbatim, edits included." }, "comment": { "type": "string", "maxLength": 2000, "description": "What the sender said about the message, in the sender's own words." }, "outcome": { "type": "string", "enum": [ "used", "used_with_edits", "not_used", "unsure" ], "description": "What happened to the message: used, used_with_edits, not_used or unsure." }, "evidence": { "type": "string", "enum": [ "did_it_myself", "reported_to_me", "inferred" ], "description": "How you know: did_it_myself (you sent or edited it), reported_to_me (the sender told you) or inferred (you concluded it). An inferred edit is stored and scored but does not train the sender's preferences." } }, "required": [ "evidence" ], "additionalProperties": false } } } } } }, "/api/platform/v1/messages/optimize_prompt": { "post": { "operationId": "messagesOptimizePrompt", "summary": "Grade Or Improve A Prompt", "description": "Grade a reusable prompt (instructions to a writer) by the emails it writes for up to six real recipients, or improve it against those emails' grades. Use when a sender wants to know whether their prompt writes good email, or wants a better prompt. Returns a run_id at once; the run takes minutes. A retry starts a second run unless the same idempotency_key is sent. Sends nothing.", "tags": [ "assets" ], "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} } } } } }, "400": { "description": "Invalid input - failed schema validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - missing scope or role", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } }, "security": [ { "ApiKeyAuth": [ "messages:execute" ] }, { "BearerAuth": [ "messages:execute" ] } ], "x-scopes": [ "messages:execute" ], "x-stability": "experimental", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt": { "type": "string", "maxLength": 20000, "description": "The reusable prompt: the instructions a writer follows to write an outbound email to any recipient, up to 20000 characters. A prompt that names one recipient, holds one fixed email or asks for non-email copy is refused as prompt_is_one_off; that is one message, for optimize_message." }, "mode": { "type": "string", "enum": [ "improve", "grade" ], "default": "improve", "description": "improve (the default) rewrites the prompt by reflecting on its emails' grades and returns it only when the revision wrote better email on held-out recipients; lift is that held-out difference. grade writes one email per recipient and grades each with the independent judge; the prompt grade is their mean. Neither predicts replies." }, "recipients": { "type": "array", "minItems": 1, "maxItems": 6, "description": "1 to 6 sample recipients the prompt's emails are written for; improve needs at least 2 (the first half train, the rest are held out). Each is resolved from the workspace's CRM and calls like an optimize_message recipient. Omitted: up to 6 of the workspace accounts whose customers spoke on calls or meetings, and their company names appear on the emails.", "items": { "type": "object", "properties": { "recipient": { "type": "object", "description": "Who the email is for: name, company, email, domain, linkedin_url, and attributes (such as title). At least one.", "properties": { "email": { "type": "string", "maxLength": 320 }, "name": { "type": "string", "maxLength": 200 }, "company": { "type": "string", "maxLength": 200 }, "domain": { "type": "string", "maxLength": 253 }, "linkedin_url": { "type": "string", "maxLength": 300 }, "attributes": { "type": "object", "maxProperties": 100, "additionalProperties": { "type": [ "string", "number", "boolean", "null" ], "maxLength": 1000 } } }, "additionalProperties": false }, "recipient_notes": { "type": "string", "maxLength": 10000, "description": "What you know about this recipient, given to the writer as a fact." }, "label": { "type": "string", "maxLength": 200, "description": "Shown on the emails written for this recipient. Default: name and company." } }, "required": [ "recipient" ], "additionalProperties": false } }, "channel": { "type": "string", "enum": [ "email", "linkedin" ] }, "context": { "type": "object", "description": "The sender's own rules, facts, voice_examples and constraints, shared by every email the prompt writes. Facts here are about the sender or the offer, not one recipient.", "properties": { "rules": { "type": "array", "items": { "type": "string" }, "description": "Hard constraints on the rewrite, such as \"no pricing\". They steer the rewrite and are not rewritten or quoted in the message. Up to 20, each up to 500 characters once trimmed." }, "voice_examples": { "type": "array", "items": { "type": "string" }, "description": "Messages the sender wrote themselves. The rewrite matches the sender's voice and does not copy their words. Up to 5, each up to 4000 characters once trimmed." }, "facts": { "type": "array", "items": { "type": "string" }, "description": "What you know first-hand about the recipient or situation that no call recording holds, one fact per entry, such as \"Met Priya at the GTM dinner on Sep 24; she said her SDRs rewrite every AI draft\". Graded as caller-supplied evidence (tier CALLER, not a customer quote): a claim a fact states is not marked fabricated, a claim that inflates one still is. Up to 10, each up to 1000 characters once trimmed." }, "keep_cta": { "type": "boolean", "description": "true to keep the draft's closing ask (its last sentence that asks for something) word for word. Checked exactly on every rewrite; the rewrite works on the rest of the message." }, "max_words": { "type": "integer", "minimum": 10, "maximum": 1000, "description": "The most words the returned message may have, checked exactly on every rewrite. 10 to 1000." }, "banned_phrases": { "type": "array", "items": { "type": "string" }, "description": "Words or phrases the rewrite leaves out, such as \"just\" or \"reaching out\", matched as whole words in any case and checked exactly on every rewrite. Up to 30, each up to 60 characters once trimmed." }, "banned_punctuation": { "type": "array", "items": { "type": "string", "enum": [ "colon", "semicolon", "exclamation" ] }, "description": "Punctuation the rewrite leaves out: any of colon, semicolon, exclamation. Checked exactly on every rewrite; a colon in a time like 2:30pm or in a link does not count." } }, "additionalProperties": false }, "idempotency_key": { "type": "string", "maxLength": 200, "description": "Any string. A second call with the same key within 24 hours returns the run the first call started, in its mode, and starts no second run. One that asks for another mode is refused as a conflict (409 over REST)." } }, "required": [ "prompt" ], "additionalProperties": false } } } } } }, "/api/platform/v1/messages/optimize_prompt/{id}": { "get": { "operationId": "messagesGetPromptRun", "summary": "Get Prompt Run", "description": "Read one prompt run you started: its status and, once complete, the prompt grade, each email it wrote with its grade, and in improve mode the revised prompt and the held-out lift. Use after optimize_prompt returned a run_id; pass wait_ms (max 30000) to wait for it to finish instead of polling quickly.", "tags": [ "assets" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The run_id optimize_prompt returned.", "schema": { "type": "string", "description": "The run_id optimize_prompt returned." } }, { "name": "wait_ms", "in": "query", "required": false, "description": "Hold the read until the run settles, at most 30000 ms.", "schema": { "type": "integer", "minimum": 0, "maximum": 30000, "description": "Hold the read until the run settles, at most 30000 ms." } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "run_id": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "running", "complete", "failed" ] }, "outcome": { "type": "string", "enum": [ "improved", "unchanged", "graded" ] }, "prompt": { "type": "string", "description": "The revised prompt; only when outcome is improved." }, "grade": { "type": "object", "description": "original, and revised in improve mode: mean (1-5, null when nothing was graded), n, emails_passing_bar, bar and per-line pass rates, over the held-out emails." }, "lift": { "type": [ "number", "null" ], "description": "Held-out revised mean minus original mean; null unless lift_reportable." }, "lift_reportable": { "type": "boolean" }, "emails": { "type": "array", "description": "Each email the prompt wrote, with its grade, its unfilled placeholders and its unsupported_claims. Each check is null when it did not run and [] when it found none." }, "disclosures": { "type": "object" } }, "required": [ "run_id", "status" ], "additionalProperties": false } }, "required": [ "data" ] } } } }, "400": { "description": "Invalid input - failed schema validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - missing scope or role", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } }, "security": [ { "ApiKeyAuth": [ "messages:execute" ] }, { "BearerAuth": [ "messages:execute" ] } ], "x-scopes": [ "messages:execute" ], "x-stability": "experimental" } }, "/api/platform/v1/research": { "post": { "operationId": "researchStart", "summary": "Start Research", "description": "Start a research job: a read-only investigation of one question over this workspace's own calls, CRM accounts and deals that settles on one cited answer. Use when a question needs several reads and a written synthesis a single search cannot give. Deprecated: search.query route:\"research\" starts the same job and polls it via research_id. Returns a research_id at once; read it with wait_ms until it settles. The job may pause with a clarifying question, finishing a partial answer at its budget.", "tags": [ "conversations" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} } } } } }, "400": { "description": "Invalid input - failed schema validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - missing scope or role", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } }, "security": [ { "ApiKeyAuth": [ "conversations:write" ] }, { "BearerAuth": [ "conversations:write" ] } ], "x-scopes": [ "conversations:write" ], "x-stability": "beta", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "question": { "type": "string", "minLength": 1, "maxLength": 8000, "description": "The question, in plain language." }, "context": { "type": "string", "maxLength": 4000, "description": "Optional background the job should know: who the answer is for, what you already know, the decision it feeds. Read as context, never as the question." }, "allow_questions": { "type": "boolean", "description": "Allow the job to pause and ask you a clarifying question when the question is ambiguous in a way that changes the answer. Default true. Set false when nobody can answer; the job then proceeds on its best reading and states the assumption." }, "as_of": { "type": [ "string", "null" ], "maxLength": 64, "description": "Optional ISO-8601 date or timestamp, e.g. \"2026-10-23\". The job's data.query, data.cluster_search, data.cluster_detail and search.query reads see the workspace as it stood then: later calls are hidden and deals carry the stage they were in. data.search, context.query_substrate and read_resource do not apply the cut yet. A bare date means the end of that day, UTC; send a timestamp for another instant. Defaults to the X-Amdahl-As-Of header, else a date the question names (\"as of Oct 23 2026\", \"Aug 24 to Oct 23 2026\"). null or \"live\" ignores a date in the question. The cut applied is echoed as as_of." } }, "required": [ "question" ], "additionalProperties": false } } } } } }, "/api/platform/v1/research/{id}": { "get": { "operationId": "researchGet", "summary": "Get Research", "description": "Read one research job by id: its status (running, needs_input, complete, failed or canceled), the clarifying question when waiting on you, and once complete the answer with the evidence it cites and whether it is partial. A failed job carries error_reason (timeout, model_error, tool_error, cost_cap, unknown) and partial_findings. Read when polling a job you started; pass wait_ms (max 45000) to wait until it settles instead of looping fast.", "tags": [ "conversations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The research_id research.start returned.", "schema": { "type": "string", "format": "uuid", "description": "The research_id research.start returned." } }, { "name": "wait_ms", "in": "query", "required": false, "description": "Optional long-poll budget in ms, hard-capped at 45000. Blocks until the job is complete, failed, canceled or needs_input, then returns the same body.", "schema": { "type": "integer", "description": "Optional long-poll budget in ms, hard-capped at 45000. Blocks until the job is complete, failed, canceled or needs_input, then returns the same body." } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "research_id": { "type": "string" }, "chat_id": { "type": "string" }, "status": { "type": "string", "enum": [ "running", "needs_input", "complete", "failed", "canceled" ] }, "question": { "type": [ "string", "null" ] }, "question_for_you": { "type": [ "object", "null" ], "description": "Set while status is needs_input: answer it with research.respond." }, "answer": { "type": [ "object", "null" ], "description": "Set once status is complete: text (markdown), partial, partial_reason, content_blocks (the evidence), follow_ups." }, "answered_questions": { "type": "array" }, "error": { "type": [ "string", "null" ] }, "error_reason": { "type": [ "string", "null" ], "enum": [ "timeout", "model_error", "tool_error", "cost_cap", "unknown", null ], "description": "The safe reason class behind `error`, set whenever `error` is." }, "partial_findings": { "type": [ "array", "null" ], "description": "Evidence the job had already presented before it failed, when it failed with anything to show. Null when the job did not fail, or failed with nothing presented." }, "created_at": { "type": "string" }, "wait_note": { "type": "string", "description": "Set when the server could not hold this read." }, "started_at": { "type": [ "string", "null" ] }, "completed_at": { "type": [ "string", "null" ] } }, "required": [ "research_id", "status" ], "additionalProperties": false } }, "required": [ "data" ] } } } }, "400": { "description": "Invalid input - failed schema validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - missing scope or role", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } }, "security": [ { "ApiKeyAuth": [ "conversations:read" ] }, { "BearerAuth": [ "conversations:read" ] } ], "x-scopes": [ "conversations:read" ], "x-stability": "beta" } }, "/api/platform/v1/research/{research_id}/respond": { "post": { "operationId": "researchRespond", "summary": "Answer Research Question", "description": "Answer the clarifying question a research job paused on, and resume the job. Use when a research read shows status needs_input: send your answer as text, or pass option_id to pick one of the listed choices. The job resumes from where it paused and reads as running.", "tags": [ "conversations" ], "parameters": [ { "name": "research_id", "in": "path", "required": true, "description": "The research_id research.start returned.", "schema": { "type": "string", "format": "uuid", "description": "The research_id research.start returned." } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} } } } } }, "400": { "description": "Invalid input - failed schema validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - missing scope or role", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } }, "security": [ { "ApiKeyAuth": [ "conversations:write" ] }, { "BearerAuth": [ "conversations:write" ] } ], "x-scopes": [ "conversations:write" ], "x-stability": "beta", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "answer": { "type": "string", "minLength": 1, "maxLength": 4000, "description": "Your answer. For a multiple-choice question, the label of your choice works." }, "option_id": { "type": "string", "description": "Optional: the id of a listed choice (question_for_you.options). `other` sends the answer as a write-in." } }, "required": [ "answer" ], "additionalProperties": false } } } } } }, "/api/platform/v1/research/{research_id}/cancel": { "post": { "operationId": "researchCancel", "summary": "Cancel Research", "description": "Stop a research job that is still running or waiting on its clarifying question. Use when the answer is no longer needed or the question was wrong; start a new job with the corrected question instead. A job that already finished is left as it is.", "tags": [ "conversations" ], "parameters": [ { "name": "research_id", "in": "path", "required": true, "description": "The research_id research.start returned.", "schema": { "type": "string", "format": "uuid", "description": "The research_id research.start returned." } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} } } } } }, "400": { "description": "Invalid input - failed schema validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - missing scope or role", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } }, "security": [ { "ApiKeyAuth": [ "conversations:write" ] }, { "BearerAuth": [ "conversations:write" ] } ], "x-scopes": [ "conversations:write" ], "x-stability": "beta", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } } } }, "/api/platform/v1/setup/status": { "get": { "operationId": "setupStatus", "summary": "Setup Status", "description": "Check the calling credential end to end: the workspace and role it acts as, its effective scopes, whether the message optimizer would run for it (and the one blocker if not), and which data connections need attention. Use when a call is refused for scope, role or quota, or to confirm a new connection works before relying on it.", "tags": [ "context" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} } } } } }, "400": { "description": "Invalid input - failed schema validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - missing scope or role", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } }, "security": [ { "ApiKeyAuth": [ "data:read" ] }, { "BearerAuth": [ "data:read" ] } ], "x-scopes": [ "data:read" ], "x-stability": "stable" } } } }