{ "openapi": "3.0.0", "info": { "title": "Weav API", "description": "API for Weav customer support platform. Access your organization's data via REST API.", "contact": { "email": "support@weav.com" }, "version": "1.0.0" }, "servers": [ { "url": "https://api.weav.com/v1", "description": "Production API" }, { "url": "https://staging.api.weav.com/v1", "description": "Staging API" }, { "url": "https://api.weav.test/v1", "description": "Local Development API" }, { "url": "{scheme}://{host}/v1", "description": "Current Domain API", "variables": { "scheme": { "enum": [ "http", "https" ], "default": "https" }, "host": { "enum": [ "api.weav.test", "weav.test", "api.weav.com", "weav.com", "staging.api.weav.com", "staging.weav.com" ], "default": "api.weav.com" } } }, { "url": "/v1" } ], "paths": { "/agents": { "get": { "tags": [ "Agents" ], "summary": "List agents", "description": "Retrieve a paginated list of agents for the authenticated organization", "operationId": "listAgents", "parameters": [ { "name": "per_page", "in": "query", "description": "Number of results per page (max 100)", "required": false, "schema": { "type": "integer", "default": 15, "maximum": 100, "minimum": 1 } }, { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Agent" } }, "links": { "type": "object" }, "meta": { "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_token": [] } ] }, "post": { "tags": [ "Agents" ], "summary": "Create agent", "description": "Create a new AI agent for the authenticated organization", "operationId": "createAgent", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 255, "example": "Agent" }, "description": { "type": "string", "example": "Helps customers with support queries", "nullable": true }, "avatar_url": { "type": "string", "format": "url", "example": "https://example.com/avatar.png", "nullable": true }, "max_messages_per_session": { "type": "integer", "maximum": 1000, "minimum": 1, "example": 50, "nullable": true }, "tone": { "type": "string", "maxLength": 255, "example": "professional", "nullable": true }, "response_length": { "type": "string", "maxLength": 255, "example": "standard", "nullable": true }, "is_active": { "type": "boolean", "example": true, "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Agent created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agent" } } } }, "400": { "description": "Validation error" }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_token": [] } ] } }, "/agents/{id}": { "get": { "tags": [ "Agents" ], "summary": "Get agent", "description": "Retrieve a specific agent by ID", "operationId": "getAgent", "parameters": [ { "name": "id", "in": "path", "description": "Agent UUID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agent" } } } }, "404": { "description": "Agent not found" }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_token": [] } ] }, "put": { "tags": [ "Agents" ], "summary": "Update agent", "description": "Update an existing agent. Cannot update copilot agents.", "operationId": "updateAgent", "parameters": [ { "name": "id", "in": "path", "description": "Agent UUID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string", "maxLength": 255, "example": "Updated Agent" }, "description": { "type": "string", "nullable": true }, "avatar_url": { "type": "string", "format": "url", "nullable": true }, "max_messages_per_session": { "type": "integer", "maximum": 1000, "minimum": 1, "nullable": true }, "tone": { "type": "string", "maxLength": 255, "nullable": true }, "is_active": { "type": "boolean", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Agent updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agent" } } } }, "400": { "description": "Validation error" }, "403": { "description": "Cannot update copilot agent" }, "404": { "description": "Agent not found" }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_token": [] } ] }, "delete": { "tags": [ "Agents" ], "summary": "Delete agent", "description": "Delete an agent. Cannot delete copilot agents.", "operationId": "deleteAgent", "parameters": [ { "name": "id", "in": "path", "description": "Agent UUID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Agent deleted successfully" }, "403": { "description": "Cannot delete copilot agent" }, "404": { "description": "Agent not found" }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_token": [] } ] } }, "/companies": { "get": { "tags": [ "Companies" ], "summary": "List companies", "operationId": "8c30cae472156af573ebed0f9b508f5d", "parameters": [ { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 15, "maximum": 100, "minimum": 1 } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Company" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_token": [] } ] }, "post": { "tags": [ "Companies" ], "summary": "Create company", "operationId": "53c99c1dbab21944ae473bcd2eea78b1", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 50 }, "domain": { "type": "string", "maxLength": 255, "nullable": true }, "country": { "description": "ISO 3166-1 alpha-2 country code (2 uppercase letters)", "type": "string", "pattern": "^[A-Z]{2}$", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Company" } } } }, "400": { "description": "Validation error" }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_token": [] } ] } }, "/companies/{id}": { "get": { "tags": [ "Companies" ], "summary": "Get company", "operationId": "6bcef3e66e7dd383562bbd82b0e7d177", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Company" } } } }, "404": { "description": "Not found" }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_token": [] } ] }, "put": { "tags": [ "Companies" ], "summary": "Update company", "operationId": "b5a14b796f969f3667b76f1708d8315d", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string", "maxLength": 50 }, "domain": { "type": "string", "nullable": true }, "country": { "description": "ISO 3166-1 alpha-2 country code (2 uppercase letters)", "type": "string", "pattern": "^[A-Z]{2}$", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Company" } } } }, "400": { "description": "Validation error" }, "404": { "description": "Not found" }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_token": [] } ] }, "delete": { "tags": [ "Companies" ], "summary": "Delete company", "operationId": "7646601cd279669697906cea4ba08303", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Deleted" }, "404": { "description": "Not found" }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_token": [] } ] } }, "/companies/{id}/customers": { "get": { "tags": [ "Companies" ], "summary": "List customers for company", "operationId": "baa7ed741c0df0ea44ca0afd294c9120", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 15, "maximum": 100, "minimum": 1 } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Customer" } } }, "type": "object" } } } }, "404": { "description": "Not found" }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_token": [] } ] } }, "/conversations": { "get": { "tags": [ "Conversations" ], "summary": "List conversations", "operationId": "28ce1d49bf0e4363ade14e99e8dddce8", "parameters": [ { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 15, "maximum": 100, "minimum": 1 } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "status", "in": "query", "description": "Filter by status", "schema": { "type": "string", "enum": [ "open", "closed" ] } }, { "name": "channel", "in": "query", "description": "Filter by channel", "schema": { "type": "string", "enum": [ "email", "chat" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Conversation" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_token": [] } ] }, "post": { "tags": [ "Conversations" ], "summary": "Create conversation", "description": "Create a new conversation. Assignment Rules: assignees must belong to the same workspace as the API key. Chat conversations can be assigned to users (or left unassigned). Agent assignment is limited to the conversation's original chat agent. Email conversations can be assigned to users, left unassigned, or assigned only to the workspace's active email agent.", "operationId": "5dba86bca25346f993c15c78dc86da33", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "channel", "customer_id" ], "properties": { "channel": { "description": "Conversation channel type", "type": "string", "enum": [ "email", "chat" ] }, "customer_id": { "description": "ID of the customer", "type": "string", "format": "uuid" }, "subject": { "type": "string", "maxLength": 500, "nullable": true }, "status": { "description": "Conversation status", "type": "string", "default": "open", "enum": [ "open", "closed" ], "nullable": true }, "priority": { "description": "Conversation priority", "type": "string", "default": "normal", "enum": [ "low", "normal", "high", "urgent" ], "nullable": true }, "assignee_id": { "description": "ID of user or agent to assign conversation to. Must belong to the same workspace. For chat, agent assignments are limited to the conversation's original chat agent. For email, only the active email agent can be assigned as agent.", "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000", "nullable": true }, "assignee_type": { "description": "Type of assignee. Defaults to 'user' when assignee_id is provided and assignee_type is omitted.", "type": "string", "enum": [ "user", "agent" ], "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Conversation created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conversation" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearer_token": [] } ] } }, "/conversations/{id}": { "get": { "tags": [ "Conversations" ], "summary": "Get conversation", "operationId": "4e00a8b19288ab0ae8e53f6d57afaa48", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conversation" } } } }, "404": { "description": "Not found" }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_token": [] } ] }, "put": { "tags": [ "Conversations" ], "summary": "Update conversation", "description": "Update an existing conversation. Assignment Rules: assignees must belong to the same workspace as the API key. Chat conversations can be assigned to users, left unassigned, or only to the conversation's original chat agent. Email conversations can be assigned to users, left unassigned, or only to the workspace's active email agent.", "operationId": "9ed9c1eb549ba9aec68b897a016b92c0", "parameters": [ { "name": "id", "in": "path", "description": "Conversation UUID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "subject": { "type": "string", "maxLength": 500, "nullable": true }, "status": { "type": "string", "enum": [ "open", "closed" ], "nullable": true }, "priority": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ], "nullable": true }, "assignee_id": { "description": "ID of user or agent to assign conversation to. Set to null to unassign. Must belong to the same workspace. For chat, agent assignments are limited to the conversation's original chat agent. For email, only the active email agent can be assigned as agent.", "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000", "nullable": true }, "assignee_type": { "description": "Type of assignee. Defaults to 'user' if assignee_id is provided and assignee_type is omitted.", "type": "string", "enum": [ "user", "agent" ], "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Conversation updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conversation" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Conversation not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearer_token": [] } ] }, "delete": { "tags": [ "Conversations" ], "summary": "Delete conversation", "operationId": "ef8d8082c18586e5bbfc0a49e4d91933", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Deleted" }, "404": { "description": "Not found" }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_token": [] } ] } }, "/conversations/{id}/messages": { "get": { "tags": [ "Conversations" ], "summary": "List messages in conversation", "operationId": "dd58e4322fb4f77a11e1af79a9b6c356", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 15, "maximum": 100, "minimum": 1 } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } } }, "type": "object" } } } }, "404": { "description": "Not found" }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_token": [] } ] } }, "/customers": { "get": { "tags": [ "Customers" ], "summary": "List customers", "operationId": "5ceb8c7bd923b627f6a2fae9d3a86181", "parameters": [ { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 15, "maximum": 100, "minimum": 1 } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "is_lead", "in": "query", "description": "Filter by leads", "schema": { "type": "boolean" } }, { "name": "email", "in": "query", "description": "Filter by email", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Customer" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_token": [] } ] }, "post": { "tags": [ "Customers" ], "summary": "Create customer", "operationId": "d6f7134be437e446e15b4d1c84c043e8", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" }, "first_name": { "type": "string", "nullable": true }, "last_name": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true }, "locale": { "type": "string", "nullable": true }, "country": { "type": "string", "nullable": true }, "region": { "type": "string", "maxLength": 10, "nullable": true }, "city": { "type": "string", "maxLength": 64, "nullable": true }, "timezone": { "type": "string", "maxLength": 64, "nullable": true }, "language": { "type": "string", "maxLength": 35, "nullable": true }, "company_id": { "type": "string", "format": "uuid", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "400": { "description": "Validation error" }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_token": [] } ] } }, "/customers/{id}": { "get": { "tags": [ "Customers" ], "summary": "Get customer", "operationId": "ac942c4c67d04225abffdc1957907656", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "404": { "description": "Not found" }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_token": [] } ] }, "put": { "tags": [ "Customers" ], "summary": "Update customer", "operationId": "57f4e626bb8299f353545cbfa9cd73d4", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "email": { "type": "string", "format": "email" }, "first_name": { "type": "string", "nullable": true }, "last_name": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true }, "locale": { "type": "string", "nullable": true }, "country": { "type": "string", "nullable": true }, "region": { "type": "string", "maxLength": 10, "nullable": true }, "city": { "type": "string", "maxLength": 64, "nullable": true }, "timezone": { "type": "string", "maxLength": 64, "nullable": true }, "language": { "type": "string", "maxLength": 35, "nullable": true }, "company_id": { "type": "string", "format": "uuid", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "400": { "description": "Validation error" }, "404": { "description": "Not found" }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_token": [] } ] }, "delete": { "tags": [ "Customers" ], "summary": "Delete customer", "operationId": "a0d24bb8331e322ba5f70c2c324aa473", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Deleted" }, "404": { "description": "Not found" }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_token": [] } ] } }, "/customers/{id}/conversations": { "get": { "tags": [ "Customers" ], "summary": "List customer conversations", "operationId": "c355218324654a24f7126d11980cf470", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 15, "maximum": 100, "minimum": 1 } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Conversation" } } }, "type": "object" } } } }, "404": { "description": "Not found" }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_token": [] } ] } }, "/kb-articles": { "get": { "tags": [ "Articles" ], "summary": "List articles", "operationId": "8dc17671fc77b3214f45f7dd44341d90", "parameters": [ { "name": "category_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "draft", "published" ] } }, { "name": "updated_since", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 15, "maximum": 100, "minimum": 1 } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/KbArticle" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_token": [] } ] }, "post": { "tags": [ "Articles" ], "summary": "Create article", "description": "Lazily creates the organization's knowledge base if this is its first write. Accepts one or more locale translations.", "operationId": "f0ed577360cb83a23a8b8c1cd74e1dfa", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "translations" ], "properties": { "category_id": { "type": "string", "format": "uuid", "nullable": true }, "status": { "description": "Defaults to draft", "type": "string", "enum": [ "draft", "published" ], "nullable": true }, "translations": { "type": "array", "items": { "required": [ "locale", "title", "content" ], "properties": { "locale": { "type": "string", "maxLength": 10, "example": "en" }, "title": { "type": "string", "maxLength": 255 }, "content": { "description": "Markdown body", "type": "string" }, "excerpt": { "description": "Also used as the meta description", "type": "string", "nullable": true }, "slug": { "description": "Auto-generated from title when omitted", "type": "string", "maxLength": 255, "nullable": true }, "seo_title": { "description": "Search and social title; the page heading remains title", "type": "string", "maxLength": 255, "nullable": true }, "noindex": { "description": "Hide this translation from search engines", "type": "boolean" }, "canonical_url": { "description": "Absolute HTTP(S) URL", "type": "string", "format": "uri", "maxLength": 2048, "nullable": true }, "og_image_url": { "description": "HTTPS social preview image", "type": "string", "format": "uri", "maxLength": 2048, "nullable": true } }, "type": "object" }, "minItems": 1 } }, "type": "object" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KbArticle" } } } }, "422": { "description": "Invalid category, validation error, duplicate locale, or slug already taken", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_token": [] } ] } }, "/kb-articles/{id}": { "get": { "tags": [ "Articles" ], "summary": "Get article", "operationId": "6ea4ab0cfb3039fb2343926334aee7b8", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KbArticle" } } } }, "404": { "description": "Not found" }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_token": [] } ] }, "put": { "tags": [ "Articles" ], "summary": "Update article", "description": "Updating an existing locale's title, content, excerpt, or slug records a revision of its prior content. SEO-only changes do not create a revision. Adding a new locale requires both title and content.", "operationId": "ef549ad5a37f2a396d03233d16f61030", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "category_id": { "type": "string", "format": "uuid", "nullable": true }, "status": { "type": "string", "enum": [ "draft", "published" ], "nullable": true }, "translations": { "type": "array", "items": { "required": [ "locale" ], "properties": { "locale": { "type": "string", "maxLength": 10, "example": "en" }, "title": { "type": "string", "maxLength": 255 }, "content": { "description": "Markdown body", "type": "string" }, "excerpt": { "description": "Also used as the meta description", "type": "string", "nullable": true }, "slug": { "type": "string", "maxLength": 255, "nullable": true }, "seo_title": { "description": "Search and social title; the page heading remains title", "type": "string", "maxLength": 255, "nullable": true }, "noindex": { "description": "Hide this translation from search engines", "type": "boolean" }, "canonical_url": { "description": "Absolute HTTP(S) URL", "type": "string", "format": "uri", "maxLength": 2048, "nullable": true }, "og_image_url": { "description": "HTTPS social preview image", "type": "string", "format": "uri", "maxLength": 2048, "nullable": true } }, "type": "object" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KbArticle" } } } }, "422": { "description": "Invalid category, validation error, duplicate locale, incomplete new translation, or slug already taken", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found" }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_token": [] } ] }, "delete": { "tags": [ "Articles" ], "summary": "Delete article", "description": "Soft-deletes the article.", "operationId": "276fac02f688be577cbf2242485df2f2", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Deleted" }, "404": { "description": "Not found" }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_token": [] } ] } }, "/kb-articles/reorder": { "post": { "tags": [ "Articles" ], "summary": "Reorder articles", "description": "Assign display positions 0..n-1 for every article in one category group. Pass `category_id: null` for the uncategorized group.", "operationId": "83c7fa54bde2d80f5c9be433f82a7df5", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "category_id", "ids" ], "properties": { "category_id": { "type": "string", "format": "uuid", "nullable": true }, "ids": { "type": "array", "items": { "type": "string", "format": "uuid" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Articles reordered", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/KbArticle" } } }, "type": "object" } } } }, "422": { "description": "Validation error" }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_token": [] } ] } }, "/kb-articles/{id}/publish": { "post": { "tags": [ "Articles" ], "summary": "Publish article", "description": "Sets status to published and records published_at (preserved across further edits; reset on the next publish after an unpublish). Immediately visible on the public read surface.", "operationId": "eae82440a321af53e336386dbc90d71c", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KbArticle" } } } }, "404": { "description": "Not found" }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_token": [] } ] } }, "/kb-articles/{id}/unpublish": { "post": { "tags": [ "Articles" ], "summary": "Unpublish article", "description": "Sets status back to draft and clears published_at. Removed from the public read surface immediately.", "operationId": "e167293cd4202d5898c67038df0f7df1", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KbArticle" } } } }, "404": { "description": "Not found" }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_token": [] } ] } }, "/kb-articles/{id}/images": { "post": { "tags": [ "Articles" ], "summary": "Upload article image", "operationId": "747efce00be001524a742da0c11bfe88", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "image" ], "properties": { "image": { "description": "JPEG, PNG, GIF, or WebP image up to 5 MB", "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "201": { "description": "Image uploaded", "content": { "application/json": { "schema": { "properties": { "url": { "type": "string", "format": "uri" }, "key": { "type": "string" } }, "type": "object" } } } } }, "security": [ { "bearer_token": [] } ] }, "delete": { "tags": [ "Articles" ], "summary": "Delete article image", "operationId": "9351ddf8e5513013014b01c67d5ccd47", "responses": { "204": { "description": "Image deleted" } }, "security": [ { "bearer_token": [] } ] } }, "/kb-articles/{id}/revisions": { "get": { "tags": [ "Articles" ], "summary": "List article revisions", "operationId": "b1b7ab2c81555c226a37148504612416", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "locale", "in": "query", "schema": { "type": "string", "maxLength": 10 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 15, "maximum": 100, "minimum": 1 } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/KbArticleRevision" } } }, "type": "object" } } } }, "404": { "description": "Not found" }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_token": [] } ] } }, "/kb-articles/{id}/revisions/{revisionId}": { "get": { "tags": [ "Articles" ], "summary": "Get article revision", "operationId": "3de6d0520d02fb6c440788747ce8ec98", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "revisionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KbArticleRevision" } } } }, "404": { "description": "Not found" }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_token": [] } ] } }, "/kb-articles/{id}/revisions/{revisionId}/restore": { "post": { "tags": [ "Articles" ], "summary": "Restore article revision", "description": "Snapshots the translation's current content as a new revision, then overwrites it with the selected revision's content.", "operationId": "2f134e491aa18b6ac69dea6dd2f23488", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "revisionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KbArticle" } } } }, "404": { "description": "Not found, or no current translation exists for the revision's locale" }, "422": { "description": "Revision's slug is now used by another translation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_token": [] } ] } }, "/kb-categories": { "get": { "tags": [ "Categories" ], "summary": "List categories", "operationId": "7263209e64c91a48f016df8d6d72741f", "parameters": [ { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 15, "maximum": 100, "minimum": 1 } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/KbCategory" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_token": [] } ] }, "post": { "tags": [ "Categories" ], "summary": "Create category", "description": "Lazily creates the organization's knowledge base if this is its first write.", "operationId": "5c49bd4ad2187e47ae85ba76e480cef5", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 255 }, "slug": { "description": "Auto-generated from name when omitted", "type": "string", "maxLength": 255, "nullable": true }, "section_id": { "type": "string", "format": "uuid", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KbCategory" } } } }, "422": { "description": "Validation error or slug already taken", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_token": [] } ] } }, "/kb-categories/{id}": { "get": { "tags": [ "Categories" ], "summary": "Get category", "operationId": "1306749b9154cb6a09d5e76d761e39a2", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KbCategory" } } } }, "404": { "description": "Not found" }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_token": [] } ] }, "put": { "tags": [ "Categories" ], "summary": "Update category", "operationId": "c9b4934c31a452b807cd0b8fcaf862ad", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string", "maxLength": 255 }, "slug": { "type": "string", "maxLength": 255, "nullable": true }, "section_id": { "type": "string", "format": "uuid", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KbCategory" } } } }, "422": { "description": "Validation error or slug already taken" }, "404": { "description": "Not found" }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_token": [] } ] }, "delete": { "tags": [ "Categories" ], "summary": "Delete category", "description": "Soft-deletes the category and clears it from articles that referenced it.", "operationId": "b6cb22cf22e2dc6a413868f4e00f8c51", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Deleted" }, "404": { "description": "Not found" }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_token": [] } ] } }, "/kb-categories/reorder": { "post": { "tags": [ "Categories" ], "summary": "Reorder categories", "description": "Assign display positions 0..n-1 for every category in the knowledge base.", "operationId": "f2c08f4220c9145b7b1f6f8c3ed010ac", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "ids" ], "properties": { "ids": { "type": "array", "items": { "type": "string", "format": "uuid" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Categories reordered", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/KbCategory" } } }, "type": "object" } } } }, "422": { "description": "Validation error" }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_token": [] } ] } }, "/kb": { "get": { "tags": [ "Knowledge Base" ], "summary": "Get knowledge base", "operationId": "2fecaf5d4b85a7d02eea459921632803", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "properties": { "id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "logo_url": { "type": "string", "nullable": true }, "improvement_enabled": { "type": "boolean" }, "mcp_enabled": { "type": "boolean" }, "social_links": { "properties": { "x": { "type": "string", "nullable": true }, "linkedin": { "type": "string", "nullable": true }, "facebook": { "type": "string", "nullable": true }, "instagram": { "type": "string", "nullable": true }, "youtube": { "type": "string", "nullable": true }, "github": { "type": "string", "nullable": true }, "discord": { "type": "string", "nullable": true }, "website": { "type": "string", "nullable": true } }, "type": "object" }, "banner": { "description": "Current public KB announcement banner settings.", "properties": { "enabled": { "type": "boolean" }, "content": { "description": "One line of inline Markdown. Blank content is returned as null.", "type": "string", "maxLength": 300, "nullable": true }, "dismissible": { "type": "boolean" }, "type": { "type": "string", "default": "info", "enum": [ "info", "warning", "critical" ] }, "light_color": { "type": "string", "pattern": "^#?[0-9A-Fa-f]{6}$", "nullable": true }, "dark_color": { "type": "string", "pattern": "^#?[0-9A-Fa-f]{6}$", "nullable": true } }, "type": "object" }, "seo": { "description": "Organization SEO controls; all defaults preserve existing indexing behavior.", "properties": { "indexing_enabled": { "type": "boolean" }, "description": { "type": "string", "maxLength": 300, "nullable": true }, "agent_instructions": { "description": "Instructions for AI agents; line breaks are preserved.", "type": "string", "maxLength": 2000, "nullable": true }, "og_image_url": { "description": "HTTPS URL for the organization's default social preview image.", "type": "string", "format": "uri", "maxLength": 2048, "nullable": true }, "verification": { "properties": { "google": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$", "nullable": true }, "bing": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$", "nullable": true }, "yandex": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$", "nullable": true } }, "type": "object" }, "content_signals": { "properties": { "ai_train": { "type": "boolean" }, "search": { "type": "boolean" }, "ai_input": { "type": "boolean" } }, "type": "object" } }, "type": "object" }, "sitemap_url": { "type": "string", "format": "uri" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_token": [] } ] }, "patch": { "tags": [ "Knowledge Base" ], "summary": "Update knowledge base settings", "operationId": "a5d451ec4676e92c5c9eadbf5588034a", "requestBody": { "description": "Send improvement_enabled, mcp_enabled, social_links, banner, seo, or any combination.", "required": true, "content": { "application/json": { "schema": { "properties": { "improvement_enabled": { "description": "Whether teammate corrections can propose KB drafts.", "type": "boolean" }, "mcp_enabled": { "description": "Whether the public MCP server and WebMCP tools are available at the KB's /mcp URL.", "type": "boolean" }, "social_links": { "description": "Partial HTTP(S) URLs, merged with stored links; null or empty removes a link.", "properties": { "x": { "type": "string", "nullable": true }, "linkedin": { "type": "string", "nullable": true }, "facebook": { "type": "string", "nullable": true }, "instagram": { "type": "string", "nullable": true }, "youtube": { "type": "string", "nullable": true }, "github": { "type": "string", "nullable": true }, "discord": { "type": "string", "nullable": true }, "website": { "type": "string", "nullable": true } }, "type": "object" }, "banner": { "description": "Partial banner update. Enabling a banner requires nonblank content.", "properties": { "enabled": { "description": "Cannot be true unless content is nonblank.", "type": "boolean" }, "content": { "description": "One line of inline Markdown (links, bold, italic, and inline code). Leading/trailing whitespace is trimmed; CR and LF are rejected.", "type": "string", "maxLength": 300, "nullable": true }, "dismissible": { "type": "boolean" }, "type": { "description": "Default background colors are #2052EB for info, #B45309 for warning, and #B91C1C for critical.", "type": "string", "default": "info", "enum": [ "info", "warning", "critical" ] }, "light_color": { "description": "Optional 6-digit hex background override for light mode.", "type": "string", "pattern": "^#?[0-9A-Fa-f]{6}$", "nullable": true }, "dark_color": { "description": "Optional 6-digit hex background override for dark mode.", "type": "string", "pattern": "^#?[0-9A-Fa-f]{6}$", "nullable": true } }, "type": "object" }, "seo": { "description": "Partial SEO settings update; values omitted from nested objects are preserved.", "properties": { "indexing_enabled": { "type": "boolean" }, "description": { "description": "One line of plain text. HTML is stripped; ampersands are preserved.", "type": "string", "maxLength": 300, "nullable": true }, "agent_instructions": { "description": "Instructions for AI agents; HTML is stripped and line breaks are preserved.", "type": "string", "maxLength": 2000, "nullable": true }, "og_image_url": { "description": "HTTPS URL for the organization's default social preview image.", "type": "string", "format": "uri", "maxLength": 2048, "nullable": true }, "verification": { "description": "Provider code or a full pasted provider meta tag.", "properties": { "google": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$", "nullable": true }, "bing": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$", "nullable": true }, "yandex": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$", "nullable": true } }, "type": "object" }, "content_signals": { "properties": { "ai_train": { "type": "boolean" }, "search": { "type": "boolean" }, "ai_input": { "type": "boolean" } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "properties": { "seo": { "properties": { "indexing_enabled": { "type": "boolean" }, "description": { "type": "string", "maxLength": 300, "nullable": true }, "agent_instructions": { "description": "Instructions for AI agents; line breaks are preserved.", "type": "string", "maxLength": 2000, "nullable": true }, "og_image_url": { "type": "string", "format": "uri", "maxLength": 2048, "nullable": true }, "verification": { "properties": { "google": { "type": "string", "nullable": true }, "bing": { "type": "string", "nullable": true }, "yandex": { "type": "string", "nullable": true } }, "type": "object" }, "content_signals": { "properties": { "ai_train": { "type": "boolean" }, "search": { "type": "boolean" }, "ai_input": { "type": "boolean" } }, "type": "object" } }, "type": "object" }, "sitemap_url": { "type": "string", "format": "uri" } }, "type": "object" } } } }, "422": { "description": "Validation error" } }, "security": [ { "bearer_token": [] } ] } }, "/kb/logo": { "post": { "tags": [ "Knowledge Base" ], "summary": "Upload knowledge base logo", "operationId": "1a30acd86ae0e8cbfca8bb3feb431158", "responses": { "200": { "description": "Logo uploaded" } }, "security": [ { "bearer_token": [] } ] }, "delete": { "tags": [ "Knowledge Base" ], "summary": "Delete knowledge base logo", "operationId": "b7fd2279e816bc13cdcf89a2d43e6487", "responses": { "200": { "description": "Logo removed" } }, "security": [ { "bearer_token": [] } ] } }, "/kb-proposals": { "get": { "tags": [ "Proposals" ], "summary": "List improvement proposals", "operationId": "4ec9612ba23bee71ff82c309dd111a54", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "needs_decision", "published", "dismissed", "ignored" ] } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 15, "maximum": 100, "minimum": 1 } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 } } ], "responses": { "200": { "description": "Success" }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_token": [] } ] } }, "/kb-proposals/{id}": { "get": { "tags": [ "Proposals" ], "summary": "Get improvement proposal", "operationId": "a3beab90d94ddefa7ebc4c590ccdaa73", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success" }, "404": { "description": "Not found" } }, "security": [ { "bearer_token": [] } ] }, "patch": { "tags": [ "Proposals" ], "summary": "Set proposal category", "operationId": "cf999816b39291ece57a8eed1ef24d95", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "category_id" ], "properties": { "category_id": { "type": "string", "format": "uuid", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Category updated" }, "422": { "description": "The category does not belong to this knowledge base" }, "409": { "description": "The proposal is not an open create proposal" } }, "security": [ { "bearer_token": [] } ] } }, "/kb-proposals/{id}/publish": { "post": { "tags": [ "Proposals" ], "summary": "Publish improvement proposal", "operationId": "ce0dbf92401cd4337328f9274472c390", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Published" }, "409": { "description": "The proposal could not be published" } }, "security": [ { "bearer_token": [] } ] } }, "/kb-proposals/{id}/dismiss": { "post": { "tags": [ "Proposals" ], "summary": "Dismiss improvement proposal", "operationId": "157529ccea55ebc7f8801cd50f3b20fe", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Dismissed" }, "409": { "description": "The proposal could not be dismissed" } }, "security": [ { "bearer_token": [] } ] } }, "/kb-proposals/{id}/revise": { "post": { "tags": [ "Proposals" ], "summary": "Revise improvement proposal", "operationId": "93a3d7a470274a4191492365289d24d5", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "instruction" ], "properties": { "instruction": { "type": "string", "maxLength": 2000 } }, "type": "object" } } } }, "responses": { "200": { "description": "Revised" }, "409": { "description": "The proposal could not be revised" } }, "security": [ { "bearer_token": [] } ] } }, "/kb-proposals/{id}/choose": { "post": { "tags": [ "Proposals" ], "summary": "Choose proposal version", "operationId": "948d2904eaa2e8733797943b67a6e474", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "choice" ], "properties": { "choice": { "type": "string", "enum": [ "current", "incoming", "merged" ] } }, "type": "object" } } } }, "responses": { "200": { "description": "Chosen; the proposal is pending again. While a proposal has status needs_decision, its evidence.decision holds the summary plus the current, incoming and merged versions ({title, content}) that can be chosen." }, "409": { "description": "The proposal is not waiting for a decision" } }, "security": [ { "bearer_token": [] } ] } }, "/kb-redirects": { "get": { "tags": [ "Redirects" ], "summary": "List redirects", "operationId": "4d11f2e4782d539e57c8e5ed4b80c259", "parameters": [ { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 15, "maximum": 100, "minimum": 1 } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/KbRedirect" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_token": [] } ] }, "post": { "tags": [ "Redirects" ], "summary": "Create or update redirect", "operationId": "45b976eb816d4806580fa231995c965b", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "path", "article_id" ], "properties": { "path": { "type": "string", "maxLength": 255 }, "article_id": { "type": "string", "format": "uuid" }, "locale": { "type": "string", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KbRedirect" } } } }, "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KbRedirect" } } } }, "422": { "description": "Invalid path or target" } }, "security": [ { "bearer_token": [] } ] } }, "/kb-redirects/{id}": { "delete": { "tags": [ "Redirects" ], "summary": "Delete redirect", "operationId": "2d4194524b1326b014fe1b3a9d783382", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Deleted" }, "404": { "description": "Not found" } }, "security": [ { "bearer_token": [] } ] } }, "/kb-search": { "get": { "tags": [ "Search" ], "summary": "Search articles", "operationId": "b64ee745ec33cd788c10aec503fd61af", "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "locale", "in": "query", "description": "Defaults to the organization's default_locale when omitted", "schema": { "type": "string", "maxLength": 10 } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "draft", "published" ] } }, { "name": "category_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "uncategorized", "in": "query", "schema": { "type": "boolean" } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 15, "maximum": 100, "minimum": 1 } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/KbArticle" } }, "meta": { "properties": { "search_method": { "type": "string", "enum": [ "keyword" ] } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_token": [] } ] } }, "/kb-sections": { "get": { "tags": [ "Sections" ], "summary": "List sections", "operationId": "aa5900809f65b6209e327f2122ac4353", "parameters": [ { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 15, "maximum": 100, "minimum": 1 } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/KbSection" } } }, "type": "object" } } } } }, "security": [ { "bearer_token": [] } ] }, "post": { "tags": [ "Sections" ], "summary": "Create section", "operationId": "0d6b7c50b0a20916e2cb991d6970ccc5", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name" ], "properties": { "name": { "type": "string" }, "slug": { "type": "string", "nullable": true }, "position": { "type": "integer", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KbSection" } } } }, "422": { "description": "Validation error or slug already taken" } }, "security": [ { "bearer_token": [] } ] } }, "/kb-sections/{id}": { "get": { "tags": [ "Sections" ], "summary": "Get section", "operationId": "c25de45f9433a06755b69b37eae0ba25", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KbSection" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_token": [] } ] }, "put": { "tags": [ "Sections" ], "summary": "Update section", "operationId": "92677ce4793ada49d9e707edd57cd030", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string" }, "slug": { "type": "string", "nullable": true }, "position": { "type": "integer", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KbSection" } } } }, "422": { "description": "Validation error or slug already taken" }, "404": { "description": "Not found" } }, "security": [ { "bearer_token": [] } ] }, "delete": { "tags": [ "Sections" ], "summary": "Delete section", "operationId": "c6e2519ef76ba0f0a3677b203464f3d0", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Deleted" }, "404": { "description": "Not found" } }, "security": [ { "bearer_token": [] } ] } }, "/kb-sections/reorder": { "post": { "tags": [ "Sections" ], "summary": "Reorder sections", "operationId": "607b73f52ca4adcaa68a85288d19abbb", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "ids" ], "properties": { "ids": { "type": "array", "items": { "type": "string", "format": "uuid" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Sections reordered" }, "422": { "description": "Section order does not match this knowledge base" } }, "security": [ { "bearer_token": [] } ] } }, "/messages": { "get": { "tags": [ "Messages" ], "summary": "List messages", "operationId": "b320285ecd3a99368d22eae71b351877", "parameters": [ { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 15, "maximum": 100, "minimum": 1 } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "conversation_id", "in": "query", "description": "Filter by conversation", "schema": { "type": "string", "format": "uuid" } }, { "name": "sender_type", "in": "query", "description": "Filter by sender type", "schema": { "type": "string", "enum": [ "customer", "user", "agent", "system" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_token": [] } ] }, "post": { "tags": [ "Messages" ], "summary": "Create message", "description": "Note: API currently validates sender_type as customer|user. The API does not accept `metadata` or `is_ai_assisted` in requests.", "operationId": "11580c70ad5d49b93225f803f230fccf", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "conversation_id", "sender_type", "content" ], "properties": { "conversation_id": { "type": "string", "format": "uuid" }, "sender_type": { "type": "string", "enum": [ "customer", "user" ] }, "sender_id": { "type": "string", "format": "uuid", "nullable": true }, "content": { "type": "string" } }, "type": "object" } } } }, "responses": { "201": { "description": "Message created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } } }, "400": { "description": "Validation error" }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_token": [] } ] } }, "/messages/{id}": { "get": { "tags": [ "Messages" ], "summary": "Get message", "operationId": "319e64f60188bdfcc18bed0aaed04aba", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } } }, "404": { "description": "Not found" }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_token": [] } ] }, "delete": { "tags": [ "Messages" ], "summary": "Delete message", "operationId": "3eaf2583977fced1bca5147d0011e52a", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Deleted" }, "404": { "description": "Not found" }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_token": [] } ] } }, "/training-data": { "get": { "tags": [ "Training Data" ], "summary": "List training data", "operationId": "438b0dee42247e04e5c6e83173e398ec", "parameters": [ { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 15, "maximum": 100, "minimum": 1 } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "type", "in": "query", "description": "Filter by type", "schema": { "type": "string", "enum": [ "text", "url", "file", "video", "qa" ] } }, { "name": "status", "in": "query", "description": "Filter by status", "schema": { "type": "string", "enum": [ "queued", "processing", "completed", "failed" ] } }, { "name": "is_processed", "in": "query", "description": "Filter by processed status", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TrainingData" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_token": [] } ] }, "post": { "tags": [ "Training Data" ], "summary": "Create training data", "description": "Create training data. Supports multiple types: text, url, file, video, qa. Processing happens automatically in the background.", "operationId": "04bd6c5d046e4714c9bbef456cd5ecaf", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "text", "url", "file", "video", "qa" ], "example": "text" }, "content": { "description": "Required for type='text'", "type": "string", "example": "Your text content here" }, "url": { "description": "Required for type='url'", "type": "string", "format": "url", "example": "https://example.com" }, "file": { "description": "Required for type='file' (multipart/form-data)", "type": "string", "format": "binary" }, "video_url": { "description": "Required for type='video'", "type": "string", "format": "url", "example": "https://youtube.com/watch?v=..." }, "question": { "description": "Required for type='qa'", "type": "string", "example": "What is your return policy?" }, "answer": { "description": "Required for type='qa'", "type": "string", "example": "Our return policy allows returns within 30 days." }, "title": { "type": "string", "maxLength": 255, "nullable": true }, "description": { "type": "string", "nullable": true }, "agent_ids": { "description": "Array of agent UUIDs to attach this training data to", "type": "array", "items": { "type": "string", "format": "uuid" }, "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Training data created. Processing will happen in background.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrainingData" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Business rule violation (for example, URL requires discovery workflow)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Creation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearer_token": [] } ] } }, "/training-data/url/process": { "post": { "tags": [ "Training Data" ], "summary": "Process URLs into training data", "description": "Creates URL training data from the provided URLs. In production, URL processing jobs are queued and run asynchronously.", "operationId": "897d7d399234663cb4b95b292c5cf94c", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "urls" ], "properties": { "urls": { "type": "array", "items": { "type": "string", "format": "url" } }, "title": { "type": "string", "maxLength": 255, "nullable": true }, "agent_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "nullable": true }, "auto_resync": { "type": "boolean", "example": false, "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "URLs accepted for processing", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "training_data": { "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "slug": { "type": "string" }, "status": { "type": "string", "example": "completed" } }, "type": "object" }, "urls_count": { "type": "integer", "example": 2 } }, "type": "object" } } } }, "422": { "description": "Validation or business rule failure (for example, NO_URLS_PROVIDED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Failed to process URLs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearer_token": [] } ] } }, "/training-data/url/exists": { "get": { "tags": [ "Training Data" ], "summary": "Check if a URL already exists", "description": "Checks whether a normalized URL already exists in completed URL training data for the current organization.", "operationId": "0f2c827b79b4cd45fe031ddf1b868180", "parameters": [ { "name": "url", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 2048 }, "example": "https://www.example.com/docs/" } ], "responses": { "200": { "description": "URL existence check result", "content": { "application/json": { "schema": { "properties": { "exists": { "type": "boolean", "example": true } }, "type": "object" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_token": [] } ] } }, "/training-data/{id}/resync-now": { "post": { "tags": [ "Training Data" ], "summary": "Manually trigger URL resync", "operationId": "9474d020a467dc1cebbbca9c97f2cf84", "parameters": [ { "name": "id", "in": "path", "description": "URL training data UUID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Resync jobs dispatched", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string" }, "data": { "properties": { "training_data_id": { "type": "string", "format": "uuid" }, "urls_count": { "type": "integer", "example": 3 } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "URL training data not found in current organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Resync unavailable for this URL training data state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_token": [] } ] } }, "/training-data/{id}": { "get": { "tags": [ "Training Data" ], "summary": "Get training data", "operationId": "9c2c1f5e0b163547651c7f85d8e9aec6", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrainingData" } } } }, "404": { "description": "Not found" }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_token": [] } ] }, "put": { "tags": [ "Training Data" ], "summary": "Update training data", "description": "The API does not accept `metadata` in requests.", "operationId": "1922bed8a564bc6ef5be3a0968845939", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "maxLength": 255, "nullable": true }, "description": { "type": "string", "nullable": true }, "agent_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrainingData" } } } }, "400": { "description": "Validation error" }, "404": { "description": "Not found" }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_token": [] } ] }, "delete": { "tags": [ "Training Data" ], "summary": "Delete training data", "operationId": "103c23627028aeac57f0880e48678255", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Deleted" }, "404": { "description": "Not found" }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_token": [] } ] } } }, "components": { "schemas": { "Error": { "title": "Error Response", "properties": { "error": { "type": "string", "example": "Error message" }, "code": { "type": "string", "example": "ERROR_CODE", "nullable": true }, "errors": { "type": "object", "nullable": true } }, "type": "object" }, "Agent": { "title": "Agent", "description": "AI agent resource", "properties": { "id": { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000" }, "name": { "type": "string", "example": "Agent" }, "slug": { "type": "string", "example": "agent" }, "description": { "type": "string", "example": "Helps customers with support queries", "nullable": true }, "avatar_url": { "type": "string", "format": "url", "example": "https://example.com/avatar.png", "nullable": true }, "max_messages_per_session": { "type": "integer", "example": 50, "nullable": true }, "tone": { "type": "string", "example": "professional", "nullable": true }, "response_length": { "type": "string", "example": "standard", "nullable": true }, "is_active": { "type": "boolean", "example": true }, "is_copilot": { "type": "boolean", "example": false }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" }, "Company": { "title": "Company", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "Acme Corp" }, "domain": { "type": "string", "example": "acme.com" }, "country": { "type": "string", "example": "US", "nullable": true }, "avatar_url": { "type": "string", "format": "url", "nullable": true }, "first_seen_at": { "type": "string", "format": "date-time", "nullable": true }, "last_seen_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" }, "Conversation": { "title": "Conversation", "properties": { "id": { "type": "string", "format": "uuid" }, "channel": { "type": "string", "enum": [ "email", "chat" ] }, "customer_id": { "type": "string", "format": "uuid" }, "subject": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "open", "closed" ] }, "priority": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ] }, "assignee_id": { "description": "ID of the assigned user or agent. Assignees must belong to the same workspace. Chat conversations can only use the original chat agent when assigning an agent. Email conversations can only use the active email agent when assigning an agent.", "type": "string", "format": "uuid", "nullable": true }, "assignee_type": { "description": "Type of assignee: 'user' for users or 'agent' for AI agents.", "type": "string", "enum": [ "user", "agent" ], "nullable": true }, "closed_at": { "type": "string", "format": "date-time", "nullable": true }, "first_response_at": { "type": "string", "format": "date-time", "nullable": true }, "last_message_at": { "type": "string", "format": "date-time", "nullable": true }, "is_spam": { "type": "boolean" }, "spam_score": { "type": "number", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" }, "Customer": { "title": "Customer", "properties": { "id": { "type": "string", "format": "uuid" }, "first_name": { "type": "string", "example": "John", "nullable": true }, "last_name": { "type": "string", "example": "Doe", "nullable": true }, "email": { "type": "string", "format": "email", "example": "john@example.com" }, "phone": { "type": "string", "nullable": true }, "locale": { "type": "string", "example": "en", "nullable": true }, "country": { "type": "string", "nullable": true }, "region": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "timezone": { "type": "string", "nullable": true }, "language": { "type": "string", "nullable": true }, "company_id": { "type": "string", "format": "uuid", "nullable": true }, "avatar_url": { "type": "string", "format": "url", "nullable": true }, "first_seen_at": { "type": "string", "format": "date-time", "nullable": true }, "last_seen_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" }, "KbArticle": { "title": "Knowledge Base Article", "properties": { "id": { "type": "string", "format": "uuid" }, "category_id": { "type": "string", "format": "uuid", "nullable": true }, "position": { "type": "integer", "nullable": true }, "status": { "type": "string", "enum": [ "draft", "published" ] }, "published_at": { "type": "string", "format": "date-time", "nullable": true }, "source": { "type": "string", "enum": [ "manual", "auto_generated", "github", "mcp" ] }, "translations": { "type": "array", "items": { "$ref": "#/components/schemas/KbArticleTranslation" } }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" }, "KbArticleRevision": { "title": "Knowledge Base Article Revision", "properties": { "id": { "type": "string", "format": "uuid" }, "locale": { "type": "string", "example": "en" }, "title": { "type": "string" }, "slug": { "type": "string" }, "content": { "description": "Markdown body", "type": "string" }, "excerpt": { "type": "string", "nullable": true }, "created_by_user_id": { "type": "string", "format": "uuid", "nullable": true }, "mcp_client_name": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" }, "KbArticleTranslation": { "title": "Knowledge Base Article Translation", "properties": { "locale": { "type": "string", "example": "en" }, "title": { "type": "string" }, "slug": { "type": "string" }, "content": { "description": "Markdown body", "type": "string" }, "excerpt": { "description": "Also used as the meta description", "type": "string", "nullable": true }, "seo_title": { "description": "Search and social title; the page heading remains title", "type": "string", "maxLength": 255, "nullable": true }, "noindex": { "description": "Hide this translation from search engines", "type": "boolean" }, "canonical_url": { "type": "string", "format": "uri", "maxLength": 2048, "nullable": true }, "og_image_url": { "type": "string", "format": "uri", "maxLength": 2048, "nullable": true }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" }, "KbCategory": { "title": "Knowledge Base Category", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" }, "section_id": { "type": "string", "format": "uuid", "nullable": true }, "position": { "type": "integer", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" }, "KbRedirect": { "title": "Knowledge Base Redirect", "properties": { "id": { "type": "string", "format": "uuid" }, "path": { "type": "string" }, "article_id": { "type": "string", "format": "uuid" }, "locale": { "type": "string" }, "created_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" }, "KbSection": { "title": "Knowledge Base Section", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" }, "position": { "type": "integer", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" }, "Message": { "title": "Message", "properties": { "id": { "type": "string", "format": "uuid" }, "conversation_id": { "type": "string", "format": "uuid" }, "sender_type": { "type": "string", "enum": [ "customer", "user", "agent", "system" ] }, "sender_id": { "type": "string", "format": "uuid", "nullable": true }, "customer_id": { "type": "string", "format": "uuid", "nullable": true }, "content": { "type": "string" }, "sent_at": { "type": "string", "format": "date-time" }, "is_internal": { "type": "boolean" }, "from": { "type": "array", "items": { "type": "string" }, "nullable": true }, "to": { "type": "array", "items": { "type": "string" }, "nullable": true }, "cc": { "type": "array", "items": { "type": "string" }, "nullable": true }, "bcc": { "type": "array", "items": { "type": "string" }, "nullable": true }, "email_status": { "type": "string", "nullable": true }, "email_error_message": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" }, "TrainingData": { "title": "Training Data", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "text", "url", "file", "video", "qa" ] }, "source": { "type": "string" }, "title": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "slug": { "type": "string", "nullable": true }, "is_processed": { "type": "boolean" }, "status": { "type": "string", "enum": [ "queued", "processing", "completed", "failed" ], "nullable": true }, "training_folder_id": { "type": "string", "format": "uuid", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" } }, "securitySchemes": { "bearer_token": { "type": "http", "scheme": "bearer", "bearerFormat": "Token", "description": "Enter your API token in the format: Bearer {token}" } } }, "tags": [ { "name": "Agents", "description": "AI agent management endpoints" }, { "name": "Companies", "description": "Company management endpoints" }, { "name": "Conversations", "description": "Conversation management endpoints" }, { "name": "Customers", "description": "Customer management endpoints" }, { "name": "Messages", "description": "Message management endpoints" }, { "name": "Training Data", "description": "Training data management endpoints" }, { "name": "Knowledge Base", "description": "Knowledge Base management endpoints" }, { "name": "Articles", "description": "Knowledge Base article endpoints" }, { "name": "Categories", "description": "Knowledge Base category endpoints" }, { "name": "Sections", "description": "Knowledge Base section endpoints" }, { "name": "Proposals", "description": "Knowledge Base improvement proposal endpoints" }, { "name": "Redirects", "description": "Knowledge Base redirect endpoints" }, { "name": "Search", "description": "Knowledge Base search endpoints" } ], "security": [ { "bearer_token": [] } ] }