{ "openapi": "3.1.0", "info": { "title": "Expedify API", "version": "v1", "description": "The Expedify public API \u2014 one scoped **`/v1`** gateway over CRM, Workflows, Knowledge Base and Analytics. Authenticate with a Bearer `agx_` API key (Settings \u2192 API Keys); every operation is gated by least-privilege scopes (default-deny). Responses use a uniform envelope with cursor pagination, `X-RateLimit-*` headers and a single error shape.\n\nEvery capability here is also available to AI agents over **MCP** (Model Context Protocol) with the same key and scopes \u2014 see the MCP reference.", "contact": { "name": "Expedify Support", "email": "support@expedify.ai", "url": "https://expedify.ai" } }, "paths": { "/v1/objects/{entity}": { "get": { "tags": [ "CRM Objects" ], "summary": "List/search records of an entity", "operationId": "list_objects_v1_objects__entity__get", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "entity", "in": "path", "required": true, "schema": { "type": "string", "title": "Entity" } }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 200, "minimum": 1 }, { "type": "null" } ], "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ], "title": "Offset" } }, { "name": "sort", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sort" } }, { "name": "order", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "pattern": "^(asc|desc)$" }, { "type": "null" } ], "title": "Order" } }, { "name": "q", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Free-text search across all fields (incl. custom fields).", "title": "Q" }, "description": "Free-text search across all fields (incl. custom fields)." }, { "name": "match", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "pattern": "^(all|any)$" }, { "type": "null" } ], "description": "Combine field filters with AND (all) or OR (any). Default all.", "title": "Match" }, "description": "Combine field filters with AND (all) or OR (any). Default all." } ], "responses": { "200": { "description": "A page of records", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContactList" }, { "$ref": "#/components/schemas/CompanyList" }, { "$ref": "#/components/schemas/DealList" }, { "$ref": "#/components/schemas/TaskList" }, { "$ref": "#/components/schemas/NoteList" }, { "$ref": "#/components/schemas/ActivityList" } ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "tags": [ "CRM Objects" ], "summary": "Create a record", "operationId": "create_object_v1_objects__entity__post", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "entity", "in": "path", "required": true, "schema": { "type": "string", "title": "Entity" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContactCreate" }, { "$ref": "#/components/schemas/CompanyCreate" }, { "$ref": "#/components/schemas/DealCreate" }, { "$ref": "#/components/schemas/TaskCreate" }, { "$ref": "#/components/schemas/NoteCreate" }, { "$ref": "#/components/schemas/ActivityCreate" } ] } } } }, "responses": { "201": { "description": "Created record", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Contact" }, { "$ref": "#/components/schemas/Company" }, { "$ref": "#/components/schemas/Deal" }, { "$ref": "#/components/schemas/Task" }, { "$ref": "#/components/schemas/Note" }, { "$ref": "#/components/schemas/Activity" } ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/objects/{entity}/{entity_id}": { "get": { "tags": [ "CRM Objects" ], "summary": "Get a record by id", "operationId": "get_object_v1_objects__entity___entity_id__get", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "entity", "in": "path", "required": true, "schema": { "type": "string", "title": "Entity" } }, { "name": "entity_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Entity Id" } } ], "responses": { "200": { "description": "The record", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Contact" }, { "$ref": "#/components/schemas/Company" }, { "$ref": "#/components/schemas/Deal" }, { "$ref": "#/components/schemas/Task" }, { "$ref": "#/components/schemas/Note" }, { "$ref": "#/components/schemas/Activity" } ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "patch": { "tags": [ "CRM Objects" ], "summary": "Partially update a record", "operationId": "update_object_v1_objects__entity___entity_id__patch", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "entity", "in": "path", "required": true, "schema": { "type": "string", "title": "Entity" } }, { "name": "entity_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Entity Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContactUpdate" }, { "$ref": "#/components/schemas/CompanyUpdate" }, { "$ref": "#/components/schemas/DealUpdate" }, { "$ref": "#/components/schemas/TaskUpdate" }, { "$ref": "#/components/schemas/NoteUpdate" }, { "$ref": "#/components/schemas/ActivityUpdate" } ] } } } }, "responses": { "200": { "description": "Updated record", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Contact" }, { "$ref": "#/components/schemas/Company" }, { "$ref": "#/components/schemas/Deal" }, { "$ref": "#/components/schemas/Task" }, { "$ref": "#/components/schemas/Note" }, { "$ref": "#/components/schemas/Activity" } ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "delete": { "tags": [ "CRM Objects" ], "summary": "Delete a record", "operationId": "delete_object_v1_objects__entity___entity_id__delete", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "entity", "in": "path", "required": true, "schema": { "type": "string", "title": "Entity" } }, { "name": "entity_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Entity Id" } } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteResult" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/objects/{entity}/{entity_id}/associations/{target}/{target_id}": { "post": { "tags": [ "CRM Objects" ], "summary": "Link a record to another (e.g. a contact to a company)", "operationId": "link_records_v1_objects__entity___entity_id__associations__target___target_id__post", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "entity", "in": "path", "required": true, "schema": { "type": "string", "title": "Entity" } }, { "name": "entity_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Entity Id" } }, { "name": "target", "in": "path", "required": true, "schema": { "type": "string", "title": "Target" } }, { "name": "target_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Target Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "default": {}, "title": "Body" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "delete": { "tags": [ "CRM Objects" ], "summary": "Unlink a record from another", "operationId": "unlink_records_v1_objects__entity___entity_id__associations__target___target_id__delete", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "entity", "in": "path", "required": true, "schema": { "type": "string", "title": "Entity" } }, { "name": "entity_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Entity Id" } }, { "name": "target", "in": "path", "required": true, "schema": { "type": "string", "title": "Target" } }, { "name": "target_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Target Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/objects/{entity}/{entity_id}/{target}": { "get": { "tags": [ "CRM Objects" ], "summary": "List records associated with a record", "operationId": "list_associated_v1_objects__entity___entity_id___target__get", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "entity", "in": "path", "required": true, "schema": { "type": "string", "title": "Entity" } }, { "name": "entity_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Entity Id" } }, { "name": "target", "in": "path", "required": true, "schema": { "type": "string", "title": "Target" } }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 200, "minimum": 1 }, { "type": "null" } ], "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ], "title": "Offset" } }, { "name": "sort", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sort" } }, { "name": "order", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "pattern": "^(asc|desc)$" }, { "type": "null" } ], "title": "Order" } }, { "name": "q", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Free-text search across the related entity's fields.", "title": "Q" }, "description": "Free-text search across the related entity's fields." }, { "name": "match", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "pattern": "^(all|any)$" }, { "type": "null" } ], "title": "Match" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/workflows/nodes": { "get": { "tags": [ "Workflows" ], "summary": "List available workflow node types", "operationId": "list_workflow_nodes_v1_workflows_nodes_get", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "category", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional category to filter by.", "title": "Category" }, "description": "Optional category to filter by." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/workflows/nodes/{node_type}": { "get": { "tags": [ "Workflows" ], "summary": "Get a node type's schema + output handles", "operationId": "get_workflow_node_schema_v1_workflows_nodes__node_type__get", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "node_type", "in": "path", "required": true, "schema": { "type": "string", "title": "Node Type" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/workflows/authoring-guide": { "get": { "tags": [ "Workflows" ], "summary": "How to write the YAML authoring spec", "operationId": "get_workflow_authoring_guide_v1_workflows_authoring_guide_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/workflows/validate": { "post": { "tags": [ "Workflows" ], "summary": "Compile + validate a spec or definition (no save)", "operationId": "validate_workflow_v1_workflows_validate_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "spec": { "type": "string", "description": "YAML authoring spec to validate." }, "definition": { "type": "object", "description": "A raw workflow definition (nodes/edges) to validate." } } } } }, "description": "Compile and validate a workflow before saving it. Pass `spec` (YAML authoring spec) or a raw `definition`. Returns {valid, errors, warnings}; never saves. Requires workflows:read." }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/workflows/templates": { "get": { "tags": [ "Workflows" ], "summary": "Search marketplace workflow templates", "operationId": "search_workflow_templates_v1_workflows_templates_get", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "search", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Search" } }, { "name": "category", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Category" } }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 100, "minimum": 1 }, { "type": "null" } ], "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ], "title": "Offset" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/workflows": { "get": { "tags": [ "Workflows" ], "summary": "List the org's workflows", "operationId": "list_workflows_v1_workflows_get", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "active", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Filter to active (true) or inactive (false).", "title": "Active" }, "description": "Filter to active (true) or inactive (false)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "tags": [ "Workflows" ], "summary": "Create a workflow from a YAML spec", "operationId": "create_workflow_v1_workflows_post", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "spec" ], "properties": { "spec": { "type": "string", "description": "The YAML authoring spec (see get_workflow_authoring_guide)." }, "name": { "type": "string", "description": "Optional name override (else taken from the spec)." }, "description": { "type": "string", "description": "Optional description override." } } } } }, "description": "Create a workflow from a YAML `spec`. Validates first and refuses to save if there are blocking errors. Saved as a DRAFT (won't run automatically until activated; you can test it immediately). Returns {workflow_id, status, warnings}. Requires workflows:author." }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/workflows/import": { "post": { "tags": [ "Workflows" ], "summary": "Import a marketplace template as a new workflow", "operationId": "import_workflow_template_v1_workflows_import_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "template_id" ], "properties": { "template_id": { "type": "string", "description": "The marketplace template id." }, "name": { "type": "string", "description": "Optional name for the imported workflow." } } } } }, "description": "Instantiate a marketplace template into this org as a new workflow (by `template_id` from search_workflow_templates). Returns the new workflow_id. Requires workflows:author." }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/workflows/run-by-name": { "post": { "tags": [ "Workflows" ], "summary": "Run (test) a workflow by name \u2014 confirm-gated", "operationId": "run_workflow_by_name_v1_workflows_run_by_name_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "name" ], "properties": { "name": { "type": "string" }, "inputs": { "type": "object" }, "confirm": { "type": "boolean" } } } } }, "description": "Run (test) a workflow by name (must be unique). Same confirm gate and real-execution semantics as run_workflow. Requires workflows:run." }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/workflows/nodes/test": { "post": { "tags": [ "Workflows" ], "summary": "Execute one node in isolation \u2014 confirm-gated", "operationId": "test_workflow_node_v1_workflows_nodes_test_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "node_type" ], "properties": { "node_type": { "type": "string", "description": "Node type id (e.g. crm_manager, api_request)." }, "config": { "type": "object", "description": "The node's config/data dict ({{templates}} allowed)." }, "inputs": { "type": "object", "description": "Sample upstream inputs the node reads / templates resolve against." }, "dry_run": { "type": "boolean", "description": "Resolve config + preview only; never executes (any tier). Use to safely exercise external_irreversible nodes." }, "confirm": { "type": "boolean", "description": "Required to execute write_internal / external_irreversible nodes. Ignored for read nodes (they auto-run)." } } } } }, "description": "Execute ONE node in isolation with sample inputs \u2014 no saved workflow needed. Give `node_type` (from list_workflow_nodes), an optional `config` (the node's data dict; {{templates}} allowed) and optional `inputs` (sample upstream data). REAL execution \u2014 no sandbox. Gated by the node's `side_effect_tier`: `read` nodes AUTO-RUN (no confirm); `write_internal` and `external_irreversible` nodes are confirm-gated (call without confirm to get config_schema + resolved-config preview, then re-call with confirm=true). `dry_run: true` resolves + previews what WOULD run WITHOUT executing (any tier) \u2014 the safe way to exercise a WALL node (external_irreversible) while building. Every response echoes `side_effect_tier`. Requires workflows:run." }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/workflows/executions/{execution_id}": { "get": { "tags": [ "Workflows" ], "summary": "Get one execution's full detail", "operationId": "get_workflow_execution_v1_workflows_executions__execution_id__get", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "execution_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Execution Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/workflows/mcp-tools": { "get": { "tags": [ "Workflows" ], "summary": "List workflows exposed as curated MCP tools", "operationId": "list_mcp_tools_v1_workflows_mcp_tools_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/workflows/{workflow_id}": { "get": { "tags": [ "Workflows" ], "summary": "Read a workflow as the editable YAML spec", "operationId": "get_workflow_v1_workflows__workflow_id__get", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "workflow_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Workflow Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "patch": { "tags": [ "Workflows" ], "summary": "Edit a workflow with granular operations", "operationId": "edit_workflow_v1_workflows__workflow_id__patch", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "workflow_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Workflow Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "operations" ], "properties": { "operations": { "type": "array", "description": "Ordered edit operations; each is an object with an `op` field plus its args.", "items": { "type": "object", "required": [ "op" ], "properties": { "op": { "type": "string" } } } }, "name": { "type": "string", "description": "Optional new name." }, "description": { "type": "string", "description": "Optional new description." } } } } }, "description": "Edit an existing workflow with a list of granular `operations`. Node references accept a step alias OR a node id. Ops: add_node{node_type,config?,alias?,description?}; set_config{node_id,config}; rename_node{node_id,alias}; set_description{node_id,description}; connect{source,target,source_handle?}; disconnect{source,target,source_handle?}; remove_node{node_id}; set_variable{name,value}. Validates and refuses to save blocking errors; active state is preserved. Requires workflows:author." }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "delete": { "tags": [ "Workflows" ], "summary": "Delete a workflow", "operationId": "delete_workflow_v1_workflows__workflow_id__delete", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "workflow_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Workflow Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/workflows/{workflow_id}/activate": { "post": { "tags": [ "Workflows" ], "summary": "Activate a workflow (fires on its triggers)", "operationId": "activate_workflow_v1_workflows__workflow_id__activate_post", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "workflow_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Workflow Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/workflows/{workflow_id}/deactivate": { "post": { "tags": [ "Workflows" ], "summary": "Deactivate a workflow (stops firing)", "operationId": "deactivate_workflow_v1_workflows__workflow_id__deactivate_post", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "workflow_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Workflow Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/workflows/{workflow_id}/run": { "post": { "tags": [ "Workflows" ], "summary": "Run (test) a workflow now \u2014 confirm-gated", "operationId": "run_workflow_v1_workflows__workflow_id__run_post", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "workflow_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Workflow Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "inputs": { "type": "object", "description": "Trigger inputs for the run." }, "confirm": { "type": "boolean", "description": "Must be true to actually execute." } } } } }, "description": "Run (test) a workflow by id, now, with optional `inputs`. REAL execution against live data/integrations \u2014 no sandbox. Confirm-gated: call without confirm to get a confirmation summary, then re-call with confirm=true once the human approves. Works on drafts too. Requires workflows:run." }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/workflows/{workflow_id}/executions": { "get": { "tags": [ "Workflows" ], "summary": "List a workflow's recent executions", "operationId": "list_workflow_executions_v1_workflows__workflow_id__executions_get", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "workflow_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Workflow Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 100, "minimum": 1 }, { "type": "null" } ], "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/workflows/{workflow_id}/mcp-tool": { "post": { "tags": [ "Workflows" ], "summary": "Expose/unexpose a workflow as a curated MCP tool", "operationId": "set_workflow_mcp_tool_v1_workflows__workflow_id__mcp_tool_post", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "workflow_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Workflow Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Expose (true) or unexpose (false). Default true." }, "tool_name": { "type": "string", "description": "Optional MCP tool name override." }, "tool_description": { "type": "string", "description": "Optional tool description shown to agents." } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/knowledge-bases": { "get": { "tags": [ "Knowledge Base" ], "summary": "List the org's knowledge bases", "operationId": "list_knowledge_bases_v1_knowledge_bases_get", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "include_entity_kbs", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Include auto-synced CRM entity KBs.", "title": "Include Entity Kbs" }, "description": "Include auto-synced CRM entity KBs." }, { "name": "include_system", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Also list read-only system/shared KBs.", "title": "Include System" }, "description": "Also list read-only system/shared KBs." }, { "name": "include_inactive", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Include Inactive" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "tags": [ "Knowledge Base" ], "summary": "Create a knowledge base", "operationId": "create_knowledge_base_v1_knowledge_bases_post", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "name" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "settings": { "type": "object", "description": "Optional RAG settings (see the KB settings schema)." } } } } }, "description": "Create a knowledge base. Optional `settings` (RAG config: chunking_strategy, search_defaults, document_summaries, \u2026). Returns the new KB. Requires knowledge:write." }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/knowledge-bases/{kb_id}": { "get": { "tags": [ "Knowledge Base" ], "summary": "Get a knowledge base's stats + settings", "operationId": "get_knowledge_base_v1_knowledge_bases__kb_id__get", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "kb_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Kb Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "patch": { "tags": [ "Knowledge Base" ], "summary": "Update a knowledge base's name/description", "operationId": "update_knowledge_base_v1_knowledge_bases__kb_id__patch", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "kb_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Kb Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string" }, "description": { "type": "string" } } } } }, "description": "Update a knowledge base's name and/or description. Requires knowledge:write." }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "delete": { "tags": [ "Knowledge Base" ], "summary": "Delete a knowledge base (and its documents)", "operationId": "delete_knowledge_base_v1_knowledge_bases__kb_id__delete", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "kb_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Kb Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/knowledge-bases/{kb_id}/settings": { "patch": { "tags": [ "Knowledge Base" ], "summary": "Merge RAG settings into a knowledge base", "operationId": "update_knowledge_base_settings_v1_knowledge_bases__kb_id__settings_patch", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "kb_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Kb Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "settings" ], "properties": { "settings": { "type": "object", "description": "Settings to merge (chunking_strategy, search_defaults, \u2026)." } } } } }, "description": "Merge RAG settings into a knowledge base (deep-merge; only keys you pass change). e.g. enable parent_child chunking, query expansion, document summaries. Requires knowledge:write." }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/knowledge-bases/{kb_id}/search": { "post": { "tags": [ "Knowledge Base" ], "summary": "Semantic/hybrid search over a KB", "operationId": "search_knowledge_base_v1_knowledge_bases__kb_id__search_post", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "kb_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Kb Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "query" ], "properties": { "query": { "type": "string", "description": "The search query." }, "top_k": { "type": "integer", "minimum": 1, "maximum": 50 }, "similarity_threshold": { "type": "number", "minimum": 0, "maximum": 1 } } } } }, "description": "Semantic/hybrid search over a KB's documents. Returns the most relevant chunks with similarity scores (re-rank/MMR/hybrid applied from the KB's settings). Use this to look something up in a knowledge base. Requires knowledge:read." }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/knowledge-bases/{kb_id}/ask": { "post": { "tags": [ "Knowledge Base" ], "summary": "RAG question-answering over a KB", "operationId": "ask_knowledge_base_v1_knowledge_bases__kb_id__ask_post", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "kb_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Kb Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "question" ], "properties": { "question": { "type": "string" }, "model": { "type": "string", "description": "Optional LLM model override." }, "top_k": { "type": "integer", "minimum": 1, "maximum": 50 } } } } }, "description": "Ask a question against a KB (RAG): searches, then an LLM answers from the retrieved context. Returns {answer, sources}. Incurs LLM credits. Requires knowledge:read." }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/knowledge-bases/{kb_id}/documents": { "get": { "tags": [ "Knowledge Base" ], "summary": "List documents in a KB", "operationId": "list_kb_documents_v1_knowledge_bases__kb_id__documents_get", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "kb_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Kb Id" } }, { "name": "search", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Search" } }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 100, "minimum": 1 }, { "type": "null" } ], "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ], "title": "Offset" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "tags": [ "Knowledge Base" ], "summary": "Add a document to a KB (text or file)", "operationId": "add_kb_document_v1_knowledge_bases__kb_id__documents_post", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "kb_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Kb Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "content": { "type": "string", "description": "Raw text/markdown content (omit if using file_base64)." }, "file_base64": { "type": "string", "description": "Base64-encoded file bytes (alternative to content)." }, "filename": { "type": "string", "description": "Original filename incl. extension, e.g. report.pdf (required with file_base64)." }, "title": { "type": "string" }, "metadata": { "type": "object", "description": "Optional metadata (source, tags, \u2026)." } } } } }, "description": "Add a document to a KB. It is chunked + embedded on the spot and is searchable on return. Provide EITHER `content` (raw text/markdown) OR `file_base64` + `filename` (a base64-encoded file \u2014 pdf/docx/pptx/xlsx/csv/json/txt, extracted server-side; extension required). Optional `title`/`metadata`. Requires knowledge:write." }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/knowledge-bases/{kb_id}/documents/{document_id}": { "get": { "tags": [ "Knowledge Base" ], "summary": "Get a document with full content", "operationId": "get_kb_document_v1_knowledge_bases__kb_id__documents__document_id__get", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "kb_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Kb Id" } }, { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Document Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "patch": { "tags": [ "Knowledge Base" ], "summary": "Update a document (re-indexes on content change)", "operationId": "update_kb_document_v1_knowledge_bases__kb_id__documents__document_id__patch", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "kb_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Kb Id" } }, { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Document Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "content": { "type": "string" }, "title": { "type": "string" }, "metadata": { "type": "object" } } } } }, "description": "Update a document. Changing `content` re-chunks + re-embeds it. `metadata` is merged. Requires knowledge:write." }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "delete": { "tags": [ "Knowledge Base" ], "summary": "Delete a document (soft by default)", "operationId": "delete_kb_document_v1_knowledge_bases__kb_id__documents__document_id__delete", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "kb_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Kb Id" } }, { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Document Id" } }, { "name": "hard", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Permanently purge instead of soft-delete.", "title": "Hard" }, "description": "Permanently purge instead of soft-delete." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/analytics/run-query": { "post": { "tags": [ "Analytics" ], "summary": "Run a read-only SQL query (ad-hoc or saved dataset)", "operationId": "run_query_v1_analytics_run_query_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "sql": { "type": "string", "description": "A read-only SELECT (ad-hoc)." }, "dataset_id": { "type": "string", "description": "Run a saved dataset." }, "question": { "type": "string", "description": "Natural-language question; auto-converted to SQL and run (org database only)." }, "integration_id": { "type": "string", "description": "Run against a connected external database (from list_data_sources). Omit for the org DB." }, "limit": { "type": "integer", "minimum": 1, "maximum": 10000 }, "offset": { "type": "integer", "minimum": 0 }, "fresh": { "type": "boolean", "description": "Bypass cache." } } } } }, "description": "Run a read-only SQL query and get rows back \u2014 the way to ANALYZE data. Provide `sql` (ad-hoc SELECT), `dataset_id` (a saved dataset), OR `question` (plain English \u2014 the NL\u2192SQL agent grounds + validates it, then it's executed; the response includes the generated_sql). Only SELECTs are allowed (DROP/DELETE/etc. blocked); org-scoped. Paginated via limit/offset. Tip: call get_data_model first to learn real columns/values. Requires analytics:read." }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/analytics/run-chart": { "post": { "tags": [ "Analytics" ], "summary": "Run a chart's server-side aggregation", "operationId": "run_chart_v1_analytics_run_chart_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "chart_id": { "type": "string", "description": "A saved chart (uses its dataset + config)." }, "dataset_id": { "type": "string", "description": "Aggregate a saved dataset." }, "sql": { "type": "string", "description": "Ad-hoc base SELECT to aggregate." }, "integration_id": { "type": "string", "description": "With ad-hoc `sql`: aggregate against an external database. Saved charts/datasets carry their own." }, "chart_config": { "type": "object", "description": "dimensions[], metrics[], breakdownBy, filters[], topN, sortByMetric." }, "limit": { "type": "integer", "minimum": 1, "maximum": 10000 }, "fresh": { "type": "boolean" } } } } }, "description": "Get server-side aggregated data for a chart (GROUP BY dimensions + metrics, breakdownBy, filters, topN). Provide `chart_id` (saved chart) OR (`dataset_id` and/or `sql`) plus a `chart_config`. Returns the plotted rows. Requires analytics:read." }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/analytics/generate-sql": { "post": { "tags": [ "Analytics" ], "summary": "Natural-language \u2192 grounded, validated SQL", "operationId": "generate_sql_v1_analytics_generate_sql_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "question" ], "properties": { "question": { "type": "string", "description": "The business question in plain English." }, "mode": { "type": "string", "enum": [ "validate", "preview", "generate_only" ] } } } } }, "description": "Turn a natural-language question into grounded, validated, read-only SQL \u2014 the SAME NL\u2192SQL agent the in-product dataset builder uses (it knows your real schema, enum values, custom-field sql_refs, join graph, and deal/lifecycle stages, and self-corrects against the DB). Prefer this over hand-writing SQL. `mode`: validate (default, self-corrects + returns sample rows), preview (more rows), generate_only (no DB). Feed the returned sql to run_query or create_dataset. Org database only \u2014 for external DBs discover schema via list_data_sources + describe_analytics_table and hand-write SQL. Requires analytics:read." }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/analytics/data-model": { "get": { "tags": [ "Analytics" ], "summary": "The org's grounded analysis data model (schema + enums + joins + custom-field refs)", "operationId": "get_data_model_v1_analytics_data_model_get", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "force_refresh", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Rebuild the cached manifest.", "title": "Force Refresh" }, "description": "Rebuild the cached manifest." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/analytics/data-sources": { "get": { "tags": [ "Analytics" ], "summary": "List queryable databases (org DB + external DB integrations)", "operationId": "list_data_sources_v1_analytics_data_sources_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/analytics/tables": { "get": { "tags": [ "Analytics" ], "summary": "List tables available for analytics", "operationId": "list_tables_v1_analytics_tables_get", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "integration_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "External database integration (from /data-sources). Omit for the org DB.", "title": "Integration Id" }, "description": "External database integration (from /data-sources). Omit for the org DB." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/analytics/tables/{table_name}": { "get": { "tags": [ "Analytics" ], "summary": "Get a table's columns + types", "operationId": "get_table_schema_v1_analytics_tables__table_name__get", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "table_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Table Name" } }, { "name": "integration_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "External database integration. Omit for the org DB.", "title": "Integration Id" }, "description": "External database integration. Omit for the org DB." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/analytics/tables/{table_name}/preview": { "get": { "tags": [ "Analytics" ], "summary": "Preview the first rows of a table", "operationId": "preview_table_v1_analytics_tables__table_name__preview_get", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "table_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Table Name" } }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 100, "minimum": 1 }, { "type": "null" } ], "title": "Limit" } }, { "name": "integration_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "External database integration. Omit for the org DB.", "title": "Integration Id" }, "description": "External database integration. Omit for the org DB." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/analytics/datasets": { "get": { "tags": [ "Analytics" ], "summary": "List saved datasets", "operationId": "list_datasets_v1_analytics_datasets_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Analytics" ], "summary": "Create a dataset from a read-only SELECT", "operationId": "create_dataset_v1_analytics_datasets_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "name", "sql" ], "properties": { "name": { "type": "string" }, "sql": { "type": "string", "description": "A read-only SELECT." }, "description": { "type": "string" }, "integration_id": { "type": "string", "description": "Build the dataset on an external database (from list_data_sources). Omit for the org DB." }, "is_shared": { "type": "boolean" } } } } }, "description": "Save a reusable dataset from a read-only SQL SELECT. The column manifest is auto-extracted. Charts are built on datasets. Requires analytics:write." }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/analytics/datasets/{dataset_id}": { "get": { "tags": [ "Analytics" ], "summary": "Get a dataset (SQL + column manifest)", "operationId": "get_dataset_v1_analytics_datasets__dataset_id__get", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Dataset Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "patch": { "tags": [ "Analytics" ], "summary": "Update a dataset", "operationId": "update_dataset_v1_analytics_datasets__dataset_id__patch", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Dataset Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "sql": { "type": "string" }, "integration_id": { "type": "string", "description": "Move the dataset onto an external database (or 'current_org' for the org DB)." }, "is_shared": { "type": "boolean" } } } } }, "description": "Update a dataset's name/description/sql/sharing (changing sql re-extracts columns). Requires analytics:write." }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "delete": { "tags": [ "Analytics" ], "summary": "Delete a dataset (charts cascade)", "operationId": "delete_dataset_v1_analytics_datasets__dataset_id__delete", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Dataset Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/analytics/charts": { "get": { "tags": [ "Analytics" ], "summary": "List charts (optionally by dataset)", "operationId": "list_charts_v1_analytics_charts_get", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "dataset_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Dataset Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "tags": [ "Analytics" ], "summary": "Create a chart on a dataset", "operationId": "create_chart_v1_analytics_charts_post", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "name", "chart_type" ], "properties": { "name": { "type": "string" }, "chart_type": { "type": "string" }, "query_id": { "type": "string", "description": "The dataset id this chart visualizes (required unless chart_type='text')." }, "chart_config": { "type": "object" }, "is_shared": { "type": "boolean" } } } } }, "description": "Create a chart on a dataset. `chart_type` \u2208 bar/line/pie/area/table/stacked_bar/horizontal_bar/donut/scatter/kpi/\u2026 `chart_config` holds dimensions[], metrics[], breakdownBy, filters[], topN. Requires analytics:write." }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/analytics/charts/{chart_id}": { "get": { "tags": [ "Analytics" ], "summary": "Get a chart", "operationId": "get_chart_v1_analytics_charts__chart_id__get", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "chart_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Chart Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "patch": { "tags": [ "Analytics" ], "summary": "Update a chart", "operationId": "update_chart_v1_analytics_charts__chart_id__patch", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "chart_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Chart Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string" }, "chart_type": { "type": "string" }, "query_id": { "type": "string" }, "chart_config": { "type": "object" }, "is_shared": { "type": "boolean" } } } } }, "description": "Update a chart's name/type/config/dataset/sharing. Requires analytics:write." }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "delete": { "tags": [ "Analytics" ], "summary": "Delete a chart", "operationId": "delete_chart_v1_analytics_charts__chart_id__delete", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "chart_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Chart Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/analytics/dashboards": { "get": { "tags": [ "Analytics" ], "summary": "List dashboards", "operationId": "list_dashboards_v1_analytics_dashboards_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Analytics" ], "summary": "Create a dashboard from charts", "operationId": "create_dashboard_v1_analytics_dashboards_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "name" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "chart_ids": { "type": "array", "items": { "type": "string" }, "description": "Chart ids to include." }, "layout": { "type": "object" }, "is_shared": { "type": "boolean" } } } } }, "description": "Create a dashboard composing existing charts (by `chart_ids`). Optional `layout` (grid positions). Requires analytics:write." }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/analytics/dashboards/{dashboard_id}": { "get": { "tags": [ "Analytics" ], "summary": "Get a dashboard + its charts", "operationId": "get_dashboard_v1_analytics_dashboards__dashboard_id__get", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "dashboard_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Dashboard Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "patch": { "tags": [ "Analytics" ], "summary": "Update a dashboard", "operationId": "update_dashboard_v1_analytics_dashboards__dashboard_id__patch", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "dashboard_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Dashboard Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "chart_ids": { "type": "array", "items": { "type": "string" } }, "layout": { "type": "object" }, "is_shared": { "type": "boolean" } } } } }, "description": "Update a dashboard's name/description/layout/chart_ids/sharing. Requires analytics:write." }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "delete": { "tags": [ "Analytics" ], "summary": "Delete a dashboard", "operationId": "delete_dashboard_v1_analytics_dashboards__dashboard_id__delete", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "dashboard_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Dashboard Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/analytics/dashboards/{dashboard_id}/with-data": { "get": { "tags": [ "Analytics" ], "summary": "Get a dashboard + all chart data (batch)", "operationId": "get_dashboard_with_data_v1_analytics_dashboards__dashboard_id__with_data_get", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "dashboard_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Dashboard Id" } }, { "name": "date_preset", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "e.g. last_30_days, this_month (omit for all-time).", "title": "Date Preset" }, "description": "e.g. last_30_days, this_month (omit for all-time)." }, { "name": "date_start", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "YYYY-MM-DD custom range start (needs date_end).", "title": "Date Start" }, "description": "YYYY-MM-DD custom range start (needs date_end)." }, { "name": "date_end", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "YYYY-MM-DD custom range end (needs date_start).", "title": "Date End" }, "description": "YYYY-MM-DD custom range end (needs date_start)." }, { "name": "fresh", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Bypass the analytics cache.", "title": "Fresh" }, "description": "Bypass the analytics cache." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/templates": { "get": { "tags": [ "Channels" ], "summary": "List/search marketing templates", "operationId": "list_templates_v1_templates_get", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Free-text search over name/subject/content.", "title": "Q" }, "description": "Free-text search over name/subject/content." }, { "name": "channel", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "e.g. email, sms, whatsapp.", "title": "Channel" }, "description": "e.g. email, sms, whatsapp." }, { "name": "category", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Category" } }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" } }, { "name": "integration_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Integration Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 200, "minimum": 1 }, { "type": "null" } ], "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ], "title": "Offset" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "tags": [ "Channels" ], "summary": "Create a marketing template", "operationId": "create_template_v1_templates_post", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "name", "channel", "content" ], "properties": { "name": { "type": "string" }, "channel": { "type": "string", "description": "email | sms | whatsapp." }, "content": { "type": "string", "description": "Template body ({{variables}} allowed)." }, "subject": { "type": "string", "description": "Subject line (email)." }, "preheader": { "type": "string" }, "category": { "type": "string" }, "status": { "type": "string" }, "is_active": { "type": "boolean" }, "description": { "type": "string" }, "integration_id": { "type": "string" }, "integration_type": { "type": "string" } } } } }, "description": "Create a marketing template. Required: `name`, `channel` (email/sms/whatsapp), `content`. Optional: `subject`, `preheader`, `category` (default 'other'), `status` (default 'draft'), `is_active`, `integration_id`, `integration_type`. Variables like {{first_name}} are auto-extracted from content/subject. Requires templates:write." }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/templates/{template_id}": { "get": { "tags": [ "Channels" ], "summary": "Get a marketing template", "operationId": "get_template_v1_templates__template_id__get", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "template_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Template Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "patch": { "tags": [ "Channels" ], "summary": "Update a marketing template", "operationId": "update_template_v1_templates__template_id__patch", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "template_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Template Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string" }, "channel": { "type": "string" }, "content": { "type": "string" }, "subject": { "type": "string" }, "preheader": { "type": "string" }, "category": { "type": "string" }, "status": { "type": "string" }, "is_active": { "type": "boolean" }, "description": { "type": "string" }, "integration_id": { "type": "string" }, "integration_type": { "type": "string" } } } } }, "description": "Update a marketing template by id (partial). Requires templates:write." }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "delete": { "tags": [ "Channels" ], "summary": "Delete a marketing template", "operationId": "delete_template_v1_templates__template_id__delete", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "template_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Template Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/assets": { "get": { "tags": [ "Channels" ], "summary": "List/search marketing assets", "operationId": "list_assets_v1_assets_get", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Free-text over name/description/filename.", "title": "Q" }, "description": "Free-text over name/description/filename." }, { "name": "asset_type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "e.g. image, document, video.", "title": "Asset Type" }, "description": "e.g. image, document, video." }, { "name": "category", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Category" } }, { "name": "tags", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "title": "Tags" } }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 200, "minimum": 1 }, { "type": "null" } ], "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ], "title": "Offset" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/assets/upload": { "post": { "tags": [ "Channels" ], "summary": "Upload a marketing asset (base64)", "operationId": "upload_asset_v1_assets_upload_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "file_base64", "filename" ], "properties": { "file_base64": { "type": "string", "description": "Base64-encoded file bytes." }, "filename": { "type": "string", "description": "Original filename incl. extension, e.g. logo.png." }, "mime_type": { "type": "string", "description": "Optional MIME type override." }, "category": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } } } } }, "description": "Upload a marketing asset from a base64-encoded file. Required: `file_base64` + `filename` (extension required). Optional `mime_type` (guessed from filename otherwise), `category`, `description`, `tags`. Bytes are stored via the org's configured storage integration (Azure Blob) and a marketing_assets row is created. Requires assets:write." }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/assets/{asset_id}": { "get": { "tags": [ "Channels" ], "summary": "Get a marketing asset", "operationId": "get_asset_v1_assets__asset_id__get", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "asset_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Asset Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "patch": { "tags": [ "Channels" ], "summary": "Update a marketing asset's metadata", "operationId": "update_asset_v1_assets__asset_id__patch", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "asset_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Asset Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } } } } }, "description": "Update a marketing asset's metadata (name/description/category/tags). Requires assets:write." }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "delete": { "tags": [ "Channels" ], "summary": "Delete a marketing asset", "operationId": "delete_asset_v1_assets__asset_id__delete", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "asset_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Asset Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/segments": { "get": { "tags": [ "Channels" ], "summary": "List CRM segments", "operationId": "list_segments_v1_segments_get", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "entity_type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "contact | company | deal.", "title": "Entity Type" }, "description": "contact | company | deal." }, { "name": "tags", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "title": "Tags" } }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 200, "minimum": 1 }, { "type": "null" } ], "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ], "title": "Offset" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "tags": [ "Channels" ], "summary": "Create a CRM segment", "operationId": "create_segment_v1_segments_post", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "name", "entity_type", "filter_config" ], "properties": { "name": { "type": "string" }, "entity_type": { "type": "string", "enum": [ "contact", "company", "deal" ] }, "filter_config": { "type": "object", "description": "Filter Builder config (filter_groups + connectors)." }, "description": { "type": "string" }, "segment_type": { "type": "string", "description": "static_onetime (default) | dynamic." }, "is_public": { "type": "boolean" }, "tags": { "type": "array", "items": { "type": "string" } } } } } }, "description": "Create a CRM segment. Required: `name`, `entity_type` (contact/company/deal), `filter_config` (the Filter Builder JSON: {filter_groups:[{conditions:[{entity,field,operator,value}], condition_connector}], group_connector}). Optional description/tags/segment_type/is_public. Created in 'pending' \u2014 call evaluate_segment to compute the member count. Tip: use preview_segment first. Requires segments:write." }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/segments/preview": { "post": { "tags": [ "Channels" ], "summary": "Preview an unsaved filter (count + optional records)", "operationId": "preview_segment_v1_segments_preview_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "entity_type", "filter_config" ], "properties": { "entity_type": { "type": "string", "enum": [ "contact", "company", "deal" ] }, "filter_config": { "type": "object", "description": "Filter Builder config (filter_groups + connectors)." }, "return_records": { "type": "boolean" }, "records_limit": { "type": "integer", "minimum": 1, "maximum": 100 } } } } }, "description": "Preview an UNSAVED filter \u2014 get the matching count (+ optional capped records) WITHOUT creating a segment. Test audience filters before saving. Required: `entity_type`, `filter_config`. `return_records`/`records_limit` as for evaluate_segment. Requires segments:read." }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/segments/{segment_id}": { "get": { "tags": [ "Channels" ], "summary": "Get a CRM segment", "operationId": "get_segment_v1_segments__segment_id__get", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "segment_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Segment Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "patch": { "tags": [ "Channels" ], "summary": "Update a CRM segment", "operationId": "update_segment_v1_segments__segment_id__patch", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "segment_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Segment Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "filter_config": { "type": "object" }, "segment_type": { "type": "string" }, "is_public": { "type": "boolean" }, "tags": { "type": "array", "items": { "type": "string" } } } } } }, "description": "Update a segment by id (partial). Changing `filter_config` does NOT auto-evaluate \u2014 call evaluate_segment to refresh. Requires segments:write." }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "delete": { "tags": [ "Channels" ], "summary": "Delete a CRM segment", "operationId": "delete_segment_v1_segments__segment_id__delete", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "segment_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Segment Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/segments/{segment_id}/evaluate": { "post": { "tags": [ "Channels" ], "summary": "(Re)evaluate a saved segment (count + optional records)", "operationId": "evaluate_segment_v1_segments__segment_id__evaluate_post", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "segment_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Segment Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "return_records": { "type": "boolean" }, "records_limit": { "type": "integer", "minimum": 1, "maximum": 100 } } } } }, "description": "(Re)evaluate a SAVED segment and return its member_count (persists the count, like the product). Pass `return_records=true` for a capped sample of matched records (`records_limit`, default 25, max 100) \u2014 omit it for a fast count-only answer. Requires segments:read." }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/campaigns": { "get": { "tags": [ "Channels" ], "summary": "List/search campaigns", "operationId": "list_campaigns_v1_campaigns_get", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" } }, { "name": "campaign_type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Campaign Type" } }, { "name": "channel", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Channel" } }, { "name": "q", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Q" } }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 200, "minimum": 1 }, { "type": "null" } ], "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ], "title": "Offset" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "tags": [ "Channels" ], "summary": "Create a draft campaign", "operationId": "create_campaign_v1_campaigns_post", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "name", "campaign_type", "channel" ], "properties": { "name": { "type": "string" }, "campaign_type": { "type": "string", "description": "e.g. one_time, broadcast." }, "channel": { "type": "string", "description": "email | sms | whatsapp." }, "template_id": { "type": "string" }, "integration_id": { "type": "string" }, "audience_id": { "type": "string", "description": "Segment/audience id to target." }, "audience_name": { "type": "string" }, "description": { "type": "string" }, "config": { "type": "object" } } } } }, "description": "Create a DRAFT campaign. Required: `name`, `campaign_type`, `channel` (email/sms/whatsapp). Optional: `template_id`, `integration_id`, `audience_id`+`audience_name` (a segment/audience to target), `description`, `config`. Always a draft \u2014 use send_campaign to launch. Requires campaigns:write." }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/campaigns/{campaign_id}": { "get": { "tags": [ "Channels" ], "summary": "Get a campaign", "operationId": "get_campaign_v1_campaigns__campaign_id__get", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Campaign Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "patch": { "tags": [ "Channels" ], "summary": "Update a campaign", "operationId": "update_campaign_v1_campaigns__campaign_id__patch", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Campaign Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "template_id": { "type": "string" }, "audience_id": { "type": "string" }, "audience_name": { "type": "string" }, "config": { "type": "object" }, "status": { "type": "string" }, "scheduled_at": { "type": "string", "description": "ISO timestamp for scheduling." } } } } }, "description": "Update a campaign by id (partial). Requires campaigns:write." }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "delete": { "tags": [ "Channels" ], "summary": "Delete (cancel) a campaign", "operationId": "delete_campaign_v1_campaigns__campaign_id__delete", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Campaign Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/campaigns/{campaign_id}/send": { "post": { "tags": [ "Channels" ], "summary": "Launch a campaign (confirm-gated + billing-enforced)", "operationId": "send_campaign_v1_campaigns__campaign_id__send_post", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Campaign Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "confirm": { "type": "boolean", "description": "Must be true to actually launch the send." } } } } }, "description": "Launch a campaign to its audience \u2014 REAL, MASS, BILLABLE outbound, no sandbox. Confirm-gated: call without confirm to get a summary + prerequisites (nothing is sent), then re-call with confirm=true to actually launch (Celery-batched send). Blocked for suspended/grace-period orgs. Requires campaigns:send." }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/communications/calls": { "get": { "tags": [ "Channels" ], "summary": "List voice calls", "operationId": "list_voice_calls_v1_communications_calls_get", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "contact_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Contact Id" } }, { "name": "direction", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "inbound | outbound.", "title": "Direction" }, "description": "inbound | outbound." }, { "name": "call_status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Call Status" } }, { "name": "call_type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "e.g. human, ai.", "title": "Call Type" }, "description": "e.g. human, ai." }, { "name": "channel", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "phone | webrtc.", "title": "Channel" }, "description": "phone | webrtc." }, { "name": "provider", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Provider" } }, { "name": "start_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO date/time; created_at >= this.", "title": "Start Date" }, "description": "ISO date/time; created_at >= this." }, { "name": "end_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO date/time; created_at <= this.", "title": "End Date" }, "description": "ISO date/time; created_at <= this." }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 200, "minimum": 1 }, { "type": "null" } ], "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ], "title": "Offset" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/communications/calls/{call_id}": { "get": { "tags": [ "Channels" ], "summary": "Get a voice call (with transcription)", "operationId": "get_voice_call_v1_communications_calls__call_id__get", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "call_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Call Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/communications/whatsapp": { "get": { "tags": [ "Channels" ], "summary": "List WhatsApp conversations", "operationId": "list_whatsapp_conversations_v1_communications_whatsapp_get", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Search contact name / phone / last message.", "title": "Q" }, "description": "Search contact name / phone / last message." }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "active | paused | closed | archived.", "title": "Status" }, "description": "active | paused | closed | archived." }, { "name": "assigned_to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent email the thread is assigned to.", "title": "Assigned To" }, "description": "Agent email the thread is assigned to." }, { "name": "unread_only", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Unread Only" } }, { "name": "integration_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Integration Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 200, "minimum": 1 }, { "type": "null" } ], "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ], "title": "Offset" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/communications/whatsapp/{conversation_id}": { "get": { "tags": [ "Channels" ], "summary": "Get a WhatsApp conversation", "operationId": "get_whatsapp_conversation_v1_communications_whatsapp__conversation_id__get", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Conversation Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/communications/whatsapp/{conversation_id}/messages": { "get": { "tags": [ "Channels" ], "summary": "List messages in a WhatsApp conversation", "operationId": "list_whatsapp_messages_v1_communications_whatsapp__conversation_id__messages_get", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Conversation Id" } }, { "name": "direction", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "inbound | outbound.", "title": "Direction" }, "description": "inbound | outbound." }, { "name": "message_type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "text | image | document | audio | video | \u2026", "title": "Message Type" }, "description": "text | image | document | audio | video | \u2026" }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 200, "minimum": 1 }, { "type": "null" } ], "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ], "title": "Offset" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/communications/sms": { "get": { "tags": [ "Channels" ], "summary": "List SMS activity", "operationId": "list_sms_messages_v1_communications_sms_get", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "sent | delivered | failed | clicked.", "title": "Status" }, "description": "sent | delivered | failed | clicked." }, { "name": "campaign_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Campaign Id" } }, { "name": "phone_number", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Phone Number" } }, { "name": "start_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO date/time; created_at >= this.", "title": "Start Date" }, "description": "ISO date/time; created_at >= this." }, { "name": "end_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO date/time; created_at <= this.", "title": "End Date" }, "description": "ISO date/time; created_at <= this." }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 200, "minimum": 1 }, { "type": "null" } ], "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ], "title": "Offset" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/integrations/catalog": { "get": { "tags": [ "Settings" ], "summary": "Browse the catalog of connectable integration types", "operationId": "list_available_integrations_v1_integrations_catalog_get", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "category", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "e.g. llm, email, database, messaging, storage, voice.", "title": "Category" }, "description": "e.g. llm, email, database, messaging, storage, voice." }, { "name": "type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A single integration type slug (e.g. openai).", "title": "Type" }, "description": "A single integration type slug (e.g. openai)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/integrations": { "get": { "tags": [ "Settings" ], "summary": "List the org's connected integrations", "operationId": "list_integrations_v1_integrations_get", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by integration_type (e.g. openai).", "title": "Type" }, "description": "Filter by integration_type (e.g. openai)." }, { "name": "active_only", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Only active integrations (default true).", "title": "Active Only" }, "description": "Only active integrations (default true)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/integrations/{integration_id}": { "get": { "tags": [ "Settings" ], "summary": "Get one connected integration", "operationId": "get_integration_v1_integrations__integration_id__get", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "integration_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Integration Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/integrations/{integration_id}/test": { "post": { "tags": [ "Settings" ], "summary": "Run a connection test for one integration (side-effecting; requires integrations:write)", "operationId": "test_integration_v1_integrations__integration_id__test_post", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "integration_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Integration Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/webhooks/incoming": { "get": { "tags": [ "Settings" ], "summary": "List incoming webhooks", "operationId": "list_incoming_webhooks_v1_webhooks_incoming_get", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "used_by", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Include the workflows each webhook is wired to.", "title": "Used By" }, "description": "Include the workflows each webhook is wired to." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "tags": [ "Settings" ], "summary": "Create an incoming webhook (returns secret once)", "operationId": "create_incoming_webhook_v1_webhooks_incoming_post", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "`slug` required; optional name/description/expected_schema/is_active.", "title": "Body" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/webhooks/incoming/{webhook_id}": { "get": { "tags": [ "Settings" ], "summary": "Get an incoming webhook", "operationId": "get_incoming_webhook_v1_webhooks_incoming__webhook_id__get", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Webhook Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "patch": { "tags": [ "Settings" ], "summary": "Update an incoming webhook", "operationId": "update_incoming_webhook_v1_webhooks_incoming__webhook_id__patch", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Webhook Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "Any writable field (partial update).", "title": "Body" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "delete": { "tags": [ "Settings" ], "summary": "Delete an incoming webhook (reference-checked)", "operationId": "delete_incoming_webhook_v1_webhooks_incoming__webhook_id__delete", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Webhook Id" } }, { "name": "force", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Delete even if workflows depend on it.", "title": "Force" }, "description": "Delete even if workflows depend on it." }, { "name": "permanent", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Hard delete (default false).", "title": "Permanent" }, "description": "Hard delete (default false)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/webhooks/incoming/{webhook_id}/regenerate-secret": { "post": { "tags": [ "Settings" ], "summary": "Rotate an incoming webhook secret", "operationId": "regenerate_incoming_webhook_secret_v1_webhooks_incoming__webhook_id__regenerate_secret_post", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Webhook Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/webhooks/incoming/{webhook_id}/logs": { "get": { "tags": [ "Settings" ], "summary": "Incoming webhook request logs", "operationId": "get_incoming_webhook_logs_v1_webhooks_incoming__webhook_id__logs_get", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Webhook Id" } }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" } }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 200, "minimum": 1 }, { "type": "null" } ], "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/webhooks/event-types": { "get": { "tags": [ "Settings" ], "summary": "List subscribable outgoing webhook event types", "operationId": "list_webhook_event_types_v1_webhooks_event_types_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/webhooks/outgoing": { "get": { "tags": [ "Settings" ], "summary": "List outgoing webhooks", "operationId": "list_outgoing_webhooks_v1_webhooks_outgoing_get", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "webhook_type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "automatic | manual.", "title": "Webhook Type" }, "description": "automatic | manual." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "tags": [ "Settings" ], "summary": "Create an outgoing webhook (SSRF-validated; returns secret once)", "operationId": "create_outgoing_webhook_v1_webhooks_outgoing_post", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "`name`, `url`, `events[]` required; optional webhook_type/is_active/retry_count/timeout_seconds.", "title": "Body" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/webhooks/outgoing/{webhook_id}": { "get": { "tags": [ "Settings" ], "summary": "Get an outgoing webhook", "operationId": "get_outgoing_webhook_v1_webhooks_outgoing__webhook_id__get", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Webhook Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "patch": { "tags": [ "Settings" ], "summary": "Update an outgoing webhook", "operationId": "update_outgoing_webhook_v1_webhooks_outgoing__webhook_id__patch", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Webhook Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "Any writable field (partial update).", "title": "Body" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "delete": { "tags": [ "Settings" ], "summary": "Delete an outgoing webhook", "operationId": "delete_outgoing_webhook_v1_webhooks_outgoing__webhook_id__delete", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Webhook Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/webhooks/outgoing/{webhook_id}/test": { "post": { "tags": [ "Settings" ], "summary": "Send a test delivery (real POST, billing-gated)", "operationId": "test_outgoing_webhook_v1_webhooks_outgoing__webhook_id__test_post", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Webhook Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "additionalProperties": true }, { "type": "null" } ], "description": "Optional `test_data` object.", "title": "Body" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/workflows/{workflow_id}/blueprint": { "get": { "tags": [ "Automation" ], "summary": "Read a workflow's blueprint", "operationId": "get_blueprint_v1_workflows__workflow_id__blueprint_get", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "workflow_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Workflow Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "put": { "tags": [ "Automation" ], "summary": "Create or replace a workflow's blueprint", "operationId": "set_blueprint_v1_workflows__workflow_id__blueprint_put", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "workflow_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Workflow Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "{blueprint:{blocks,edges}} or top-level {blocks,edges}.", "title": "Payload" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "delete": { "tags": [ "Automation" ], "summary": "Clear a workflow's blueprint", "operationId": "delete_blueprint_v1_workflows__workflow_id__blueprint_delete", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "workflow_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Workflow Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/workflows/{workflow_id}/blueprint/validate": { "post": { "tags": [ "Automation" ], "summary": "Validate a workflow's stored blueprint", "operationId": "validate_stored_blueprint_v1_workflows__workflow_id__blueprint_validate_post", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "workflow_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Workflow Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/blueprints": { "get": { "tags": [ "Automation" ], "summary": "List workflows that have a blueprint", "operationId": "list_blueprints_v1_blueprints_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/blueprints/validate": { "post": { "tags": [ "Automation" ], "summary": "Validate an inline blueprint definition", "operationId": "validate_inline_blueprint_v1_blueprints_validate_post", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "title": "Payload", "description": "{blueprint:{blocks,edges}} or top-level {blocks,edges}." } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "bearerAuth": [] } ] } } }, "components": { "schemas": { "Activity": { "type": "object", "title": "Activities", "description": "A activity record (fields exposed by the public API).", "properties": { "id": { "type": "string" }, "activity_type": { "type": "string" }, "activity_subtype": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "entity_type": { "type": "string" }, "entity_id": { "type": "string" }, "contact_id": { "type": "string" }, "company_id": { "type": "string" }, "deal_id": { "type": "string" }, "performed_by_email": { "type": "string" }, "performed_at": { "type": "string" } } }, "ActivityCreate": { "additionalProperties": false, "properties": { "activity_type": { "description": "e.g. call, email, note (required).", "maxLength": 64, "title": "Activity Type", "type": "string" }, "entity_type": { "description": "contact|company|deal (required).", "maxLength": 32, "title": "Entity Type", "type": "string" }, "entity_id": { "description": "Linked record id (required).", "title": "Entity Id", "type": "string" }, "activity_subtype": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "default": null, "title": "Activity Subtype" }, "title": { "anyOf": [ { "maxLength": 512, "type": "string" }, { "type": "null" } ], "default": null, "title": "Title" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Description" }, "contact_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Contact Id" }, "company_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Company Id" }, "deal_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Deal Id" } }, "required": [ "activity_type", "entity_type", "entity_id" ], "title": "ActivityCreate", "type": "object" }, "ActivityList": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Activity" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } }, "ActivityUpdate": { "additionalProperties": false, "properties": { "activity_subtype": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "default": null, "title": "Activity Subtype" }, "title": { "anyOf": [ { "maxLength": 512, "type": "string" }, { "type": "null" } ], "default": null, "title": "Title" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Description" } }, "title": "ActivityUpdate", "type": "object" }, "Company": { "type": "object", "title": "Companies", "description": "A company record (fields exposed by the public API).", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "domain": { "type": "string" }, "website": { "type": "string" }, "industry": { "type": "string" }, "company_type": { "type": "string" }, "size": { "type": "string" }, "annual_revenue": { "type": "number" }, "description": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "country": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": "string" }, "linkedin_url": { "type": "string" }, "source": { "type": "string" }, "status": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "custom_fields": { "type": "object", "additionalProperties": true }, "owner_email": { "type": "string" }, "created_by_email": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } } }, "CompanyCreate": { "additionalProperties": false, "properties": { "name": { "description": "Company name (required).", "maxLength": 255, "title": "Name", "type": "string" }, "domain": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "default": null, "title": "Domain" }, "website": { "anyOf": [ { "maxLength": 512, "type": "string" }, { "type": "null" } ], "default": null, "title": "Website" }, "industry": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "default": null, "title": "Industry" }, "company_type": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "default": null, "title": "Company Type" }, "size": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "default": null, "title": "Size" }, "annual_revenue": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Annual Revenue" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Description" }, "city": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "default": null, "title": "City" }, "state": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "default": null, "title": "State" }, "country": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "default": null, "title": "Country" }, "phone": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "default": null, "title": "Phone" }, "email": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "default": null, "title": "Email" }, "linkedin_url": { "anyOf": [ { "maxLength": 512, "type": "string" }, { "type": "null" } ], "default": null, "title": "Linkedin Url" }, "source": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "default": null, "title": "Source" }, "status": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "default": null, "title": "Status" }, "owner_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Owner Email" }, "tags": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Tags" }, "custom_fields": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Custom Fields" } }, "required": [ "name" ], "title": "CompanyCreate", "type": "object" }, "CompanyList": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Company" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } }, "CompanyUpdate": { "additionalProperties": false, "properties": { "name": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "default": null, "title": "Name" }, "domain": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "default": null, "title": "Domain" }, "website": { "anyOf": [ { "maxLength": 512, "type": "string" }, { "type": "null" } ], "default": null, "title": "Website" }, "industry": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "default": null, "title": "Industry" }, "company_type": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "default": null, "title": "Company Type" }, "size": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "default": null, "title": "Size" }, "annual_revenue": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Annual Revenue" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Description" }, "city": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "default": null, "title": "City" }, "state": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "default": null, "title": "State" }, "country": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "default": null, "title": "Country" }, "phone": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "default": null, "title": "Phone" }, "email": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "default": null, "title": "Email" }, "linkedin_url": { "anyOf": [ { "maxLength": 512, "type": "string" }, { "type": "null" } ], "default": null, "title": "Linkedin Url" }, "source": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "default": null, "title": "Source" }, "status": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "default": null, "title": "Status" }, "owner_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Owner Email" }, "tags": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Tags" }, "custom_fields": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Custom Fields" } }, "title": "CompanyUpdate", "type": "object" }, "Contact": { "type": "object", "title": "Contacts", "description": "A contact record (fields exposed by the public API).", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "phone": { "type": "string" }, "mobile": { "type": "string" }, "job_title": { "type": "string" }, "department": { "type": "string" }, "lead_status": { "type": "string" }, "lead_score": { "type": "integer" }, "source": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "country": { "type": "string" }, "linkedin_url": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "custom_fields": { "type": "object", "additionalProperties": true }, "owner_email": { "type": "string" }, "created_by_email": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } } }, "ContactCreate": { "additionalProperties": false, "properties": { "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Primary email (recommended; used for dedup).", "title": "Email" }, "first_name": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "default": null, "title": "First Name" }, "last_name": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Name" }, "phone": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "default": null, "title": "Phone" }, "mobile": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "default": null, "title": "Mobile" }, "job_title": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "default": null, "title": "Job Title" }, "department": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "default": null, "title": "Department" }, "lead_status": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "default": null, "title": "Lead Status" }, "lead_score": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Lead Score" }, "source": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "default": null, "title": "Source" }, "city": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "default": null, "title": "City" }, "state": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "default": null, "title": "State" }, "country": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "default": null, "title": "Country" }, "linkedin_url": { "anyOf": [ { "maxLength": 512, "type": "string" }, { "type": "null" } ], "default": null, "title": "Linkedin Url" }, "owner_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Assign an owner; omit to leave unassigned.", "title": "Owner Email" }, "tags": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Tags" }, "custom_fields": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "Org-defined fields; auto-registered.", "title": "Custom Fields" } }, "title": "ContactCreate", "type": "object" }, "ContactList": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } }, "ContactUpdate": { "additionalProperties": false, "properties": { "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Email" }, "first_name": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "default": null, "title": "First Name" }, "last_name": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Name" }, "phone": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "default": null, "title": "Phone" }, "mobile": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "default": null, "title": "Mobile" }, "job_title": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "default": null, "title": "Job Title" }, "department": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "default": null, "title": "Department" }, "lead_status": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "default": null, "title": "Lead Status" }, "lead_score": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Lead Score" }, "source": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "default": null, "title": "Source" }, "city": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "default": null, "title": "City" }, "state": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "default": null, "title": "State" }, "country": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "default": null, "title": "Country" }, "linkedin_url": { "anyOf": [ { "maxLength": 512, "type": "string" }, { "type": "null" } ], "default": null, "title": "Linkedin Url" }, "owner_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Owner Email" }, "tags": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Tags" }, "custom_fields": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Custom Fields" } }, "title": "ContactUpdate", "type": "object" }, "Deal": { "type": "object", "title": "Deals", "description": "A deal record (fields exposed by the public API).", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "number" }, "currency": { "type": "string" }, "stage_name": { "type": "string" }, "probability": { "type": "integer" }, "deal_type": { "type": "string" }, "expected_close_date": { "type": "string" }, "description": { "type": "string" }, "next_step": { "type": "string" }, "source": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "is_won": { "type": "boolean" }, "is_lost": { "type": "boolean" }, "deal_status": { "type": "string" }, "custom_fields": { "type": "object", "additionalProperties": true }, "owner_email": { "type": "string" }, "created_by_email": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } } }, "DealCreate": { "additionalProperties": false, "properties": { "name": { "description": "Deal name (required).", "maxLength": 255, "title": "Name", "type": "string" }, "value": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Value" }, "currency": { "anyOf": [ { "maxLength": 8, "type": "string" }, { "type": "null" } ], "default": null, "title": "Currency" }, "stage_name": { "anyOf": [ { "maxLength": 128, "type": "string" }, { "type": "null" } ], "default": null, "title": "Stage Name" }, "probability": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Probability" }, "deal_type": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "default": null, "title": "Deal Type" }, "expected_close_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "ISO date (YYYY-MM-DD).", "title": "Expected Close Date" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Description" }, "next_step": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Next Step" }, "source": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "default": null, "title": "Source" }, "owner_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Owner Email" }, "tags": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Tags" }, "custom_fields": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Custom Fields" } }, "required": [ "name" ], "title": "DealCreate", "type": "object" }, "DealList": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Deal" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } }, "DealUpdate": { "additionalProperties": false, "properties": { "name": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "default": null, "title": "Name" }, "value": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Value" }, "currency": { "anyOf": [ { "maxLength": 8, "type": "string" }, { "type": "null" } ], "default": null, "title": "Currency" }, "stage_name": { "anyOf": [ { "maxLength": 128, "type": "string" }, { "type": "null" } ], "default": null, "title": "Stage Name" }, "probability": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Probability" }, "deal_type": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "default": null, "title": "Deal Type" }, "expected_close_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Expected Close Date" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Description" }, "next_step": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Next Step" }, "source": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "default": null, "title": "Source" }, "owner_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Owner Email" }, "tags": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Tags" }, "custom_fields": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Custom Fields" } }, "title": "DealUpdate", "type": "object" }, "DeleteResult": { "type": "object", "required": [ "deleted", "id" ], "properties": { "deleted": { "type": "boolean" }, "id": { "type": "string" } } }, "ErrorEnvelope": { "type": "object", "description": "The uniform error shape returned by every /v1 endpoint.", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "type", "message", "request_id" ], "properties": { "type": { "type": "string", "description": "Machine-readable error type, e.g. not_found, forbidden, rate_limited." }, "message": { "type": "string", "description": "Human-readable explanation." }, "request_id": { "type": "string", "description": "Correlation id \u2014 quote it in support requests." }, "param": { "type": "string", "description": "The offending parameter, when applicable." } } } } }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "Note": { "type": "object", "title": "Notes", "description": "A note record (fields exposed by the public API).", "properties": { "id": { "type": "string" }, "content": { "type": "string" }, "entity_type": { "type": "string" }, "entity_id": { "type": "string" }, "is_pinned": { "type": "boolean" }, "created_by_email": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } } }, "NoteCreate": { "additionalProperties": false, "properties": { "content": { "description": "Note body (required).", "title": "Content", "type": "string" }, "entity_type": { "description": "Linked entity: contact|company|deal (required).", "maxLength": 32, "title": "Entity Type", "type": "string" }, "entity_id": { "description": "Linked record id (required).", "title": "Entity Id", "type": "string" }, "is_pinned": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Is Pinned" } }, "required": [ "content", "entity_type", "entity_id" ], "title": "NoteCreate", "type": "object" }, "NoteList": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Note" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } }, "NoteUpdate": { "additionalProperties": false, "properties": { "content": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Content" }, "is_pinned": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Is Pinned" } }, "title": "NoteUpdate", "type": "object" }, "Pagination": { "type": "object", "required": [ "limit", "offset", "total", "has_more" ], "properties": { "limit": { "type": "integer" }, "offset": { "type": "integer" }, "total": { "type": "integer" }, "has_more": { "type": "boolean" } } }, "Task": { "type": "object", "title": "Tasks", "description": "A task record (fields exposed by the public API).", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "type": { "type": "string" }, "priority": { "type": "string" }, "status": { "type": "string" }, "contact_id": { "type": "string" }, "company_id": { "type": "string" }, "deal_id": { "type": "string" }, "due_date": { "type": "string" }, "reminder_date": { "type": "string" }, "completed_at": { "type": "string" }, "assigned_to_email": { "type": "string" }, "assigned_by_email": { "type": "string" }, "created_by_email": { "type": "string" }, "entity_type": { "type": "string" }, "entity_id": { "type": "string" }, "labels": { "type": "string" }, "source": { "type": "string" }, "task_number": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } } }, "TaskCreate": { "additionalProperties": false, "properties": { "title": { "description": "Task title (required).", "maxLength": 512, "title": "Title", "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Description" }, "type": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "default": null, "title": "Type" }, "priority": { "anyOf": [ { "maxLength": 32, "type": "string" }, { "type": "null" } ], "default": null, "title": "Priority" }, "status": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "default": null, "title": "Status" }, "contact_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Contact Id" }, "company_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Company Id" }, "deal_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Deal Id" }, "due_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "ISO timestamp.", "title": "Due Date" }, "reminder_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Reminder Date" }, "assigned_to_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Assigned To Email" }, "entity_type": { "anyOf": [ { "maxLength": 32, "type": "string" }, { "type": "null" } ], "default": null, "title": "Entity Type" }, "entity_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Entity Id" }, "labels": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Labels" }, "source": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "default": null, "title": "Source" } }, "required": [ "title" ], "title": "TaskCreate", "type": "object" }, "TaskList": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Task" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } }, "TaskUpdate": { "additionalProperties": false, "properties": { "title": { "anyOf": [ { "maxLength": 512, "type": "string" }, { "type": "null" } ], "default": null, "title": "Title" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Description" }, "type": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "default": null, "title": "Type" }, "priority": { "anyOf": [ { "maxLength": 32, "type": "string" }, { "type": "null" } ], "default": null, "title": "Priority" }, "status": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "default": null, "title": "Status" }, "contact_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Contact Id" }, "company_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Company Id" }, "deal_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Deal Id" }, "due_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Due Date" }, "reminder_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Reminder Date" }, "assigned_to_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Assigned To Email" }, "labels": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Labels" } }, "title": "TaskUpdate", "type": "object" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" } }, "securitySchemes": { "bearerAuth": { "type": "http", "description": "Scoped API key. Send as: Authorization: Bearer agx_", "scheme": "bearer" } } }, "servers": [ { "url": "https://api.expedify.ai", "description": "Production" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "CRM Objects" }, { "name": "Workflows" }, { "name": "Automation" }, { "name": "Knowledge Base" }, { "name": "Analytics" }, { "name": "Channels" }, { "name": "Settings" } ] }