id of an existing record in the domains table.",
"example": 16,
"nullable": true
},
"source_tags": {
"type": "array",
"description": "Optional tags to filter which training sources are searched.",
"example": [
"enterprise",
"pricing"
],
"items": {
"type": "string"
}
},
"language": {
"type": "string",
"description": "Optional 2-character language code.",
"example": "en",
"nullable": true
},
"response_format": {
"type": "string",
"description": "",
"example": "html",
"enum": [
"plaintext",
"markdown",
"html"
],
"nullable": true
},
"current_page": {
"type": "object",
"description": "Optional current-page context shown to the AI so it can disambiguate questions like \"when is the training?\" by knowing which page the visitor is on.",
"example": [],
"properties": {
"url": {
"type": "string",
"description": "Page URL (host + path, no query).",
"example": "example.com/trainings/leadership",
"nullable": true
},
"title": {
"type": "string",
"description": "Page title.",
"example": "Leadership Training May 2026",
"nullable": true
}
},
"nullable": true
},
"is_test": {
"type": "boolean",
"description": "",
"example": true,
"nullable": true
},
"attachments": {
"type": "array",
"description": "Must not have more than 5 items.",
"example": null,
"items": {
"type": "object",
"nullable": true,
"properties": {
"url": {
"type": "string",
"description": "This field is required when attachments is present. Must not be greater than 2048 characters.",
"example": "http://breitenberg.com/nostrum-aut-adipisci-quidem-nostrum.html"
},
"name": {
"type": "string",
"description": "This field is required when attachments is present. Must not be greater than 255 characters.",
"example": "l"
},
"size": {
"type": "integer",
"description": "Must be at least 0. Must not be greater than 10485760.",
"example": 20,
"nullable": true
},
"mime": {
"type": "string",
"description": "Must not be greater than 100 characters.",
"example": "q",
"nullable": true
}
}
}
}
},
"required": [
"message"
]
}
}
}
}
},
"parameters": [
{
"in": "path",
"name": "chatbot_id",
"description": "The chatbot UUID.",
"example": "8a832d1b-0f49-47f6-a05f-0b65b91d2107",
"required": true,
"schema": {
"type": "string"
}
}
]
},
"/api/v1/chatbots/{chatbot_id}/conversations/{conversation_id}": {
"get": {
"summary": "Get Conversation",
"operationId": "getConversation",
"description": "Retrieve conversation history and metadata.",
"parameters": [],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"example": {
"conversation_id": "550e8400-e29b-41d4-a716-446655440000",
"chatbot_id": "bot_123",
"messages": [
{
"id": "msg_001",
"role": "user",
"content": "What's your pricing?",
"created_at": "2026-01-29T10:30:00Z"
},
{
"id": "msg_002",
"role": "assistant",
"content": "Our pricing starts at...",
"sources": [],
"created_at": "2026-01-29T10:30:05Z"
}
],
"contact": {
"email": "john@example.com",
"name": "John Doe"
},
"created_at": "2026-01-29T10:30:00Z",
"message_count": 4
},
"properties": {
"conversation_id": {
"type": "string",
"example": "550e8400-e29b-41d4-a716-446655440000"
},
"chatbot_id": {
"type": "string",
"example": "bot_123"
},
"messages": {
"type": "array",
"example": [
{
"id": "msg_001",
"role": "user",
"content": "What's your pricing?",
"created_at": "2026-01-29T10:30:00Z"
},
{
"id": "msg_002",
"role": "assistant",
"content": "Our pricing starts at...",
"sources": [],
"created_at": "2026-01-29T10:30:05Z"
}
],
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "msg_001"
},
"role": {
"type": "string",
"example": "user"
},
"content": {
"type": "string",
"example": "What's your pricing?"
},
"created_at": {
"type": "string",
"example": "2026-01-29T10:30:00Z"
}
}
}
},
"contact": {
"type": "object",
"properties": {
"email": {
"type": "string",
"example": "john@example.com"
},
"name": {
"type": "string",
"example": "John Doe"
}
}
},
"created_at": {
"type": "string",
"example": "2026-01-29T10:30:00Z"
},
"message_count": {
"type": "integer",
"example": 4
}
}
}
}
}
}
},
"tags": [
"Chatbot Messages"
]
},
"parameters": [
{
"in": "path",
"name": "chatbot_id",
"description": "The chatbot UUID.",
"example": "8a832d1b-0f49-47f6-a05f-0b65b91d2107",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "path",
"name": "conversation_id",
"description": "The conversation UUID.",
"example": "550e8400-e29b-41d4-a716-446655440000",
"required": true,
"schema": {
"type": "string"
}
}
]
},
"/api/v1/chatbots/{chatbot_id}/conversations/{conversation_id}/messages": {
"get": {
"summary": "Poll New Messages",
"operationId": "pollNewMessages",
"description": "Poll for new messages in a conversation (typically used while waiting\nfor or chatting with a human agent). Returns only messages with id\ngreater than `after_id`, plus the current conversation state.\n\nRecommended polling interval: 3-5 seconds while a chat is active.",
"parameters": [
{
"in": "query",
"name": "after_id",
"description": "Optional. Return only messages with id greater than this.",
"example": 12345,
"required": false,
"schema": {
"type": "integer",
"description": "Optional. Return only messages with id greater than this.",
"example": 12345
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"example": {
"conversation_id": "550e8400-e29b-41d4-a716-446655440000",
"mode": "live",
"waiting_for_agent": false,
"agent": {
"name": "Sarah"
},
"is_closed": false,
"messages": [
{
"id": 12346,
"role": "agent",
"sender_name": "Sarah",
"content": "Hi! How can I help?",
"created_at": "2026-05-11T10:30:05Z"
}
],
"last_message_id": 12346
},
"properties": {
"conversation_id": {
"type": "string",
"example": "550e8400-e29b-41d4-a716-446655440000"
},
"mode": {
"type": "string",
"example": "live"
},
"waiting_for_agent": {
"type": "boolean",
"example": false
},
"agent": {
"type": "object",
"properties": {
"name": {
"type": "string",
"example": "Sarah"
}
}
},
"is_closed": {
"type": "boolean",
"example": false
},
"messages": {
"type": "array",
"example": [
{
"id": 12346,
"role": "agent",
"sender_name": "Sarah",
"content": "Hi! How can I help?",
"created_at": "2026-05-11T10:30:05Z"
}
],
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"example": 12346
},
"role": {
"type": "string",
"example": "agent"
},
"sender_name": {
"type": "string",
"example": "Sarah"
},
"content": {
"type": "string",
"example": "Hi! How can I help?"
},
"created_at": {
"type": "string",
"example": "2026-05-11T10:30:05Z"
}
}
}
},
"last_message_id": {
"type": "integer",
"example": 12346
}
}
}
}
}
}
},
"tags": [
"Chatbot Messages"
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"after_id": {
"type": "integer",
"description": "Must be at least 0.",
"example": 27,
"nullable": true
}
}
}
}
}
}
},
"parameters": [
{
"in": "path",
"name": "chatbot_id",
"description": "The chatbot UUID.",
"example": "8a832d1b-0f49-47f6-a05f-0b65b91d2107",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "path",
"name": "conversation_id",
"description": "The conversation UUID.",
"example": "550e8400-e29b-41d4-a716-446655440000",
"required": true,
"schema": {
"type": "string"
}
}
]
},
"/api/v1/chatbots/{chatbot_id}/conversations/{conversation_id}/escalate": {
"post": {
"summary": "Request Live Chat Escalation",
"operationId": "requestLiveChatEscalation",
"description": "Explicitly escalate a conversation to a human agent. The visitor's\nsubsequent messages (via POST /messages) will be delivered to the\nagent instead of generating AI responses. The client should poll\nGET /conversations/{id}/messages for agent replies.",
"parameters": [],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"description": "",
"type": "object",
"example": {
"conversation_id": "550e8400-e29b-41d4-a716-446655440000",
"status": "queued",
"mode": "waiting_for_agent",
"message": "You're in the queue. An agent will join shortly."
},
"properties": {
"conversation_id": {
"type": "string",
"example": "550e8400-e29b-41d4-a716-446655440000"
},
"status": {
"type": "string",
"example": "queued"
},
"mode": {
"type": "string",
"example": "waiting_for_agent"
},
"message": {
"type": "string",
"example": "You're in the queue. An agent will join shortly."
}
}
},
{
"description": "No agents online",
"type": "object",
"example": {
"conversation_id": "550e8400-e29b-41d4-a716-446655440000",
"status": "no_agents_available",
"mode": "ai",
"message": "No agents are currently available."
},
"properties": {
"conversation_id": {
"type": "string",
"example": "550e8400-e29b-41d4-a716-446655440000"
},
"status": {
"type": "string",
"example": "no_agents_available"
},
"mode": {
"type": "string",
"example": "ai"
},
"message": {
"type": "string",
"example": "No agents are currently available."
}
}
}
]
}
}
}
}
},
"tags": [
"Chatbot Messages"
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"description": "Optional short reason shown to agents.",
"example": "User asked to speak to support",
"nullable": true
}
}
}
}
}
}
},
"parameters": [
{
"in": "path",
"name": "chatbot_id",
"description": "The chatbot UUID.",
"example": "8a832d1b-0f49-47f6-a05f-0b65b91d2107",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "path",
"name": "conversation_id",
"description": "The conversation UUID.",
"example": "550e8400-e29b-41d4-a716-446655440000",
"required": true,
"schema": {
"type": "string"
}
}
]
},
"/api/v1/chatbots/{chatbot_id}/websites": {
"get": {
"summary": "List Websites",
"operationId": "listWebsites",
"description": "Get all websites (crawls, sitemaps, bulk uploads) for a chatbot, with page counts per status.",
"parameters": [],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"example": {
"websites": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Sitemap example.com",
"url": "https://example.com/sitemap.xml",
"type": "sitemap",
"status": "completed",
"progress": 100,
"webpages_count": 42,
"sync_frequency": "weekly",
"last_synced_at": "2026-03-12T08:00:00Z",
"created_at": "2026-01-29T10:30:00Z",
"updated_at": "2026-01-29T10:30:00Z"
}
]
},
"properties": {
"websites": {
"type": "array",
"example": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Sitemap example.com",
"url": "https://example.com/sitemap.xml",
"type": "sitemap",
"status": "completed",
"progress": 100,
"webpages_count": 42,
"sync_frequency": "weekly",
"last_synced_at": "2026-03-12T08:00:00Z",
"created_at": "2026-01-29T10:30:00Z",
"updated_at": "2026-01-29T10:30:00Z"
}
],
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "550e8400-e29b-41d4-a716-446655440000"
},
"name": {
"type": "string",
"example": "Sitemap example.com"
},
"url": {
"type": "string",
"example": "https://example.com/sitemap.xml"
},
"type": {
"type": "string",
"example": "sitemap"
},
"status": {
"type": "string",
"example": "completed"
},
"progress": {
"type": "integer",
"example": 100
},
"webpages_count": {
"type": "integer",
"example": 42
},
"sync_frequency": {
"type": "string",
"example": "weekly"
},
"last_synced_at": {
"type": "string",
"example": "2026-03-12T08:00:00Z"
},
"created_at": {
"type": "string",
"example": "2026-01-29T10:30:00Z"
},
"updated_at": {
"type": "string",
"example": "2026-01-29T10:30:00Z"
}
}
}
}
}
}
}
}
}
},
"tags": [
"Chatbot Websites"
],
"x-mcp": true,
"x-mcp-name": "websites.list"
},
"parameters": [
{
"in": "path",
"name": "chatbot_id",
"description": "The chatbot UUID.",
"example": "8a832d1b-0f49-47f6-a05f-0b65b91d2107",
"required": true,
"schema": {
"type": "string"
}
}
]
},
"/api/v1/chatbots/{chatbot_id}/websites/{website_id}": {
"get": {
"summary": "Get Website",
"operationId": "getWebsite",
"description": "Get details for a specific website, including page counts grouped by status.",
"parameters": [],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"example": {
"website": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Sitemap example.com",
"url": "https://example.com/sitemap.xml",
"type": "sitemap",
"status": "completed",
"progress": 100,
"webpages_count": 42,
"status_counts": {
"completed": 38,
"error": 2,
"pending": 2
},
"sync_frequency": "weekly",
"last_synced_at": "2026-03-12T08:00:00Z",
"created_at": "2026-01-29T10:30:00Z",
"updated_at": "2026-01-29T10:30:00Z"
}
},
"properties": {
"website": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "550e8400-e29b-41d4-a716-446655440000"
},
"name": {
"type": "string",
"example": "Sitemap example.com"
},
"url": {
"type": "string",
"example": "https://example.com/sitemap.xml"
},
"type": {
"type": "string",
"example": "sitemap"
},
"status": {
"type": "string",
"example": "completed"
},
"progress": {
"type": "integer",
"example": 100
},
"webpages_count": {
"type": "integer",
"example": 42
},
"status_counts": {
"type": "object",
"properties": {
"completed": {
"type": "integer",
"example": 38
},
"error": {
"type": "integer",
"example": 2
},
"pending": {
"type": "integer",
"example": 2
}
}
},
"sync_frequency": {
"type": "string",
"example": "weekly"
},
"last_synced_at": {
"type": "string",
"example": "2026-03-12T08:00:00Z"
},
"created_at": {
"type": "string",
"example": "2026-01-29T10:30:00Z"
},
"updated_at": {
"type": "string",
"example": "2026-01-29T10:30:00Z"
}
}
}
}
}
}
}
}
},
"tags": [
"Chatbot Websites"
],
"x-mcp": true,
"x-mcp-name": "websites.get"
},
"delete": {
"summary": "Delete Website",
"operationId": "deleteWebsite",
"description": "Delete a website and all its pages. Deletion happens in the background.\n\nCRITICAL: Removes every page trained from this website. Confirm with the user first.",
"parameters": [],
"responses": {
"202": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"example": {
"message": "Website deletion has been queued and will be processed in the background."
},
"properties": {
"message": {
"type": "string",
"example": "Website deletion has been queued and will be processed in the background."
}
}
}
}
}
}
},
"tags": [
"Chatbot Websites"
],
"x-mcp": true,
"x-mcp-name": "websites.delete"
},
"parameters": [
{
"in": "path",
"name": "chatbot_id",
"description": "The chatbot UUID.",
"example": "8a832d1b-0f49-47f6-a05f-0b65b91d2107",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "path",
"name": "website_id",
"description": "The website UUID.",
"example": "550e8400-e29b-41d4-a716-446655440000",
"required": true,
"schema": {
"type": "string"
}
}
]
},
"/api/v1/chatbots/{chatbot_id}/websites/crawl": {
"post": {
"summary": "Crawl Domain",
"operationId": "crawlDomain",
"description": "Start crawling a domain to discover and train pages. Pages are automatically discovered, crawled, and processed.\n\nNOTE: Crawling runs in the background and can take minutes for large sites. Poll websites.get for page counts per status. Do not start the same crawl twice.",
"parameters": [],
"responses": {
"201": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"example": {
"website": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Crawl example.com",
"url": "https://example.com",
"type": "crawler",
"status": "crawling",
"progress": 0
},
"message": "Domain crawl started"
},
"properties": {
"website": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "550e8400-e29b-41d4-a716-446655440000"
},
"name": {
"type": "string",
"example": "Crawl example.com"
},
"url": {
"type": "string",
"example": "https://example.com"
},
"type": {
"type": "string",
"example": "crawler"
},
"status": {
"type": "string",
"example": "crawling"
},
"progress": {
"type": "integer",
"example": 0
}
}
},
"message": {
"type": "string",
"example": "Domain crawl started"
}
}
}
}
}
}
},
"tags": [
"Chatbot Websites"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Optional display name. Auto-generated from URL if omitted.",
"example": "My Website",
"nullable": true
},
"include_paths": {
"type": "string",
"description": "Comma-separated paths to include.",
"example": "/docs,/blog",
"nullable": true
},
"exclude_paths": {
"type": "string",
"description": "Comma-separated paths to exclude.",
"example": "/admin,/login",
"nullable": true
},
"url": {
"type": "string",
"description": "The domain URL to crawl.",
"example": "https://example.com"
}
},
"required": [
"url"
]
}
}
}
},
"x-mcp": true,
"x-mcp-name": "websites.crawl"
},
"parameters": [
{
"in": "path",
"name": "chatbot_id",
"description": "The chatbot UUID.",
"example": "8a832d1b-0f49-47f6-a05f-0b65b91d2107",
"required": true,
"schema": {
"type": "string"
}
}
]
},
"/api/v1/chatbots/{chatbot_id}/websites/sitemap": {
"post": {
"summary": "Process Sitemap",
"operationId": "processSitemap",
"description": "Submit a sitemap URL to discover and train pages. The sitemap is parsed and all discovered URLs are crawled.\n\nNOTE: Runs in the background. Poll websites.get for page counts per status.",
"parameters": [],
"responses": {
"201": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"example": {
"website": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Sitemap example.com",
"url": "https://example.com/sitemap.xml",
"type": "sitemap",
"status": "crawling",
"progress": 0
},
"message": "Sitemap processing started"
},
"properties": {
"website": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "550e8400-e29b-41d4-a716-446655440000"
},
"name": {
"type": "string",
"example": "Sitemap example.com"
},
"url": {
"type": "string",
"example": "https://example.com/sitemap.xml"
},
"type": {
"type": "string",
"example": "sitemap"
},
"status": {
"type": "string",
"example": "crawling"
},
"progress": {
"type": "integer",
"example": 0
}
}
},
"message": {
"type": "string",
"example": "Sitemap processing started"
}
}
}
}
}
}
},
"tags": [
"Chatbot Websites"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Optional display name. Auto-generated from URL if omitted.",
"example": "My Sitemap",
"nullable": true
},
"include_paths": {
"type": "string",
"description": "Comma-separated paths to include.",
"example": "/docs,/blog",
"nullable": true
},
"exclude_paths": {
"type": "string",
"description": "Comma-separated paths to exclude.",
"example": "/admin,/login",
"nullable": true
},
"url": {
"type": "string",
"description": "The sitemap URL.",
"example": "https://example.com/sitemap.xml"
}
},
"required": [
"url"
]
}
}
}
},
"x-mcp": true,
"x-mcp-name": "websites.importSitemap"
},
"parameters": [
{
"in": "path",
"name": "chatbot_id",
"description": "The chatbot UUID.",
"example": "8a832d1b-0f49-47f6-a05f-0b65b91d2107",
"required": true,
"schema": {
"type": "string"
}
}
]
},
"/api/v1/chatbots/{chatbot_id}/websites/{website_id}/webpages": {
"get": {
"summary": "List Website Pages",
"operationId": "listWebsitePages",
"description": "Get all pages belonging to a website, with optional filtering.",
"parameters": [
{
"in": "query",
"name": "status",
"description": "Filter by status (pending, completed, error, etc.).",
"example": "completed",
"required": false,
"schema": {
"type": "string",
"description": "Filter by status (pending, completed, error, etc.).",
"example": "completed"
}
},
{
"in": "query",
"name": "search",
"description": "Search pages by URL.",
"example": "/docs",
"required": false,
"schema": {
"type": "string",
"description": "Search pages by URL.",
"example": "/docs"
}
},
{
"in": "query",
"name": "limit",
"description": "Number of results per page.",
"example": 50,
"required": false,
"schema": {
"type": "integer",
"description": "Number of results per page.",
"example": 50
}
},
{
"in": "query",
"name": "offset",
"description": "Offset for pagination.",
"example": 0,
"required": false,
"schema": {
"type": "integer",
"description": "Offset for pagination.",
"example": 0
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"example": {
"webpages": [
{
"id": "794d9b3b-d68f-498a-bb25-de9689722603",
"url": "https://example.com/docs/getting-started",
"title": "Getting Started",
"status": "completed",
"used_for_training": true,
"cleaned_char_count": 4500,
"tags": [
{
"id": "uuid",
"tag_slug": "event-2026",
"label": "Event 2026"
}
],
"crawled_at": "2026-01-29T10:30:00Z",
"created_at": "2026-01-29T10:00:00Z"
}
],
"total": 42,
"has_more": false
},
"properties": {
"webpages": {
"type": "array",
"example": [
{
"id": "794d9b3b-d68f-498a-bb25-de9689722603",
"url": "https://example.com/docs/getting-started",
"title": "Getting Started",
"status": "completed",
"used_for_training": true,
"cleaned_char_count": 4500,
"tags": [
{
"id": "uuid",
"tag_slug": "event-2026",
"label": "Event 2026"
}
],
"crawled_at": "2026-01-29T10:30:00Z",
"created_at": "2026-01-29T10:00:00Z"
}
],
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "794d9b3b-d68f-498a-bb25-de9689722603"
},
"url": {
"type": "string",
"example": "https://example.com/docs/getting-started"
},
"title": {
"type": "string",
"example": "Getting Started"
},
"status": {
"type": "string",
"example": "completed"
},
"used_for_training": {
"type": "boolean",
"example": true
},
"cleaned_char_count": {
"type": "integer",
"example": 4500
},
"tags": {
"type": "array",
"example": [
{
"id": "uuid",
"tag_slug": "event-2026",
"label": "Event 2026"
}
],
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "uuid"
},
"tag_slug": {
"type": "string",
"example": "event-2026"
},
"label": {
"type": "string",
"example": "Event 2026"
}
}
}
},
"crawled_at": {
"type": "string",
"example": "2026-01-29T10:30:00Z"
},
"created_at": {
"type": "string",
"example": "2026-01-29T10:00:00Z"
}
}
}
},
"total": {
"type": "integer",
"example": 42
},
"has_more": {
"type": "boolean",
"example": false
}
}
}
}
}
}
},
"tags": [
"Chatbot Websites"
],
"x-mcp": true,
"x-mcp-name": "websites.listPages"
},
"post": {
"summary": "Add Page to Website",
"operationId": "addPageToWebsite",
"description": "Add a URL to an existing website. The page will be automatically crawled and trained.",
"parameters": [],
"responses": {
"200": {
"description": "URL already exists",
"content": {
"application/json": {
"schema": {
"type": "object",
"example": {
"webpage": {
"id": "uuid",
"url": "https://example.com/docs/new-page",
"status": "pending"
},
"already_exists": true,
"source": {
"type": "website",
"website_id": "uuid",
"label": "as part of Documentation"
},
"message": "This URL already existed as part of Documentation. It has been queued for retraining."
},
"properties": {
"webpage": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "uuid"
},
"url": {
"type": "string",
"example": "https://example.com/docs/new-page"
},
"status": {
"type": "string",
"example": "pending"
}
}
},
"already_exists": {
"type": "boolean",
"example": true
},
"source": {
"type": "object",
"properties": {
"type": {
"type": "string",
"example": "website"
},
"website_id": {
"type": "string",
"example": "uuid"
},
"label": {
"type": "string",
"example": "as part of Documentation"
}
}
},
"message": {
"type": "string",
"example": "This URL already existed as part of Documentation. It has been queued for retraining."
}
}
}
}
}
},
"201": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"example": {
"webpage": {
"id": "794d9b3b-d68f-498a-bb25-de9689722603",
"url": "https://example.com/docs/new-page",
"status": "pending",
"used_for_training": true,
"created_at": "2026-03-13T10:00:00Z"
},
"message": "Page added and crawl started"
},
"properties": {
"webpage": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "794d9b3b-d68f-498a-bb25-de9689722603"
},
"url": {
"type": "string",
"example": "https://example.com/docs/new-page"
},
"status": {
"type": "string",
"example": "pending"
},
"used_for_training": {
"type": "boolean",
"example": true
},
"created_at": {
"type": "string",
"example": "2026-03-13T10:00:00Z"
}
}
},
"message": {
"type": "string",
"example": "Page added and crawl started"
}
}
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"example": {
"error": "training_pages_limit_reached",
"message": "You have reached your page credits limit. Upgrade your plan to train more pages."
},
"properties": {
"error": {
"type": "string",
"example": "training_pages_limit_reached"
},
"message": {
"type": "string",
"example": "You have reached your page credits limit. Upgrade your plan to train more pages."
}
}
}
}
}
}
},
"tags": [
"Chatbot Websites"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "The URL to add.",
"example": "https://example.com/docs/new-page"
}
},
"required": [
"url"
]
}
}
}
},
"x-mcp": true,
"x-mcp-name": "websites.addPage"
},
"parameters": [
{
"in": "path",
"name": "chatbot_id",
"description": "The chatbot UUID.",
"example": "8a832d1b-0f49-47f6-a05f-0b65b91d2107",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "path",
"name": "website_id",
"description": "The website UUID.",
"example": "550e8400-e29b-41d4-a716-446655440000",
"required": true,
"schema": {
"type": "string"
}
}
]
},
"/api/v1/chatbots/{chatbot_id}/webpages": {
"get": {
"summary": "List Webpages",
"operationId": "listWebpages",
"description": "Get all training webpages for a chatbot with their status and tags.",
"parameters": [],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"example": {
"webpages": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"url": "https://example.com/docs",
"title": "Documentation",
"status": "completed",
"used_for_training": true,
"cleaned_char_count": 4500,
"crawled_at": "2026-01-29T10:30:00Z",
"tags": [
{
"id": "tag-uuid",
"tag_slug": "docs",
"label": "Documentation"
}
],
"created_at": "2026-01-29T10:00:00Z"
}
]
},
"properties": {
"webpages": {
"type": "array",
"example": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"url": "https://example.com/docs",
"title": "Documentation",
"status": "completed",
"used_for_training": true,
"cleaned_char_count": 4500,
"crawled_at": "2026-01-29T10:30:00Z",
"tags": [
{
"id": "tag-uuid",
"tag_slug": "docs",
"label": "Documentation"
}
],
"created_at": "2026-01-29T10:00:00Z"
}
],
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "550e8400-e29b-41d4-a716-446655440000"
},
"url": {
"type": "string",
"example": "https://example.com/docs"
},
"title": {
"type": "string",
"example": "Documentation"
},
"status": {
"type": "string",
"example": "completed"
},
"used_for_training": {
"type": "boolean",
"example": true
},
"cleaned_char_count": {
"type": "integer",
"example": 4500
},
"crawled_at": {
"type": "string",
"example": "2026-01-29T10:30:00Z"
},
"tags": {
"type": "array",
"example": [
{
"id": "tag-uuid",
"tag_slug": "docs",
"label": "Documentation"
}
],
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "tag-uuid"
},
"tag_slug": {
"type": "string",
"example": "docs"
},
"label": {
"type": "string",
"example": "Documentation"
}
}
}
},
"created_at": {
"type": "string",
"example": "2026-01-29T10:00:00Z"
}
}
}
}
}
}
}
}
}
},
"tags": [
"Chatbot Webpages"
],
"x-mcp": true,
"x-mcp-name": "webpages.list"
},
"post": {
"summary": "Add Webpage",
"operationId": "addWebpage",
"description": "Add a URL to the chatbot's training sources. The page will be automatically crawled and trained.\nIf the URL already exists, it will be retrained.\n\nNOTE: Crawling runs in the background. Poll webpages.get until status is completed. Re-adding an existing URL retrains it.",
"parameters": [],
"responses": {
"200": {
"description": "URL already exists",
"content": {
"application/json": {
"schema": {
"type": "object",
"example": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"url": "https://example.com/docs",
"status": "pending",
"already_exists": true
},
"properties": {
"id": {
"type": "string",
"example": "550e8400-e29b-41d4-a716-446655440000"
},
"url": {
"type": "string",
"example": "https://example.com/docs"
},
"status": {
"type": "string",
"example": "pending"
},
"already_exists": {
"type": "boolean",
"example": true
}
}
}
}
}
},
"201": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"example": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"url": "https://example.com/docs",
"status": "pending",
"used_for_training": true,
"created_at": "2026-01-29T10:30:00Z"
},
"properties": {
"id": {
"type": "string",
"example": "550e8400-e29b-41d4-a716-446655440000"
},
"url": {
"type": "string",
"example": "https://example.com/docs"
},
"status": {
"type": "string",
"example": "pending"
},
"used_for_training": {
"type": "boolean",
"example": true
},
"created_at": {
"type": "string",
"example": "2026-01-29T10:30:00Z"
}
}
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"example": {
"error": "training_pages_limit_reached",
"message": "You have reached your page credits limit. Upgrade your plan to train more pages."
},
"properties": {
"error": {
"type": "string",
"example": "training_pages_limit_reached"
},
"message": {
"type": "string",
"example": "You have reached your page credits limit. Upgrade your plan to train more pages."
}
}
}
}
}
}
},
"tags": [
"Chatbot Webpages"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "The URL to crawl and train.",
"example": "https://example.com/docs"
}
},
"required": [
"url"
]
}
}
}
},
"x-mcp": true,
"x-mcp-name": "webpages.add"
},
"parameters": [
{
"in": "path",
"name": "chatbot_id",
"description": "The chatbot UUID.",
"example": "8a832d1b-0f49-47f6-a05f-0b65b91d2107",
"required": true,
"schema": {
"type": "string"
}
}
]
},
"/api/v1/chatbots/{chatbot_id}/webpages/{webpage_id}": {
"get": {
"summary": "Get Webpage",
"operationId": "getWebpage",
"description": "Get details for a specific webpage.",
"parameters": [],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"example": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"url": "https://example.com/docs",
"title": "Documentation",
"status": "completed",
"used_for_training": true,
"cleaned_char_count": 4500,
"crawled_at": "2026-01-29T10:30:00Z",
"created_at": "2026-01-29T10:00:00Z"
},
"properties": {
"id": {
"type": "string",
"example": "550e8400-e29b-41d4-a716-446655440000"
},
"url": {
"type": "string",
"example": "https://example.com/docs"
},
"title": {
"type": "string",
"example": "Documentation"
},
"status": {
"type": "string",
"example": "completed"
},
"used_for_training": {
"type": "boolean",
"example": true
},
"cleaned_char_count": {
"type": "integer",
"example": 4500
},
"crawled_at": {
"type": "string",
"example": "2026-01-29T10:30:00Z"
},
"created_at": {
"type": "string",
"example": "2026-01-29T10:00:00Z"
}
}
}
}
}
}
},
"tags": [
"Chatbot Webpages"
],
"x-mcp": true,
"x-mcp-name": "webpages.get"
},
"delete": {
"summary": "Delete Webpage",
"operationId": "deleteWebpage",
"description": "Delete a webpage and its associated training data.",
"parameters": [],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"example": {
"message": "Webpage deleted successfully"
},
"properties": {
"message": {
"type": "string",
"example": "Webpage deleted successfully"
}
}
}
}
}
}
},
"tags": [
"Chatbot Webpages"
],
"x-mcp": true,
"x-mcp-name": "webpages.delete"
},
"parameters": [
{
"in": "path",
"name": "chatbot_id",
"description": "The chatbot UUID.",
"example": "8a832d1b-0f49-47f6-a05f-0b65b91d2107",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "path",
"name": "webpage_id",
"description": "The webpage UUID.",
"example": "550e8400-e29b-41d4-a716-446655440000",
"required": true,
"schema": {
"type": "string"
}
}
]
},
"/api/v1/chatbots/{chatbot_id}/files": {
"get": {
"summary": "List Files",
"operationId": "listFiles",
"description": "Get all uploaded files for a chatbot with their processing status and tags.",
"parameters": [],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"example": {
"files": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"original_name": "product-guide.pdf",
"file_type": "pdf",
"mime_type": "application/pdf",
"file_size": 245000,
"status": "completed",
"cleaned_char_count": 12000,
"tags": [
{
"id": "tag-uuid",
"tag_slug": "products",
"label": "Products"
}
],
"created_at": "2026-01-29T10:30:00Z"
}
]
},
"properties": {
"files": {
"type": "array",
"example": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"original_name": "product-guide.pdf",
"file_type": "pdf",
"mime_type": "application/pdf",
"file_size": 245000,
"status": "completed",
"cleaned_char_count": 12000,
"tags": [
{
"id": "tag-uuid",
"tag_slug": "products",
"label": "Products"
}
],
"created_at": "2026-01-29T10:30:00Z"
}
],
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "550e8400-e29b-41d4-a716-446655440000"
},
"original_name": {
"type": "string",
"example": "product-guide.pdf"
},
"file_type": {
"type": "string",
"example": "pdf"
},
"mime_type": {
"type": "string",
"example": "application/pdf"
},
"file_size": {
"type": "integer",
"example": 245000
},
"status": {
"type": "string",
"example": "completed"
},
"cleaned_char_count": {
"type": "integer",
"example": 12000
},
"tags": {
"type": "array",
"example": [
{
"id": "tag-uuid",
"tag_slug": "products",
"label": "Products"
}
],
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "tag-uuid"
},
"tag_slug": {
"type": "string",
"example": "products"
},
"label": {
"type": "string",
"example": "Products"
}
}
}
},
"created_at": {
"type": "string",
"example": "2026-01-29T10:30:00Z"
}
}
}
}
}
}
}
}
}
},
"tags": [
"Chatbot Files"
]
},
"post": {
"summary": "Upload File",
"operationId": "uploadFile",
"description": "Upload a file for the chatbot to train on. Supported formats: PDF, Word (doc/docx), Excel (xls/xlsx), PowerPoint (ppt/pptx), images, audio, text, CSV, JSON, XML, ZIP, Outlook (.msg), and EPUB.\nMax file size: 5MB.",
"parameters": [],
"responses": {
"201": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"example": {
"message": "File uploaded and queued for processing",
"file": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"original_name": "product-guide.pdf",
"file_type": "pdf",
"mime_type": "application/pdf",
"file_size": 245000,
"status": "pending",
"created_at": "2026-01-29T10:30:00Z"
}
},
"properties": {
"message": {
"type": "string",
"example": "File uploaded and queued for processing"
},
"file": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "550e8400-e29b-41d4-a716-446655440000"
},
"original_name": {
"type": "string",
"example": "product-guide.pdf"
},
"file_type": {
"type": "string",
"example": "pdf"
},
"mime_type": {
"type": "string",
"example": "application/pdf"
},
"file_size": {
"type": "integer",
"example": 245000
},
"status": {
"type": "string",
"example": "pending"
},
"created_at": {
"type": "string",
"example": "2026-01-29T10:30:00Z"
}
}
}
}
}
}
}
}
},
"tags": [
"Chatbot Files"
],
"requestBody": {
"required": true,
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"properties": {
"file": {
"type": "string",
"format": "binary",
"description": "The file to upload (max 5MB)."
}
},
"required": [
"file"
]
}
}
}
}
},
"parameters": [
{
"in": "path",
"name": "chatbot_id",
"description": "The chatbot UUID.",
"example": "8a832d1b-0f49-47f6-a05f-0b65b91d2107",
"required": true,
"schema": {
"type": "string"
}
}
]
},
"/api/v1/chatbots/{chatbot_id}/files/{file_id}": {
"get": {
"summary": "Get File",
"operationId": "getFile",
"description": "Get details for a specific uploaded file.",
"parameters": [],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"example": {
"file": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"original_name": "product-guide.pdf",
"file_type": "pdf",
"mime_type": "application/pdf",
"file_size": 245000,
"status": "completed",
"cleaned_char_count": 12000,
"created_at": "2026-01-29T10:30:00Z"
}
},
"properties": {
"file": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "550e8400-e29b-41d4-a716-446655440000"
},
"original_name": {
"type": "string",
"example": "product-guide.pdf"
},
"file_type": {
"type": "string",
"example": "pdf"
},
"mime_type": {
"type": "string",
"example": "application/pdf"
},
"file_size": {
"type": "integer",
"example": 245000
},
"status": {
"type": "string",
"example": "completed"
},
"cleaned_char_count": {
"type": "integer",
"example": 12000
},
"created_at": {
"type": "string",
"example": "2026-01-29T10:30:00Z"
}
}
}
}
}
}
}
}
},
"tags": [
"Chatbot Files"
]
},
"delete": {
"summary": "Delete File",
"operationId": "deleteFile",
"description": "Delete a file and its associated training data.",
"parameters": [],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"example": {
"message": "File deleted successfully"
},
"properties": {
"message": {
"type": "string",
"example": "File deleted successfully"
}
}
}
}
}
}
},
"tags": [
"Chatbot Files"
]
},
"parameters": [
{
"in": "path",
"name": "chatbot_id",
"description": "The chatbot UUID.",
"example": "8a832d1b-0f49-47f6-a05f-0b65b91d2107",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "path",
"name": "file_id",
"description": "The file UUID.",
"example": "550e8400-e29b-41d4-a716-446655440000",
"required": true,
"schema": {
"type": "string"
}
}
]
},
"/api/v1/chatbots/{chatbot_id}/training-texts": {
"get": {
"summary": "List Training Texts",
"operationId": "listTrainingTexts",
"description": "Get all training texts for a chatbot, ordered by sort order.",
"parameters": [],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"example": {
"training_texts": [
{
"id": "794d9b3b-d68f-498a-bb25-de9689722603",
"title": "Bus Schedule",
"content": "The bus departs every 30 minutes...",
"char_count": 42,
"status": "completed",
"sort_order": 0,
"tags": [
{
"id": "uuid",
"tag_slug": "event-2026",
"label": "Event 2026"
}
],
"created_at": "2026-03-13T10:00:00.000000Z",
"updated_at": "2026-03-13T10:00:00.000000Z"
}
],
"usage": {
"text_chars_used": 42,
"text_chars_limit": 1000000,
"training_pages_used": 5,
"training_pages_limit": 1000
}
},
"properties": {
"training_texts": {
"type": "array",
"example": [
{
"id": "794d9b3b-d68f-498a-bb25-de9689722603",
"title": "Bus Schedule",
"content": "The bus departs every 30 minutes...",
"char_count": 42,
"status": "completed",
"sort_order": 0,
"tags": [
{
"id": "uuid",
"tag_slug": "event-2026",
"label": "Event 2026"
}
],
"created_at": "2026-03-13T10:00:00.000000Z",
"updated_at": "2026-03-13T10:00:00.000000Z"
}
],
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "794d9b3b-d68f-498a-bb25-de9689722603"
},
"title": {
"type": "string",
"example": "Bus Schedule"
},
"content": {
"type": "string",
"example": "The bus departs every 30 minutes..."
},
"char_count": {
"type": "integer",
"example": 42
},
"status": {
"type": "string",
"example": "completed"
},
"sort_order": {
"type": "integer",
"example": 0
},
"tags": {
"type": "array",
"example": [
{
"id": "uuid",
"tag_slug": "event-2026",
"label": "Event 2026"
}
],
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "uuid"
},
"tag_slug": {
"type": "string",
"example": "event-2026"
},
"label": {
"type": "string",
"example": "Event 2026"
}
}
}
},
"created_at": {
"type": "string",
"example": "2026-03-13T10:00:00.000000Z"
},
"updated_at": {
"type": "string",
"example": "2026-03-13T10:00:00.000000Z"
}
}
}
},
"usage": {
"type": "object",
"properties": {
"text_chars_used": {
"type": "integer",
"example": 42
},
"text_chars_limit": {
"type": "integer",
"example": 1000000
},
"training_pages_used": {
"type": "integer",
"example": 5
},
"training_pages_limit": {
"type": "integer",
"example": 1000
}
}
}
}
}
}
}
}
},
"tags": [
"Chatbot Text Snippets"
],
"x-mcp": true,
"x-mcp-name": "training.list"
},
"post": {
"summary": "Create Training Text",
"operationId": "createTrainingText",
"description": "Create a new training text piece for a chatbot. Content is automatically chunked and embedded for AI search.\n\nNOTE: Processing runs in the background; the chatbot can use the new text shortly after status becomes completed (see training.get).",
"parameters": [],
"responses": {
"201": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"example": {
"training_text": {
"id": "794d9b3b-d68f-498a-bb25-de9689722603",
"title": "Bus Schedule",
"content": "The bus departs every 30 minutes...",
"char_count": 42,
"status": "processing",
"sort_order": 0,
"tags": [
{
"id": "uuid",
"tag_slug": "event-2026",
"label": "Event 2026"
}
],
"created_at": "2026-03-13T10:00:00.000000Z",
"updated_at": "2026-03-13T10:00:00.000000Z"
},
"usage": {
"text_chars_used": 42,
"text_chars_limit": 1000000,
"training_pages_used": 5,
"training_pages_limit": 1000
},
"message": "Training text created successfully"
},
"properties": {
"training_text": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "794d9b3b-d68f-498a-bb25-de9689722603"
},
"title": {
"type": "string",
"example": "Bus Schedule"
},
"content": {
"type": "string",
"example": "The bus departs every 30 minutes..."
},
"char_count": {
"type": "integer",
"example": 42
},
"status": {
"type": "string",
"example": "processing"
},
"sort_order": {
"type": "integer",
"example": 0
},
"tags": {
"type": "array",
"example": [
{
"id": "uuid",
"tag_slug": "event-2026",
"label": "Event 2026"
}
],
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "uuid"
},
"tag_slug": {
"type": "string",
"example": "event-2026"
},
"label": {
"type": "string",
"example": "Event 2026"
}
}
}
},
"created_at": {
"type": "string",
"example": "2026-03-13T10:00:00.000000Z"
},
"updated_at": {
"type": "string",
"example": "2026-03-13T10:00:00.000000Z"
}
}
},
"usage": {
"type": "object",
"properties": {
"text_chars_used": {
"type": "integer",
"example": 42
},
"text_chars_limit": {
"type": "integer",
"example": 1000000
},
"training_pages_used": {
"type": "integer",
"example": 5
},
"training_pages_limit": {
"type": "integer",
"example": 1000
}
}
},
"message": {
"type": "string",
"example": "Training text created successfully"
}
}
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"example": {
"error": "training_pages_limit_reached",
"message": "You have reached your training pages limit. Upgrade your plan for more."
},
"properties": {
"error": {
"type": "string",
"example": "training_pages_limit_reached"
},
"message": {
"type": "string",
"example": "You have reached your training pages limit. Upgrade your plan for more."
}
}
}
}
}
}
},
"tags": [
"Chatbot Text Snippets"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Short internal title.",
"example": "Bus Schedule"
},
"content": {
"type": "string",
"description": "The training content.",
"example": "The bus departs every 30 minutes from the main entrance."
},
"tag_slugs": {
"type": "array",
"description": "Optional tag slugs to attach.",
"example": [
"event-2026"
],
"items": {
"type": "string"
}
},
"tag_ids": {
"type": "array",
"description": "Must be a valid UUID.",
"example": [
"6b72fe4a-5b40-307c-bc24-f79acf9a1bb9"
],
"items": {
"type": "string"
}
},
"sort_order": {
"type": "integer",
"description": "Optional display order.",
"example": 0,
"nullable": true
}
},
"required": [
"title",
"content"
]
}
}
}
},
"x-mcp": true,
"x-mcp-name": "training.create"
},
"parameters": [
{
"in": "path",
"name": "chatbot_id",
"description": "The chatbot ID.",
"example": "8a832d1b-0f49-47f6-a05f-0b65b91d2107",
"required": true,
"schema": {
"type": "string"
}
}
]
},
"/api/v1/chatbots/{chatbot_id}/training-texts/{id}": {
"get": {
"summary": "Get Training Text",
"operationId": "getTrainingText",
"description": "Get a single training text by ID.",
"parameters": [],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"example": {
"training_text": {
"id": "794d9b3b-d68f-498a-bb25-de9689722603",
"title": "Bus Schedule",
"content": "The bus departs every 30 minutes...",
"char_count": 42,
"status": "completed",
"sort_order": 0,
"tags": [
{
"id": "uuid",
"tag_slug": "event-2026",
"label": "Event 2026"
}
],
"created_at": "2026-03-13T10:00:00.000000Z",
"updated_at": "2026-03-13T10:00:00.000000Z"
},
"usage": {
"text_chars_used": 42,
"text_chars_limit": 1000000,
"training_pages_used": 5,
"training_pages_limit": 1000
}
},
"properties": {
"training_text": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "794d9b3b-d68f-498a-bb25-de9689722603"
},
"title": {
"type": "string",
"example": "Bus Schedule"
},
"content": {
"type": "string",
"example": "The bus departs every 30 minutes..."
},
"char_count": {
"type": "integer",
"example": 42
},
"status": {
"type": "string",
"example": "completed"
},
"sort_order": {
"type": "integer",
"example": 0
},
"tags": {
"type": "array",
"example": [
{
"id": "uuid",
"tag_slug": "event-2026",
"label": "Event 2026"
}
],
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "uuid"
},
"tag_slug": {
"type": "string",
"example": "event-2026"
},
"label": {
"type": "string",
"example": "Event 2026"
}
}
}
},
"created_at": {
"type": "string",
"example": "2026-03-13T10:00:00.000000Z"
},
"updated_at": {
"type": "string",
"example": "2026-03-13T10:00:00.000000Z"
}
}
},
"usage": {
"type": "object",
"properties": {
"text_chars_used": {
"type": "integer",
"example": 42
},
"text_chars_limit": {
"type": "integer",
"example": 1000000
},
"training_pages_used": {
"type": "integer",
"example": 5
},
"training_pages_limit": {
"type": "integer",
"example": 1000
}
}
}
}
}
}
}
}
},
"tags": [
"Chatbot Text Snippets"
],
"x-mcp": true,
"x-mcp-name": "training.get"
},
"put": {
"summary": "Update Training Text",
"operationId": "updateTrainingText",
"description": "Update a training text's title, content, or tags. If content changes, it is automatically re-chunked and re-embedded.\n\nNOTE: tag_slugs replaces the full tag set; send the complete list.",
"parameters": [],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"example": {
"training_text": {
"id": "794d9b3b-d68f-498a-bb25-de9689722603",
"title": "Bus Schedule Updated",
"content": "The bus departs every 15 minutes...",
"char_count": 50,
"status": "processing",
"sort_order": 1,
"tags": [
{
"id": "uuid",
"tag_slug": "event-2026",
"label": "Event 2026"
}
],
"created_at": "2026-03-13T10:00:00.000000Z",
"updated_at": "2026-03-13T10:05:00.000000Z"
},
"usage": {
"text_chars_used": 50,
"text_chars_limit": 1000000,
"training_pages_used": 5,
"training_pages_limit": 1000
},
"message": "Training text updated successfully"
},
"properties": {
"training_text": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "794d9b3b-d68f-498a-bb25-de9689722603"
},
"title": {
"type": "string",
"example": "Bus Schedule Updated"
},
"content": {
"type": "string",
"example": "The bus departs every 15 minutes..."
},
"char_count": {
"type": "integer",
"example": 50
},
"status": {
"type": "string",
"example": "processing"
},
"sort_order": {
"type": "integer",
"example": 1
},
"tags": {
"type": "array",
"example": [
{
"id": "uuid",
"tag_slug": "event-2026",
"label": "Event 2026"
}
],
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "uuid"
},
"tag_slug": {
"type": "string",
"example": "event-2026"
},
"label": {
"type": "string",
"example": "Event 2026"
}
}
}
},
"created_at": {
"type": "string",
"example": "2026-03-13T10:00:00.000000Z"
},
"updated_at": {
"type": "string",
"example": "2026-03-13T10:05:00.000000Z"
}
}
},
"usage": {
"type": "object",
"properties": {
"text_chars_used": {
"type": "integer",
"example": 50
},
"text_chars_limit": {
"type": "integer",
"example": 1000000
},
"training_pages_used": {
"type": "integer",
"example": 5
},
"training_pages_limit": {
"type": "integer",
"example": 1000
}
}
},
"message": {
"type": "string",
"example": "Training text updated successfully"
}
}
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"example": {
"error": "text_training_limit_reached",
"message": "Updating this text would exceed your text training limit."
},
"properties": {
"error": {
"type": "string",
"example": "text_training_limit_reached"
},
"message": {
"type": "string",
"example": "Updating this text would exceed your text training limit."
}
}
}
}
}
}
},
"tags": [
"Chatbot Text Snippets"
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Short internal title.",
"example": "Bus Schedule Updated"
},
"content": {
"type": "string",
"description": "The training content.",
"example": "The bus departs every 15 minutes from the main entrance."
},
"tag_slugs": {
"type": "array",
"description": "Tag slugs to sync (replaces existing tags).",
"example": [
"event-2026"
],
"items": {
"type": "string"
}
},
"tag_ids": {
"type": "array",
"description": "Must be a valid UUID.",
"example": [
"6b72fe4a-5b40-307c-bc24-f79acf9a1bb9"
],
"items": {
"type": "string"
}
},
"sort_order": {
"type": "integer",
"description": "Display order.",
"example": 1,
"nullable": true
}
}
}
}
}
},
"x-mcp": true,
"x-mcp-name": "training.update"
},
"delete": {
"summary": "Delete Training Text",
"operationId": "deleteTrainingText",
"description": "Delete a training text and its associated chunks and embeddings.",
"parameters": [],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"example": {
"message": "Training text deleted successfully",
"usage": {
"text_chars_used": 0,
"text_chars_limit": 1000000,
"training_pages_used": 4,
"training_pages_limit": 1000
}
},
"properties": {
"message": {
"type": "string",
"example": "Training text deleted successfully"
},
"usage": {
"type": "object",
"properties": {
"text_chars_used": {
"type": "integer",
"example": 0
},
"text_chars_limit": {
"type": "integer",
"example": 1000000
},
"training_pages_used": {
"type": "integer",
"example": 4
},
"training_pages_limit": {
"type": "integer",
"example": 1000
}
}
}
}
}
}
}
}
},
"tags": [
"Chatbot Text Snippets"
],
"x-mcp": true,
"x-mcp-name": "training.delete"
},
"parameters": [
{
"in": "path",
"name": "chatbot_id",
"description": "The chatbot ID.",
"example": "8a832d1b-0f49-47f6-a05f-0b65b91d2107",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "path",
"name": "id",
"description": "The training text ID.",
"example": "794d9b3b-d68f-498a-bb25-de9689722603",
"required": true,
"schema": {
"type": "string"
}
}
]
},
"/api/v1/chatbots/{chatbot_id}/tags": {
"get": {
"summary": "List Tags",
"operationId": "listTags",
"description": "Get all tags for a chatbot, including usage counts per content type.",
"parameters": [],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"example": {
"tags": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"tag_slug": "event-2026",
"label": "Event 2026",
"webpages_count": 3,
"files_count": 1,
"training_texts_count": 2,
"created_at": "2026-01-29T10:30:00Z",
"updated_at": "2026-01-29T10:30:00Z"
}
]
},
"properties": {
"tags": {
"type": "array",
"example": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"tag_slug": "event-2026",
"label": "Event 2026",
"webpages_count": 3,
"files_count": 1,
"training_texts_count": 2,
"created_at": "2026-01-29T10:30:00Z",
"updated_at": "2026-01-29T10:30:00Z"
}
],
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "550e8400-e29b-41d4-a716-446655440000"
},
"tag_slug": {
"type": "string",
"example": "event-2026"
},
"label": {
"type": "string",
"example": "Event 2026"
},
"webpages_count": {
"type": "integer",
"example": 3
},
"files_count": {
"type": "integer",
"example": 1
},
"training_texts_count": {
"type": "integer",
"example": 2
},
"created_at": {
"type": "string",
"example": "2026-01-29T10:30:00Z"
},
"updated_at": {
"type": "string",
"example": "2026-01-29T10:30:00Z"
}
}
}
}
}
}
}
}
}
},
"tags": [
"Chatbot Tags"
],
"x-mcp": true,
"x-mcp-name": "tags.list"
},
"post": {
"summary": "Create Tag",
"operationId": "createTag",
"description": "Create a new tag for a chatbot. Slug is auto-generated from the label if not provided.\n\nNOTE: Tags group training content per chatbot. Use tag_slug values with training.create / training.update.",
"parameters": [],
"responses": {
"201": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"example": {
"tag": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"tag_slug": "event-2026",
"label": "Event 2026",
"webpages_count": 0,
"files_count": 0,
"training_texts_count": 0,
"created_at": "2026-01-29T10:30:00Z",
"updated_at": "2026-01-29T10:30:00Z"
},
"message": "Tag created successfully"
},
"properties": {
"tag": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "550e8400-e29b-41d4-a716-446655440000"
},
"tag_slug": {
"type": "string",
"example": "event-2026"
},
"label": {
"type": "string",
"example": "Event 2026"
},
"webpages_count": {
"type": "integer",
"example": 0
},
"files_count": {
"type": "integer",
"example": 0
},
"training_texts_count": {
"type": "integer",
"example": 0
},
"created_at": {
"type": "string",
"example": "2026-01-29T10:30:00Z"
},
"updated_at": {
"type": "string",
"example": "2026-01-29T10:30:00Z"
}
}
},
"message": {
"type": "string",
"example": "Tag created successfully"
}
}
}
}
}
},
"422": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"example": {
"message": "A tag with this slug already exists for this chatbot."
},
"properties": {
"message": {
"type": "string",
"example": "A tag with this slug already exists for this chatbot."
}
}
}
}
}
}
},
"tags": [
"Chatbot Tags"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"label": {
"type": "string",
"description": "The tag display name.",
"example": "Event 2026"
},
"tag_slug": {
"type": "string",
"description": "Optional custom slug. Auto-generated from label if omitted.",
"example": "event-2026",
"nullable": true
}
},
"required": [
"label"
]
}
}
}
},
"x-mcp": true,
"x-mcp-name": "tags.create"
},
"parameters": [
{
"in": "path",
"name": "chatbot_id",
"description": "The chatbot UUID.",
"example": "8a832d1b-0f49-47f6-a05f-0b65b91d2107",
"required": true,
"schema": {
"type": "string"
}
}
]
},
"/api/v1/chatbots/{chatbot_id}/tags/{tag}": {
"put": {
"summary": "Update Tag",
"operationId": "updateTag",
"description": "Update a tag's label or slug. If the slug changes, all associated content chunks are retagged in the vector DB.",
"parameters": [],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"example": {
"tag": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"tag_slug": "summer-event-2026",
"label": "Summer Event 2026",
"webpages_count": 3,
"files_count": 1,
"training_texts_count": 2,
"created_at": "2026-01-29T10:30:00Z",
"updated_at": "2026-01-29T12:00:00Z"
},
"message": "Tag updated successfully"
},
"properties": {
"tag": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "550e8400-e29b-41d4-a716-446655440000"
},
"tag_slug": {
"type": "string",
"example": "summer-event-2026"
},
"label": {
"type": "string",
"example": "Summer Event 2026"
},
"webpages_count": {
"type": "integer",
"example": 3
},
"files_count": {
"type": "integer",
"example": 1
},
"training_texts_count": {
"type": "integer",
"example": 2
},
"created_at": {
"type": "string",
"example": "2026-01-29T10:30:00Z"
},
"updated_at": {
"type": "string",
"example": "2026-01-29T12:00:00Z"
}
}
},
"message": {
"type": "string",
"example": "Tag updated successfully"
}
}
}
}
}
},
"422": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"example": {
"message": "A tag with this slug already exists for this chatbot."
},
"properties": {
"message": {
"type": "string",
"example": "A tag with this slug already exists for this chatbot."
}
}
}
}
}
}
},
"tags": [
"Chatbot Tags"
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"label": {
"type": "string",
"description": "The tag display name.",
"example": "Summer Event 2026"
},
"tag_slug": {
"type": "string",
"description": "The tag slug.",
"example": "summer-event-2026"
}
}
}
}
}
},
"x-mcp": true,
"x-mcp-name": "tags.update"
},
"delete": {
"summary": "Delete Tag",
"operationId": "deleteTag",
"description": "Delete a tag. Related content associations are removed automatically.",
"parameters": [],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"example": {
"message": "Tag deleted successfully"
},
"properties": {
"message": {
"type": "string",
"example": "Tag deleted successfully"
}
}
}
}
}
}
},
"tags": [
"Chatbot Tags"
],
"x-mcp": true,
"x-mcp-name": "tags.delete"
},
"parameters": [
{
"in": "path",
"name": "chatbot_id",
"description": "The chatbot UUID.",
"example": "8a832d1b-0f49-47f6-a05f-0b65b91d2107",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "path",
"name": "tag",
"description": "The tag UUID.",
"example": "550e8400-e29b-41d4-a716-446655440000",
"required": true,
"schema": {
"type": "string"
}
}
]
},
"/api/v1/faqs": {
"get": {
"summary": "List FAQs",
"operationId": "listFAQs",
"description": "Get all FAQ collections for the authenticated user, including item counts.",
"parameters": [],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"example": {
"data": [
{
"id": 1,
"title": "General Questions",
"items_count": 12,
"created_at": "2026-01-29T10:30:00Z"
}
]
},
"properties": {
"data": {
"type": "array",
"example": [
{
"id": 1,
"title": "General Questions",
"items_count": 12,
"created_at": "2026-01-29T10:30:00Z"
}
],
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"example": 1
},
"title": {
"type": "string",
"example": "General Questions"
},
"items_count": {
"type": "integer",
"example": 12
},
"created_at": {
"type": "string",
"example": "2026-01-29T10:30:00Z"
}
}
}
}
}
}
}
}
}
},
"tags": [
"FAQs"
],
"x-mcp": true,
"x-mcp-name": "faqs.list"
},
"post": {
"summary": "Create FAQ",
"operationId": "createFAQ",
"description": "Create a new FAQ collection.",
"parameters": [],
"responses": {
"201": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"example": {
"data": {
"id": 2,
"title": "Pricing Questions"
}
},
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"example": 2
},
"title": {
"type": "string",
"example": "Pricing Questions"
}
}
}
}
}
}
}
}
},
"tags": [
"FAQs"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "The FAQ collection title.",
"example": "Pricing Questions"
}
},
"required": [
"title"
]
}
}
}
},
"x-mcp": true,
"x-mcp-name": "faqs.create"
}
},
"/api/v1/faqs/{faq_id}": {
"get": {
"summary": "Get FAQ",
"operationId": "getFAQ",
"description": "Get a FAQ collection with all its question/answer items.",
"parameters": [],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"example": {
"data": {
"id": 1,
"title": "General Questions",
"items": [
{
"id": 10,
"question": "What are your business hours?",
"answer": "We are open Monday to Friday, 9am to 5pm.",
"order": 1
}
]
}
},
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"example": 1
},
"title": {
"type": "string",
"example": "General Questions"
},
"items": {
"type": "array",
"example": [
{
"id": 10,
"question": "What are your business hours?",
"answer": "We are open Monday to Friday, 9am to 5pm.",
"order": 1
}
],
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"example": 10
},
"question": {
"type": "string",
"example": "What are your business hours?"
},
"answer": {
"type": "string",
"example": "We are open Monday to Friday, 9am to 5pm."
},
"order": {
"type": "integer",
"example": 1
}
}
}
}
}
}
}
}
}
}
}
},
"tags": [
"FAQs"
],
"x-mcp": true,
"x-mcp-name": "faqs.get"
},
"put": {
"summary": "Update FAQ",
"operationId": "updateFAQ",
"description": "Update a FAQ collection's title.",
"parameters": [],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"example": {
"data": {
"id": 1,
"title": "Updated FAQ Title"
}
},
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"example": 1
},
"title": {
"type": "string",
"example": "Updated FAQ Title"
}
}
}
}
}
}
}
}
},
"tags": [
"FAQs"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "The new title.",
"example": "Updated FAQ Title"
}
},
"required": [
"title"
]
}
}
}
},
"x-mcp": true,
"x-mcp-name": "faqs.update"
},
"delete": {
"summary": "Delete FAQ",
"operationId": "deleteFAQ",
"description": "Delete a FAQ collection and all its items.\n\nCRITICAL: Deletes every question in the collection too. Confirm with the user first.",
"parameters": [],
"responses": {
"204": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "object",
"example": [],
"properties": []
}
}
}
}
},
"tags": [
"FAQs"
],
"x-mcp": true,
"x-mcp-name": "faqs.delete"
},
"parameters": [
{
"in": "path",
"name": "faq_id",
"description": "The FAQ ID.",
"example": 1,
"required": true,
"schema": {
"type": "integer"
}
}
]
},
"/api/v1/faqs/{faq_id}/items": {
"post": {
"summary": "Create FAQ Item",
"operationId": "createFAQItem",
"description": "Add a question/answer pair to a FAQ collection.",
"parameters": [],
"responses": {
"201": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"example": {
"data": {
"id": 15,
"question": "What are your business hours?",
"answer": "We are open Monday to Friday, 9am to 5pm.",
"order": 3
}
},
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"example": 15
},
"question": {
"type": "string",
"example": "What are your business hours?"
},
"answer": {
"type": "string",
"example": "We are open Monday to Friday, 9am to 5pm."
},
"order": {
"type": "integer",
"example": 3
}
}
}
}
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"example": {
"error": "training_pages_limit_reached",
"message": "You have reached your training pages limit. Upgrade your plan for more."
},
"properties": {
"error": {
"type": "string",
"example": "training_pages_limit_reached"
},
"message": {
"type": "string",
"example": "You have reached your training pages limit. Upgrade your plan for more."
}
}
}
}
}
}
},
"tags": [
"FAQs"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"question": {
"type": "string",
"description": "The question text.",
"example": "What are your business hours?"
},
"answer": {
"type": "string",
"description": "The answer text.",
"example": "We are open Monday to Friday, 9am to 5pm."
}
},
"required": [
"question",
"answer"
]
}
}
}
},
"x-mcp": true,
"x-mcp-name": "faqs.addItem"
},
"parameters": [
{
"in": "path",
"name": "faq_id",
"description": "The FAQ ID.",
"example": 1,
"required": true,
"schema": {
"type": "integer"
}
}
]
},
"/api/v1/faqs/{faq_id}/items/{item_id}": {
"put": {
"summary": "Update FAQ Item",
"operationId": "updateFAQItem",
"description": "Update a question/answer pair.",
"parameters": [],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"example": {
"data": {
"id": 15,
"question": "What are your updated business hours?",
"answer": "We are now open 24/7.",
"order": 3
}
},
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"example": 15
},
"question": {
"type": "string",
"example": "What are your updated business hours?"
},
"answer": {
"type": "string",
"example": "We are now open 24/7."
},
"order": {
"type": "integer",
"example": 3
}
}
}
}
}
}
}
}
},
"tags": [
"FAQs"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"question": {
"type": "string",
"description": "The question text.",
"example": "What are your updated business hours?"
},
"answer": {
"type": "string",
"description": "The answer text.",
"example": "We are now open 24/7."
}
},
"required": [
"question",
"answer"
]
}
}
}
},
"x-mcp": true,
"x-mcp-name": "faqs.updateItem"
},
"delete": {
"summary": "Delete FAQ Item",
"operationId": "deleteFAQItem",
"description": "Delete a question/answer pair from a FAQ collection.",
"parameters": [],
"responses": {
"204": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "object",
"example": [],
"properties": []
}
}
}
}
},
"tags": [
"FAQs"
],
"x-mcp": true,
"x-mcp-name": "faqs.deleteItem"
},
"parameters": [
{
"in": "path",
"name": "faq_id",
"description": "The FAQ ID.",
"example": 1,
"required": true,
"schema": {
"type": "integer"
}
},
{
"in": "path",
"name": "item_id",
"description": "The FAQ item ID.",
"example": 15,
"required": true,
"schema": {
"type": "integer"
}
}
]
},
"/api/v1/contacts": {
"get": {
"summary": "List Contacts",
"operationId": "listContacts",
"description": "Get all contacts with optional search and status filtering. Search also matches custom field values.",
"parameters": [
{
"in": "query",
"name": "search",
"description": "Search by name, email, phone, company, or any custom field value.",
"example": "john",
"required": false,
"schema": {
"type": "string",
"description": "Search by name, email, phone, company, or any custom field value.",
"example": "john"
}
},
{
"in": "query",
"name": "status",
"description": "Filter by status.",
"example": "lead",
"required": false,
"schema": {
"type": "string",
"description": "Filter by status.",
"example": "lead"
}
},
{
"in": "query",
"name": "per_page",
"description": "Results per page (default 50).",
"example": 25,
"required": false,
"schema": {
"type": "integer",
"description": "Results per page (default 50).",
"example": 25
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"example": {
"data": [
{
"id": "con_abc123",
"email": "john@example.com",
"phone": "+1234567890",
"name": "John Doe",
"company": "Acme Corp",
"status": "lead",
"notes": null,
"inbox_count": 3,
"deals_count": 1,
"last_contact_at": "2026-01-29 10:30:00",
"created_at": "2026-01-15 08:00:00"
}
]
},
"properties": {
"data": {
"type": "array",
"example": [
{
"id": "con_abc123",
"email": "john@example.com",
"phone": "+1234567890",
"name": "John Doe",
"company": "Acme Corp",
"status": "lead",
"notes": null,
"inbox_count": 3,
"deals_count": 1,
"last_contact_at": "2026-01-29 10:30:00",
"created_at": "2026-01-15 08:00:00"
}
],
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "con_abc123"
},
"email": {
"type": "string",
"example": "john@example.com"
},
"phone": {
"type": "string",
"example": "+1234567890"
},
"name": {
"type": "string",
"example": "John Doe"
},
"company": {
"type": "string",
"example": "Acme Corp"
},
"status": {
"type": "string",
"example": "lead"
},
"notes": {
"type": "string",
"example": null,
"nullable": true
},
"inbox_count": {
"type": "integer",
"example": 3
},
"deals_count": {
"type": "integer",
"example": 1
},
"last_contact_at": {
"type": "string",
"example": "2026-01-29 10:30:00"
},
"created_at": {
"type": "string",
"example": "2026-01-15 08:00:00"
}
}
}
}
}
}
}
}
}
},
"tags": [
"Contacts"
],
"x-mcp": true,
"x-mcp-name": "contacts.list"
},
"post": {
"summary": "Create Contact",
"operationId": "createContact",
"description": "Create a new contact. At least email or phone is required.\n\nNOTE: Use contacts.lookup first if the person may already exist; email and phone are not unique-checked here.",
"parameters": [],
"responses": {
"201": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"example": {
"data": {
"id": "con_abc123",
"email": "john@example.com",
"name": "John Doe",
"company": "Acme Corp",
"status": "lead"
}
},
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "con_abc123"
},
"email": {
"type": "string",
"example": "john@example.com"
},
"name": {
"type": "string",
"example": "John Doe"
},
"company": {
"type": "string",
"example": "Acme Corp"
},
"status": {
"type": "string",
"example": "lead"
}
}
}
}
}
}
}
},
"409": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"example": {
"error": "Contact with this email or phone already exists"
},
"properties": {
"error": {
"type": "string",
"example": "Contact with this email or phone already exists"
}
}
}
}
}
},
"422": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"example": {
"error": "Email or phone is required"
},
"properties": {
"error": {
"type": "string",
"example": "Email or phone is required"
}
}
}
}
}
}
},
"tags": [
"Contacts"
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"email": {
"type": "string",
"description": "Contact email (required if no phone).",
"example": "john@example.com"
},
"phone": {
"type": "string",
"description": "Contact phone (required if no email).",
"example": "+1234567890"
},
"name": {
"type": "string",
"description": "Contact name.",
"example": "John Doe"
},
"company": {
"type": "string",
"description": "Company name.",
"example": "Acme Corp"
},
"notes": {
"type": "string",
"description": "Internal notes.",
"example": "Met at conference"
},
"status": {
"type": "string",
"description": "Contact status.",
"example": "lead"
}
}
}
}
}
},
"x-mcp": true,
"x-mcp-name": "contacts.create"
}
},
"/api/v1/contacts/lookup": {
"get": {
"summary": "Lookup Contact",
"operationId": "lookupContact",
"description": "Find a contact by email or phone number.\n\nNOTE: Pass either email or phone. When nothing matches this succeeds with \"data\": null rather than failing, so check for null before assuming the contact exists.",
"parameters": [
{
"in": "query",
"name": "email",
"description": "Lookup by email.",
"example": "john@example.com",
"required": false,
"schema": {
"type": "string",
"description": "Lookup by email.",
"example": "john@example.com"
}
},
{
"in": "query",
"name": "phone",
"description": "Lookup by phone.",
"example": "+1234567890",
"required": false,
"schema": {
"type": "string",
"description": "Lookup by phone.",
"example": "+1234567890"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"description": "",
"type": "object",
"example": {
"data": {
"id": "con_abc123",
"email": "john@example.com",
"name": "John Doe"
}
},
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "con_abc123"
},
"email": {
"type": "string",
"example": "john@example.com"
},
"name": {
"type": "string",
"example": "John Doe"
}
}
}
}
},
{
"description": "Not found",
"type": "object",
"example": {
"data": null
},
"properties": {
"data": {
"type": "string",
"example": null,
"nullable": true
}
}
}
]
}
}
}
}
},
"tags": [
"Contacts"
],
"x-mcp": true,
"x-mcp-name": "contacts.lookup"
}
},
"/api/v1/contacts/mark-customer": {
"post": {
"summary": "Mark Contact as Customer",
"operationId": "markContactAsCustomer",
"description": "Flip a contact to status \"customer\" by email, and auto-Won any open deals\nlinked to that contact. If the contact does not exist yet, it is created\nwith status \"customer\". Idempotent, safe to call from a webhook fired on\nevery payment event.",
"parameters": [],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"example": {
"success": true,
"contact_id": 123,
"created": false,
"status_changed": true,
"deals_won": 2
},
"properties": {
"success": {
"type": "boolean",
"example": true
},
"contact_id": {
"type": "integer",
"example": 123
},
"created": {
"type": "boolean",
"example": false
},
"status_changed": {
"type": "boolean",
"example": true
},
"deals_won": {
"type": "integer",
"example": 2
}
}
}
}
}
},
"422": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"example": {
"error": "The email field is required."
},
"properties": {
"error": {
"type": "string",
"example": "The email field is required."
}
}
}
}
}
}
},
"tags": [
"Contacts"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"email": {
"type": "string",
"description": "The customer's email address.",
"example": "customer@example.com"
},
"name": {
"type": "string",
"description": "Optional name to store when creating a new contact.",
"example": "Jane Doe",
"nullable": true
}
},
"required": [
"email"
]
}
}
}
},
"x-mcp": true,
"x-mcp-name": "contacts.markCustomer"
}
},
"/api/v1/contacts/{contact_id}": {
"get": {
"summary": "Get Contact",
"operationId": "getContact",
"description": "Get a contact with their recent conversations, deals, and total deal value.",
"parameters": [],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"example": {
"data": {
"id": "con_abc123",
"email": "john@example.com",
"name": "John Doe",
"company": "Acme Corp",
"status": "lead"
},
"inbox_preview": [],
"deals": [],
"deals_total_value": 5000,
"next_action": null
},
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "con_abc123"
},
"email": {
"type": "string",
"example": "john@example.com"
},
"name": {
"type": "string",
"example": "John Doe"
},
"company": {
"type": "string",
"example": "Acme Corp"
},
"status": {
"type": "string",
"example": "lead"
}
}
},
"inbox_preview": {
"type": "array",
"example": []
},
"deals": {
"type": "array",
"example": []
},
"deals_total_value": {
"type": "integer",
"example": 5000
},
"next_action": {
"type": "string",
"example": null,
"nullable": true
}
}
}
}
}
}
},
"tags": [
"Contacts"
],
"x-mcp": true,
"x-mcp-name": "contacts.get"
},
"put": {
"summary": "Update Contact",
"operationId": "updateContact",
"description": "Update contact details.\n\nNOTE: status must be one of contact, lead, customer, inactive. Only fields you send are changed.",
"parameters": [],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"example": {
"data": {
"id": "con_abc123",
"email": "john.updated@example.com",
"name": "John Doe",
"status": "customer"
}
},
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "con_abc123"
},
"email": {
"type": "string",
"example": "john.updated@example.com"
},
"name": {
"type": "string",
"example": "John Doe"
},
"status": {
"type": "string",
"example": "customer"
}
}
}
}
}
}
}
}
},
"tags": [
"Contacts"
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"email": {
"type": "string",
"description": "Contact email.",
"example": "john.updated@example.com"
},
"phone": {
"type": "string",
"description": "Contact phone.",
"example": "+1234567890"
},
"name": {
"type": "string",
"description": "Contact name.",
"example": "John Doe"
},
"company": {
"type": "string",
"description": "Company name.",
"example": "Acme Corp"
},
"notes": {
"type": "string",
"description": "Internal notes.",
"example": "Follow up next week"
},
"status": {
"type": "string",
"description": "Contact status (contact, lead, customer, inactive).",
"example": "customer"
}
}
}
}
}
},
"x-mcp": true,
"x-mcp-name": "contacts.update"
},
"delete": {
"summary": "Delete Contact",
"operationId": "deleteContact",
"description": "Erase a contact together with everything attached to them: their inbox conversations (with messages and attachments) and their deals all go too. This is the \"right to be forgotten\" path. The response reports how many conversations and deals were removed.\n\nCRITICAL: This is far wider than it sounds. It is not \"remove a row from my contact list\", it wipes the person's whole history from the account. Everything is hidden rather than erased, so support can still recover it, but nothing in the app or the API can. Always tell the user what will go and get explicit confirmation first. To take someone off a list without destroying the history, use contacts.update with status inactive instead.",
"parameters": [],
"responses": {
"204": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "object",
"example": [],
"properties": []
}
}
}
}
},
"tags": [
"Contacts"
],
"x-mcp": true,
"x-mcp-name": "contacts.delete"
},
"parameters": [
{
"in": "path",
"name": "contact_id",
"description": "The contact ID.",
"example": "con_abc123",
"required": true,
"schema": {
"type": "string"
}
}
]
},
"/api/v1/deals": {
"get": {
"summary": "List Deals",
"operationId": "listDeals",
"description": "Get all deals with optional search and tag filtering.\n\nNOTE: Archived deals are hidden unless show_archived=true. Each deal carries status_id; resolve names with dealStatuses.list.",
"parameters": [
{
"in": "query",
"name": "search",
"description": "Search by name, email, phone, or company.",
"example": "acme",
"required": false,
"schema": {
"type": "string",
"description": "Search by name, email, phone, or company.",
"example": "acme"
}
},
{
"in": "query",
"name": "show_archived",
"description": "Include archived deals (default false).",
"example": false,
"required": false,
"schema": {
"type": "boolean",
"description": "Include archived deals (default false).",
"example": false
}
},
{
"in": "query",
"name": "tag_id",
"description": "Filter by CRM tag ID.",
"example": 1,
"required": false,
"schema": {
"type": "integer",
"description": "Filter by CRM tag ID.",
"example": 1
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"example": {
"data": [
{
"id": 574,
"uuid": "1880ba56-57f3-466d-a7c4-fb296546f031",
"status_id": null,
"status": null,
"row_id": null,
"assigned_to": null,
"assigned_user": null,
"notification_id": null,
"contact_id": null,
"domain_id": null,
"name": "Christiansen-Rice deal",
"email": "imoen@example.net",
"phone": "+18626587458",
"company": "Keebler-Greenholt",
"source": "Manual",
"notes": "A deleniti soluta ducimus.",
"external_url": null,
"value": "3229.00",
"temperature": "warm",
"outcome": null,
"archived_at": null,
"next_action_at": null,
"next_auto_follow_up_at": null,
"auto_follow_up_is_scheduled": false,
"follow_ups_sent": null,
"last_auto_follow_up_sent_at": null,
"last_ai_draft": null,
"last_ai_draft_at": null,
"business": null,
"follow_up_max": null,
"created_at": "2026-09-25 12:07:11",
"updated_at": "2026-09-25 12:07:11"
},
{
"id": 575,
"uuid": "afbf60d7-1534-40f5-bdda-3d93c71ee7b2",
"status_id": null,
"status": null,
"row_id": null,
"assigned_to": null,
"assigned_user": null,
"notification_id": null,
"contact_id": null,
"domain_id": null,
"name": "Bednar-Walsh deal",
"email": "zachary.sipes@example.com",
"phone": "+13344980512",
"company": "Smitham, Carroll and Swift",
"source": "Manual",
"notes": "Tempore rerum et atque quidem.",
"external_url": null,
"value": "5562.00",
"temperature": "warm",
"outcome": null,
"archived_at": null,
"next_action_at": null,
"next_auto_follow_up_at": null,
"auto_follow_up_is_scheduled": false,
"follow_ups_sent": null,
"last_auto_follow_up_sent_at": null,
"last_ai_draft": null,
"last_ai_draft_at": null,
"business": null,
"follow_up_max": null,
"created_at": "2026-09-25 12:07:11",
"updated_at": "2026-09-25 12:07:11"
}
]
},
"properties": {
"data": {
"type": "array",
"example": [
{
"id": 574,
"uuid": "1880ba56-57f3-466d-a7c4-fb296546f031",
"status_id": null,
"status": null,
"row_id": null,
"assigned_to": null,
"assigned_user": null,
"notification_id": null,
"contact_id": null,
"domain_id": null,
"name": "Christiansen-Rice deal",
"email": "imoen@example.net",
"phone": "+18626587458",
"company": "Keebler-Greenholt",
"source": "Manual",
"notes": "A deleniti soluta ducimus.",
"external_url": null,
"value": "3229.00",
"temperature": "warm",
"outcome": null,
"archived_at": null,
"next_action_at": null,
"next_auto_follow_up_at": null,
"auto_follow_up_is_scheduled": false,
"follow_ups_sent": null,
"last_auto_follow_up_sent_at": null,
"last_ai_draft": null,
"last_ai_draft_at": null,
"business": null,
"follow_up_max": null,
"created_at": "2026-09-25 12:07:11",
"updated_at": "2026-09-25 12:07:11"
},
{
"id": 575,
"uuid": "afbf60d7-1534-40f5-bdda-3d93c71ee7b2",
"status_id": null,
"status": null,
"row_id": null,
"assigned_to": null,
"assigned_user": null,
"notification_id": null,
"contact_id": null,
"domain_id": null,
"name": "Bednar-Walsh deal",
"email": "zachary.sipes@example.com",
"phone": "+13344980512",
"company": "Smitham, Carroll and Swift",
"source": "Manual",
"notes": "Tempore rerum et atque quidem.",
"external_url": null,
"value": "5562.00",
"temperature": "warm",
"outcome": null,
"archived_at": null,
"next_action_at": null,
"next_auto_follow_up_at": null,
"auto_follow_up_is_scheduled": false,
"follow_ups_sent": null,
"last_auto_follow_up_sent_at": null,
"last_ai_draft": null,
"last_ai_draft_at": null,
"business": null,
"follow_up_max": null,
"created_at": "2026-09-25 12:07:11",
"updated_at": "2026-09-25 12:07:11"
}
],
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"example": 574
},
"uuid": {
"type": "string",
"example": "1880ba56-57f3-466d-a7c4-fb296546f031"
},
"status_id": {
"type": "string",
"example": null,
"nullable": true
},
"status": {
"type": "string",
"example": null,
"nullable": true
},
"row_id": {
"type": "string",
"example": null,
"nullable": true
},
"assigned_to": {
"type": "string",
"example": null,
"nullable": true
},
"assigned_user": {
"type": "string",
"example": null,
"nullable": true
},
"notification_id": {
"type": "string",
"example": null,
"nullable": true
},
"contact_id": {
"type": "string",
"example": null,
"nullable": true
},
"domain_id": {
"type": "string",
"example": null,
"nullable": true
},
"name": {
"type": "string",
"example": "Christiansen-Rice deal"
},
"email": {
"type": "string",
"example": "imoen@example.net"
},
"phone": {
"type": "string",
"example": "+18626587458"
},
"company": {
"type": "string",
"example": "Keebler-Greenholt"
},
"source": {
"type": "string",
"example": "Manual"
},
"notes": {
"type": "string",
"example": "A deleniti soluta ducimus."
},
"external_url": {
"type": "string",
"example": null,
"nullable": true
},
"value": {
"type": "string",
"example": "3229.00"
},
"temperature": {
"type": "string",
"example": "warm"
},
"outcome": {
"type": "string",
"example": null,
"nullable": true
},
"archived_at": {
"type": "string",
"example": null,
"nullable": true
},
"next_action_at": {
"type": "string",
"example": null,
"nullable": true
},
"next_auto_follow_up_at": {
"type": "string",
"example": null,
"nullable": true
},
"auto_follow_up_is_scheduled": {
"type": "boolean",
"example": false
},
"follow_ups_sent": {
"type": "string",
"example": null,
"nullable": true
},
"last_auto_follow_up_sent_at": {
"type": "string",
"example": null,
"nullable": true
},
"last_ai_draft": {
"type": "string",
"example": null,
"nullable": true
},
"last_ai_draft_at": {
"type": "string",
"example": null,
"nullable": true
},
"business": {
"type": "string",
"example": null,
"nullable": true
},
"follow_up_max": {
"type": "string",
"example": null,
"nullable": true
},
"created_at": {
"type": "string",
"example": "2026-09-25 12:07:11"
},
"updated_at": {
"type": "string",
"example": "2026-09-25 12:07:11"
}
}
}
}
}
}
}
}
}
},
"tags": [
"Deals"
],
"x-mcp": true,
"x-mcp-name": "deals.list"
},
"post": {
"summary": "Create Deal",
"operationId": "createDeal",
"description": "Create a new deal. If no status_id is provided, the deal is placed in the first pipeline status.\n\nNOTE: Call dealStatuses.list first to pick a valid status_id; ids differ per account. temperature accepts cold, warm, hot.",
"parameters": [],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"example": {
"data": {
"id": 576,
"uuid": "59d30066-a4ab-42de-b9a4-6f49fbf2b9c0",
"status_id": null,
"status": null,
"row_id": null,
"assigned_to": null,
"assigned_user": null,
"notification_id": null,
"contact_id": null,
"domain_id": null,
"name": "Price Ltd deal",
"email": "dare.emelie@example.com",
"phone": "+14324666067",
"company": "Leffler PLC",
"source": "Manual",
"notes": "Facere tempora ex voluptatem laboriosam.",
"external_url": null,
"value": "3497.00",
"temperature": "warm",
"outcome": null,
"archived_at": null,
"next_action_at": null,
"next_auto_follow_up_at": null,
"auto_follow_up_is_scheduled": false,
"follow_ups_sent": null,
"last_auto_follow_up_sent_at": null,
"last_ai_draft": null,
"last_ai_draft_at": null,
"business": null,
"follow_up_max": null,
"created_at": "2026-09-25 12:07:11",
"updated_at": "2026-09-25 12:07:11"
}
},
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"example": 576
},
"uuid": {
"type": "string",
"example": "59d30066-a4ab-42de-b9a4-6f49fbf2b9c0"
},
"status_id": {
"type": "string",
"example": null,
"nullable": true
},
"status": {
"type": "string",
"example": null,
"nullable": true
},
"row_id": {
"type": "string",
"example": null,
"nullable": true
},
"assigned_to": {
"type": "string",
"example": null,
"nullable": true
},
"assigned_user": {
"type": "string",
"example": null,
"nullable": true
},
"notification_id": {
"type": "string",
"example": null,
"nullable": true
},
"contact_id": {
"type": "string",
"example": null,
"nullable": true
},
"domain_id": {
"type": "string",
"example": null,
"nullable": true
},
"name": {
"type": "string",
"example": "Price Ltd deal"
},
"email": {
"type": "string",
"example": "dare.emelie@example.com"
},
"phone": {
"type": "string",
"example": "+14324666067"
},
"company": {
"type": "string",
"example": "Leffler PLC"
},
"source": {
"type": "string",
"example": "Manual"
},
"notes": {
"type": "string",
"example": "Facere tempora ex voluptatem laboriosam."
},
"external_url": {
"type": "string",
"example": null,
"nullable": true
},
"value": {
"type": "string",
"example": "3497.00"
},
"temperature": {
"type": "string",
"example": "warm"
},
"outcome": {
"type": "string",
"example": null,
"nullable": true
},
"archived_at": {
"type": "string",
"example": null,
"nullable": true
},
"next_action_at": {
"type": "string",
"example": null,
"nullable": true
},
"next_auto_follow_up_at": {
"type": "string",
"example": null,
"nullable": true
},
"auto_follow_up_is_scheduled": {
"type": "boolean",
"example": false
},
"follow_ups_sent": {
"type": "string",
"example": null,
"nullable": true
},
"last_auto_follow_up_sent_at": {
"type": "string",
"example": null,
"nullable": true
},
"last_ai_draft": {
"type": "string",
"example": null,
"nullable": true
},
"last_ai_draft_at": {
"type": "string",
"example": null,
"nullable": true
},
"business": {
"type": "string",
"example": null,
"nullable": true
},
"follow_up_max": {
"type": "string",
"example": null,
"nullable": true
},
"created_at": {
"type": "string",
"example": "2026-09-25 12:07:11"
},
"updated_at": {
"type": "string",
"example": "2026-09-25 12:07:11"
}
}
}
}
}
}
}
}
},
"tags": [
"Deals"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The deal name.",
"example": "Enterprise License"
},
"email": {
"type": "string",
"description": "Contact email.",
"example": "john@acme.com"
},
"phone": {
"type": "string",
"description": "Contact phone.",
"example": "+1234567890"
},
"company": {
"type": "string",
"description": "Company name.",
"example": "Acme Corp"
},
"value": {
"type": "number",
"description": "Deal value.",
"example": 5000
},
"source": {
"type": "string",
"description": "Lead source.",
"example": "API"
},
"notes": {
"type": "string",
"description": "Internal notes.",
"example": "Interested in annual plan"
},
"external_url": {
"type": "string",
"description": "External URL for context (e.g. quote page, contract link).",
"example": "https://acme.com/quotes/123"
},
"temperature": {
"type": "string",
"description": "Deal temperature (cold, warm, hot).",
"example": "warm"
},
"status_id": {
"type": "integer",
"description": "Pipeline status ID (uses first status if omitted).",
"example": 1
},
"row_id": {
"type": "integer",
"description": "Optional pipeline row (swimlane) ID.",
"example": 3
},
"assigned_to": {
"type": "integer",
"description": "Team member (user ID) to assign the deal to. Must be a member of your team (see GET /team-members). Defaults to the API key's owner.",
"example": 42
},
"contact_id": {
"type": "string",
"description": "Link to existing contact.",
"example": "con_abc123"
},
"domain_id": {
"type": "integer",
"description": "Business (domain) this deal belongs to. Defaults to the contact's or thread's domain if omitted.",
"example": 42
},
"meta": {
"type": "object",
"description": "Free-form key/value facts stored on the deal (each value max 1000 chars). Shown on the deal page.",
"example": {
"service_type": "Full service",
"booking_start": "2026-11-01"
},
"properties": []
},
"skip_auto_follow_up": {
"type": "boolean",
"description": "Set to true to NOT schedule Boei's AI auto follow-up for this deal. Use it when another system already handles outreach for this deal. Default false.",
"example": true
}
},
"required": [
"name"
]
}
}
}
},
"x-mcp": true,
"x-mcp-name": "deals.create"
}
},
"/api/v1/deals/{deal_id}": {
"get": {
"summary": "Get Deal",
"operationId": "getDeal",
"description": "Get a single deal with its status, assigned user, contact, and tags.",
"parameters": [],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"example": {
"data": {
"id": 577,
"uuid": "d4e7d344-ad61-44de-a22e-30b729eaf898",
"status_id": null,
"status": null,
"row_id": null,
"assigned_to": null,
"assigned_user": null,
"notification_id": null,
"contact_id": null,
"domain_id": null,
"name": "Price Ltd deal",
"email": "imclaughlin@example.org",
"phone": "+17159527161",
"company": "Leuschke-Feeney",
"source": "Manual",
"notes": "Laboriosam praesentium quis adipisci molestias fugit deleniti distinctio.",
"external_url": null,
"value": "7442.00",
"temperature": "warm",
"outcome": null,
"archived_at": null,
"next_action_at": null,
"next_auto_follow_up_at": null,
"auto_follow_up_is_scheduled": false,
"follow_ups_sent": null,
"last_auto_follow_up_sent_at": null,
"last_ai_draft": null,
"last_ai_draft_at": null,
"business": null,
"follow_up_max": null,
"created_at": "2026-09-25 12:07:11",
"updated_at": "2026-09-25 12:07:11"
}
},
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"example": 577
},
"uuid": {
"type": "string",
"example": "d4e7d344-ad61-44de-a22e-30b729eaf898"
},
"status_id": {
"type": "string",
"example": null,
"nullable": true
},
"status": {
"type": "string",
"example": null,
"nullable": true
},
"row_id": {
"type": "string",
"example": null,
"nullable": true
},
"assigned_to": {
"type": "string",
"example": null,
"nullable": true
},
"assigned_user": {
"type": "string",
"example": null,
"nullable": true
},
"notification_id": {
"type": "string",
"example": null,
"nullable": true
},
"contact_id": {
"type": "string",
"example": null,
"nullable": true
},
"domain_id": {
"type": "string",
"example": null,
"nullable": true
},
"name": {
"type": "string",
"example": "Price Ltd deal"
},
"email": {
"type": "string",
"example": "imclaughlin@example.org"
},
"phone": {
"type": "string",
"example": "+17159527161"
},
"company": {
"type": "string",
"example": "Leuschke-Feeney"
},
"source": {
"type": "string",
"example": "Manual"
},
"notes": {
"type": "string",
"example": "Laboriosam praesentium quis adipisci molestias fugit deleniti distinctio."
},
"external_url": {
"type": "string",
"example": null,
"nullable": true
},
"value": {
"type": "string",
"example": "7442.00"
},
"temperature": {
"type": "string",
"example": "warm"
},
"outcome": {
"type": "string",
"example": null,
"nullable": true
},
"archived_at": {
"type": "string",
"example": null,
"nullable": true
},
"next_action_at": {
"type": "string",
"example": null,
"nullable": true
},
"next_auto_follow_up_at": {
"type": "string",
"example": null,
"nullable": true
},
"auto_follow_up_is_scheduled": {
"type": "boolean",
"example": false
},
"follow_ups_sent": {
"type": "string",
"example": null,
"nullable": true
},
"last_auto_follow_up_sent_at": {
"type": "string",
"example": null,
"nullable": true
},
"last_ai_draft": {
"type": "string",
"example": null,
"nullable": true
},
"last_ai_draft_at": {
"type": "string",
"example": null,
"nullable": true
},
"business": {
"type": "string",
"example": null,
"nullable": true
},
"follow_up_max": {
"type": "string",
"example": null,
"nullable": true
},
"created_at": {
"type": "string",
"example": "2026-09-25 12:07:11"
},
"updated_at": {
"type": "string",
"example": "2026-09-25 12:07:11"
}
}
}
}
}
}
}
}
},
"tags": [
"Deals"
],
"x-mcp": true,
"x-mcp-name": "deals.get"
},
"put": {
"summary": "Update Deal",
"operationId": "updateDeal",
"description": "Update deal details, status, assignment, or temperature.\n\nCRITICAL: Setting outcome (won, lost, abandoned) closes the deal. To move a deal to another pipeline column send status_id from dealStatuses.list instead.",
"parameters": [],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"example": {
"data": {
"id": 578,
"uuid": "311629f6-b523-401c-a3e8-2343905a2b01",
"status_id": null,
"status": null,
"row_id": null,
"assigned_to": null,
"assigned_user": null,
"notification_id": null,
"contact_id": null,
"domain_id": null,
"name": "Price Ltd deal",
"email": "okeefe.isidro@example.org",
"phone": "+19152306227",
"company": "Schultz Group",
"source": "Manual",
"notes": "Fugit deleniti distinctio eum doloremque id aut libero.",
"external_url": null,
"value": "8669.00",
"temperature": "warm",
"outcome": null,
"archived_at": null,
"next_action_at": null,
"next_auto_follow_up_at": null,
"auto_follow_up_is_scheduled": false,
"follow_ups_sent": null,
"last_auto_follow_up_sent_at": null,
"last_ai_draft": null,
"last_ai_draft_at": null,
"business": null,
"follow_up_max": null,
"created_at": "2026-09-25 12:07:11",
"updated_at": "2026-09-25 12:07:11"
}
},
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"example": 578
},
"uuid": {
"type": "string",
"example": "311629f6-b523-401c-a3e8-2343905a2b01"
},
"status_id": {
"type": "string",
"example": null,
"nullable": true
},
"status": {
"type": "string",
"example": null,
"nullable": true
},
"row_id": {
"type": "string",
"example": null,
"nullable": true
},
"assigned_to": {
"type": "string",
"example": null,
"nullable": true
},
"assigned_user": {
"type": "string",
"example": null,
"nullable": true
},
"notification_id": {
"type": "string",
"example": null,
"nullable": true
},
"contact_id": {
"type": "string",
"example": null,
"nullable": true
},
"domain_id": {
"type": "string",
"example": null,
"nullable": true
},
"name": {
"type": "string",
"example": "Price Ltd deal"
},
"email": {
"type": "string",
"example": "okeefe.isidro@example.org"
},
"phone": {
"type": "string",
"example": "+19152306227"
},
"company": {
"type": "string",
"example": "Schultz Group"
},
"source": {
"type": "string",
"example": "Manual"
},
"notes": {
"type": "string",
"example": "Fugit deleniti distinctio eum doloremque id aut libero."
},
"external_url": {
"type": "string",
"example": null,
"nullable": true
},
"value": {
"type": "string",
"example": "8669.00"
},
"temperature": {
"type": "string",
"example": "warm"
},
"outcome": {
"type": "string",
"example": null,
"nullable": true
},
"archived_at": {
"type": "string",
"example": null,
"nullable": true
},
"next_action_at": {
"type": "string",
"example": null,
"nullable": true
},
"next_auto_follow_up_at": {
"type": "string",
"example": null,
"nullable": true
},
"auto_follow_up_is_scheduled": {
"type": "boolean",
"example": false
},
"follow_ups_sent": {
"type": "string",
"example": null,
"nullable": true
},
"last_auto_follow_up_sent_at": {
"type": "string",
"example": null,
"nullable": true
},
"last_ai_draft": {
"type": "string",
"example": null,
"nullable": true
},
"last_ai_draft_at": {
"type": "string",
"example": null,
"nullable": true
},
"business": {
"type": "string",
"example": null,
"nullable": true
},
"follow_up_max": {
"type": "string",
"example": null,
"nullable": true
},
"created_at": {
"type": "string",
"example": "2026-09-25 12:07:11"
},
"updated_at": {
"type": "string",
"example": "2026-09-25 12:07:11"
}
}
}
}
}
}
}
}
},
"tags": [
"Deals"
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The deal name.",
"example": "Enterprise License v2"
},
"email": {
"type": "string",
"description": "Contact email.",
"example": "john@acme.com"
},
"phone": {
"type": "string",
"description": "Contact phone.",
"example": "+1234567890"
},
"company": {
"type": "string",
"description": "Company name.",
"example": "Acme Corp"
},
"value": {
"type": "number",
"description": "Deal value.",
"example": 7500
},
"source": {
"type": "string",
"description": "Lead source.",
"example": "API"
},
"notes": {
"type": "string",
"description": "Internal notes.",
"example": "Negotiating price"
},
"external_url": {
"type": "string",
"description": "External URL for context.",
"example": "https://acme.com/quotes/123"
},
"temperature": {
"type": "string",
"description": "Deal temperature (cold, warm, hot).",
"example": "hot"
},
"outcome": {
"type": "string",
"description": "Terminal outcome (won, lost, abandoned). Setting this closes the deal.",
"example": "won"
},
"status_id": {
"type": "integer",
"description": "Pipeline status ID.",
"example": 2
},
"row_id": {
"type": "integer",
"description": "Pipeline row (swimlane) ID.",
"example": 3
},
"assigned_to": {
"type": "integer",
"description": "Team member (user ID) to assign the deal to. Must be a member of your team (see GET /team-members).",
"example": 42
},
"contact_id": {
"type": "string",
"description": "Link to existing contact.",
"example": "con_abc123"
},
"domain_id": {
"type": "integer",
"description": "Move the deal to a different business (must be one you own).",
"example": 42
},
"meta": {
"type": "object",
"description": "Key/value facts to merge into the deal's meta. Keys not present are left untouched; a null value removes that key.",
"example": {
"country": "Netherlands",
"recruiter": null
},
"properties": []
}
}
}
}
}
},
"x-mcp": true,
"x-mcp-name": "deals.update"
},
"delete": {
"summary": "Delete Deal",
"operationId": "deleteDeal",
"description": "Delete a deal. It disappears from the pipeline and from this API, but it is hidden rather than erased, so support can still bring it back with its activity timeline intact.\n\nNOTE: Recoverable, but there is no undo in the app or the API. Prefer deals.archive when the user just wants it off the board; use delete for records that should not exist at all. Confirm with the user either way.",
"parameters": [],
"responses": {
"204": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "object",
"example": [],
"properties": []
}
}
}
}
},
"tags": [
"Deals"
],
"x-mcp": true,
"x-mcp-name": "deals.delete"
},
"parameters": [
{
"in": "path",
"name": "deal_id",
"description": "The deal ID.",
"example": 1,
"required": true,
"schema": {
"type": "integer"
}
}
]
},
"/api/v1/deals/{deal_id}/archive": {
"post": {
"summary": "Archive Deal",
"operationId": "archiveDeal",
"description": "Archive a deal (soft-hide from the pipeline).",
"parameters": [],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"example": {
"data": {
"id": 579,
"uuid": "bd7d7030-eac3-4d79-8e2e-c8825e7c5a01",
"status_id": null,
"status": null,
"row_id": null,
"assigned_to": null,
"assigned_user": null,
"notification_id": null,
"contact_id": null,
"domain_id": null,
"name": "Price Ltd deal",
"email": "ztromp@example.org",
"phone": "+15596932083",
"company": "Wisoky-Kshlerin",
"source": "Manual",
"notes": "Doloremque id aut libero aliquam veniam corporis.",
"external_url": null,
"value": "6441.00",
"temperature": "warm",
"outcome": null,
"archived_at": null,
"next_action_at": null,
"next_auto_follow_up_at": null,
"auto_follow_up_is_scheduled": false,
"follow_ups_sent": null,
"last_auto_follow_up_sent_at": null,
"last_ai_draft": null,
"last_ai_draft_at": null,
"business": null,
"follow_up_max": null,
"created_at": "2026-09-25 12:07:11",
"updated_at": "2026-09-25 12:07:11"
}
},
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"example": 579
},
"uuid": {
"type": "string",
"example": "bd7d7030-eac3-4d79-8e2e-c8825e7c5a01"
},
"status_id": {
"type": "string",
"example": null,
"nullable": true
},
"status": {
"type": "string",
"example": null,
"nullable": true
},
"row_id": {
"type": "string",
"example": null,
"nullable": true
},
"assigned_to": {
"type": "string",
"example": null,
"nullable": true
},
"assigned_user": {
"type": "string",
"example": null,
"nullable": true
},
"notification_id": {
"type": "string",
"example": null,
"nullable": true
},
"contact_id": {
"type": "string",
"example": null,
"nullable": true
},
"domain_id": {
"type": "string",
"example": null,
"nullable": true
},
"name": {
"type": "string",
"example": "Price Ltd deal"
},
"email": {
"type": "string",
"example": "ztromp@example.org"
},
"phone": {
"type": "string",
"example": "+15596932083"
},
"company": {
"type": "string",
"example": "Wisoky-Kshlerin"
},
"source": {
"type": "string",
"example": "Manual"
},
"notes": {
"type": "string",
"example": "Doloremque id aut libero aliquam veniam corporis."
},
"external_url": {
"type": "string",
"example": null,
"nullable": true
},
"value": {
"type": "string",
"example": "6441.00"
},
"temperature": {
"type": "string",
"example": "warm"
},
"outcome": {
"type": "string",
"example": null,
"nullable": true
},
"archived_at": {
"type": "string",
"example": null,
"nullable": true
},
"next_action_at": {
"type": "string",
"example": null,
"nullable": true
},
"next_auto_follow_up_at": {
"type": "string",
"example": null,
"nullable": true
},
"auto_follow_up_is_scheduled": {
"type": "boolean",
"example": false
},
"follow_ups_sent": {
"type": "string",
"example": null,
"nullable": true
},
"last_auto_follow_up_sent_at": {
"type": "string",
"example": null,
"nullable": true
},
"last_ai_draft": {
"type": "string",
"example": null,
"nullable": true
},
"last_ai_draft_at": {
"type": "string",
"example": null,
"nullable": true
},
"business": {
"type": "string",
"example": null,
"nullable": true
},
"follow_up_max": {
"type": "string",
"example": null,
"nullable": true
},
"created_at": {
"type": "string",
"example": "2026-09-25 12:07:11"
},
"updated_at": {
"type": "string",
"example": "2026-09-25 12:07:11"
}
}
}
}
}
}
}
}
},
"tags": [
"Deals"
],
"x-mcp": true,
"x-mcp-name": "deals.archive"
},
"parameters": [
{
"in": "path",
"name": "deal_id",
"description": "The deal ID.",
"example": 1,
"required": true,
"schema": {
"type": "integer"
}
}
]
},
"/api/v1/deals/{deal_id}/unarchive": {
"post": {
"summary": "Unarchive Deal",
"operationId": "unarchiveDeal",
"description": "Restore an archived deal to the pipeline.",
"parameters": [],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"example": {
"data": {
"id": 580,
"uuid": "57bddb5d-b552-4ed5-aca4-de2f1a61c6e6",
"status_id": null,
"status": null,
"row_id": null,
"assigned_to": null,
"assigned_user": null,
"notification_id": null,
"contact_id": null,
"domain_id": null,
"name": "Price Ltd deal",
"email": "matilda.feeney@example.net",
"phone": "+16463295127",
"company": "McDermott-Klocko",
"source": "Manual",
"notes": "Corporis dolorem mollitia deleniti nemo odit quia officia.",
"external_url": null,
"value": "3723.00",
"temperature": "warm",
"outcome": null,
"archived_at": null,
"next_action_at": null,
"next_auto_follow_up_at": null,
"auto_follow_up_is_scheduled": false,
"follow_ups_sent": null,
"last_auto_follow_up_sent_at": null,
"last_ai_draft": null,
"last_ai_draft_at": null,
"business": null,
"follow_up_max": null,
"created_at": "2026-09-25 12:07:11",
"updated_at": "2026-09-25 12:07:11"
}
},
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"example": 580
},
"uuid": {
"type": "string",
"example": "57bddb5d-b552-4ed5-aca4-de2f1a61c6e6"
},
"status_id": {
"type": "string",
"example": null,
"nullable": true
},
"status": {
"type": "string",
"example": null,
"nullable": true
},
"row_id": {
"type": "string",
"example": null,
"nullable": true
},
"assigned_to": {
"type": "string",
"example": null,
"nullable": true
},
"assigned_user": {
"type": "string",
"example": null,
"nullable": true
},
"notification_id": {
"type": "string",
"example": null,
"nullable": true
},
"contact_id": {
"type": "string",
"example": null,
"nullable": true
},
"domain_id": {
"type": "string",
"example": null,
"nullable": true
},
"name": {
"type": "string",
"example": "Price Ltd deal"
},
"email": {
"type": "string",
"example": "matilda.feeney@example.net"
},
"phone": {
"type": "string",
"example": "+16463295127"
},
"company": {
"type": "string",
"example": "McDermott-Klocko"
},
"source": {
"type": "string",
"example": "Manual"
},
"notes": {
"type": "string",
"example": "Corporis dolorem mollitia deleniti nemo odit quia officia."
},
"external_url": {
"type": "string",
"example": null,
"nullable": true
},
"value": {
"type": "string",
"example": "3723.00"
},
"temperature": {
"type": "string",
"example": "warm"
},
"outcome": {
"type": "string",
"example": null,
"nullable": true
},
"archived_at": {
"type": "string",
"example": null,
"nullable": true
},
"next_action_at": {
"type": "string",
"example": null,
"nullable": true
},
"next_auto_follow_up_at": {
"type": "string",
"example": null,
"nullable": true
},
"auto_follow_up_is_scheduled": {
"type": "boolean",
"example": false
},
"follow_ups_sent": {
"type": "string",
"example": null,
"nullable": true
},
"last_auto_follow_up_sent_at": {
"type": "string",
"example": null,
"nullable": true
},
"last_ai_draft": {
"type": "string",
"example": null,
"nullable": true
},
"last_ai_draft_at": {
"type": "string",
"example": null,
"nullable": true
},
"business": {
"type": "string",
"example": null,
"nullable": true
},
"follow_up_max": {
"type": "string",
"example": null,
"nullable": true
},
"created_at": {
"type": "string",
"example": "2026-09-25 12:07:11"
},
"updated_at": {
"type": "string",
"example": "2026-09-25 12:07:11"
}
}
}
}
}
}
}
}
},
"tags": [
"Deals"
],
"x-mcp": true,
"x-mcp-name": "deals.unarchive"
},
"parameters": [
{
"in": "path",
"name": "deal_id",
"description": "The deal ID.",
"example": 1,
"required": true,
"schema": {
"type": "integer"
}
}
]
},
"/api/v1/deal-statuses": {
"get": {
"summary": "List Deal Statuses",
"operationId": "listDealStatuses",
"description": "Get all pipeline statuses (columns). Creates default statuses (New, Contacted, Qualified, Proposal, Won, Lost) if none exist.\n\nNOTE: Call this before deals.create or deals.update when you need a status_id. Order in the response is the pipeline order.",
"parameters": [],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"example": {
"data": [
{
"id": 1,
"name": "New",
"color": "#3b82f6",
"order": 0
},
{
"id": 2,
"name": "Contacted",
"color": "#f59e0b",
"order": 1
},
{
"id": 3,
"name": "Won",
"color": "#10b981",
"order": 2
},
{
"id": 4,
"name": "Lost",
"color": "#ef4444",
"order": 3
}
]
},
"properties": {
"data": {
"type": "array",
"example": [
{
"id": 1,
"name": "New",
"color": "#3b82f6",
"order": 0
},
{
"id": 2,
"name": "Contacted",
"color": "#f59e0b",
"order": 1
},
{
"id": 3,
"name": "Won",
"color": "#10b981",
"order": 2
},
{
"id": 4,
"name": "Lost",
"color": "#ef4444",
"order": 3
}
],
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "New"
},
"color": {
"type": "string",
"example": "#3b82f6"
},
"order": {
"type": "integer",
"example": 0
}
}
}
}
}
}
}
}
}
},
"tags": [
"Deal Statuses"
],
"x-mcp": true,
"x-mcp-name": "dealStatuses.list"
},
"post": {
"summary": "Create Deal Status",
"operationId": "createDealStatus",
"description": "Add a new pipeline status column.",
"parameters": [],
"responses": {
"201": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"example": {
"data": {
"id": 5,
"name": "Proposal Sent",
"emoji": "💰",
"color": "#8b5cf6",
"order": 4
}
},
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"example": 5
},
"name": {
"type": "string",
"example": "Proposal Sent"
},
"emoji": {
"type": "string",
"example": "💰"
},
"color": {
"type": "string",
"example": "#8b5cf6"
},
"order": {
"type": "integer",
"example": 4
}
}
}
}
}
}
}
}
},
"tags": [
"Deal Statuses"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Status name.",
"example": "Proposal Sent"
},
"emoji": {
"type": "string",
"description": "Optional emoji shown on the column header.",
"example": "💰"
},
"color": {
"type": "string",
"description": "Hex color code.",
"example": "#8b5cf6"
}
},
"required": [
"name"
]
}
}
}
},
"x-mcp": true,
"x-mcp-name": "dealStatuses.create"
}
},
"/api/v1/deal-statuses/{status_id}": {
"put": {
"summary": "Update Deal Status",
"operationId": "updateDealStatus",
"description": "Update a pipeline status name or color.",
"parameters": [],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"example": {
"data": {
"id": 1,
"name": "Qualified",
"emoji": "✅",
"color": "#06b6d4",
"order": 0
}
},
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "Qualified"
},
"emoji": {
"type": "string",
"example": "✅"
},
"color": {
"type": "string",
"example": "#06b6d4"
},
"order": {
"type": "integer",
"example": 0
}
}
}
}
}
}
}
}
},
"tags": [
"Deal Statuses"
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Status name.",
"example": "Qualified"
},
"emoji": {
"type": "string",
"description": "Optional emoji shown on the column header.",
"example": "✅"
},
"color": {
"type": "string",
"description": "Hex color code.",
"example": "#06b6d4"
}
}
}
}
}
},
"x-mcp": true,
"x-mcp-name": "dealStatuses.update"
},
"delete": {
"summary": "Delete Deal Status",
"operationId": "deleteDealStatus",
"description": "Delete a pipeline status. Deals in this status are moved to the first remaining status.\n\nCRITICAL: Deals in this column are moved to the first remaining column. Confirm with the user first.",
"parameters": [],
"responses": {
"204": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "object",
"example": [],
"properties": []
}
}
}
}
},
"tags": [
"Deal Statuses"
],
"x-mcp": true,
"x-mcp-name": "dealStatuses.delete"
},
"parameters": [
{
"in": "path",
"name": "status_id",
"description": "The status ID.",
"example": 1,
"required": true,
"schema": {
"type": "integer"
}
}
]
},
"/api/v1/inbox": {
"get": {
"summary": "List Threads",
"operationId": "listThreads",
"description": "Get inbox threads with filtering and pagination. Returns most recent threads first.\n\nNOTE: Default status filter is all_except_closed. Pass status=all to include closed threads. Thread ids are UUIDs.",
"parameters": [
{
"in": "query",
"name": "status",
"description": "Filter by status (open, pending, closed, all, all_except_closed, snoozed, spam). Default: all_except_closed.",
"example": "open",
"required": false,
"schema": {
"type": "string",
"description": "Filter by status (open, pending, closed, all, all_except_closed, snoozed, spam). Default: all_except_closed.",
"example": "open"
}
},
{
"in": "query",
"name": "search",
"description": "Search by sender name, email, or content.",
"example": "john",
"required": false,
"schema": {
"type": "string",
"description": "Search by sender name, email, or content.",
"example": "john"
}
},
{
"in": "query",
"name": "chatbot",
"description": "Filter by chatbot UUID.",
"example": "8a832d1b-0f49-47f6-a05f-0b65b91d2107",
"required": false,
"schema": {
"type": "string",
"description": "Filter by chatbot UUID.",
"example": "8a832d1b-0f49-47f6-a05f-0b65b91d2107"
}
},
{
"in": "query",
"name": "tag",
"description": "Filter by tag ID (owner-scoped; cross-owner ids return empty). Combines with status/chatbot/channel/etc. via AND.",
"example": 42,
"required": false,
"schema": {
"type": "integer",
"description": "Filter by tag ID (owner-scoped; cross-owner ids return empty). Combines with status/chatbot/channel/etc. via AND.",
"example": 42
}
},
{
"in": "query",
"name": "per_page",
"description": "Results per page (max 100, default 50).",
"example": 25,
"required": false,
"schema": {
"type": "integer",
"description": "Results per page (max 100, default 50).",
"example": 25
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"example": {
"data": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"type": "Contact Form",
"thread_type": "contact_form",
"status": "open",
"customer": "John Doe",
"contact": "john@example.com",
"email": "john@example.com",
"subject": "Question about pricing",
"preview_text": "I would like to know more about...",
"message_count": 3,
"created_at": "2026-01-29 10:30:00",
"last_message_at": "2026-01-29 11:00:00"
}
],
"meta": {
"current_page": 1,
"last_page": 5,
"per_page": 25,
"total": 120
}
},
"properties": {
"data": {
"type": "array",
"example": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"type": "Contact Form",
"thread_type": "contact_form",
"status": "open",
"customer": "John Doe",
"contact": "john@example.com",
"email": "john@example.com",
"subject": "Question about pricing",
"preview_text": "I would like to know more about...",
"message_count": 3,
"created_at": "2026-01-29 10:30:00",
"last_message_at": "2026-01-29 11:00:00"
}
],
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "550e8400-e29b-41d4-a716-446655440000"
},
"type": {
"type": "string",
"example": "Contact Form"
},
"thread_type": {
"type": "string",
"example": "contact_form"
},
"status": {
"type": "string",
"example": "open"
},
"customer": {
"type": "string",
"example": "John Doe"
},
"contact": {
"type": "string",
"example": "john@example.com"
},
"email": {
"type": "string",
"example": "john@example.com"
},
"subject": {
"type": "string",
"example": "Question about pricing"
},
"preview_text": {
"type": "string",
"example": "I would like to know more about..."
},
"message_count": {
"type": "integer",
"example": 3
},
"created_at": {
"type": "string",
"example": "2026-01-29 10:30:00"
},
"last_message_at": {
"type": "string",
"example": "2026-01-29 11:00:00"
}
}
}
},
"meta": {
"type": "object",
"properties": {
"current_page": {
"type": "integer",
"example": 1
},
"last_page": {
"type": "integer",
"example": 5
},
"per_page": {
"type": "integer",
"example": 25
},
"total": {
"type": "integer",
"example": 120
}
}
}
}
}
}
}
}
},
"tags": [
"Inbox"
],
"x-mcp": true,
"x-mcp-name": "inbox.list"
},
"post": {
"summary": "Create Thread",
"operationId": "createThread",
"description": "Create a new inbox thread from an external source (e.g., contact form, CRM, or custom integration).\n\nNOTE: thread_type must be one of contact_form, callback, feedback, newsletter, channel_message. status accepts open or pending (default: open); legacy aliases are normalized before storage. domain_id (the business the thread belongs to) can be omitted when the account has one business; with several, the validation error lists the available ids and names.",
"parameters": [],
"responses": {
"201": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"example": {
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"thread_type": "contact_form",
"status": "open",
"customer": "John Doe",
"email": "john@example.com",
"message_count": 1
}
},
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "550e8400-e29b-41d4-a716-446655440000"
},
"thread_type": {
"type": "string",
"example": "contact_form"
},
"status": {
"type": "string",
"example": "open"
},
"customer": {
"type": "string",
"example": "John Doe"
},
"email": {
"type": "string",
"example": "john@example.com"
},
"message_count": {
"type": "integer",
"example": 1
}
}
}
}
}
}
}
}
},
"tags": [
"Inbox"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"thread_type": {
"type": "string",
"description": "The thread type.",
"example": "contact_form"
},
"subject": {
"type": "string",
"description": "Thread subject.",
"example": "Question about pricing",
"nullable": true
},
"sender_name": {
"type": "string",
"description": "Sender's name.",
"example": "John Doe",
"nullable": true
},
"sender_email": {
"type": "string",
"description": "Sender's email.",
"example": "john@example.com",
"nullable": true
},
"sender_phone": {
"type": "string",
"description": "Sender's phone.",
"example": "+1234567890",
"nullable": true
},
"message": {
"type": "string",
"description": "The initial message body.",
"example": "I would like to know more about your enterprise plan."
},
"contact_id": {
"type": "string",
"description": "Link to existing contact.",
"example": "con_abc123",
"nullable": true
},
"domain_id": {
"type": "integer",
"description": "The business (domain) this thread belongs to. Optional when the account has exactly one business.",
"example": 42,
"nullable": true
},
"status": {
"type": "string",
"description": "Initial status: open or pending (default: open).",
"example": "open"
}
},
"required": [
"thread_type",
"message"
]
}
}
}
},
"x-mcp": true,
"x-mcp-name": "inbox.createThread"
}
},
"/api/v1/inbox/{thread_id}": {
"get": {
"summary": "Get Thread",
"operationId": "getThread",
"description": "Get a single thread with all its messages.",
"parameters": [],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"example": {
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"type": "Contact Form",
"status": "open",
"customer": "John Doe",
"email": "john@example.com"
},
"messages": [
{
"id": 1,
"direction": "inbound",
"sender_type": "contact",
"sender_name": "John Doe",
"body": "I have a question about pricing.",
"content_type": "text",
"created_at": "2026-01-29 10:30:00"
}
]
},
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "550e8400-e29b-41d4-a716-446655440000"
},
"type": {
"type": "string",
"example": "Contact Form"
},
"status": {
"type": "string",
"example": "open"
},
"customer": {
"type": "string",
"example": "John Doe"
},
"email": {
"type": "string",
"example": "john@example.com"
}
}
},
"messages": {
"type": "array",
"example": [
{
"id": 1,
"direction": "inbound",
"sender_type": "contact",
"sender_name": "John Doe",
"body": "I have a question about pricing.",
"content_type": "text",
"created_at": "2026-01-29 10:30:00"
}
],
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"example": 1
},
"direction": {
"type": "string",
"example": "inbound"
},
"sender_type": {
"type": "string",
"example": "contact"
},
"sender_name": {
"type": "string",
"example": "John Doe"
},
"body": {
"type": "string",
"example": "I have a question about pricing."
},
"content_type": {
"type": "string",
"example": "text"
},
"created_at": {
"type": "string",
"example": "2026-01-29 10:30:00"
}
}
}
}
}
}
}
}
}
},
"tags": [
"Inbox"
],
"x-mcp": true,
"x-mcp-name": "inbox.get"
},
"delete": {
"summary": "Delete Thread",
"operationId": "deleteThread",
"description": "Delete an inbox thread together with its messages, attachments and session data. The thread disappears from the inbox for everyone on the account.\n\nCRITICAL: No undo in the app or the API. The thread is hidden rather than erased, so support can still recover it. Prefer inbox.updateStatus with status=closed unless the user explicitly asks to delete the conversation (e.g. spam, or a GDPR erasure request).",
"parameters": [],
"responses": {
"204": {
"description": "Deleted",
"content": {
"application/json": {
"schema": {
"type": "object",
"example": [],
"properties": []
}
}
}
},
"404": {
"description": "Not found",
"content": {
"application/json": {
"schema": {
"type": "object",
"example": {
"error": "Thread not found"
},
"properties": {
"error": {
"type": "string",
"example": "Thread not found"
}
}
}
}
}
}
},
"tags": [
"Inbox"
],
"x-mcp": true,
"x-mcp-name": "inbox.deleteThread"
},
"parameters": [
{
"in": "path",
"name": "thread_id",
"description": "The thread UUID.",
"example": "550e8400-e29b-41d4-a716-446655440000",
"required": true,
"schema": {
"type": "string"
}
}
]
},
"/api/v1/inbox/{thread_id}/messages": {
"post": {
"summary": "Add Message to Thread",
"operationId": "addMessageToThread",
"description": "Add a new message to an existing thread.\n\nCRITICAL: sender_type=agent records the message as a reply from your team; sender_type=contact (default) records it as an incoming message. This stores the message in the inbox only, it does not email or chat the visitor.",
"parameters": [],
"responses": {
"201": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"example": {
"data": {
"id": 5,
"direction": "inbound",
"sender_type": "contact",
"sender_name": "John Doe",
"body": "Thank you for your response, I have one more question.",
"content_type": "text",
"created_at": "2026-01-29 11:00:00"
}
},
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"example": 5
},
"direction": {
"type": "string",
"example": "inbound"
},
"sender_type": {
"type": "string",
"example": "contact"
},
"sender_name": {
"type": "string",
"example": "John Doe"
},
"body": {
"type": "string",
"example": "Thank you for your response, I have one more question."
},
"content_type": {
"type": "string",
"example": "text"
},
"created_at": {
"type": "string",
"example": "2026-01-29 11:00:00"
}
}
}
}
}
}
}
}
},
"tags": [
"Inbox"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"description": "The message body.",
"example": "Thank you for your response, I have one more question."
},
"sender_type": {
"type": "string",
"description": "Sender type (contact, agent). Default: contact.",
"example": "contact",
"nullable": true
},
"sender_name": {
"type": "string",
"description": "Sender's name.",
"example": "John Doe",
"nullable": true
}
},
"required": [
"message"
]
}
}
}
},
"x-mcp": true,
"x-mcp-name": "inbox.addMessage"
},
"parameters": [
{
"in": "path",
"name": "thread_id",
"description": "The thread UUID.",
"example": "550e8400-e29b-41d4-a716-446655440000",
"required": true,
"schema": {
"type": "string"
}
}
]
},
"/api/v1/inbox/{thread_id}/status": {
"put": {
"summary": "Update Thread Status",
"operationId": "updateThreadStatus",
"description": "Update the status of an inbox thread.\n\nNOTE: status must be open, pending or closed. Legacy aliases are normalized. Snoozing requires the dedicated snooze endpoint and a date; snoozed is not a stored status. Invalid values return 400.",
"parameters": [],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"example": {
"status": "closed"
},
"properties": {
"status": {
"type": "string",
"example": "closed"
}
}
}
}
}
}
},
"tags": [
"Inbox"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "The new status.",
"example": "closed"
}
},
"required": [
"status"
]
}
}
}
},
"x-mcp": true,
"x-mcp-name": "inbox.updateStatus"
},
"parameters": [
{
"in": "path",
"name": "thread_id",
"description": "The thread UUID.",
"example": "550e8400-e29b-41d4-a716-446655440000",
"required": true,
"schema": {
"type": "string"
}
}
]
},
"/api/v1/deals/{deal_id}/activities": {
"get": {
"summary": "List activities for a deal",
"operationId": "listActivitiesForADeal",
"description": "Returns all activities on the deal in creation order. Includes system\nevents and auto follow-ups so the frontend can render one unified\ntimeline. Filter with ?open=1 for open-only or ?type=task for a\nsingle type.",
"parameters": [
{
"in": "query",
"name": "open",
"description": "If true, return only open (non-completed) activities.",
"example": true,
"required": false,
"schema": {
"type": "boolean",
"description": "If true, return only open (non-completed) activities.",
"example": true
}
},
{
"in": "query",
"name": "type",
"description": "Filter by activity type.",
"example": "task",
"required": false,
"schema": {
"type": "string",
"description": "Filter by activity type.",
"example": "task"
}
}
],
"responses": {
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"example": {
"error": "invalid_api_key",
"message": "Invalid API key"
},
"properties": {
"error": {
"type": "string",
"example": "invalid_api_key"
},
"message": {
"type": "string",
"example": "Invalid API key"
}
}
}
}
}
}
},
"tags": [
"Deal Activities"
],
"x-mcp": true,
"x-mcp-name": "dealActivities.list"
},
"post": {
"summary": "Create an activity on a deal",
"operationId": "createAnActivityOnADeal",
"description": "Operator-created activities only (task/call/call_in/call_out/meeting/\nemail/lunch/deadline). auto_follow_up and system rows are written by\nthe automation and the CrmLeadObserver respectively and are not\ncreatable via this endpoint.",
"parameters": [],
"responses": [],
"tags": [
"Deal Activities"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "Activity type. One of: task, call, call_in, call_out, meeting, email, lunch, deadline.",
"example": "task"
},
"title": {
"type": "string",
"description": "Short label shown on the timeline.",
"example": "Follow up on quote"
},
"description": {
"type": "string",
"description": "Longer notes.",
"example": "Client asked for pricing on the enterprise tier.",
"nullable": true
},
"due_at": {
"type": "string",
"description": "Due date/time in Y-m-d H:i:s or ISO 8601.",
"example": "2026-08-20 10:00:00",
"nullable": true
},
"due_end_at": {
"type": "string",
"description": "Optional end time (for meetings).",
"example": "2026-08-20 11:00:00",
"nullable": true
},
"owner_id": {
"type": "integer",
"description": "User assigned to the activity (defaults to the creator).",
"example": 42,
"nullable": true
},
"completed_at": {
"type": "string",
"description": "If set on create, records the activity as already-completed (used for logging retroactive calls).",
"example": "2026-08-13 09:30:00",
"nullable": true
},
"contact_id": {
"type": "string",
"description": "Optional contact link (defaults to the deal's contact).",
"example": "con_abc123",
"nullable": true
}
},
"required": [
"type",
"title"
]
}
}
}
},
"x-mcp": true,
"x-mcp-name": "dealActivities.create"
},
"parameters": [
{
"in": "path",
"name": "deal_id",
"description": "The deal ID.",
"example": 1,
"required": true,
"schema": {
"type": "integer"
}
}
]
},
"/api/v1/deals/{deal_id}/activities/{activity_id}": {
"put": {
"summary": "Update an activity",
"operationId": "updateAnActivity",
"description": "Edits an existing activity. Auto follow-ups and system events cannot be\nedited via this endpoint (they're managed by the automation and the\nobserver). Completion is toggled via the dedicated complete /\nuncomplete endpoints, so completed_at is not accepted here.",
"parameters": [],
"responses": [],
"tags": [
"Deal Activities"
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "",
"example": null
},
"title": {
"type": "string",
"description": "Must not be greater than 255 characters.",
"example": "b"
},
"description": {
"type": "string",
"description": "",
"example": "Eius et animi quos velit et.",
"nullable": true
},
"due_at": {
"type": "string",
"description": "Must be a valid date.",
"example": "2026-09-25T12:07:11",
"nullable": true
},
"due_end_at": {
"type": "string",
"description": "Must be a valid date. Must be a date after or equal to due_at.",
"example": "2052-10-18",
"nullable": true
},
"owner_id": {
"type": "integer",
"description": "The id of an existing record in the users table.",
"example": 16,
"nullable": true
},
"contact_id": {
"type": "string",
"description": "The id of an existing record in the contacts table.",
"example": "architecto",
"nullable": true
}
}
}
}
}
},
"x-mcp": true,
"x-mcp-name": "dealActivities.update"
},
"delete": {
"summary": "Delete an activity",
"operationId": "deleteAnActivity",
"description": "Hard-deletes the activity. System events cannot be deleted (they're\npart of the audit trail). Auto follow-ups are removed when the\nautomation completes them, but can be deleted manually if the operator\nwants to cancel the next scheduled AI follow-up.",
"parameters": [],
"responses": [],
"tags": [
"Deal Activities"
],
"x-mcp": true,
"x-mcp-name": "dealActivities.delete"
},
"parameters": [
{
"in": "path",
"name": "deal_id",
"description": "The deal ID.",
"example": 1,
"required": true,
"schema": {
"type": "integer"
}
},
{
"in": "path",
"name": "activity_id",
"description": "The activity ID.",
"example": 55,
"required": true,
"schema": {
"type": "integer"
}
}
]
},
"/api/v1/deals/{deal_id}/activities/{activity_id}/complete": {
"post": {
"summary": "Mark an activity complete",
"operationId": "markAnActivityComplete",
"description": "Sets completed_at=now(). For auto_follow_up rows, completion is what\nthe SendFollowUpJob does after actually sending; hitting this endpoint\nmanually is equivalent to \"cancel next AI follow-up without scheduling\nanother one\" — the automation does NOT chain a new one on manual\ncomplete.",
"parameters": [],
"responses": [],
"tags": [
"Deal Activities"
],
"x-mcp": true,
"x-mcp-name": "dealActivities.complete"
},
"parameters": [
{
"in": "path",
"name": "deal_id",
"description": "The deal ID.",
"example": 1,
"required": true,
"schema": {
"type": "integer"
}
},
{
"in": "path",
"name": "activity_id",
"description": "The activity ID.",
"example": 55,
"required": true,
"schema": {
"type": "integer"
}
}
]
},
"/api/v1/deals/{deal_id}/activities/{activity_id}/uncomplete": {
"post": {
"summary": "Mark an activity open again",
"operationId": "markAnActivityOpenAgain",
"description": "Clears completed_at. Only user-editable types can be reopened.",
"parameters": [],
"responses": [],
"tags": [
"Deal Activities"
],
"x-mcp": true,
"x-mcp-name": "dealActivities.uncomplete"
},
"parameters": [
{
"in": "path",
"name": "deal_id",
"description": "The deal ID.",
"example": 1,
"required": true,
"schema": {
"type": "integer"
}
},
{
"in": "path",
"name": "activity_id",
"description": "The activity ID.",
"example": 55,
"required": true,
"schema": {
"type": "integer"
}
}
]
},
"/api/v1/deal-rows": {
"get": {
"summary": "List Deal Rows",
"operationId": "listDealRows",
"description": "Get the pipeline rows (swimlanes) of your account, in board order. Use the ids as `row_id` when creating or updating deals. Returns an empty list when the board has no rows (simple view).",
"parameters": [],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"example": {
"data": [
{
"id": 7,
"name": "Host families",
"order": 0
},
{
"id": 8,
"name": "Au pairs",
"order": 1
}
]
},
"properties": {
"data": {
"type": "array",
"example": [
{
"id": 7,
"name": "Host families",
"order": 0
},
{
"id": 8,
"name": "Au pairs",
"order": 1
}
],
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"example": 7
},
"name": {
"type": "string",
"example": "Host families"
},
"order": {
"type": "integer",
"example": 0
}
}
}
}
}
}
}
}
}
},
"tags": [
"Deal Rows"
]
},
"post": {
"summary": "Create Deal Row",
"operationId": "createDealRow",
"description": "Add a row (swimlane) at the bottom of the board.",
"parameters": [],
"responses": {
"201": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"example": {
"data": {
"id": 8,
"name": "Au pairs",
"order": 1
}
},
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"example": 8
},
"name": {
"type": "string",
"example": "Au pairs"
},
"order": {
"type": "integer",
"example": 1
}
}
}
}
}
}
}
}
},
"tags": [
"Deal Rows"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Row name.",
"example": "Au pairs"
}
},
"required": [
"name"
]
}
}
}
}
}
},
"/api/v1/team-members": {
"get": {
"summary": "List Team Members",
"operationId": "listTeamMembers",
"description": "Get the users a deal or activity can be assigned to from this account: the key's owner, their agency parent, and collaborators. Use the ids as `assigned_to` on deals and `owner_id` on activities.",
"parameters": [],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"example": {
"data": [
{
"id": 42,
"name": "Nadia Peters",
"email": "nadia@example.com"
},
{
"id": 57,
"name": "Tom Bakker",
"email": "tom@example.com"
}
]
},
"properties": {
"data": {
"type": "array",
"example": [
{
"id": 42,
"name": "Nadia Peters",
"email": "nadia@example.com"
},
{
"id": 57,
"name": "Tom Bakker",
"email": "tom@example.com"
}
],
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"example": 42
},
"name": {
"type": "string",
"example": "Nadia Peters"
},
"email": {
"type": "string",
"example": "nadia@example.com"
}
}
}
}
}
}
}
}
}
},
"tags": [
"Team Members"
]
}
}
},
"externalDocs": {
"description": "Boei developer resources",
"url": "https://boei.help/developers/"
}
}