{ "openapi": "3.0.3", "info": { "title": "API Documentation", "version": "1.0.0", "description": "\n# Introduction\n\nWelcome to the API. This API provides programmatic access to all platform features including AI agents, smart lists, documents, sequences, and media generation.\n\n## Authentication\n\nThe API supports two types of authentication:\n\n1. **Company API Keys** - Scoped to a specific company\n2. **Personal Access Keys** - User-level keys that work across all your companies\n\n---\n\n### Option 1: Company API Key\n\nCompany API keys are tied to a specific company. Use this when you only need to access one company.\n\n**Getting a Company API Key:**\n\n1. Log in to your dashboard\n2. Navigate to **Integrations** page\n3. Find the **API Keys** section and click **Generate New Key**\n4. Copy and securely store your API key (it won't be shown again)\n\n**Usage:**\n\nInclude your API key in the `X-API-Key` header:\n\n```bash\ncurl -X GET \"https://api.example.com/api/v0/agents\" \\\n -H \"X-API-Key: YOUR_COMPANY_API_KEY\" \\\n -H \"Content-Type: application/json\"\n```\n\nOr use the `Authorization` header (OpenAI-compatible):\n\n```bash\ncurl -X GET \"https://api.example.com/api/v0/agents\" \\\n -H \"Authorization: Bearer YOUR_COMPANY_API_KEY\" \\\n -H \"Content-Type: application/json\"\n```\n\n---\n\n### Option 2: Personal Access Key\n\nPersonal access keys are tied to your user account and can access any company you belong to. Use this when you need to access multiple companies or build integrations that work across companies.\n\n**Getting a Personal Access Key:**\n\n1. Log in to your dashboard\n2. Click on your avatar/profile icon and go to **Profile**\n3. Find the **Personal Access Keys** section\n4. Click **Create New Key**\n5. Give it a name and optionally set an expiration date\n6. Copy and securely store your key (it won't be shown again)\n\n**Usage:**\n\nPersonal access keys start with `pak_` and **require** you to specify which company to access using the `X-Company-ID` header:\n\n```bash\ncurl -X GET \"https://api.example.com/api/v0/agents\" \\\n -H \"Authorization: Bearer pak_your_personal_access_key\" \\\n -H \"X-Company-ID: your_company_id\" \\\n -H \"Content-Type: application/json\"\n```\n\nOr using the `X-API-Key` header:\n\n```bash\ncurl -X GET \"https://api.example.com/api/v0/agents\" \\\n -H \"X-API-Key: pak_your_personal_access_key\" \\\n -H \"X-Company-ID: your_company_id\" \\\n -H \"Content-Type: application/json\"\n```\n\nYou can also pass the company ID as a query parameter:\n\n```bash\ncurl -X GET \"https://api.example.com/api/v0/agents?companyId=your_company_id\" \\\n -H \"Authorization: Bearer pak_your_personal_access_key\" \\\n -H \"Content-Type: application/json\"\n```\n\n**Finding Your Company ID:**\n\nYour company ID can be found in the dashboard URL when viewing a company, or via the Settings page.\n\n---\n\n### Which Key Type Should I Use?\n\n| Use Case | Recommended Key Type |\n|----------|---------------------|\n| Single company integration | Company API Key |\n| Multi-company dashboard | Personal Access Key |\n| CI/CD pipelines | Company API Key |\n| Personal automation scripts | Personal Access Key |\n| Third-party app integration | Company API Key |\n\n---\n\n## Response Format\n\nAll responses are returned in JSON format. Successful responses include the requested data:\n\n```json\n{\n \"id\": \"abc123\",\n \"name\": \"My Agent\",\n \"created\": \"2024-01-15T10:30:00Z\"\n}\n```\n\nError responses follow a consistent structure:\n\n```json\n{\n \"error\": \"Description of what went wrong\"\n}\n```\n\n## HTTP Status Codes\n\n| Code | Description |\n|------|-------------|\n| 200 | Success |\n| 201 | Created |\n| 400 | Bad Request - Invalid parameters |\n| 401 | Unauthorized - Invalid or missing API key |\n| 403 | Forbidden - Insufficient permissions |\n| 404 | Not Found - Resource doesn't exist |\n| 429 | Too Many Requests - Rate limit exceeded |\n| 500 | Internal Server Error |\n\n## Pagination\n\nList endpoints support pagination using `page` and `pageSize` parameters:\n\n```\nGET /api/v0/agents?page=1&pageSize=20\n```\n\nPaginated responses include:\n- `items`: Array of results\n- `total`: Total number of items\n- `pages`: Total number of pages\n- `hasNext`: Whether more pages exist\n\n## OpenAI Compatibility\n\nThe Chat API (`/api/v0/chat/completions`) is fully compatible with the OpenAI API specification.\n\n---\n\n## Anthropic Compatibility & Claude Code\n\nThe platform also exposes an **Anthropic Messages API-compatible** endpoint, so any Anthropic SDK \u2014 including **Claude Code** \u2014 can use the platform as its LLM provider. Requests are billed against your platform credits like any other API usage.\n\n### Endpoints\n\n| Endpoint | Description |\n|----------|-------------|\n| `POST /api/v0/claude/v1/messages` | Create a message (streaming and non-streaming, tool use supported) |\n| `POST /api/v0/claude/v1/messages/count_tokens` | Estimate token count for a request |\n| `GET /api/v0/claude/v1/models` | List available models |\n\nAuthentication works exactly like the rest of the API: send your API key as `Authorization: Bearer ` or `x-api-key: `. Personal access keys (`pak_...`) also work but require the `X-Company-ID` header, which Claude Code cannot send by default \u2014 use a **Company API Key** for Claude Code.\n\n### Setting up Claude Code\n\n1. **Install Claude Code** (skip if already installed):\n\n```bash\n# macOS / Linux / WSL \u2014 native installer\ncurl -fsSL https://claude.ai/install.sh | bash\n\n# Or via npm (requires Node.js 18+)\nnpm install -g @anthropic-ai/claude-code\n```\n\nOn Windows (PowerShell):\n\n```powershell\nirm https://claude.ai/install.ps1 | iex\n```\n\nVerify the install with `claude --version`. See the official docs at https://code.claude.com/docs for more install options.\n\n2. **Get a Company API Key**: Dashboard \u2192 **Integrations** \u2192 **API Keys** \u2192 **Generate New Key**.\n\n3. **Configure Claude Code.** Either export environment variables in your shell:\n\n```bash\nexport ANTHROPIC_BASE_URL=\"https://api.example.com/api/v0/claude\"\nexport ANTHROPIC_AUTH_TOKEN=\"YOUR_COMPANY_API_KEY\"\nclaude\n```\n\nOr persist the settings in `~/.claude/settings.json` (applies to all projects) or `.claude/settings.local.json` in a project. Set the model variables to any platform model names \u2014 for example:\n\n```json\n{\n \"env\": {\n \"ANTHROPIC_BASE_URL\": \"https://api.example.com/api/v0/claude\",\n \"ANTHROPIC_AUTH_TOKEN\": \"YOUR_COMPANY_API_KEY\",\n \"ANTHROPIC_MODEL\": \"qwen3.8-max\",\n \"ANTHROPIC_DEFAULT_OPUS_MODEL\": \"kimi-k3\",\n \"ANTHROPIC_DEFAULT_SONNET_MODEL\": \"qwen3.8-max\",\n \"ANTHROPIC_DEFAULT_HAIKU_MODEL\": \"deepseek-v4.1-flash\"\n }\n}\n```\n\n4. **Verify** with `/status` inside Claude Code \u2014 it should show your custom base URL \u2014 or test the endpoint directly:\n\n```bash\ncurl -X POST \"https://api.example.com/api/v0/claude/v1/messages\" \\\n -H \"Authorization: Bearer YOUR_COMPANY_API_KEY\" \\\n -H \"anthropic-version: 2023-06-01\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"model\": \"qwen3.8-max\", \"max_tokens\": 64, \"messages\": [{\"role\": \"user\", \"content\": \"Hello\"}]}'\n```\n\n### Model names\n\nThe `model` field accepts any model name from `GET /api/v0/models` \u2014 any provider, not just Anthropic \u2014 so you can run Claude Code on any model the platform offers. When Claude Code sends its default Anthropic model ids (e.g. `claude-sonnet-4-5-20250929`), they are routed by tier to platform models: opus-class requests run on the platform's highest-capability model, sonnet-class on the balanced default, and haiku-class (background tasks) on the fastest low-cost model. Set `ANTHROPIC_MODEL` and the `ANTHROPIC_DEFAULT_*_MODEL` variables to exact platform model names for full control over routing.\n\nOptionally set `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1` so Claude Code lists the platform's models in its `/model` picker.\n\n### Notes and limitations\n\n- **Streaming** is fully supported (Anthropic SSE event format with keep-alive pings).\n- **Tool use** is supported: Claude Code's client-side tools (file edits, bash, etc.) are forwarded to the model and executed locally by Claude Code \u2014 never on the platform's servers.\n- Server-side Anthropic tools (web search, code execution), extended thinking blocks, and prompt caching directives are accepted but ignored.\n- Usage is billed per request based on real token counts and appears in your usage dashboard under the chat feature.\n\n### Using the Anthropic SDK directly\n\n```python\nimport anthropic\n\nclient = anthropic.Anthropic(\n base_url=\"https://api.example.com/api/v0/claude\",\n auth_token=\"YOUR_COMPANY_API_KEY\",\n)\n\nresponse = client.messages.create(\n model=\"kimi-k3\",\n max_tokens=1024,\n messages=[{\"role\": \"user\", \"content\": \"Hello\"}],\n)\nprint(response.content[0].text)\n```\n\n---\n\n## MCP (Model Context Protocol) Integration\n\nThe platform provides an MCP server that allows AI assistants like Claude Desktop, Cursor, Windsurf, and other MCP-compatible tools to interact with the full platform API.\n\n### What is MCP?\n\nModel Context Protocol (MCP) is an open standard that allows AI assistants to securely connect to external tools and data sources. With MCP, your AI assistant can:\n\n- Browse and manage your AI agents\n- Create and monitor outreach sequences\n- Search your knowledge base documents\n- Generate AI content, images, audio, and video\n- Execute browser automation tasks\n- And access every other platform feature\n\n### MCP Server URL\n\n```\nhttps://api.example.com/api/v0/mcp\n```\n\nThis endpoint implements the **MCP Streamable HTTP Transport** (JSON-RPC 2.0) and is compatible with `mcp-remote` and other MCP clients.\n\n### Available Tools\n\nThe MCP server provides 3 tools that give access to the entire platform API:\n\n| Tool | Description |\n|------|-------------|\n| `platform_list_capabilities` | Browse available API endpoints by category (Agents, Sequences, Lists, Documents, etc.) |\n| `platform_get_action_details` | Get the full specification for an endpoint including required parameters |\n| `platform_execute_action` | Execute any API endpoint with automatic authentication |\n\n### Connecting Claude Desktop\n\n1. Open your Claude Desktop configuration file:\n - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n - **Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n2. Add the MCP server configuration:\n\n```json\n{\n \"mcpServers\": {\n \"platform\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"mcp-remote\", \"https://api.example.com/api/v0/mcp\"],\n \"env\": {\n \"API_KEY\": \"your_api_key_here\"\n }\n }\n }\n}\n```\n\n3. Restart Claude Desktop\n\n4. You can now ask Claude to interact with your platform data, for example:\n - \"List my AI agents\"\n - \"Show me my active sequences\"\n - \"Create a new email sequence for cold outreach\"\n - \"Search my documents for pricing information\"\n\n### Connecting Cursor / Windsurf\n\n1. Open Settings and navigate to the MCP section\n\n2. Add a new MCP server with:\n - **URL**: `https://api.example.com/api/v0/mcp`\n - **Authentication**: Bearer token with your API key\n\n3. The platform tools will now be available in your AI assistant\n\n### Connecting via mcp-remote (Generic)\n\nFor any MCP-compatible client, you can use the `mcp-remote` package:\n\n```bash\nnpx mcp-remote https://api.example.com/api/v0/mcp --header \"Authorization: Bearer YOUR_API_KEY\"\n```\n\n### Authentication for MCP\n\nMCP requests use the same authentication as the REST API:\n\n**Using Company API Key:**\n```\nAuthorization: Bearer YOUR_COMPANY_API_KEY\n```\n\n**Using Personal Access Key:**\n```\nAuthorization: Bearer pak_your_personal_access_key\nX-Company-ID: your_company_id\n```\n\n### Example MCP Interactions\n\n**List available capabilities:**\n```json\n{\n \"name\": \"platform_list_capabilities\",\n \"arguments\": {\n \"category\": \"Sequences\"\n }\n}\n```\n\n**Get action details:**\n```json\n{\n \"name\": \"platform_get_action_details\",\n \"arguments\": {\n \"operationId\": \"sequences_saveSequence\"\n }\n}\n```\n\n**Execute an action:**\n```json\n{\n \"name\": \"platform_execute_action\",\n \"arguments\": {\n \"operationId\": \"agents_listAgents\"\n }\n}\n```\n\n### MCP Endpoints\n\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `/api/v0/mcp/info` | GET | Get MCP server information and capabilities |\n| `/api/v0/mcp/tools/list` | GET | List all available MCP tools |\n| `/api/v0/mcp/tools/call` | POST | Execute an MCP tool call |\n" }, "servers": [ { "url": "https://api.parallellabs.app" } ], "tags": [ { "name": "Agents", "description": "Create, manage, and interact with AI agents that handle customer interactions across multiple channels including website chat, email, SMS, and voice." }, { "name": "Audio", "description": "Generate text-to-speech audio using ElevenLabs." }, { "name": "Brand Kit", "description": "One brand kit per company drives both content-engine visuals and landing-page/website rendering: logos and reusable images, an AI image style prompt, canvas config and PNG templates, plus favicon/logo, injected CSS/head scripts and brand guidelines. Build a full kit automatically from a website or an uploaded image." }, { "name": "Browser", "description": "Execute browser automation tasks with natural language." }, { "name": "Canvas", "description": "Render a standalone HTML canvas into shareable art \u2014 a still PNG or a looping MP4 \u2014 and return a permanent public URL." }, { "name": "Chat", "description": "OpenAI-compatible chat completions API." }, { "name": "Companies", "description": "Manage companies and workspaces. Each company has its own agents, lists, sequences, and other resources." }, { "name": "Company Users", "description": "Manage team members and their access to companies." }, { "name": "Content", "description": "AI content engine. Use saveContentCampaign to create or update standard and SEO Autopilot campaigns. Non-null targetKeywords enables Autopilot; configure blog delivery in channels.blog_post.subSettings, schedule with publishDaysOfWeek, and pause with frequency=manual. Read campaign records through the existing campaign list and review articles through the Content Engine. No separate Autopilot configuration endpoint is needed." }, { "name": "Content Research", "description": "SEO/AEO opportunity engine: score a domain against competitors and AI answers, then generate/track scored content opportunities." }, { "name": "Departments", "description": "Organize employees into departments for better team structure." }, { "name": "Documentation", "description": "Browse and search platform documentation, and request docs that are missing." }, { "name": "Documents", "description": "Manage your knowledge base documents for AI training and reference." }, { "name": "Domains", "description": "Two distinct services: branded-domain connections use an owned domain or subdomain for SSL termination and routing to tracking links, landing pages, and published websites ($5/month per additional connection); domain registration is a separate one-time purchase. Read pricing and availability before confirming a registration or DNS change." }, { "name": "Employees", "description": "Customizable AI personas you can list and chat with." }, { "name": "Images", "description": "Generate AI images using DALL-E, Leonardo, and other providers." }, { "name": "Inbox", "description": "Manage incoming messages and communications across channels." }, { "name": "Integrations", "description": "Discovery endpoints that resolve IDs from connected third-party accounts (HeyReach, Salesforge, Twilio, Meta Ads, CRMs) for other actions to use." }, { "name": "Keys", "description": "Manage API keys for programmatic access to the platform." }, { "name": "Landing Pages", "description": "Create and manage landing pages for lead capture and campaigns." }, { "name": "Leads", "description": "Prospect acquisition: search the professional people database by role and company filters, import or export the results, enrich known people (emails and phones separately), and review \"Find Leads at Company\" matches. Read the lead-generation skill (skills_getSkill) for the end-to-end workflow. Search is free and requires available data-credit window capacity or at least 1 lead data credit. Email enrichment and imports cost one data credit per record; phone enrichment costs two per returned number.", "x-relatedSkills": [ "lead-generation" ] }, { "name": "Linkedin", "description": "Connected LinkedIn accounts, shared daily action counts, and asynchronous profile visits, connection requests, messages, likes and comments. Poll action tasks without resubmitting." }, { "name": "Lists", "description": "Manage smart lists for organizing contacts and data.", "x-relatedSkills": [ "cold-email-outreach", "campaign-email", "lead-generation" ] }, { "name": "Marketing Campaigns", "description": "Create, schedule, and send one-shot marketing email campaigns to a smart list, and track open/click performance. To send from your own domain through the platform, add a sending domain (integrations_addEmailSendingDomain, or integrations_addHostedEmailSendingDomain for a domain purchased here), add its DNS records, call integrations_verifyEmailSendingDomain until verified, then integrations_addEmailSendingSender and use the returned sender id as the campaign senderProfileId. integrations_getEmailSendingTenant shows whether sending is paused.", "x-relatedSkills": [ "campaign-email" ] }, { "name": "Mcp", "description": "Model Context Protocol (MCP) server for AI assistants like Claude Desktop, Cursor, and Windsurf. Provides tools for full platform API access." }, { "name": "Memories", "description": "Store and retrieve conversation context and user preferences for AI personalization." }, { "name": "Models", "description": "List available AI models." }, { "name": "Monitors", "description": "Track keywords across social platforms (Reddit, Hacker News, LinkedIn, X, Quora) to discover relevant conversations and get AI reply suggestions." }, { "name": "Organizations", "description": "List the organizations the authenticated user belongs to \u2014 the top-level grouping above companies." }, { "name": "People", "description": "Saved contacts and relationships in Company Brain: search and browse one resolved profile per person (merged across sequences, lists, conversations and campaigns) with their activity timeline." }, { "name": "Projects", "description": "Organize work into projects for better task management." }, { "name": "SEO", "description": "SEO toolkit: keyword and domain lookups, site audits, scheduled per-domain monitoring (rank, backlinks, competitors, AI visibility), Search Console, and a raw DataForSEO passthrough." }, { "name": "Scheduled Tasks", "description": "Schedule AI employee runs \u2014 one-time, recurring, or heartbeat \u2014 and manage their history, status, and grading." }, { "name": "Sequences", "description": "Manage automated outreach sequences for email, SMS, and multi-channel campaigns.", "x-relatedSkills": [ "cold-email-outreach" ] }, { "name": "Skills" }, { "name": "Support", "description": "Create and manage support tickets, post follow-up messages on tickets, and track their status." }, { "name": "Tags", "description": "Organize and categorize resources with custom tags." }, { "name": "Usage", "description": "Track API usage, credits, and billing information." }, { "name": "Video", "description": "Generate AI videos using fal.ai models." }, { "name": "Voices", "description": "Manage voice clones and text-to-speech voice options." }, { "name": "Web", "description": "Real-time web tools: search the web and news, read/screenshot any page, and pull jobs, local-business and trending-topic data." }, { "name": "Websites", "description": "Read, audit and edit the company's multi-page Jinja/HTML websites, staging edits on a review branch for the owner to approve.", "x-relatedSkills": [ "website-editing" ] } ], "paths": { "/api/v0/integrations/heyreach/campaigns": { "get": { "tags": [ "Integrations" ], "operationId": "integrations_listHeyreachCampaigns", "parameters": [ { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID to scope the lookup to." }, "description": "Company ID to scope the lookup to." }, { "name": "integrationId", "in": "query", "required": true, "schema": { "type": "string", "description": "The integration whose sub-resources to list." }, "description": "The integration whose sub-resources to list." } ], "responses": { "400": { "description": "integrationId/companyId required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Integration not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "HeyReach campaigns", "content": { "application/json": { "schema": { "type": "object", "properties": { "campaigns": { "type": "array", "items": { "type": "object" }, "description": "HeyReach campaigns (each has at least an id and name) \u2014 use the id as a step campaignId." } }, "description": "HeyReach campaigns for an integration" } } } } }, "summary": "List HeyReach campaigns for an integration, to find a step campaignId.", "description": "Pass companyId and the heyreachIntegrationId as query params; use a returned\ncampaign id as the heyreach_campaign step's campaignId." } }, "/api/v0/integrations/salesforge/workspaces": { "post": { "tags": [ "Integrations" ], "operationId": "integrations_listSalesforgeWorkspaces", "parameters": [], "responses": { "400": { "description": "companyId/integrationId required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Integration not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Salesforge workspaces", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object" }, "description": "Workspaces or sequences, each with at least an id and name." } }, "description": "Salesforge workspaces or sequences list (vendor shape)" } } } } }, "summary": "List Salesforge workspaces for an integration, to find a step workspaceId.", "description": "POST companyId and the salesforgeIntegrationId; use a returned workspace id\nas the salesforge_campaign step's workspaceId.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID." }, "integrationId": { "type": "string", "description": "Salesforge integration ID." } }, "required": [ "companyId", "integrationId" ], "description": "Request body for the Salesforge workspaces lookup" } } }, "description": "Integration to list workspaces for" } } }, "/api/v0/integrations/salesforge/sequences": { "post": { "tags": [ "Integrations" ], "operationId": "integrations_listSalesforgeSequences", "parameters": [], "responses": { "400": { "description": "companyId/integrationId/workspaceId required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Integration not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Salesforge sequences", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object" }, "description": "Workspaces or sequences, each with at least an id and name." } }, "description": "Salesforge workspaces or sequences list (vendor shape)" } } } } }, "summary": "List Salesforge sequences in a workspace, to find a step sequenceId.", "description": "POST companyId, the salesforgeIntegrationId, and a workspaceId; use a\nreturned sequence id as the salesforge_campaign step's sequenceId.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID." }, "integrationId": { "type": "string", "description": "Salesforge integration ID." }, "workspaceId": { "type": "string", "description": "Salesforge workspace ID to list sequences in." } }, "required": [ "companyId", "integrationId", "workspaceId" ], "description": "Request body for the Salesforge sequences lookup" } } }, "description": "Workspace to list sequences for" } } }, "/api/v0/email-sending/tenant": { "get": { "tags": [ "Marketing Campaigns" ], "operationId": "integrations_getEmailSendingTenant", "parameters": [ { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string", "description": "Company ID. Not needed with a Company API key, which is already scoped to one company." }, "description": "Company ID. Not needed with a Company API key, which is already scoped to one company." } ], "responses": { "400": { "description": "companyId is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No company access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "The company's sending account, or null before any domain is added", "content": { "application/json": { "schema": { "type": "object", "properties": { "tenant": { "type": "object", "properties": { "id": { "type": "string", "description": "Sending account ID." }, "companyId": { "type": "string", "description": "Company that owns the sending account." }, "sendingStatus": { "type": "string", "description": "ENABLED or REINSTATED means mail is sending; DISABLED means sending is paused, usually for high bounce or complaint rates." }, "sendingStatusCause": { "type": "string", "description": "Why sending was paused, when it is paused." }, "lastStatusCheckDate": { "type": "string", "format": "date-time", "description": "When the sending status was last refreshed." } }, "description": "The company's email sending account" } }, "description": "Email sending account (null until the first domain is added)" } } } } }, "summary": "Get the company's email sending account and whether sending is paused.", "description": "The account is created when the first sending domain is added. A DISABLED\nsendingStatus means marketing campaign sending is paused for this company." } }, "/api/v0/email-sending/tenant/refresh": { "post": { "tags": [ "Marketing Campaigns" ], "operationId": "integrations_refreshEmailSendingTenant", "parameters": [], "responses": { "400": { "description": "companyId is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No company access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Email service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "The sending account with its current status", "content": { "application/json": { "schema": { "type": "object", "properties": { "tenant": { "type": "object", "properties": { "id": { "type": "string", "description": "Sending account ID." }, "companyId": { "type": "string", "description": "Company that owns the sending account." }, "sendingStatus": { "type": "string", "description": "ENABLED or REINSTATED means mail is sending; DISABLED means sending is paused, usually for high bounce or complaint rates." }, "sendingStatusCause": { "type": "string", "description": "Why sending was paused, when it is paused." }, "lastStatusCheckDate": { "type": "string", "format": "date-time", "description": "When the sending status was last refreshed." } }, "description": "The company's email sending account" } }, "description": "Email sending account (null until the first domain is added)" } } } } }, "summary": "Refresh the company's sending status from the email service.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID. Not needed with a Company API key, which is already scoped to one company." } }, "description": "Company to act on" } } }, "description": "Company to refresh" } } }, "/api/v0/email-sending/domains": { "get": { "tags": [ "Marketing Campaigns" ], "operationId": "integrations_listEmailSendingDomains", "parameters": [ { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string", "description": "Company ID. Not needed with a Company API key, which is already scoped to one company." }, "description": "Company ID. Not needed with a Company API key, which is already scoped to one company." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Page number (1-indexed).", "default": 1 }, "description": "Page number (1-indexed)." }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "description": "Items per page (max 100).", "default": 20 }, "description": "Items per page (max 100)." } ], "responses": { "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No company access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Paginated sending domains", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Sending domain ID \u2014 the domainId for verify, senders, and delete." }, "domain": { "type": "string", "description": "The domain mail is sent from." }, "mailFromDomain": { "type": "string", "description": "Bounce (MAIL FROM) subdomain." }, "status": { "type": "string", "description": "pending, verified, or failed. Senders can be added only once verified." }, "dkimStatus": { "type": "string", "description": "DKIM verification status." }, "mailFromStatus": { "type": "string", "description": "MAIL FROM verification status." }, "dnsRecords": { "type": "array", "items": { "type": "object" }, "description": "DNS records to add: [{type, name, value, priority, purpose, required, autoAdded}]. autoAdded records were written for you." }, "purchasedDomainId": { "type": "string", "description": "Purchased domain this sending domain uses, when DNS is managed automatically." }, "integrationId": { "type": "string", "description": "Sending integration created once the domain is verified." }, "lastVerificationDate": { "type": "string", "format": "date-time", "description": "When verification was last checked." }, "verifiedDate": { "type": "string", "format": "date-time", "description": "When the domain was verified." }, "created_date": { "type": "string", "format": "date-time", "description": "When the domain was added." } }, "description": "Sending domain" }, "description": "Sending domains, newest first." }, "total": { "type": "integer", "description": "Total sending domains." }, "page": { "type": "integer", "description": "Current page." }, "pages": { "type": "integer", "description": "Total pages." }, "has_next": { "type": "boolean", "description": "Whether another page exists." } }, "description": "Paginated list of sending domains" } } } } }, "summary": "List the company's marketing email sending domains with their DNS records and verification status." }, "post": { "tags": [ "Marketing Campaigns" ], "operationId": "integrations_addEmailSendingDomain", "parameters": [], "responses": { "400": { "description": "Invalid domain", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No company access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Domain already in use", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Email service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "201": { "description": "The pending domain with the DNS records to add", "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "object", "properties": { "id": { "type": "string", "description": "Sending domain ID \u2014 the domainId for verify, senders, and delete." }, "domain": { "type": "string", "description": "The domain mail is sent from." }, "mailFromDomain": { "type": "string", "description": "Bounce (MAIL FROM) subdomain." }, "status": { "type": "string", "description": "pending, verified, or failed. Senders can be added only once verified." }, "dkimStatus": { "type": "string", "description": "DKIM verification status." }, "mailFromStatus": { "type": "string", "description": "MAIL FROM verification status." }, "dnsRecords": { "type": "array", "items": { "type": "object" }, "description": "DNS records to add: [{type, name, value, priority, purpose, required, autoAdded}]. autoAdded records were written for you." }, "purchasedDomainId": { "type": "string", "description": "Purchased domain this sending domain uses, when DNS is managed automatically." }, "integrationId": { "type": "string", "description": "Sending integration created once the domain is verified." }, "lastVerificationDate": { "type": "string", "format": "date-time", "description": "When verification was last checked." }, "verifiedDate": { "type": "string", "format": "date-time", "description": "When the domain was verified." }, "created_date": { "type": "string", "format": "date-time", "description": "When the domain was added." } }, "description": "Sending domain" } }, "description": "Sending domain" } } } } }, "summary": "Add a domain you manage for sending marketing campaigns.", "description": "Returns dnsRecords to add at your DNS provider. After adding them, call\nintegrations_verifyEmailSendingDomain until status is verified, then add a sender.\nFor a domain purchased on the platform, use integrations_addHostedEmailSendingDomain instead.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID. Not needed with a Company API key, which is already scoped to one company." }, "domain": { "type": "string", "description": "Domain or subdomain to send from, such as news.example.com. Add the returned dnsRecords at your DNS provider, then call verify." } }, "required": [ "domain" ], "description": "Domain to send marketing email from" } } }, "description": "Domain to send from" } } }, "/api/v0/email-sending/hosted-domains": { "post": { "tags": [ "Marketing Campaigns" ], "operationId": "integrations_addHostedEmailSendingDomain", "parameters": [], "responses": { "400": { "description": "A valid purchasedDomainId is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No company access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Domain already in use", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Email service or DNS update unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "201": { "description": "The pending domain; its DNS records are added automatically", "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "object", "properties": { "id": { "type": "string", "description": "Sending domain ID \u2014 the domainId for verify, senders, and delete." }, "domain": { "type": "string", "description": "The domain mail is sent from." }, "mailFromDomain": { "type": "string", "description": "Bounce (MAIL FROM) subdomain." }, "status": { "type": "string", "description": "pending, verified, or failed. Senders can be added only once verified." }, "dkimStatus": { "type": "string", "description": "DKIM verification status." }, "mailFromStatus": { "type": "string", "description": "MAIL FROM verification status." }, "dnsRecords": { "type": "array", "items": { "type": "object" }, "description": "DNS records to add: [{type, name, value, priority, purpose, required, autoAdded}]. autoAdded records were written for you." }, "purchasedDomainId": { "type": "string", "description": "Purchased domain this sending domain uses, when DNS is managed automatically." }, "integrationId": { "type": "string", "description": "Sending integration created once the domain is verified." }, "lastVerificationDate": { "type": "string", "format": "date-time", "description": "When verification was last checked." }, "verifiedDate": { "type": "string", "format": "date-time", "description": "When the domain was verified." }, "created_date": { "type": "string", "format": "date-time", "description": "When the domain was added." } }, "description": "Sending domain" } }, "description": "Sending domain" } } } } }, "summary": "Send from a domain purchased here; DNS records are written automatically.", "description": "Call integrations_verifyEmailSendingDomain until status is verified, then add a sender.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID. Not needed with a Company API key, which is already scoped to one company." }, "purchasedDomainId": { "type": "string", "description": "ID of a domain purchased on the platform (from GET /api/v0/domains). Its DNS records are written automatically." } }, "required": [ "purchasedDomainId" ], "description": "Purchased domain to send marketing email from" } } }, "description": "Purchased domain to send from" } } }, "/api/v0/email-sending/domains/{domainId}/verify": { "post": { "tags": [ "Marketing Campaigns" ], "operationId": "integrations_verifyEmailSendingDomain", "parameters": [ { "name": "domainId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "companyId is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No company access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Domain not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Email service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "The domain with its refreshed verification status", "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "object", "properties": { "id": { "type": "string", "description": "Sending domain ID \u2014 the domainId for verify, senders, and delete." }, "domain": { "type": "string", "description": "The domain mail is sent from." }, "mailFromDomain": { "type": "string", "description": "Bounce (MAIL FROM) subdomain." }, "status": { "type": "string", "description": "pending, verified, or failed. Senders can be added only once verified." }, "dkimStatus": { "type": "string", "description": "DKIM verification status." }, "mailFromStatus": { "type": "string", "description": "MAIL FROM verification status." }, "dnsRecords": { "type": "array", "items": { "type": "object" }, "description": "DNS records to add: [{type, name, value, priority, purpose, required, autoAdded}]. autoAdded records were written for you." }, "purchasedDomainId": { "type": "string", "description": "Purchased domain this sending domain uses, when DNS is managed automatically." }, "integrationId": { "type": "string", "description": "Sending integration created once the domain is verified." }, "lastVerificationDate": { "type": "string", "format": "date-time", "description": "When verification was last checked." }, "verifiedDate": { "type": "string", "format": "date-time", "description": "When the domain was verified." }, "created_date": { "type": "string", "format": "date-time", "description": "When the domain was added." } }, "description": "Sending domain" } }, "description": "Sending domain" } } } } }, "summary": "Check a sending domain's DNS records and mark it verified once they are in place.", "description": "DNS changes can take minutes to hours to propagate; call again later while status is pending.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID. Not needed with a Company API key, which is already scoped to one company." } }, "description": "Company to act on" } } }, "description": "Company that owns the domain" } } }, "/api/v0/email-sending/domains/{domainId}/senders": { "post": { "tags": [ "Marketing Campaigns" ], "operationId": "integrations_addEmailSendingSender", "parameters": [ { "name": "domainId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Domain not verified or invalid sender", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No company access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Domain not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "201": { "description": "The new sender profile", "content": { "application/json": { "schema": { "type": "object", "properties": { "sender": { "type": "object", "properties": { "id": { "type": "string", "description": "Sender profile ID \u2014 use it as a marketing campaign senderProfileId." }, "name": { "type": "string", "description": "Sender name recipients see." }, "email": { "type": "string", "description": "Sender email address." }, "integrationId": { "type": "string", "description": "Sending integration the sender uses." }, "dailySendingLimit": { "type": "integer", "description": "Maximum emails this sender sends per day." } }, "description": "Sender profile" } }, "description": "Created sender profile" } } } } }, "summary": "Create a sender address on a verified sending domain.", "description": "The returned sender id is a senderProfileId for marketing_campaigns_createCampaign or marketing_campaigns_updateCampaign.\nSenders created here send marketing campaigns only, not sequences.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID. Not needed with a Company API key, which is already scoped to one company." }, "name": { "type": "string", "description": "Sender name recipients will see, such as Acme News." }, "localPart": { "type": "string", "description": "Part of the address before the @, such as news for news@example.com." } }, "required": [ "name", "localPart" ], "description": "Sender address to create on a verified sending domain" } } }, "description": "Sender name and address" } } }, "/api/v0/email-sending/domains/{domainId}": { "delete": { "tags": [ "Marketing Campaigns" ], "operationId": "integrations_deleteEmailSendingDomain", "parameters": [ { "name": "domainId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string", "description": "Company ID. Not needed with a Company API key, which is already scoped to one company." }, "description": "Company ID. Not needed with a Company API key, which is already scoped to one company." } ], "responses": { "400": { "description": "companyId is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No company access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Domain not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Email service or DNS update unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Deletion confirmation", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "description": "Deleted" } }, "description": "Deletion confirmation" } } } } }, "summary": "Remove a sending domain. Its senders can no longer send marketing campaigns." } }, "/api/v0/integrations/by-type/{integration_type}": { "get": { "tags": [ "Integrations" ], "operationId": "integrations_getIntegrationsByType", "parameters": [ { "name": "integration_type", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID to scope the lookup to." }, "description": "Company ID to scope the lookup to." }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "description": "Optional sub-type filter. For LinkedIn accounts, set integration_type=browser_session and type=linkedin_login." }, "description": "Optional sub-type filter. For LinkedIn accounts, set integration_type=browser_session and type=linkedin_login." }, { "name": "provider", "in": "query", "required": false, "schema": { "type": "string", "description": "Optional provider filter (e.g. composio); returns all integrations for that provider regardless of type." }, "description": "Optional provider filter (e.g. composio); returns all integrations for that provider regardless of type." } ], "responses": { "400": { "description": "companyId is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Matching integrations", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Integration ID \u2014 the value to put in sender-profile or sequence integration fields." }, "name": { "type": "string", "description": "Display name of the integration." }, "instanceName": { "type": "string", "description": "Account/instance name." }, "status": { "type": "string", "description": "Health status (e.g. healthy)." }, "type": { "type": "string", "description": "Underlying integration type." }, "integration_type": { "type": "string", "description": "Functional category of the integration." }, "provider": { "type": "string", "description": "Provider (native, composio, etc.)." } }, "description": "Integration summary item" }, "description": "Matching integrations." } }, "description": "List of integrations matching the requested type" } } } } }, "summary": "List integrations of a given type, to discover valid integration IDs.", "description": "Use this to find IDs for sequence and sender-profile channel fields. Common\nintegration_type path values: browser_session (with query type=linkedin_login)\nfor LinkedIn accounts, sms for Twilio/phone, scheduling for calendar booking,\nemail for mailboxes. Supports comma-separated types (e.g. 'tools,toolset') and\nan optional provider query param (e.g. provider=composio) to fetch all\nintegrations for that provider regardless of type." } }, "/api/v0/integrations/twilio/{integration_id}/phone-numbers": { "get": { "tags": [ "Integrations" ], "operationId": "integrations_getTwilioPhoneNumbers", "parameters": [ { "name": "integration_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "companyId is required / invalid integration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Integration not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Available phone numbers", "content": { "application/json": { "schema": { "type": "object", "properties": { "phoneNumbers": { "type": "array", "items": { "type": "object", "properties": { "sid": { "type": "string", "description": "Twilio phone number SID." }, "phoneNumber": { "type": "string", "description": "The number in E.164 format \u2014 the value to use for a sequence/sender-profile phone." }, "friendlyName": { "type": "string", "description": "Display name for the number." }, "smsUrl": { "type": "string", "description": "Current SMS webhook URL." } }, "description": "Twilio phone number" }, "description": "Available sending phone numbers on the Twilio account." } }, "description": "Available phone numbers for a Twilio integration" } } } } }, "summary": "List the sending phone numbers available on a Twilio integration.", "description": "Use this to pick a number for a sender profile's phone or a sequence's\nfallback phoneNumbers. Pass companyId as a query parameter." } }, "/api/v0/integrations/meta-ads/{integration_id}/audiences": { "get": { "tags": [ "Integrations" ], "operationId": "integrations_getMetaAdsAudiences", "parameters": [ { "name": "integration_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID to scope the lookup to." }, "description": "Company ID to scope the lookup to." } ], "responses": { "400": { "description": "companyId required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Integration not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Meta Ads custom audiences", "content": { "application/json": { "schema": { "type": "object", "properties": { "audiences": { "type": "array", "items": { "type": "object" }, "description": "Custom audiences (id, name, description, approximate_count, ...) \u2014 use the id as a step audienceId." } }, "description": "Meta Ads custom audiences for an integration" } } } } }, "summary": "List Meta Ads custom audiences for an integration, to find a step audienceId.", "description": "Pass companyId as a query param and the integration in the path; use a\nreturned audience id as the meta_ads_audience step's audienceId.\n\nAPI Reference: https://developers.facebook.com/docs/marketing-api/audiences/guides/custom-audiences" } }, "/api/v0/documents/upload": { "post": { "tags": [ "Documents" ], "operationId": "documents_uploadDocuments", "parameters": [], "responses": { "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Document uploaded successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "description": "Success message" } }, "description": "Success response" } } } } }, "summary": "Upload a document file to the knowledge base.", "description": "Supports PDF, DOCX, TXT, and other text-based file formats.\nPremium PDF processing is available for better text extraction.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "premiumPdf": { "type": "boolean", "description": "Use premium PDF processing", "default": false }, "path": { "type": "string", "description": "Path to store document (default: /)", "default": "/" }, "tags": { "type": "string", "description": "Comma-separated tags" } }, "required": [ "companyId" ], "description": "Multipart form data for document upload" } } }, "description": "Document upload (multipart form)" } } }, "/api/v0/documents/{documentId}": { "delete": { "tags": [ "Documents" ], "operationId": "documents_deleteDocument", "parameters": [ { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Document deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "description": "Success message" } }, "description": "Success response" } } } } }, "summary": "Delete a document from the knowledge base.", "description": "Permanently removes the document and all associated embeddings." } }, "/api/v0/documents/{companyId}/{documentId}": { "get": { "tags": [ "Documents" ], "operationId": "documents_getDocumentContents", "parameters": [ { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Document text content", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "description": "Document text content" } }, "description": "Document content response" } } } } }, "summary": "Get the text content of a document.", "description": "Returns the full text content extracted from the document." } }, "/api/v0/documents/{companyId}/document/{documentId}": { "get": { "tags": [ "Documents" ], "operationId": "documents_getDocument", "parameters": [ { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Document metadata", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Document ID" }, "name": { "type": "string", "description": "Document name" }, "type": { "type": "string", "description": "Document type: file, folder" }, "path": { "type": "string", "description": "Document path" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Document tags" }, "folderTags": { "type": "array", "items": { "type": "string" }, "description": "Auto-apply tags from folder" }, "childTags": { "type": "array", "items": { "type": "string" }, "description": "Tags from child documents" }, "sharing": { "type": "string", "description": "Sharing status: Private, Shared, External" }, "shareVisibility": { "type": "string", "description": "Share visibility level" }, "isExternal": { "type": "boolean", "description": "Whether document is from external share" }, "created": { "type": "string", "description": "Creation timestamp" }, "updated": { "type": "string", "description": "Last update timestamp" } }, "description": "Document object" } } } } }, "summary": "Get document metadata by ID.", "description": "Returns document details including name, path, type, and tags." } }, "/api/v0/documents": { "post": { "tags": [ "Documents" ], "operationId": "documents_updateDocument", "parameters": [], "responses": { "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Document saved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the saved document" } }, "description": "Document save response" } } } } }, "summary": "Create or update a document.", "description": "Send ``id`` to update that document; omit it to create a new one. The\nresponse returns the document ID either way.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the document to update. Omit it to create a new document; the response returns the generated ID.", "default": null }, "name": { "type": "string", "description": "Document name" }, "content": { "type": "string", "description": "Document content" }, "type": { "type": "string", "description": "File type (e.g., .txt)" }, "companyId": { "type": "string", "description": "Company ID" }, "path": { "type": "string", "description": "Document path", "default": "/" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Array of tag strings" } }, "required": [ "name", "content", "type", "companyId" ], "description": "Request body for updating a document" } } }, "description": "Document data" } }, "get": { "tags": [ "Documents" ], "operationId": "documents_getDocuments", "parameters": [ { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string", "description": "Company ID" }, "description": "Company ID" }, { "name": "path", "in": "query", "required": false, "schema": { "type": "string", "description": "Path to get documents from (default: /)", "default": "/" }, "description": "Path to get documents from (default: /)" }, { "name": "includeTags", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Include tag information", "default": false }, "description": "Include tag information" } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "List of documents and folders at the specified path" } }, "summary": "List documents and folders at a path.", "description": "Returns all documents and folders at the specified path,\nsorted with folders first, then files alphabetically." } }, "/api/v0/documents/folders": { "get": { "tags": [ "Documents" ], "operationId": "documents_getFolders", "parameters": [ { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string", "description": "Company ID" }, "description": "Company ID" }, { "name": "includeTags", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Include tags (default: false)", "default": false }, "description": "Include tags (default: false)" }, { "name": "includeFiles", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Include files (default: false)", "default": false }, "description": "Include files (default: false)" } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Folder structure", "content": { "application/json": { "schema": { "type": "object", "properties": { "folders": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Folder ID" }, "name": { "type": "string", "description": "Folder name" }, "path": { "type": "string", "description": "Folder path" } }, "description": "Folder object" }, "description": "Nested folder structure" } }, "description": "Folders response" } } } } }, "summary": "Get all folders in the knowledge base.", "description": "Returns the folder structure with optional tag information." }, "post": { "tags": [ "Documents" ], "operationId": "documents_createFolder", "parameters": [], "responses": { "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Folder name conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Folder created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "description": "Success message" } }, "description": "Success response" } } } } }, "summary": "Create a new folder in the knowledge base.", "description": "Creates a folder at the specified path.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Folder name" }, "path": { "type": "string", "description": "Parent folder path (default: /)", "default": "/" }, "companyId": { "type": "string", "description": "Company ID" } }, "required": [ "name", "companyId" ], "description": "Request body for creating a folder" } } }, "description": "Folder creation data" } } }, "/api/v0/documents/move": { "post": { "tags": [ "Documents" ], "operationId": "documents_moveFile", "parameters": [], "responses": { "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Document moved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "description": "Success message" } }, "description": "Success response" } } } } }, "summary": "Move one or more documents to a different folder.", "description": "Accepts either a single documentId or a documentIds list and moves\neach document to the specified target folder.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "documentId": { "type": "string", "description": "ID of document to move (single move)" }, "documentIds": { "type": "array", "items": { "type": "string" }, "description": "IDs of documents to move (bulk move); provide this or documentId" }, "folder": { "type": "object", "description": "Target folder: {name: string, path: string}" } }, "required": [ "companyId", "folder" ], "description": "Request body for moving one or more documents" } } }, "description": "Move operation data" } } }, "/api/v0/documents/copy": { "post": { "tags": [ "Documents" ], "operationId": "documents_copyFile", "parameters": [], "responses": { "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Document copied successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "description": "Success message" }, "newDocumentId": { "type": "string", "description": "ID of the new document copy" } }, "description": "Document copy response" } } } } }, "summary": "Copy a document to a different folder.", "description": "Creates a copy of the document in the specified target folder.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "documentId": { "type": "string", "description": "ID of document to copy" }, "folder": { "type": "object", "description": "Target folder: {name: string, path: string}" } }, "required": [ "companyId", "documentId", "folder" ], "description": "Request body for copying a document" } } }, "description": "Copy operation data" } } }, "/api/v0/documents/convert": { "post": { "tags": [ "Documents" ], "operationId": "documents_convertDocuments", "parameters": [], "responses": { "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Converted documents", "content": { "application/json": { "schema": { "type": "object", "properties": { "documents": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Document name" }, "content": { "type": "string", "description": "Extracted text content" }, "tokens": { "type": "integer", "description": "Token count" }, "type": { "type": "string", "description": "File type" } }, "description": "Converted document object" }, "description": "List of converted documents" } }, "description": "Document conversion response" } } } } }, "summary": "Convert uploaded files to text format.", "description": "Extracts text content from uploaded files without saving them to the knowledge base.\nOptionally generates summaries for large documents.\n\nWith keepOriginal, the original file is stored too (originalFileId) so the chat\ncan copy it into the conversation's project, and a spreadsheet too large to\ninline comes back as a preview of its columns and first rows.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "generateSummary": { "type": "boolean", "description": "Generate summary for large documents", "default": false }, "keepOriginal": { "type": "boolean", "description": "Store the original file so it can be saved to a chat project", "default": false } }, "required": [ "companyId" ], "description": "Multipart form data for document conversion" } } }, "description": "Convert files (multipart form)" } } }, "/api/v0/documents/folders/{folderId}": { "delete": { "tags": [ "Documents" ], "operationId": "documents_deleteFolder", "parameters": [ { "name": "folderId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "delete", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Delete folder contents (default: false)", "default": false }, "description": "Delete folder contents (default: false)" } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Folder not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Folder deletion result", "content": { "application/json": { "schema": { "type": "object", "properties": { "changes": { "type": "array", "items": { "type": "object" }, "description": "List of affected documents" } }, "description": "Folder delete response" } } } } }, "summary": "Delete a folder from the knowledge base.", "description": "If delete=true, also deletes all documents inside the folder.\nOtherwise, documents are moved to the root folder." } }, "/api/v0/documents/folders/{folderId}/tags": { "put": { "tags": [ "Documents" ], "operationId": "documents_updateFolderTags", "parameters": [ { "name": "folderId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Folder not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Folder tags updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "description": "Success message" } }, "description": "Success response" } } } } }, "summary": "Update tags for a folder.", "description": "Sets the auto-apply tags for documents created in this folder.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Array of tag strings to apply" } }, "required": [ "companyId" ], "description": "Request body for updating folder tags" } } }, "description": "Folder tags update data" } } }, "/api/v0/documents/search": { "get": { "tags": [ "Documents" ], "operationId": "documents_searchDocuments", "parameters": [ { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string", "description": "Company ID" }, "description": "Company ID" }, { "name": "query", "in": "query", "required": true, "schema": { "type": "string", "description": "Search query string" }, "description": "Search query string" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "description": "Maximum results (default: 20)", "default": 20 }, "description": "Maximum results (default: 20)" } ], "responses": { "400": { "description": "Company ID required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Search results", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Document ID" }, "name": { "type": "string", "description": "Document name" }, "path": { "type": "string", "description": "Document path" }, "snippet": { "type": "string", "description": "Matching content snippet" }, "score": { "type": "number", "description": "Relevance score" } }, "description": "Search result item" }, "description": "Search results" } }, "description": "Document search response" } } } } }, "summary": "Search documents by name, content (vector search), and tags.", "description": "Performs semantic search across the knowledge base." }, "post": { "tags": [ "Documents" ], "operationId": "documents_searchDocumentsPost", "parameters": [ { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID." }, "description": "Company ID." } ], "responses": { "400": { "description": "Query required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Search results", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Document ID" }, "name": { "type": "string", "description": "Document name" }, "path": { "type": "string", "description": "Document path" }, "snippet": { "type": "string", "description": "Matching content snippet" }, "score": { "type": "number", "description": "Relevance score" } }, "description": "Search result item" }, "description": "Search results" } }, "description": "Document search response" } } } } }, "summary": "Search documents using POST (API-only, for n8n compatibility).", "description": "Performs semantic search across the knowledge base.\nCompanyId is derived from the API key." } }, "/api/v0/documents/recently-deleted": { "get": { "tags": [ "Documents" ], "operationId": "documents_getRecentlyDeleted", "parameters": [ { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string", "description": "Company ID" }, "description": "Company ID" }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "description": "Number of days to look back (default: 30)", "default": 30 }, "description": "Number of days to look back (default: 30)" } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "List of recently deleted documents" } }, "summary": "Get recently deleted documents.", "description": "Returns documents deleted within the specified number of days." } }, "/api/v0/documents/{documentId}/restore": { "post": { "tags": [ "Documents" ], "operationId": "documents_restoreDocument", "parameters": [ { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Document restored successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "description": "Success message" } }, "description": "Success response" } } } } }, "summary": "Restore a deleted document.", "description": "Restores a previously deleted document from the recycle bin." } }, "/api/v0/documents/folders/{folderId}/rename": { "put": { "tags": [ "Documents" ], "operationId": "documents_renameFolder", "parameters": [ { "name": "folderId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Folder rename result", "content": { "application/json": { "schema": { "type": "object", "properties": { "documentsUpdated": { "type": "integer", "description": "Number of documents updated" }, "embeddingsUpdated": { "type": "integer", "description": "Number of embeddings updated" }, "sharesUpdated": { "type": "integer", "description": "Number of shares updated" } }, "description": "Folder rename response" } } } } }, "summary": "Rename a folder and update all related documents, embeddings, and shares.", "description": "Updates the folder name and propagates the change to all child documents.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "newName": { "type": "string", "description": "New folder name" } }, "required": [ "companyId", "newName" ], "description": "Request body for renaming a folder" } } }, "description": "Folder rename data" } } }, "/api/v0/documents/folders/{folderId}/move": { "put": { "tags": [ "Documents" ], "operationId": "documents_moveFolderRoute", "parameters": [ { "name": "folderId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Folder move result", "content": { "application/json": { "schema": { "type": "object", "properties": { "documentsUpdated": { "type": "integer", "description": "Number of documents updated" }, "embeddingsUpdated": { "type": "integer", "description": "Number of embeddings updated" }, "sharesUpdated": { "type": "integer", "description": "Number of shares updated" } }, "description": "Folder rename response" } } } } }, "summary": "Move a folder to a different parent folder.", "description": "Updates the folder location and propagates the change to all child documents.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "folder": { "type": "object", "description": "Target folder: {name: string, path: string}" } }, "required": [ "companyId", "folder" ], "description": "Request body for moving a folder" } } }, "description": "Folder move data" } } }, "/api/v0/documents/{documentId}/details": { "get": { "tags": [ "Documents" ], "operationId": "documents_getDocumentDetailsApi", "parameters": [ { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID." }, "description": "Company ID." } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Document metadata", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Document ID" }, "name": { "type": "string", "description": "Document name" }, "type": { "type": "string", "description": "Document type: file, folder" }, "path": { "type": "string", "description": "Document path" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Document tags" }, "folderTags": { "type": "array", "items": { "type": "string" }, "description": "Auto-apply tags from folder" }, "childTags": { "type": "array", "items": { "type": "string" }, "description": "Tags from child documents" }, "sharing": { "type": "string", "description": "Sharing status: Private, Shared, External" }, "shareVisibility": { "type": "string", "description": "Share visibility level" }, "isExternal": { "type": "boolean", "description": "Whether document is from external share" }, "created": { "type": "string", "description": "Creation timestamp" }, "updated": { "type": "string", "description": "Last update timestamp" } }, "description": "Document object" } } } } }, "summary": "Get document metadata by ID (API-only).", "description": "Returns document details including name, path, type, and tags.\nCompanyId is derived from the API key." } }, "/api/v0/documents/{documentId}/content": { "get": { "tags": [ "Documents" ], "operationId": "documents_getDocumentContentApi", "parameters": [ { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID." }, "description": "Company ID." } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Document text content", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "description": "Document text content" } }, "description": "Document content response" } } } } }, "summary": "Get document content by ID (API-only).", "description": "Returns the full text content of the document.\nCompanyId is derived from the API key." } }, "/api/v0/documents/create": { "post": { "tags": [ "Documents" ], "operationId": "documents_createDocumentApi", "parameters": [ { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID." }, "description": "Company ID." } ], "responses": { "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "201": { "description": "Document created", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "description": "Success message" } }, "description": "Success response" } } } } }, "summary": "Create a new document (API-only).", "description": "Supports two modes:\n1. JSON body for text content: { name, content, path, tags }\n2. Multipart form for file upload: file, path, tags\n\nCompanyId is derived from the API key." } }, "/api/v0/documents/{documentId}/update": { "put": { "tags": [ "Documents" ], "operationId": "documents_updateDocumentApi", "parameters": [ { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Document updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "description": "Success message" } }, "description": "Success response" } } } } }, "summary": "Update an existing document (API-only).", "description": "Updates the document content. Optionally update name and tags.\nCompanyId is derived from the API key." } }, "/api/v0/api_keys": { "get": { "tags": [ "Keys" ], "operationId": "keys_listApiKeys", "parameters": [ { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string", "description": "Company ID to filter by" }, "description": "Company ID to filter by" } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "List of API keys", "content": { "application/json": { "schema": { "type": "object", "properties": { "apiKey": { "type": "string", "description": "The generated API key" } }, "description": "API key response" } } } } }, "summary": "List all API keys for the current user.", "description": "Values are masked; the plaintext is only ever returned once, at creation." }, "put": { "tags": [ "Keys" ], "operationId": "keys_upsertApiKey", "parameters": [], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "The API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "apiKey": { "type": "string", "description": "The generated API key" } }, "description": "API key response" } } } } }, "summary": "Create or get an existing API key.", "description": "Keys are stored hashed, so an existing key's plaintext can never be\nreturned; the response carries `created: false` and a masked value\ninstead. Delete the key (or pick a new name) to obtain a usable value.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "name": { "type": "string", "description": "API key name" } }, "required": [ "companyId", "name" ], "description": "Request body for creating an API key" } } }, "description": "API key details" } }, "post": { "tags": [ "Keys" ], "operationId": "keys_saveApiKey", "parameters": [], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "The generated API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "apiKey": { "type": "string", "description": "The generated API key" } }, "description": "API key response" } } } } }, "summary": "Create a new API key.", "description": "The plaintext is returned exactly once, at creation.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "name": { "type": "string", "description": "API key name" } }, "required": [ "companyId", "name" ], "description": "Request body for creating an API key" } } }, "description": "API key details" } }, "delete": { "tags": [ "Keys" ], "operationId": "keys_deleteApiKey", "parameters": [], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Delete an API key.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "name": { "type": "string", "description": "API key name" } }, "required": [ "companyId", "name" ], "description": "Request body for deleting an API key" } } }, "description": "API key to delete" } } }, "/api/v0/api_keys/{companyId}/{name}": { "get": { "tags": [ "Keys" ], "operationId": "keys_getApiKey", "parameters": [ { "name": "companyId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "API key not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "API key details", "content": { "application/json": { "schema": { "type": "object", "properties": { "apiKey": { "type": "string", "description": "The generated API key" } }, "description": "API key response" } } } } }, "summary": "Get a specific API key by company ID and name.", "description": "The value is masked." } }, "/api/v0/employees": { "post": { "tags": [ "Employees" ], "operationId": "employees_createEmployee", "parameters": [], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not enabled or company access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Created employees", "content": { "application/json": { "schema": { "type": "object", "properties": { "employees": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Employee ID" }, "name": { "type": "string", "description": "Employee name" }, "title": { "type": "string", "description": "Employee job title" }, "prompt": { "type": "string", "description": "Employee system prompt/persona" } }, "description": "Employee object" }, "description": "Created employees" }, "success": { "type": "boolean", "description": "Whether creation was successful" } }, "description": "Response after creating employees" } } } } }, "summary": "Create one or more AI employees.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "title": { "type": "string", "description": "Job title for the employee" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags to assign to the employee" }, "numEmployees": { "type": "integer", "description": "Number of employees to create (default: 1)" } }, "required": [ "companyId" ], "description": "Request body for creating employees" } } }, "description": "Employee creation request" } }, "get": { "tags": [ "Employees" ], "operationId": "employees_listEmployeesApi", "parameters": [ { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "description": "Search query to filter employees by name or title" }, "description": "Search query to filter employees by name or title" } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "List of employees", "content": { "application/json": { "schema": { "type": "object", "properties": { "employees": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Employee ID" }, "name": { "type": "string", "description": "Employee name" }, "title": { "type": "string", "description": "Employee job title" }, "prompt": { "type": "string", "description": "Employee system prompt/persona" } }, "description": "Employee object" }, "description": "Array of employees" }, "companyId": { "type": "string", "description": "Company ID" } }, "description": "List of employees" } } } } }, "summary": "List all employees (API-only, companyId from API key).", "description": "Returns employees for the company associated with the API key." } }, "/api/v0/companies/{companyId}/employees": { "get": { "tags": [ "Employees" ], "operationId": "employees_getEmployees", "parameters": [ { "name": "companyId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "description": "Search query to filter employees by name or title" }, "description": "Search query to filter employees by name or title" } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "List of employees", "content": { "application/json": { "schema": { "type": "object", "properties": { "employees": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Employee ID" }, "name": { "type": "string", "description": "Employee name" }, "title": { "type": "string", "description": "Employee job title" }, "prompt": { "type": "string", "description": "Employee system prompt/persona" } }, "description": "Employee object" }, "description": "Array of employees" }, "companyId": { "type": "string", "description": "Company ID" } }, "description": "List of employees" } } } } }, "summary": "Get all employees for a company." } }, "/api/v0/employees/{employeeId}": { "delete": { "tags": [ "Employees" ], "operationId": "employees_deleteEmployees", "parameters": [ { "name": "employeeId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Employee not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Employee deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "description": "Success message" } }, "description": "Success response" } } } } }, "summary": "Delete an employee." }, "post": { "tags": [ "Employees" ], "operationId": "employees_saveEmployees", "parameters": [ { "name": "employeeId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID." }, "description": "Company ID." } ], "responses": { "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not enabled or not allowed to edit this employee", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Employee saved", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the saved employee" } }, "description": "Employee save response" } } } } }, "summary": "Create or update an employee.", "description": "The employee ID comes from the URL. If an employee with that ID exists, the\nfields in the body are updated (send only what should change); otherwise a\nnew employee is created under that ID, which requires a companyId. An `id`\nin the body is ignored.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID. Required to create an employee; ignored on update (an employee cannot be moved to another company)." }, "name": { "type": "string", "description": "Employee name" }, "title": { "type": "string", "description": "Job title" }, "description": { "type": "string", "description": "Short description of what the employee does" }, "prompt": { "type": "string", "description": "System prompt/persona" }, "responseInstructions": { "type": "string", "description": "Response instructions" }, "greetingMessage": { "type": "string", "description": "Greeting shown when a new chat starts" }, "starterPrompts": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "description": "Short playbook title shown on the card" }, "prompt": { "type": "string", "description": "Message sent when the card is clicked" } }, "required": [ "title", "prompt" ] }, "description": "Clickable playbooks shown when a new chat starts" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags" }, "picture": { "type": "string", "description": "Picture URL" }, "departmentIds": { "type": "array", "items": { "type": "string" }, "description": "Department IDs; replaces the employee's department assignments" } }, "description": "Request body for creating or updating an employee. The employee ID comes from the URL path; send only the fields to change. companyId is required when the employee does not exist yet (or comes from the API key)." } } }, "description": "Fields to set on the employee" } }, "get": { "tags": [ "Employees" ], "operationId": "employees_getEmployee", "parameters": [ { "name": "employeeId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID." }, "description": "Company ID." } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Employee not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Employee details", "content": { "application/json": { "schema": { "type": "object", "properties": { "employee": { "type": "object", "properties": { "id": { "type": "string", "description": "Employee ID" }, "name": { "type": "string", "description": "Employee name" }, "title": { "type": "string", "description": "Employee job title" }, "prompt": { "type": "string", "description": "Employee system prompt/persona" } }, "description": "Employee details" } }, "description": "Response with employee details" } } } } }, "summary": "Get a specific employee by ID." } }, "/api/v0/employee-personas": { "get": { "tags": [ "Employees" ], "operationId": "employees_getEmployeePersonas", "parameters": [ { "name": "category", "in": "query", "required": false, "schema": { "type": "string", "description": "Filter personas by category" }, "description": "Filter personas by category" } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "List of employee persona templates", "content": { "application/json": { "schema": { "type": "object", "properties": { "personas": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Persona ID" }, "name": { "type": "string", "description": "Persona name" }, "title": { "type": "string", "description": "Job title" }, "description": { "type": "string", "description": "Description" }, "category": { "type": "string", "description": "Category" }, "systemPrompt": { "type": "string", "description": "System prompt" }, "picture": { "type": "string", "description": "Picture URL" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags" }, "usageCount": { "type": "integer", "description": "Number of times used" } }, "description": "Employee persona template" }, "description": "List of personas" } }, "description": "List of employee personas" } } } } }, "summary": "Get all employee persona templates." } }, "/api/v0/employee-personas/categories": { "get": { "tags": [ "Employees" ], "operationId": "employees_getEmployeePersonaCategories", "parameters": [], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "List of persona categories", "content": { "application/json": { "schema": { "type": "object", "properties": { "categories": { "type": "array", "items": { "type": "string" }, "description": "List of category names" } }, "description": "List of persona categories" } } } } }, "summary": "Get all unique persona categories." } }, "/api/v0/employee-personas/{personaId}": { "get": { "tags": [ "Employees" ], "operationId": "employees_getEmployeePersona", "parameters": [ { "name": "personaId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Persona not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Persona details", "content": { "application/json": { "schema": { "type": "object", "properties": { "persona": { "type": "object", "properties": { "id": { "type": "string", "description": "Persona ID" }, "name": { "type": "string", "description": "Persona name" }, "title": { "type": "string", "description": "Job title" }, "description": { "type": "string", "description": "Description" }, "category": { "type": "string", "description": "Category" }, "systemPrompt": { "type": "string", "description": "System prompt" }, "picture": { "type": "string", "description": "Picture URL" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags" }, "usageCount": { "type": "integer", "description": "Number of times used" } }, "description": "Persona details" } }, "description": "Employee persona detail" } } } } }, "summary": "Get a single employee persona by ID." } }, "/api/v0/employee-personas/search": { "get": { "tags": [ "Employees" ], "operationId": "employees_searchEmployeePersonas", "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "description": "Search query" }, "description": "Search query" }, { "name": "category", "in": "query", "required": false, "schema": { "type": "string", "description": "Filter by category" }, "description": "Filter by category" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "description": "Maximum number of results to return" }, "description": "Maximum number of results to return" } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Search results", "content": { "application/json": { "schema": { "type": "object", "properties": { "personas": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Persona ID" }, "name": { "type": "string", "description": "Persona name" }, "title": { "type": "string", "description": "Job title" }, "description": { "type": "string", "description": "Description" }, "category": { "type": "string", "description": "Category" }, "systemPrompt": { "type": "string", "description": "System prompt" }, "picture": { "type": "string", "description": "Picture URL" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags" }, "usageCount": { "type": "integer", "description": "Number of times used" } }, "description": "Employee persona template" }, "description": "List of personas" } }, "description": "List of employee personas" } } } } }, "summary": "Search employee personas." } }, "/api/v0/employees/create-from-persona": { "post": { "tags": [ "Employees" ], "operationId": "employees_createEmployeeFromPersona", "parameters": [], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Persona not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "201": { "description": "Created employee", "content": { "application/json": { "schema": { "type": "object", "properties": { "employee": { "type": "object", "properties": { "id": { "type": "string", "description": "Employee ID" }, "name": { "type": "string", "description": "Employee name" }, "title": { "type": "string", "description": "Employee job title" }, "prompt": { "type": "string", "description": "Employee system prompt/persona" } }, "description": "Created employee" }, "success": { "type": "boolean", "description": "Whether creation was successful" } }, "description": "Response after creating a single employee" } } } } }, "summary": "Create a new employee from a persona template.", "description": "Takes a persona ID and creates an employee with the persona's attributes.\nOptionally allows overriding specific fields.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "personaId": { "type": "string", "description": "Persona template ID" }, "overrides": { "type": "object", "description": "Optional field overrides: {name?: string, title?: string, prompt?: string, picture?: string, responseInstructions?: string}" } }, "required": [ "companyId", "personaId" ], "description": "Request body for creating employee from persona template" } } }, "description": "Create from persona request" } } }, "/api/v0/employees/chat": { "post": { "tags": [ "Employees" ], "operationId": "employees_chatEmployee", "parameters": [], "responses": { "400": { "description": "Missing required parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Employee not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Chat response", "content": { "application/json": { "schema": { "type": "object", "properties": { "response": { "type": "string", "description": "AI-generated response" }, "model": { "type": "string", "description": "Model used for the response" }, "settings": { "type": "object", "description": "Applied settings for the completion" } }, "description": "Chat completion response from employee" } } } } }, "summary": "Chat with an employee.", "description": "Send a message to a specific AI employee and receive a response based on\ntheir persona and your company's knowledge base. A new chat is created when\nchatId is omitted; pass the returned chatId back to continue the conversation.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID." }, "employeeId": { "type": "string", "description": "ID of the employee to chat with" }, "message": { "type": "string", "description": "The message to send to the employee" }, "chatId": { "type": "string", "description": "ID of an existing chat to continue. Omit to start a new chat." }, "settings": { "type": "object", "properties": { "platformTools": { "type": "boolean", "description": "Enable company-scoped platform tools" }, "scheduledTemplateSetup": { "type": "object", "description": "Scheduled template resource and integration selections (no credentials)" }, "model": { "type": "string", "description": "AI model to use (e.g., gpt-5-nano, claude-sonnet-5)" }, "temperature": { "type": "number", "description": "Temperature for model variation (0.0-1.0). Default: 0.7" }, "reasoningEffort": { "type": "string", "description": "Reasoning effort for models that support reasoning tokens. Valid values: \"none\", \"minimal\", \"low\", \"medium\", \"high\", \"xhigh\". Empty string means use model default.", "enum": [ "", "none", "minimal", "low", "medium", "high", "xhigh" ] }, "strategy": { "type": "string", "description": "Response strategy. Valid values: \"one-shot\", \"chain\", \"function-chain\", \"langchain\". Default: \"function-chain\"", "enum": [ "one-shot", "chain", "function-chain", "langchain" ] }, "memoryScope": { "type": "string", "description": "Memory scope for context retrieval. Valid values: \"chat\", \"company\", \"global\". Default: \"chat\"", "enum": [ "chat", "company", "global" ] }, "shortTermMemories": { "type": "boolean", "description": "Include short-term memories in context. Default: true" }, "longTermMemories": { "type": "boolean", "description": "Include long-term memories in context. Default: false" }, "documents": { "type": "boolean", "description": "Enable document retrieval from knowledge base. Default: true" }, "documentScope": { "type": "string", "description": "Document scope for retrieval. Valid values: \"root\", \"folder\", \"file\", \"tags\". Default: \"root\"", "enum": [ "root", "folder", "file", "tags" ] }, "documentStrategy": { "type": "string", "description": "Document retrieval strategy. Default: \"similarity-ranking\"" }, "documentPath": { "type": "string", "description": "Document path for scoping retrieval. Default: \"/\"" }, "requestDocuments": { "type": "array", "items": { "type": "object" }, "description": "Specific documents to include in context. Array of {id: string, name?: string, path?: string} objects" }, "searchEngine": { "type": "boolean", "description": "Enable web search via search engine. Default: false" }, "websites": { "type": "boolean", "description": "Enable website content retrieval. Default: false" }, "websitesJs": { "type": "boolean", "description": "Enable JavaScript-rendered website reading. Default: false" }, "news": { "type": "boolean", "description": "Enable online news search. Default: false" }, "company": { "type": "boolean", "description": "Include company context. Default: true" }, "employee": { "type": "boolean", "description": "Include employee context. Default: true" }, "responseInstructions": { "type": "boolean", "description": "Include response instructions in context. Default: true" }, "image": { "type": "string", "description": "Image URL for vision models" }, "lists": { "type": "boolean", "description": "Enable access to lists feature. Default: false" }, "browserTask": { "type": "object", "description": "Browser task configuration: {integrationId: string, task: string, useVision?: boolean} for web automation" }, "documentCreation": { "type": "boolean", "description": "Enable document creation tool. Default: false" }, "inboxId": { "type": "string", "description": "ID of an inbox the employee works from. When set, the employee gets inbox tools (list with a live provider pull, read, send, reply, forward, mark handled) and uses this inbox for email by default. Empty: no inbox" }, "sleepTool": { "type": "boolean", "description": "Enable the sleep tool, which pauses briefly mid-run. Default: true" }, "canvasTool": { "type": "boolean", "description": "Enable the create_canvas tool, which renders an HTML canvas into a shareable image. Default: true" }, "mcpServers": { "type": "array", "items": { "type": "string" }, "description": "Array of MCP server IDs to enable" }, "composioTools": { "type": "array", "items": { "type": "string" }, "description": "Array of Composio integration IDs to enable as tools" }, "toolRouter": { "type": "boolean", "description": "Enable Composio tool router for dynamic tool discovery across 1000+ apps. Default: false" }, "audienceTools": { "type": "boolean", "description": "Enable the lead tools: enrich, leads, lead_field_options, import_leads. Default: false" }, "voiceId": { "type": "string", "description": "ElevenLabs voice ID to override employee default for TTS" } }, "description": "Optional settings to override defaults" } }, "required": [ "companyId", "employeeId", "message" ], "description": "Request body for chatting with an employee" } } }, "description": "Chat request" } } }, "/api/v0/employees/chat/async": { "post": { "tags": [ "Employees" ], "operationId": "employees_chatEmployeeAsync", "parameters": [], "responses": { "400": { "description": "Missing required parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Employee not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "202": { "description": "Chat initiated", "content": { "application/json": { "schema": { "type": "object", "properties": { "chatId": { "type": "string", "description": "The chat ID to use for polling" }, "userMessageId": { "type": "string", "description": "The ID of the user message" }, "assistantMessageId": { "type": "string", "description": "The ID of the assistant message (populated when complete)" }, "status": { "type": "string", "description": "Status of the request (processing)" } }, "description": "Response when starting an async chat" } } } } }, "summary": "Start an async chat with an employee.", "description": "Returns immediately with a chat ID that can be used to poll for the response.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID." }, "employeeId": { "type": "string", "description": "ID of the employee to chat with" }, "message": { "type": "string", "description": "The message to send to the employee" }, "chatId": { "type": "string", "description": "ID of an existing chat to continue. Omit to start a new chat." }, "settings": { "type": "object", "properties": { "platformTools": { "type": "boolean", "description": "Enable company-scoped platform tools" }, "scheduledTemplateSetup": { "type": "object", "description": "Scheduled template resource and integration selections (no credentials)" }, "model": { "type": "string", "description": "AI model to use (e.g., gpt-5-nano, claude-sonnet-5)" }, "temperature": { "type": "number", "description": "Temperature for model variation (0.0-1.0). Default: 0.7" }, "reasoningEffort": { "type": "string", "description": "Reasoning effort for models that support reasoning tokens. Valid values: \"none\", \"minimal\", \"low\", \"medium\", \"high\", \"xhigh\". Empty string means use model default.", "enum": [ "", "none", "minimal", "low", "medium", "high", "xhigh" ] }, "strategy": { "type": "string", "description": "Response strategy. Valid values: \"one-shot\", \"chain\", \"function-chain\", \"langchain\". Default: \"function-chain\"", "enum": [ "one-shot", "chain", "function-chain", "langchain" ] }, "memoryScope": { "type": "string", "description": "Memory scope for context retrieval. Valid values: \"chat\", \"company\", \"global\". Default: \"chat\"", "enum": [ "chat", "company", "global" ] }, "shortTermMemories": { "type": "boolean", "description": "Include short-term memories in context. Default: true" }, "longTermMemories": { "type": "boolean", "description": "Include long-term memories in context. Default: false" }, "documents": { "type": "boolean", "description": "Enable document retrieval from knowledge base. Default: true" }, "documentScope": { "type": "string", "description": "Document scope for retrieval. Valid values: \"root\", \"folder\", \"file\", \"tags\". Default: \"root\"", "enum": [ "root", "folder", "file", "tags" ] }, "documentStrategy": { "type": "string", "description": "Document retrieval strategy. Default: \"similarity-ranking\"" }, "documentPath": { "type": "string", "description": "Document path for scoping retrieval. Default: \"/\"" }, "requestDocuments": { "type": "array", "items": { "type": "object" }, "description": "Specific documents to include in context. Array of {id: string, name?: string, path?: string} objects" }, "searchEngine": { "type": "boolean", "description": "Enable web search via search engine. Default: false" }, "websites": { "type": "boolean", "description": "Enable website content retrieval. Default: false" }, "websitesJs": { "type": "boolean", "description": "Enable JavaScript-rendered website reading. Default: false" }, "news": { "type": "boolean", "description": "Enable online news search. Default: false" }, "company": { "type": "boolean", "description": "Include company context. Default: true" }, "employee": { "type": "boolean", "description": "Include employee context. Default: true" }, "responseInstructions": { "type": "boolean", "description": "Include response instructions in context. Default: true" }, "image": { "type": "string", "description": "Image URL for vision models" }, "lists": { "type": "boolean", "description": "Enable access to lists feature. Default: false" }, "browserTask": { "type": "object", "description": "Browser task configuration: {integrationId: string, task: string, useVision?: boolean} for web automation" }, "documentCreation": { "type": "boolean", "description": "Enable document creation tool. Default: false" }, "inboxId": { "type": "string", "description": "ID of an inbox the employee works from. When set, the employee gets inbox tools (list with a live provider pull, read, send, reply, forward, mark handled) and uses this inbox for email by default. Empty: no inbox" }, "sleepTool": { "type": "boolean", "description": "Enable the sleep tool, which pauses briefly mid-run. Default: true" }, "canvasTool": { "type": "boolean", "description": "Enable the create_canvas tool, which renders an HTML canvas into a shareable image. Default: true" }, "mcpServers": { "type": "array", "items": { "type": "string" }, "description": "Array of MCP server IDs to enable" }, "composioTools": { "type": "array", "items": { "type": "string" }, "description": "Array of Composio integration IDs to enable as tools" }, "toolRouter": { "type": "boolean", "description": "Enable Composio tool router for dynamic tool discovery across 1000+ apps. Default: false" }, "audienceTools": { "type": "boolean", "description": "Enable the lead tools: enrich, leads, lead_field_options, import_leads. Default: false" }, "voiceId": { "type": "string", "description": "ElevenLabs voice ID to override employee default for TTS" } }, "description": "Optional settings to override defaults" } }, "required": [ "companyId", "employeeId", "message" ], "description": "Request body for chatting with an employee" } } }, "description": "Async chat request" } } }, "/api/v0/employees/chat/async/{chat_id}": { "get": { "tags": [ "Employees" ], "operationId": "employees_getAsyncChatResult", "parameters": [ { "name": "chat_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Chat not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Chat result", "content": { "application/json": { "schema": { "type": "object", "properties": { "chatId": { "type": "string", "description": "The chat ID" }, "status": { "type": "string", "description": "Status: processing, completed, or error" }, "response": { "type": "string", "description": "AI-generated response (when completed)" }, "fullText": { "type": "string", "description": "Full response text (when completed)" }, "context": { "type": "object", "description": "Context information from the response" }, "error": { "type": "string", "description": "Error message (when status is error)" }, "userMessage": { "type": "string", "description": "The original user message" } }, "description": "Response when polling for async chat result" } } } } }, "summary": "Get the result of an async chat request.", "description": "Poll this endpoint with the chat ID returned from the async chat endpoint." } }, "/api/v0/chat/completions": { "post": { "tags": [ "Chat" ], "operationId": "chat_chatCompletions", "parameters": [], "responses": { "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Chat completion response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Completion ID" }, "object": { "type": "string", "description": "Object type (chat.completion)" }, "created": { "type": "integer", "description": "Creation timestamp" }, "model": { "type": "string", "description": "Model used" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "description": "Choice index" }, "message": { "type": "object", "properties": { "role": { "type": "string", "description": "Message role: system, user, or assistant" }, "content": { "type": "string", "description": "Message content" } }, "required": [ "role", "content" ], "description": "Generated message" }, "logprobs": { "type": "string", "description": "Log probabilities" }, "finish_reason": { "type": "string", "description": "Reason for completion" } }, "description": "Completion choice" }, "description": "Completion choices" }, "usage": { "type": "object", "properties": { "prompt_tokens": { "type": "integer", "description": "Prompt token count" }, "completion_tokens": { "type": "integer", "description": "Completion token count" }, "total_tokens": { "type": "integer", "description": "Total token count" } }, "description": "Token usage" }, "system_fingerprint": { "type": "string", "description": "System fingerprint" } }, "description": "Chat completion response" } } } } }, "summary": "Create a chat completion (OpenAI compatible).", "description": "Fully compatible with OpenAI's API specification for seamless\nintegration with OpenAI libraries. Supports both streaming and\nnon-streaming responses.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string", "description": "Model ID to use" }, "messages": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "description": "Message role: system, user, or assistant" }, "content": { "type": "string", "description": "Message content" } }, "required": [ "role", "content" ], "description": "Chat message object" }, "description": "Array of messages in the conversation" }, "temperature": { "type": "number", "description": "Sampling temperature (0-2)", "default": 1.0 }, "max_tokens": { "type": "integer", "description": "Maximum tokens to generate" }, "top_p": { "type": "number", "description": "Nucleus sampling parameter (0-1)", "default": 1.0 }, "n": { "type": "integer", "description": "Number of completions (only 1 supported)", "default": 1 }, "stream": { "type": "boolean", "description": "Enable streaming response", "default": false }, "stop": { "type": "string", "description": "Stop sequences (string or array)" }, "presence_penalty": { "type": "number", "description": "Presence penalty (-2.0 to 2.0)", "default": 0.0 }, "frequency_penalty": { "type": "number", "description": "Frequency penalty (-2.0 to 2.0)", "default": 0.0 }, "logit_bias": { "type": "object", "description": "Token ID to bias mapping" }, "user": { "type": "string", "description": "End-user identifier" }, "response_format": { "type": "object", "description": "Response format specification" }, "seed": { "type": "integer", "description": "Random seed for reproducibility" }, "tools": { "type": "array", "items": { "type": "object" }, "description": "Tool definitions" }, "tool_choice": { "type": "string", "description": "Tool choice specification" } }, "required": [ "model", "messages" ], "description": "Request body for chat completion (OpenAI compatible)" } } }, "description": "Chat completion request (OpenAI compatible)" } } }, "/api/v0/claude/v1/messages": { "post": { "tags": [ "Chat" ], "operationId": "chat_anthropicMessages", "parameters": [], "responses": { "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown model", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Message response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Message ID" }, "type": { "type": "string", "description": "Object type (message)" }, "role": { "type": "string", "description": "Message role (assistant)" }, "model": { "type": "string", "description": "Model used (as requested)" }, "content": { "type": "array", "items": { "type": "object" }, "description": "Array of content blocks (text and tool_use)" }, "stop_reason": { "type": "string", "description": "Why generation stopped: end_turn, max_tokens, or tool_use" }, "stop_sequence": { "type": "string", "description": "Stop sequence hit, if any" }, "usage": { "type": "object", "properties": { "input_tokens": { "type": "integer", "description": "Input token count" }, "output_tokens": { "type": "integer", "description": "Output token count" } }, "description": "Token usage" } }, "description": "Message response (Anthropic Messages API compatible)" } } } } }, "summary": "Create a message (Anthropic Messages API compatible).", "description": "Point Claude Code or any Anthropic SDK at\nANTHROPIC_BASE_URL=https:///api/v0/claude with a platform\nAPI key as ANTHROPIC_AUTH_TOKEN. Supports streaming and tool use.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string", "description": "Model ID (accepted as required by the Anthropic API; every request is served by the platform's fixed compat model)" }, "messages": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "description": "Message role: user or assistant" }, "content": { "type": "string", "description": "Message content: string or array of content blocks" } }, "required": [ "role", "content" ], "description": "Anthropic message object" }, "description": "Array of input messages" }, "max_tokens": { "type": "integer", "description": "Maximum tokens to generate" }, "system": { "type": "string", "description": "System prompt: string or array of text blocks" }, "stream": { "type": "boolean", "description": "Enable server-sent event streaming", "default": false }, "temperature": { "type": "number", "description": "Sampling temperature (0-1)" }, "top_p": { "type": "number", "description": "Nucleus sampling parameter" }, "top_k": { "type": "integer", "description": "Top-k sampling parameter" }, "stop_sequences": { "type": "array", "items": { "type": "string" }, "description": "Custom stop sequences" }, "tools": { "type": "array", "items": { "type": "object" }, "description": "Tool definitions (Anthropic tool format)" }, "tool_choice": { "type": "object", "description": "Tool choice specification" }, "metadata": { "type": "object", "description": "Request metadata" } }, "required": [ "model", "messages", "max_tokens" ], "description": "Request body for creating a message (Anthropic Messages API compatible)" } } }, "description": "Message request (Anthropic Messages API compatible)" } } }, "/api/v0/claude/v1/messages/count_tokens": { "post": { "tags": [ "Chat" ], "operationId": "chat_anthropicCountTokens", "parameters": [], "responses": { "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Estimated token count", "content": { "application/json": { "schema": { "type": "object", "properties": { "input_tokens": { "type": "integer", "description": "Estimated input token count" } }, "description": "Token count estimate" } } } } }, "summary": "Count tokens for a message request (Anthropic API compatible).", "description": "Character-based estimate; close enough for Claude Code's context\nmanagement.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string", "description": "Model ID" }, "messages": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "description": "Message role: user or assistant" }, "content": { "type": "string", "description": "Message content: string or array of content blocks" } }, "required": [ "role", "content" ], "description": "Anthropic message object" }, "description": "Array of input messages" }, "system": { "type": "string", "description": "System prompt: string or array of text blocks" }, "tools": { "type": "array", "items": { "type": "object" }, "description": "Tool definitions (Anthropic tool format)" } }, "required": [ "messages" ], "description": "Request body for token counting (Anthropic API compatible)" } } }, "description": "Token count request (Anthropic API compatible)" } } }, "/api/v0/claude/v1/models": { "get": { "tags": [ "Chat" ], "operationId": "chat_anthropicModels", "parameters": [], "responses": { "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Available models", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object" }, "description": "Model objects { type, id, display_name, created_at }" }, "has_more": { "type": "boolean", "description": "Whether more pages exist (always false)" }, "first_id": { "type": "string", "description": "First model ID in the list" }, "last_id": { "type": "string", "description": "Last model ID in the list" } }, "description": "Available models (Anthropic API compatible)" } } } } }, "summary": "List available models (Anthropic API compatible).", "description": "Lets Claude Code discover platform models when\nCLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 is set. This API serves every\nrequest with ANTHROPIC_COMPAT_MODEL, so that is the only model listed." } }, "/api/v0/projects": { "get": { "tags": [ "Projects" ], "operationId": "projects_getProjects", "parameters": [ { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID" }, "description": "Company ID" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Page number (default: 1)", "default": 1 }, "description": "Page number (default: 1)" }, { "name": "perPage", "in": "query", "required": false, "schema": { "type": "integer", "description": "Items per page (default: 20)", "default": 20 }, "description": "Items per page (default: 20)" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "description": "Search term for name/description" }, "description": "Search term for name/description" }, { "name": "includeShared", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Include shared projects (default: true)", "default": true }, "description": "Include shared projects (default: true)" } ], "responses": { "400": { "description": "Missing companyId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Paginated list of projects", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Project ID" }, "name": { "type": "string", "description": "Project name" }, "description": { "type": "string", "description": "Project description" }, "instructions": { "type": "string", "description": "Custom AI instructions" }, "sharing": { "type": "string", "description": "Sharing mode: 'Private' or 'Shared'" }, "settings": { "type": "object", "description": "Additional project settings" }, "uid": { "type": "string", "description": "Owner user ID" }, "companyId": { "type": "string", "description": "Company ID" }, "created": { "type": "number", "description": "Creation timestamp" }, "updated": { "type": "number", "description": "Last update timestamp" } }, "description": "Project object" }, "description": "List of projects" }, "total": { "type": "integer", "description": "Total number of projects" }, "page": { "type": "integer", "description": "Current page number" }, "perPage": { "type": "integer", "description": "Items per page" } }, "description": "Paginated list of projects" } } } } }, "summary": "Get all workspace projects.", "description": "Returns paginated list of projects with optional search and sharing filters." }, "post": { "tags": [ "Projects" ], "operationId": "projects_createProject", "parameters": [], "responses": { "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Created project", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Project ID" }, "name": { "type": "string", "description": "Project name" }, "description": { "type": "string", "description": "Project description" }, "instructions": { "type": "string", "description": "Custom AI instructions" }, "sharing": { "type": "string", "description": "Sharing mode: 'Private' or 'Shared'" }, "settings": { "type": "object", "description": "Additional project settings" }, "uid": { "type": "string", "description": "Owner user ID" }, "companyId": { "type": "string", "description": "Company ID" }, "created": { "type": "number", "description": "Creation timestamp" }, "updated": { "type": "number", "description": "Last update timestamp" } }, "description": "Project object" } } } } }, "summary": "Create a new workspace project.", "description": "Creates a project with optional description, AI instructions, and sharing settings.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Project name" }, "companyId": { "type": "string", "description": "Company ID" }, "description": { "type": "string", "description": "Project description" }, "instructions": { "type": "string", "description": "Custom AI instructions" }, "sharing": { "type": "string", "description": "Sharing mode: 'Private' or 'Shared'", "default": "Private" }, "settings": { "type": "object", "description": "Additional project settings" } }, "required": [ "name", "companyId" ], "description": "Request body for creating a project" } } }, "description": "Project creation parameters" } } }, "/api/v0/projects/{project_id}": { "get": { "tags": [ "Projects" ], "operationId": "projects_getProject", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID" }, "description": "Company ID" } ], "responses": { "400": { "description": "Missing companyId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Project not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Project details", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Project ID" }, "name": { "type": "string", "description": "Project name" }, "description": { "type": "string", "description": "Project description" }, "instructions": { "type": "string", "description": "Custom AI instructions" }, "sharing": { "type": "string", "description": "Sharing mode: 'Private' or 'Shared'" }, "settings": { "type": "object", "description": "Additional project settings" }, "uid": { "type": "string", "description": "Owner user ID" }, "companyId": { "type": "string", "description": "Company ID" }, "created": { "type": "number", "description": "Creation timestamp" }, "updated": { "type": "number", "description": "Last update timestamp" } }, "description": "Project object" } } } } }, "summary": "Get a workspace project by ID.", "description": "Returns project if found and accessible to the user." }, "patch": { "tags": [ "Projects" ], "operationId": "projects_updateProject", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Project not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Updated project", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Project ID" }, "name": { "type": "string", "description": "Project name" }, "description": { "type": "string", "description": "Project description" }, "instructions": { "type": "string", "description": "Custom AI instructions" }, "sharing": { "type": "string", "description": "Sharing mode: 'Private' or 'Shared'" }, "settings": { "type": "object", "description": "Additional project settings" }, "uid": { "type": "string", "description": "Owner user ID" }, "companyId": { "type": "string", "description": "Company ID" }, "created": { "type": "number", "description": "Creation timestamp" }, "updated": { "type": "number", "description": "Last update timestamp" } }, "description": "Project object" } } } } }, "summary": "Update a workspace project.", "description": "All fields are optional. Only provided fields will be updated.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "name": { "type": "string", "description": "Project name" }, "description": { "type": "string", "description": "Project description" }, "instructions": { "type": "string", "description": "Custom AI instructions" }, "sharing": { "type": "string", "description": "Sharing mode: 'Private' or 'Shared'" }, "settings": { "type": "object", "description": "Additional project settings" } }, "required": [ "companyId" ], "description": "Request body for updating a project" } } }, "description": "Project update parameters" } }, "delete": { "tags": [ "Projects" ], "operationId": "projects_deleteProject", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID" }, "description": "Company ID" } ], "responses": { "400": { "description": "Missing companyId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Project not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Deletion confirmation", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Success indicator" } }, "description": "Success response" } } } } }, "summary": "Delete a workspace project.", "description": "Deletes the project and all associated files." } }, "/api/v0/projects/{project_id}/files": { "get": { "tags": [ "Projects" ], "operationId": "projects_getProjectFiles", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID" }, "description": "Company ID" }, { "name": "path", "in": "query", "required": false, "schema": { "type": "string", "description": "Directory path (default: /)" }, "description": "Directory path (default: /)" }, { "name": "includeContent", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Include file content (default: false)", "default": false }, "description": "Include file content (default: false)" } ], "responses": { "400": { "description": "Missing companyId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Project not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "List of project files", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "File ID" }, "name": { "type": "string", "description": "File name" }, "path": { "type": "string", "description": "File path" }, "type": { "type": "string", "description": "File type/extension" }, "mimeType": { "type": "string", "description": "MIME type" }, "content": { "type": "string", "description": "File content (if requested)" }, "isDirectory": { "type": "boolean", "description": "Whether this is a directory" }, "size": { "type": "integer", "description": "File size in bytes" }, "isPublished": { "type": "boolean", "description": "Whether file is publicly published" }, "publicSlug": { "type": "string", "description": "Public URL slug (if published)" }, "publicUrl": { "type": "string", "description": "Full public URL (if published)" }, "created": { "type": "number", "description": "Creation timestamp" }, "updated": { "type": "number", "description": "Last update timestamp" } }, "description": "Project file object" } } } } }, "summary": "Get files in a workspace project.", "description": "Returns list of files in the specified directory path." }, "post": { "tags": [ "Projects" ], "operationId": "projects_createProjectFile", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Project not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Created file", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "File ID" }, "name": { "type": "string", "description": "File name" }, "path": { "type": "string", "description": "File path" }, "type": { "type": "string", "description": "File type/extension" }, "mimeType": { "type": "string", "description": "MIME type" }, "content": { "type": "string", "description": "File content (if requested)" }, "isDirectory": { "type": "boolean", "description": "Whether this is a directory" }, "size": { "type": "integer", "description": "File size in bytes" }, "isPublished": { "type": "boolean", "description": "Whether file is publicly published" }, "publicSlug": { "type": "string", "description": "Public URL slug (if published)" }, "publicUrl": { "type": "string", "description": "Full public URL (if published)" }, "created": { "type": "number", "description": "Creation timestamp" }, "updated": { "type": "number", "description": "Last update timestamp" } }, "description": "Project file object" } } } } }, "summary": "Create a new file in a project.", "description": "Creates a file or directory at the specified path.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "path": { "type": "string", "description": "Full file path (e.g., '/src/main.py')" }, "content": { "type": "string", "description": "File content", "default": "" }, "mimeType": { "type": "string", "description": "MIME type of the file" }, "isDirectory": { "type": "boolean", "description": "Whether this is a directory", "default": false } }, "required": [ "companyId", "path" ], "description": "Request body for creating a project file" } } }, "description": "File creation parameters" } } }, "/api/v0/projects/{project_id}/tree": { "get": { "tags": [ "Projects" ], "operationId": "projects_getProjectTree", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID" }, "description": "Company ID" } ], "responses": { "400": { "description": "Missing companyId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Project not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Project file tree", "content": { "application/json": { "schema": { "type": "object", "properties": { "tree": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "File/directory ID" }, "name": { "type": "string", "description": "File/directory name" }, "type": { "type": "string", "description": "Node type: 'file' or 'directory'" }, "path": { "type": "string", "description": "Full path" }, "children": { "type": "array", "items": { "type": "object", "description": "Recursive reference (same schema)" }, "description": "Child nodes (for directories)" } }, "description": "File tree node" }, "description": "Root level nodes" } }, "description": "Project file tree" } } } } }, "summary": "Get the full file tree for a project.", "description": "Returns nested tree structure with all files and directories." } }, "/api/v0/projects/{project_id}/files/{file_id}": { "get": { "tags": [ "Projects" ], "operationId": "projects_getProjectFile", "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID" }, "description": "Company ID" } ], "responses": { "400": { "description": "Missing companyId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Project or file not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "File with content", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "File ID" }, "name": { "type": "string", "description": "File name" }, "path": { "type": "string", "description": "File path" }, "type": { "type": "string", "description": "File type/extension" }, "mimeType": { "type": "string", "description": "MIME type" }, "content": { "type": "string", "description": "File content (if requested)" }, "isDirectory": { "type": "boolean", "description": "Whether this is a directory" }, "size": { "type": "integer", "description": "File size in bytes" }, "isPublished": { "type": "boolean", "description": "Whether file is publicly published" }, "publicSlug": { "type": "string", "description": "Public URL slug (if published)" }, "publicUrl": { "type": "string", "description": "Full public URL (if published)" }, "created": { "type": "number", "description": "Creation timestamp" }, "updated": { "type": "number", "description": "Last update timestamp" } }, "description": "Project file object" } } } } }, "summary": "Get a file by ID.", "description": "Returns file details including content." }, "put": { "tags": [ "Projects" ], "operationId": "projects_updateProjectFile", "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Project or file not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Updated file", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "File ID" }, "name": { "type": "string", "description": "File name" }, "path": { "type": "string", "description": "File path" }, "type": { "type": "string", "description": "File type/extension" }, "mimeType": { "type": "string", "description": "MIME type" }, "content": { "type": "string", "description": "File content (if requested)" }, "isDirectory": { "type": "boolean", "description": "Whether this is a directory" }, "size": { "type": "integer", "description": "File size in bytes" }, "isPublished": { "type": "boolean", "description": "Whether file is publicly published" }, "publicSlug": { "type": "string", "description": "Public URL slug (if published)" }, "publicUrl": { "type": "string", "description": "Full public URL (if published)" }, "created": { "type": "number", "description": "Creation timestamp" }, "updated": { "type": "number", "description": "Last update timestamp" } }, "description": "Project file object" } } } } }, "summary": "Update file content.", "description": "Replaces the content of an existing file.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "originalContent": { "type": "string", "description": "Content originally loaded by the editor; rejects stale saves with HTTP 409" }, "content": { "type": "string", "description": "New file content" } }, "required": [ "companyId", "content" ], "description": "Request body for updating a project file" } } }, "description": "File update parameters" } }, "delete": { "tags": [ "Projects" ], "operationId": "projects_deleteProjectFile", "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID" }, "description": "Company ID" } ], "responses": { "400": { "description": "Missing companyId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Project or file not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Deletion confirmation", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Success indicator" } }, "description": "Success response" } } } } }, "summary": "Delete a file.", "description": "Permanently removes a file from the project." } }, "/api/v0/projects/{project_id}/files/mv": { "post": { "tags": [ "Projects" ], "operationId": "projects_moveProjectFile", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Project not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Moved file", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "File ID" }, "name": { "type": "string", "description": "File name" }, "path": { "type": "string", "description": "File path" }, "type": { "type": "string", "description": "File type/extension" }, "mimeType": { "type": "string", "description": "MIME type" }, "content": { "type": "string", "description": "File content (if requested)" }, "isDirectory": { "type": "boolean", "description": "Whether this is a directory" }, "size": { "type": "integer", "description": "File size in bytes" }, "isPublished": { "type": "boolean", "description": "Whether file is publicly published" }, "publicSlug": { "type": "string", "description": "Public URL slug (if published)" }, "publicUrl": { "type": "string", "description": "Full public URL (if published)" }, "created": { "type": "number", "description": "Creation timestamp" }, "updated": { "type": "number", "description": "Last update timestamp" } }, "description": "Project file object" } } } } }, "summary": "Move or rename a file.", "description": "Moves a file from source path to destination path.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "source": { "type": "string", "description": "Source file path" }, "destination": { "type": "string", "description": "Destination file path" } }, "required": [ "companyId", "source", "destination" ], "description": "Request body for moving/renaming a project file" } } }, "description": "Move/rename parameters" } } }, "/api/v0/projects/{project_id}/files/cp": { "post": { "tags": [ "Projects" ], "operationId": "projects_copyProjectFile", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Project not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Copied file", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "File ID" }, "name": { "type": "string", "description": "File name" }, "path": { "type": "string", "description": "File path" }, "type": { "type": "string", "description": "File type/extension" }, "mimeType": { "type": "string", "description": "MIME type" }, "content": { "type": "string", "description": "File content (if requested)" }, "isDirectory": { "type": "boolean", "description": "Whether this is a directory" }, "size": { "type": "integer", "description": "File size in bytes" }, "isPublished": { "type": "boolean", "description": "Whether file is publicly published" }, "publicSlug": { "type": "string", "description": "Public URL slug (if published)" }, "publicUrl": { "type": "string", "description": "Full public URL (if published)" }, "created": { "type": "number", "description": "Creation timestamp" }, "updated": { "type": "number", "description": "Last update timestamp" } }, "description": "Project file object" } } } } }, "summary": "Copy a file.", "description": "Creates a copy of a file at the destination path.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "source": { "type": "string", "description": "Source file path" }, "destination": { "type": "string", "description": "Destination file path" } }, "required": [ "companyId", "source", "destination" ], "description": "Request body for copying a project file" } } }, "description": "Copy parameters" } } }, "/api/v0/projects/{project_id}/files/mkdir": { "post": { "tags": [ "Projects" ], "operationId": "projects_createProjectDirectory", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Project not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Created directory", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "File ID" }, "name": { "type": "string", "description": "File name" }, "path": { "type": "string", "description": "File path" }, "type": { "type": "string", "description": "File type/extension" }, "mimeType": { "type": "string", "description": "MIME type" }, "content": { "type": "string", "description": "File content (if requested)" }, "isDirectory": { "type": "boolean", "description": "Whether this is a directory" }, "size": { "type": "integer", "description": "File size in bytes" }, "isPublished": { "type": "boolean", "description": "Whether file is publicly published" }, "publicSlug": { "type": "string", "description": "Public URL slug (if published)" }, "publicUrl": { "type": "string", "description": "Full public URL (if published)" }, "created": { "type": "number", "description": "Creation timestamp" }, "updated": { "type": "number", "description": "Last update timestamp" } }, "description": "Project file object" } } } } }, "summary": "Create a directory.", "description": "Creates a new directory at the specified path.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "path": { "type": "string", "description": "Directory path (e.g., '/src/utils')" } }, "required": [ "companyId", "path" ], "description": "Request body for creating a project directory" } } }, "description": "Directory creation parameters" } } }, "/api/v0/chats/{chat_id}/project": { "get": { "tags": [ "Projects" ], "operationId": "projects_getChatProject", "parameters": [ { "name": "chat_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID" }, "description": "Company ID" } ], "responses": { "400": { "description": "Missing companyId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Attached project or null", "content": { "application/json": { "schema": { "type": "object", "properties": { "project": { "type": "object", "properties": { "id": { "type": "string", "description": "Project ID" }, "name": { "type": "string", "description": "Project name" }, "description": { "type": "string", "description": "Project description" }, "instructions": { "type": "string", "description": "Custom AI instructions" }, "sharing": { "type": "string", "description": "Sharing mode: 'Private' or 'Shared'" }, "settings": { "type": "object", "description": "Additional project settings" }, "uid": { "type": "string", "description": "Owner user ID" }, "companyId": { "type": "string", "description": "Company ID" }, "created": { "type": "number", "description": "Creation timestamp" }, "updated": { "type": "number", "description": "Last update timestamp" } }, "description": "Attached project (null if none)" } }, "description": "Chat project attachment" } } } } }, "summary": "Get the project attached to a chat.", "description": "Returns the attached project or null if none." }, "post": { "tags": [ "Projects" ], "operationId": "projects_attachProjectToChat", "parameters": [ { "name": "chat_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Attachment confirmation", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Success indicator" } }, "description": "Success response" } } } } }, "summary": "Attach a project to a chat.", "description": "Links a workspace project to a chat for file access.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "projectId": { "type": "string", "description": "Project ID to attach" } }, "required": [ "companyId", "projectId" ], "description": "Request body for attaching a project to a chat" } } }, "description": "Project attachment parameters" } }, "delete": { "tags": [ "Projects" ], "operationId": "projects_detachProjectFromChat", "parameters": [ { "name": "chat_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID" }, "description": "Company ID" } ], "responses": { "400": { "description": "Missing companyId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Detachment confirmation", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Success indicator" } }, "description": "Success response" } } } } }, "summary": "Detach a project from a chat.", "description": "Removes the project link from a chat." } }, "/api/v0/projects/{project_id}/files/{file_id}/export": { "post": { "tags": [ "Projects" ], "operationId": "projects_exportProjectFile", "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID" }, "description": "Company ID" }, { "name": "format", "in": "query", "required": true, "schema": { "type": "string", "description": "Export format: original, pdf, docx, csv, pptx" }, "description": "Export format: original, pdf, docx, csv, pptx" } ], "responses": { "400": { "description": "Invalid format or missing parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Project or file not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Download a project file in its original format or a supported document format.", "description": "Returns the file in the requested format as a download.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "description": "Current editor content to download" } }, "required": [ "content" ] } } }, "description": "POST exports current editor content without saving; GET exports the saved file" } }, "get": { "tags": [ "Projects" ], "operationId": "projects_exportProjectFile", "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID" }, "description": "Company ID" }, { "name": "format", "in": "query", "required": true, "schema": { "type": "string", "description": "Export format: original, pdf, docx, csv, pptx" }, "description": "Export format: original, pdf, docx, csv, pptx" } ], "responses": { "400": { "description": "Invalid format or missing parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Project or file not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Download a project file in its original format or a supported document format.", "description": "Returns the file in the requested format as a download.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "description": "Current editor content to download" } }, "required": [ "content" ] } } }, "description": "POST exports current editor content without saving; GET exports the saved file" } } }, "/api/v0/projects/{project_id}/files/{file_id}/publish": { "post": { "tags": [ "Projects" ], "operationId": "projects_publishFile", "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID" }, "description": "Company ID" } ], "responses": { "400": { "description": "Missing companyId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "File not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Published file with public URL", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "File ID" }, "name": { "type": "string", "description": "File name" }, "path": { "type": "string", "description": "File path" }, "type": { "type": "string", "description": "File type/extension" }, "mimeType": { "type": "string", "description": "MIME type" }, "content": { "type": "string", "description": "File content (if requested)" }, "isDirectory": { "type": "boolean", "description": "Whether this is a directory" }, "size": { "type": "integer", "description": "File size in bytes" }, "isPublished": { "type": "boolean", "description": "Whether file is publicly published" }, "publicSlug": { "type": "string", "description": "Public URL slug (if published)" }, "publicUrl": { "type": "string", "description": "Full public URL (if published)" }, "created": { "type": "number", "description": "Creation timestamp" }, "updated": { "type": "number", "description": "Last update timestamp" } }, "description": "Project file object" } } } } }, "summary": "Publish a file to make it publicly accessible.", "description": "Returns the file with publicSlug and publicUrl for sharing." } }, "/api/v0/projects/{project_id}/files/{file_id}/unpublish": { "post": { "tags": [ "Projects" ], "operationId": "projects_unpublishFile", "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID" }, "description": "Company ID" } ], "responses": { "400": { "description": "Missing companyId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "File not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Unpublished file", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "File ID" }, "name": { "type": "string", "description": "File name" }, "path": { "type": "string", "description": "File path" }, "type": { "type": "string", "description": "File type/extension" }, "mimeType": { "type": "string", "description": "MIME type" }, "content": { "type": "string", "description": "File content (if requested)" }, "isDirectory": { "type": "boolean", "description": "Whether this is a directory" }, "size": { "type": "integer", "description": "File size in bytes" }, "isPublished": { "type": "boolean", "description": "Whether file is publicly published" }, "publicSlug": { "type": "string", "description": "Public URL slug (if published)" }, "publicUrl": { "type": "string", "description": "Full public URL (if published)" }, "created": { "type": "number", "description": "Creation timestamp" }, "updated": { "type": "number", "description": "Last update timestamp" } }, "description": "Project file object" } } } } }, "summary": "Unpublish a file to remove public access.", "description": "Removes the public URL and makes the file private again." } }, "/api/v0/companies/{companyId}/memories": { "get": { "tags": [ "Memories" ], "operationId": "memories_getMemoriesList", "parameters": [ { "name": "companyId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Page number (default: 1)" }, "description": "Page number (default: 1)" }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "description": "Items per page (default: 50)" }, "description": "Items per page (default: 50)" }, { "name": "includeInactive", "in": "query", "required": false, "schema": { "type": "string", "description": "Include inactive memories (true/false)" }, "description": "Include inactive memories (true/false)" }, { "name": "category", "in": "query", "required": false, "schema": { "type": "string", "description": "Filter by category" }, "description": "Filter by category" } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "List of memories", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Memory ID" }, "content": { "type": "string", "description": "Memory content text" }, "category": { "type": "string", "description": "Memory category" }, "isActive": { "type": "boolean", "description": "Whether the memory is active" }, "sourceChatId": { "type": "string", "description": "Source chat ID" }, "sourceMessageId": { "type": "string", "description": "Source message ID" }, "metadata": { "type": "object", "description": "Additional metadata" }, "created": { "type": "number", "description": "Creation timestamp" }, "updated": { "type": "number", "description": "Last update timestamp" } }, "description": "Memory object" }, "description": "List of memory objects" }, "total": { "type": "integer", "description": "Total count of memories" }, "page": { "type": "integer", "description": "Current page number" }, "pageSize": { "type": "integer", "description": "Items per page" } }, "description": "List of memories" } } } } }, "summary": "Get paginated list of memories for the current user." }, "post": { "tags": [ "Memories" ], "operationId": "memories_createMemoryRoute", "parameters": [ { "name": "companyId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Created memory", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Memory ID" }, "content": { "type": "string", "description": "Memory content text" }, "category": { "type": "string", "description": "Memory category" }, "isActive": { "type": "boolean", "description": "Whether the memory is active" }, "sourceChatId": { "type": "string", "description": "Source chat ID" }, "sourceMessageId": { "type": "string", "description": "Source message ID" }, "metadata": { "type": "object", "description": "Additional metadata" }, "created": { "type": "number", "description": "Creation timestamp" }, "updated": { "type": "number", "description": "Last update timestamp" } }, "description": "Memory object" } } } } }, "summary": "Create a new memory.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "description": "Memory content text" }, "category": { "type": "string", "description": "Memory category" }, "sourceChatId": { "type": "string", "description": "Source chat ID if memory originated from a chat" }, "sourceMessageId": { "type": "string", "description": "Source message ID if memory originated from a message" }, "metadata": { "type": "object", "description": "Additional metadata for the memory" } }, "required": [ "content" ], "description": "Request body for creating a memory" } } }, "description": "Memory data" } } }, "/api/v0/companies/{companyId}/memories/{memoryId}": { "get": { "tags": [ "Memories" ], "operationId": "memories_getMemory", "parameters": [ { "name": "companyId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "memoryId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Memory not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Memory details", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Memory ID" }, "content": { "type": "string", "description": "Memory content text" }, "category": { "type": "string", "description": "Memory category" }, "isActive": { "type": "boolean", "description": "Whether the memory is active" }, "sourceChatId": { "type": "string", "description": "Source chat ID" }, "sourceMessageId": { "type": "string", "description": "Source message ID" }, "metadata": { "type": "object", "description": "Additional metadata" }, "created": { "type": "number", "description": "Creation timestamp" }, "updated": { "type": "number", "description": "Last update timestamp" } }, "description": "Memory object" } } } } }, "summary": "Get a specific memory by ID." }, "put": { "tags": [ "Memories" ], "operationId": "memories_updateMemoryRoute", "parameters": [ { "name": "companyId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "memoryId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Memory not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Updated memory", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Memory ID" }, "content": { "type": "string", "description": "Memory content text" }, "category": { "type": "string", "description": "Memory category" }, "isActive": { "type": "boolean", "description": "Whether the memory is active" }, "sourceChatId": { "type": "string", "description": "Source chat ID" }, "sourceMessageId": { "type": "string", "description": "Source message ID" }, "metadata": { "type": "object", "description": "Additional metadata" }, "created": { "type": "number", "description": "Creation timestamp" }, "updated": { "type": "number", "description": "Last update timestamp" } }, "description": "Memory object" } } } } }, "summary": "Update an existing memory.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "description": "Memory content text" }, "category": { "type": "string", "description": "Memory category" }, "isActive": { "type": "boolean", "description": "Whether the memory is active" }, "companyId": { "type": "string", "description": "Company ID (set to null to make global, or company ID to make company-specific)" } }, "description": "Request body for updating a memory" } } }, "description": "Memory update data" } }, "delete": { "tags": [ "Memories" ], "operationId": "memories_deleteMemoryRoute", "parameters": [ { "name": "companyId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "memoryId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Memory not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Delete a memory (soft delete)." } }, "/api/v0/companies/{companyId}/memories/{memoryId}/toggle": { "patch": { "tags": [ "Memories" ], "operationId": "memories_toggleMemoryActiveRoute", "parameters": [ { "name": "companyId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "memoryId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Memory not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Updated memory with toggled active status", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Memory ID" }, "content": { "type": "string", "description": "Memory content text" }, "category": { "type": "string", "description": "Memory category" }, "isActive": { "type": "boolean", "description": "Whether the memory is active" }, "sourceChatId": { "type": "string", "description": "Source chat ID" }, "sourceMessageId": { "type": "string", "description": "Source message ID" }, "metadata": { "type": "object", "description": "Additional metadata" }, "created": { "type": "number", "description": "Creation timestamp" }, "updated": { "type": "number", "description": "Last update timestamp" } }, "description": "Memory object" } } } } }, "summary": "Toggle a memory's active status." } }, "/api/v0/companies": { "get": { "tags": [ "Companies" ], "operationId": "companies_getCompanies", "parameters": [], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "List of companies", "content": { "application/json": { "schema": { "type": "object", "properties": { "companies": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Company ID" }, "name": { "type": "string", "description": "Company name" }, "description": { "type": "string", "description": "Company description" }, "website": { "type": "string", "description": "Company website" }, "industry": { "type": "string", "description": "Industry type" }, "size": { "type": "string", "description": "Company size" }, "location": { "type": "string", "description": "Company location" }, "logoUrl": { "type": "string", "description": "Company logo URL" }, "uid": { "type": "string", "description": "Owner user ID" }, "organizationId": { "type": "string", "description": "Organization funding this company" }, "organizationName": { "type": "string", "description": "Name of the organization funding this company" }, "subscriptionType": { "type": "string", "description": "Subscription type" }, "created_date": { "type": "string", "format": "date-time", "description": "Creation date" } }, "description": "Company object" }, "description": "List of companies" } }, "description": "List of companies" } } } } }, "summary": "Get all companies accessible by the authenticated user." }, "post": { "tags": [ "Companies" ], "operationId": "companies_saveCompany", "parameters": [], "responses": { "400": { "description": "Company name is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Company limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Company saved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "description": "Success message" } }, "description": "Success response" } } } } }, "summary": "Create or update a company.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Company ID (omit for new company)" }, "organizationId": { "type": "string", "description": "Organization to create the company in; it is billed to that organization and counts against its company limit. You must be a member. Ignored on update \u2014 omit to use your account organization." }, "name": { "type": "string", "description": "Company name" }, "description": { "type": "string", "description": "Company description" }, "website": { "type": "string", "description": "Company website URL" }, "industry": { "type": "string", "description": "Industry type" }, "size": { "type": "string", "description": "Company size" }, "location": { "type": "string", "description": "Company location" }, "logoUrl": { "type": "string", "description": "Company logo URL. Use the Images API to generate a logo and get a URL." }, "apps": { "type": "array", "items": { "type": "object" }, "description": "Company-configured custom apps shown in the side menu. Each entry: {id, name, icon, enabled, openInNewTab?, url?, appId?}. `url` embeds an external site (iframe, or new tab when openInNewTab); `appId` references a Public builder app shared into the company." } }, "required": [ "name" ], "description": "Request body for creating or updating a company" } } }, "description": "Company data" } } }, "/api/v0/companies/{companyId}": { "get": { "tags": [ "Companies" ], "operationId": "companies_getCompany", "parameters": [ { "name": "companyId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Company access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Company not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Company details", "content": { "application/json": { "schema": { "type": "object", "properties": { "company": { "type": "object", "properties": { "id": { "type": "string", "description": "Company ID" }, "name": { "type": "string", "description": "Company name" }, "description": { "type": "string", "description": "Company description" }, "website": { "type": "string", "description": "Company website" }, "industry": { "type": "string", "description": "Industry type" }, "size": { "type": "string", "description": "Company size" }, "location": { "type": "string", "description": "Company location" }, "logoUrl": { "type": "string", "description": "Company logo URL" }, "uid": { "type": "string", "description": "Owner user ID" }, "organizationId": { "type": "string", "description": "Organization funding this company" }, "organizationName": { "type": "string", "description": "Name of the organization funding this company" }, "subscriptionType": { "type": "string", "description": "Subscription type" }, "created_date": { "type": "string", "format": "date-time", "description": "Creation date" } }, "description": "Company object" } }, "description": "Single company response" } } } } }, "summary": "Get a specific company by ID." }, "delete": { "tags": [ "Companies" ], "operationId": "companies_deleteCompany", "parameters": [ { "name": "companyId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Company not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Company deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "description": "Success message" } }, "description": "Success response" } } } } }, "summary": "Delete a company." } }, "/api/v0/companies/{companyId}/tags": { "get": { "tags": [ "Companies" ], "operationId": "companies_getCompanyTags", "parameters": [ { "name": "companyId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "List of company tags", "content": { "application/json": { "schema": { "type": "object", "properties": { "tags": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Tag name" }, "description": { "type": "string", "description": "Tag description" }, "source": { "type": "string", "description": "Tag source: table, employee, document, both" } }, "description": "Tag object" }, "description": "List of tags" } }, "description": "List of tags" } } } } }, "summary": "Get all tags for a company." } }, "/api/v0/companies/{companyId}/leave": { "post": { "tags": [ "Companies" ], "operationId": "companies_leaveCompany", "parameters": [ { "name": "companyId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Cannot leave company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Company not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Left company successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "description": "Success message" } }, "description": "Success response" } } } } }, "summary": "Remove the current user from a company. Billing owner cannot leave." } }, "/api/v0/companies/{companyId}/transfer-ownership": { "put": { "tags": [ "Companies" ], "operationId": "companies_transferOwnership", "parameters": [ { "name": "companyId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Ownership transferred successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "description": "Success message" } }, "description": "Success response" } } } } }, "summary": "Transfer company ownership to another company owner.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "newOwnerId": { "type": "string", "description": "UID of the new owner" } }, "required": [ "newOwnerId" ], "description": "Request body for transferring company ownership" } } }, "description": "Transfer ownership request" } } }, "/api/v0/companies/{companyId}/features": { "put": { "tags": [ "Companies" ], "operationId": "companies_updateCompanyFeatures", "parameters": [ { "name": "companyId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Features updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "description": "Success message" } }, "description": "Success response" } } } } }, "summary": "Update allowed features for a company (owner only).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "allowedFeatures": { "type": "array", "items": { "type": "string" }, "description": "List of allowed feature names" } }, "description": "Request body for updating company allowed features" } } }, "description": "Allowed features list" } } }, "/api/v0/companies/order": { "post": { "tags": [ "Companies" ], "operationId": "companies_updateCompaniesOrder", "parameters": [], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Order updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "description": "Success message" } }, "description": "Success response" } } } } }, "summary": "Update the display order of companies.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companies": { "type": "array", "items": { "type": "object" }, "description": "Array of {id: string, order: integer} objects to update display order" } }, "description": "Request body for updating company display order" } } }, "description": "Company order list" } } }, "/api/v0/company_users": { "post": { "tags": [ "Company Users" ], "operationId": "company_users_addCompanyUser", "parameters": [], "responses": { "400": { "description": "Invalid email", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not authorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "User limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "User added successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "description": "Success message" } }, "description": "Success response" } } } } }, "summary": "Add a user/collaborator to a company.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "Email address of the user to add" }, "role": { "type": "string", "description": "Role: owner, admin, or member", "default": "member" }, "companyId": { "type": "string", "description": "Company ID to add the user to" }, "allowedFeatures": { "type": "array", "items": { "type": "string" }, "description": "List of features the user is allowed to access" } }, "required": [ "email", "companyId" ], "description": "Request body for adding a company user" } } }, "description": "Add company user request" } } }, "/api/v0/company_users/{companyId}": { "get": { "tags": [ "Company Users" ], "operationId": "company_users_getCompanyUsers", "parameters": [ { "name": "companyId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Page number (default: 1)", "default": 1 }, "description": "Page number (default: 1)" }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Items per page (default: 10, max: 50)", "default": 10 }, "description": "Items per page (default: 10, max: 50)" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "description": "Search by name or email" }, "description": "Search by name or email" } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not authorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "List of company users", "content": { "application/json": { "schema": { "type": "object", "properties": { "company_users": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Company user ID" }, "companyId": { "type": "string", "description": "Company ID" }, "uid": { "type": "string", "description": "User ID (null if not yet signed up)" }, "email": { "type": "string", "description": "User email" }, "role": { "type": "string", "description": "Role: owner, admin, or member" }, "displayName": { "type": "string", "description": "User display name" }, "photo": { "type": "string", "description": "User photo URL" }, "allowedFeatures": { "type": "array", "items": { "type": "string" }, "description": "Allowed features" }, "createdDate": { "type": "string", "description": "Created date ISO string" } }, "description": "Company user object" }, "description": "List of company users" }, "pagination": { "type": "object", "properties": { "page": { "type": "integer", "description": "Current page" }, "per_page": { "type": "integer", "description": "Items per page" }, "total": { "type": "integer", "description": "Total number of items" }, "pages": { "type": "integer", "description": "Total number of pages" }, "has_next": { "type": "boolean", "description": "Has next page" }, "has_prev": { "type": "boolean", "description": "Has previous page" } }, "description": "Pagination info" } }, "description": "Paginated list of company users" } } } } }, "summary": "Get all users/collaborators for a company with pagination." } }, "/api/v0/company_users/{memberId}": { "delete": { "tags": [ "Company Users" ], "operationId": "company_users_removeMember", "parameters": [ { "name": "memberId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not authorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Member not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "User removed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "description": "Success message" } }, "description": "Success response" } } } } }, "summary": "Remove a user/collaborator from a company." }, "put": { "tags": [ "Company Users" ], "operationId": "company_users_updateCompanyUser", "parameters": [ { "name": "memberId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not authorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Member not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Role updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "description": "Success message" } }, "description": "Success response" } } } } }, "summary": "Update a company user's role.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "string", "description": "New role: owner, admin, or member" } }, "required": [ "role" ], "description": "Request body for updating a company user role" } } }, "description": "Update role request" } } }, "/api/v0/company_users/{memberId}/features": { "put": { "tags": [ "Company Users" ], "operationId": "company_users_updateCompanyUserFeatures", "parameters": [ { "name": "memberId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid features", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not authorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Member not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Features updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "description": "Success message" } }, "description": "Success response" } } } } }, "summary": "Update the allowed features for a company user.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "allowedFeatures": { "type": "array", "items": { "type": "string" }, "description": "List of features the user is allowed to access" } }, "required": [ "allowedFeatures" ], "description": "Request body for updating a company user allowed features" } } }, "description": "Update allowed features request" } } }, "/api/v0/company_users/{companyId}/my-role": { "get": { "tags": [ "Company Users" ], "operationId": "company_users_getMyRole", "parameters": [ { "name": "companyId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "User not found in company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Current user role in company", "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "string", "description": "Role: owner, admin, or member" }, "email": { "type": "string", "description": "User email" }, "uid": { "type": "string", "description": "User ID" }, "companyId": { "type": "string", "description": "Company ID" } }, "description": "Current user role in company" } } } } }, "summary": "Get the current user's role in a specific company." } }, "/api/v0/company_users/{memberId}/subscription-type": { "get": { "tags": [ "Company Users" ], "operationId": "company_users_getMemberSubscriptionType", "parameters": [ { "name": "memberId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Member not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Member subscription type", "content": { "application/json": { "schema": { "type": "object", "properties": { "subscriptionType": { "type": "string", "description": "Subscription type" }, "memberId": { "type": "string", "description": "Member ID" } }, "description": "Member subscription type" } } } } }, "summary": "Get the subscription type of a company member by their ID." } }, "/api/v0/company_users/{memberId}/resend-invite": { "post": { "tags": [ "Company Users" ], "operationId": "company_users_resendInvite", "parameters": [ { "name": "memberId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "User already signed up", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not authorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Member not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Invitation sent successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "description": "Success message" } }, "description": "Success response" } } } } }, "summary": "Resend an invitation email to a collaborator who hasn't logged in yet." } }, "/api/v0/usage": { "get": { "tags": [ "Usage" ], "operationId": "usage_getUsage", "parameters": [ { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string", "description": "Company ID to get usage for" }, "description": "Company ID to get usage for" }, { "name": "organizationId", "in": "query", "required": false, "schema": { "type": "string", "description": "Report this organization's plan, limits and balances instead of the caller's own funding. The caller must belong to the organization." }, "description": "Report this organization's plan, limits and balances instead of the caller's own funding. The caller must belong to the organization." }, { "name": "whitelabelId", "in": "query", "required": false, "schema": { "type": "string", "description": "Whitelabel instance ID" }, "description": "Whitelabel instance ID" } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No access to the named organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Organization not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Usage information with features and quotas", "content": { "application/json": { "schema": { "type": "object", "properties": { "usage": { "type": "object", "properties": { "id": { "type": "string", "description": "User ID" }, "email": { "type": "string", "description": "User email" }, "creditLimit": { "type": "integer", "description": "Credit limit" }, "creditUsage": { "type": "number", "description": "Credits used" }, "topupCredits": { "type": "number", "description": "Never-expiring platform credit balance" }, "dataCreditLimit": { "type": "integer", "description": "Total monthly data credit limit" }, "dataCreditUsage": { "type": "number", "description": "Data credits used this month" }, "dataCredits": { "type": "number", "description": "Total spendable data credits" }, "seats": { "type": "integer", "description": "Number of seats" }, "seatsUsed": { "type": "integer", "description": "Seats used" }, "companyLimit": { "type": "integer", "description": "Company limit" }, "companiesUsed": { "type": "integer", "description": "Companies used" }, "domainLimit": { "type": "integer", "description": "Max custom tracking domains" }, "linkedinAccountLimit": { "type": "integer", "description": "Max connected LinkedIn accounts" }, "staticIpLimit": { "type": "integer", "description": "Max dedicated static IPs for browser automation" }, "freeModelsOnly": { "type": "boolean", "description": "Whether paid models are downgraded to the free fallback" }, "windowCredits": { "type": "number", "description": "Included credits per rolling window; null when the monthly allowance applies" }, "windowHours": { "type": "integer", "description": "Length of the rolling credit window in hours" }, "windowCreditUsage": { "type": "number", "description": "Included credits spent inside the current rolling window" }, "dataWindowCredits": { "type": "number", "description": "Included data credits per independent rolling window" }, "dataWindowHours": { "type": "integer", "description": "Length of the data-credit window in hours" }, "dataWindowCreditUsage": { "type": "number", "description": "Included data credits used inside the rolling window" }, "dataWindowResetsInSeconds": { "type": "integer", "description": "Seconds until the oldest data-window usage ages out" }, "dataTopupCredits": { "type": "number", "description": "Never-expiring data top-up balance" }, "subscriptionType": { "type": "string", "description": "Subscription tier" }, "subscriptionTierName": { "type": "string", "description": "Friendly tier name for custom tiers" }, "superUser": { "type": "boolean", "description": "Whether user is a super user" }, "isOrgManaged": { "type": "boolean", "description": "Whether user is managed by an organization" }, "organizationId": { "type": "string", "description": "Organization ID if org-managed" }, "organizationName": { "type": "string", "description": "Organization name if org-managed" } }, "description": "Usage details" }, "features": { "type": "object", "description": "Feature access flags" }, "hasWhitelabelAccess": { "type": "boolean", "description": "Whether user has whitelabel access" }, "companyQuota": { "type": "object", "properties": { "quotaEnabled": { "type": "boolean", "description": "Whether quota is enabled" }, "creditLimit": { "type": "integer", "description": "Credit limit for company" }, "creditUsage": { "type": "number", "description": "Credits used by company" }, "availableCredits": { "type": "integer", "description": "Available credits" } }, "description": "Company quota info" }, "companyRole": { "type": "string", "description": "User role in company" }, "companyProvisioning": { "type": "object", "properties": { "provisioned": { "type": "boolean", "description": "Whether company is provisioned" }, "organizationId": { "type": "string", "description": "Organization ID" }, "organizationName": { "type": "string", "description": "Organization name" }, "seats": { "type": "integer", "description": "Number of seats" }, "status": { "type": "string", "description": "Organization status" } }, "description": "Company provisioning info" } }, "description": "Usage response with features and quotas" } } } } }, "summary": "Get usage information including credits, features, and quotas." } }, "/api/v0/usage/histogram/last_30_days": { "get": { "tags": [ "Usage" ], "operationId": "usage_getUsageHistogramLast30Days", "parameters": [ { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string", "description": "Company ID" }, "description": "Company ID" } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Usage histogram for last 30 days", "content": { "application/json": { "schema": { "type": "object", "properties": { "histogram": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "description": "Date string" }, "usage": { "type": "number", "description": "Usage value for this date" } }, "description": "Usage histogram data point" }, "description": "Histogram data points" } }, "description": "Usage histogram for last 30 days" } } } } }, "summary": "Get daily usage histogram for the last 30 days." } }, "/api/v0/usage/features/last_30_days": { "get": { "tags": [ "Usage" ], "operationId": "usage_getUsageByFeaturesLast30Days", "parameters": [ { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string", "description": "Company ID" }, "description": "Company ID" } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Usage breakdown by features for last 30 days", "content": { "application/json": { "schema": { "type": "object", "properties": { "features": { "type": "array", "items": { "type": "object", "properties": { "feature": { "type": "string", "description": "Feature name" }, "usage": { "type": "number", "description": "Usage for this feature" } }, "description": "Usage by feature" }, "description": "Feature usage breakdown" } }, "description": "Usage breakdown by features" } } } } }, "summary": "Get usage breakdown by feature for the last 30 days." } }, "/api/v0/usage/leaderboard": { "get": { "tags": [ "Usage" ], "operationId": "usage_getUsageLeaderboard", "parameters": [ { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID" }, "description": "Company ID" } ], "responses": { "400": { "description": "Company ID required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Top 10 users by credit usage", "content": { "application/json": { "schema": { "type": "object", "properties": { "leaderboard": { "type": "array", "items": { "type": "object", "properties": { "rank": { "type": "integer", "description": "Rank position" }, "uid": { "type": "string", "description": "User ID" }, "email": { "type": "string", "description": "User email" }, "creditUsage": { "type": "number", "description": "Credits used" } }, "description": "Leaderboard entry" }, "description": "Leaderboard entries" } }, "description": "Top 10 users by credit usage" } } } } }, "summary": "Get top 10 users by credit usage in a company." } }, "/api/v0/usage/hours-saved": { "get": { "tags": [ "Usage" ], "operationId": "usage_getHoursSaved", "parameters": [ { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID" }, "description": "Company ID" } ], "responses": { "400": { "description": "Company ID required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Estimated hours saved by automation", "content": { "application/json": { "schema": { "type": "object", "properties": { "totalHours": { "type": "number", "description": "Total hours saved" }, "totalMinutes": { "type": "number", "description": "Total minutes saved" }, "valueSaved": { "type": "number", "description": "Estimated value saved in dollars" }, "breakdown": { "type": "array", "items": { "type": "object", "properties": { "actionType": { "type": "string", "description": "Action type" }, "count": { "type": "integer", "description": "Number of actions" }, "minutesSaved": { "type": "number", "description": "Minutes saved" } }, "description": "Hours saved breakdown" }, "description": "Breakdown by action type" } }, "description": "Estimated hours saved by automation" } } } } }, "summary": "Get estimated hours saved by automation for a company.", "description": "Calculates time saved based on automated actions performed in the last 30 days,\nusing industry-standard time estimates for each action type." } }, "/api/v0/usage/history": { "get": { "tags": [ "Usage" ], "operationId": "usage_getUserUsageHistory", "parameters": [ { "name": "startDate", "in": "query", "required": false, "schema": { "type": "string", "description": "ISO 8601 start datetime (inclusive)" }, "description": "ISO 8601 start datetime (inclusive)" }, { "name": "endDate", "in": "query", "required": false, "schema": { "type": "string", "description": "ISO 8601 end datetime (inclusive)" }, "description": "ISO 8601 end datetime (inclusive)" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "description": "Page size, default 100, max 1000" }, "description": "Page size, default 100, max 1000" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "description": "Pagination offset, default 0" }, "description": "Pagination offset, default 0" }, { "name": "userUid", "in": "query", "required": false, "schema": { "type": "string", "description": "Only rows for this user (organization history only)" }, "description": "Only rows for this user (organization history only)" }, { "name": "feature", "in": "query", "required": false, "schema": { "type": "string", "description": "Only rows for this feature key (organization history only)" }, "description": "Only rows for this feature key (organization history only)" } ], "responses": { "400": { "description": "Invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Paginated usage history for the authenticated user", "content": { "application/json": { "schema": { "type": "object", "properties": { "rows": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Usage record ID" }, "created": { "type": "string", "description": "ISO 8601 timestamp" }, "companyId": { "type": "string", "description": "Company the usage occurred in" }, "userUid": { "type": "string", "description": "User who incurred the usage" }, "model": { "type": "string", "description": "Model name" }, "feature": { "type": "string", "description": "Feature key" }, "credits": { "type": "number", "description": "Credits consumed" }, "tokens": { "type": "number", "description": "Total tokens" }, "inputTokens": { "type": "number", "description": "Input tokens" }, "outputTokens": { "type": "number", "description": "Output tokens" }, "userDisplayName": { "type": "string", "description": "Display name of the user (organization history only)" }, "userEmail": { "type": "string", "description": "Email of the user (organization history only)" }, "userPhoto": { "type": "string", "description": "Photo URL of the user (organization history only)" }, "companyName": { "type": "string", "description": "Name of the company (organization history only)" }, "companyLogoUrl": { "type": "string", "description": "Logo URL of the company (organization history only)" } }, "description": "Usage history entry" }, "description": "Usage rows" }, "total": { "type": "integer", "description": "Total rows matching filter" }, "limit": { "type": "integer", "description": "Page size used" }, "offset": { "type": "integer", "description": "Pagination offset used" } }, "description": "Paginated user usage history" } } } } }, "summary": "Get paginated usage history rows for the authenticated user.", "description": "Filtered to the user's own usage. When authenticated via a company API key,\nresults are additionally restricted to that company." } }, "/api/v0/usage/history/summary": { "get": { "tags": [ "Usage" ], "operationId": "usage_getUserUsageHistorySummary", "parameters": [ { "name": "startDate", "in": "query", "required": false, "schema": { "type": "string", "description": "ISO 8601 start datetime (inclusive)" }, "description": "ISO 8601 start datetime (inclusive)" }, { "name": "endDate", "in": "query", "required": false, "schema": { "type": "string", "description": "ISO 8601 end datetime (inclusive)" }, "description": "ISO 8601 end datetime (inclusive)" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "description": "Page size, default 100, max 1000" }, "description": "Page size, default 100, max 1000" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "description": "Pagination offset, default 0" }, "description": "Pagination offset, default 0" }, { "name": "userUid", "in": "query", "required": false, "schema": { "type": "string", "description": "Only rows for this user (organization history only)" }, "description": "Only rows for this user (organization history only)" }, { "name": "feature", "in": "query", "required": false, "schema": { "type": "string", "description": "Only rows for this feature key (organization history only)" }, "description": "Only rows for this feature key (organization history only)" } ], "responses": { "400": { "description": "Invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Aggregate usage totals for the authenticated user", "content": { "application/json": { "schema": { "type": "object", "properties": { "totals": { "type": "object", "properties": { "credits": { "type": "number" }, "tokens": { "type": "number" }, "inputTokens": { "type": "number" }, "outputTokens": { "type": "number" }, "requests": { "type": "integer" } } }, "byModel": { "type": "array", "items": { "type": "object", "properties": { "model": { "type": "string" }, "feature": { "type": "string" }, "credits": { "type": "number" }, "tokens": { "type": "number" }, "requests": { "type": "integer" } } } }, "byFeature": { "type": "array", "items": { "type": "object", "properties": { "model": { "type": "string" }, "feature": { "type": "string" }, "credits": { "type": "number" }, "tokens": { "type": "number" }, "requests": { "type": "integer" } } } } }, "description": "Aggregate usage totals for a user" } } } } }, "summary": "Get aggregate usage totals for the authenticated user.", "description": "Returns total credits/tokens/requests plus breakdowns by model and feature.\nFiltered to the user; company API keys add a company filter." } }, "/api/v0/organizations/{orgId}/usage/history": { "get": { "tags": [ "Usage" ], "operationId": "usage_getOrgUsageHistory", "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "startDate", "in": "query", "required": false, "schema": { "type": "string", "description": "ISO 8601 start datetime (inclusive)" }, "description": "ISO 8601 start datetime (inclusive)" }, { "name": "endDate", "in": "query", "required": false, "schema": { "type": "string", "description": "ISO 8601 end datetime (inclusive)" }, "description": "ISO 8601 end datetime (inclusive)" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "description": "Page size, default 100, max 1000" }, "description": "Page size, default 100, max 1000" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "description": "Pagination offset, default 0" }, "description": "Pagination offset, default 0" }, { "name": "userUid", "in": "query", "required": false, "schema": { "type": "string", "description": "Only rows for this user (organization history only)" }, "description": "Only rows for this user (organization history only)" }, { "name": "feature", "in": "query", "required": false, "schema": { "type": "string", "description": "Only rows for this feature key (organization history only)" }, "description": "Only rows for this feature key (organization history only)" }, { "name": "creditType", "in": "query", "required": false, "schema": { "type": "string", "description": "Filter to ai or data credits; omitted includes both" }, "description": "Filter to ai or data credits; omitted includes both" } ], "responses": { "400": { "description": "Invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Organization not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Paginated usage history for an organization", "content": { "application/json": { "schema": { "type": "object", "properties": { "rows": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Usage record ID" }, "created": { "type": "string", "description": "ISO 8601 timestamp" }, "companyId": { "type": "string", "description": "Company the usage occurred in" }, "userUid": { "type": "string", "description": "User who incurred the usage" }, "model": { "type": "string", "description": "Model name" }, "feature": { "type": "string", "description": "Feature key" }, "credits": { "type": "number", "description": "Credits consumed" }, "tokens": { "type": "number", "description": "Total tokens" }, "inputTokens": { "type": "number", "description": "Input tokens" }, "outputTokens": { "type": "number", "description": "Output tokens" }, "userDisplayName": { "type": "string", "description": "Display name of the user (organization history only)" }, "userEmail": { "type": "string", "description": "Email of the user (organization history only)" }, "userPhoto": { "type": "string", "description": "Photo URL of the user (organization history only)" }, "companyName": { "type": "string", "description": "Name of the company (organization history only)" }, "companyLogoUrl": { "type": "string", "description": "Logo URL of the company (organization history only)" } }, "description": "Usage history entry" }, "description": "Usage rows" }, "total": { "type": "integer", "description": "Total rows matching filter" }, "limit": { "type": "integer", "description": "Page size used" }, "offset": { "type": "integer", "description": "Pagination offset used" } }, "description": "Paginated user usage history" } } } } }, "summary": "Get paginated usage history rows across all companies in an organization.", "description": "Caller must be an organization owner or admin. Optional `userUid` and\n`feature` query parameters narrow results within the org." } }, "/api/v0/organizations/{orgId}/usage/history/summary": { "get": { "tags": [ "Usage" ], "operationId": "usage_getOrgUsageHistorySummary", "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "startDate", "in": "query", "required": false, "schema": { "type": "string", "description": "ISO 8601 start datetime (inclusive)" }, "description": "ISO 8601 start datetime (inclusive)" }, { "name": "endDate", "in": "query", "required": false, "schema": { "type": "string", "description": "ISO 8601 end datetime (inclusive)" }, "description": "ISO 8601 end datetime (inclusive)" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "description": "Page size, default 100, max 1000" }, "description": "Page size, default 100, max 1000" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "description": "Pagination offset, default 0" }, "description": "Pagination offset, default 0" }, { "name": "userUid", "in": "query", "required": false, "schema": { "type": "string", "description": "Only rows for this user (organization history only)" }, "description": "Only rows for this user (organization history only)" }, { "name": "feature", "in": "query", "required": false, "schema": { "type": "string", "description": "Only rows for this feature key (organization history only)" }, "description": "Only rows for this feature key (organization history only)" }, { "name": "creditType", "in": "query", "required": false, "schema": { "type": "string", "description": "Filter to ai or data credits; omitted includes both" }, "description": "Filter to ai or data credits; omitted includes both" } ], "responses": { "400": { "description": "Invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Organization not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Aggregate usage totals for an organization", "content": { "application/json": { "schema": { "type": "object", "properties": { "totals": { "type": "object", "properties": { "credits": { "type": "number" }, "tokens": { "type": "number" }, "inputTokens": { "type": "number" }, "outputTokens": { "type": "number" }, "requests": { "type": "integer" } } }, "byModel": { "type": "array", "items": { "type": "object", "properties": { "model": { "type": "string" }, "feature": { "type": "string" }, "credits": { "type": "number" }, "tokens": { "type": "number" }, "requests": { "type": "integer" } } } }, "byFeature": { "type": "array", "items": { "type": "object", "properties": { "model": { "type": "string" }, "feature": { "type": "string" }, "credits": { "type": "number" }, "tokens": { "type": "number" }, "requests": { "type": "integer" } } } } }, "description": "Aggregate usage totals for a user" } } } } }, "summary": "Get aggregate usage totals across all companies in an organization." } }, "/api/v0/organizations/{orgId}/usage/activity": { "get": { "tags": [ "Usage" ], "operationId": "usage_getOrgUsageActivity", "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "startDate", "in": "query", "required": false, "schema": { "type": "string", "description": "ISO 8601 start datetime (inclusive)" }, "description": "ISO 8601 start datetime (inclusive)" }, { "name": "endDate", "in": "query", "required": false, "schema": { "type": "string", "description": "ISO 8601 end datetime (inclusive)" }, "description": "ISO 8601 end datetime (inclusive)" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "description": "Page size, default 100, max 1000" }, "description": "Page size, default 100, max 1000" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "description": "Pagination offset, default 0" }, "description": "Pagination offset, default 0" }, { "name": "userUid", "in": "query", "required": false, "schema": { "type": "string", "description": "Only rows for this user (organization history only)" }, "description": "Only rows for this user (organization history only)" }, { "name": "feature", "in": "query", "required": false, "schema": { "type": "string", "description": "Only rows for this feature key (organization history only)" }, "description": "Only rows for this feature key (organization history only)" }, { "name": "creditType", "in": "query", "required": false, "schema": { "type": "string", "description": "Filter to ai or data credits; omitted includes both" }, "description": "Filter to ai or data credits; omitted includes both" } ], "responses": { "400": { "description": "Invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Organization not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Usage activity bucketed over the requested range", "content": { "application/json": { "schema": { "type": "object", "properties": { "buckets": { "type": "array", "items": { "type": "object", "properties": { "bucket": { "type": "string", "description": "ISO timestamp of the bucket start" }, "credits": { "type": "number", "description": "Credits used in this bucket" }, "requests": { "type": "integer", "description": "Billable requests in this bucket" } }, "description": "Usage activity bucket" }, "description": "Buckets, oldest first" }, "unit": { "type": "string", "description": "Bucket width: minute, hour, day, week or month" }, "startDate": { "type": "string", "description": "ISO start of the charted range" }, "endDate": { "type": "string", "description": "ISO end of the charted range" } }, "description": "Usage activity bucketed over the requested range" } } } } }, "summary": "Get organization usage bucketed over a time range, for the chart above the log.", "description": "Takes the same `startDate`, `endDate`, `userUid` and `feature` filters as\nthe usage history endpoint, so the chart always describes the same rows the\nlog is showing. The bucket width adapts to the range." } }, "/api/v0/organizations/{orgId}/usage/histogram": { "get": { "tags": [ "Usage" ], "operationId": "usage_getOrgUsageHistogram", "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "creditType", "in": "query", "required": false, "schema": { "type": "string", "description": "Filter to ai or data credits; omitted includes both" }, "description": "Filter to ai or data credits; omitted includes both" }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "description": "Rolling window in days, default 30, clamped to 1\u201390" }, "description": "Rolling window in days, default 30, clamped to 1\u201390" }, { "name": "endDate", "in": "query", "required": false, "schema": { "type": "string", "description": "Inclusive ISO 8601 window end; defaults to now" }, "description": "Inclusive ISO 8601 window end; defaults to now" } ], "responses": { "400": { "description": "Invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Organization not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Daily credit usage for an organization, one series per user", "content": { "application/json": { "schema": { "type": "object", "properties": { "histogram": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "description": "Date string" }, "usage": { "type": "number", "description": "Usage value for this date" } }, "description": "Usage histogram data point" }, "description": "Histogram data points" } }, "description": "Usage histogram for last 30 days" } } } } }, "summary": "Daily credit usage across an organization for the last N days (default 30, max 90), stacked by user." } }, "/api/v0/organizations": { "get": { "tags": [ "Organizations" ], "operationId": "organizations_listMyOrganizations", "parameters": [], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Company API keys not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Organizations the authenticated user belongs to", "content": { "application/json": { "schema": { "type": "object", "properties": { "organizations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Organization ID" }, "name": { "type": "string", "description": "Organization name" }, "role": { "type": "string", "description": "Caller's relationship: 'owner', 'admin', or 'member'" }, "subscriptionType": { "type": "string", "description": "Organization subscription tier" }, "status": { "type": "string", "description": "Organization status" }, "creditLimit": { "type": "number", "description": "Monthly credit limit" }, "creditUsage": { "type": "number", "description": "Current month credit usage" }, "seats": { "type": "integer", "description": "Seat limit" }, "companyLimit": { "type": "integer", "description": "Company limit" } }, "description": "Organization summary entry" } } }, "description": "Organizations the authenticated user belongs to" } } } } }, "summary": "List organizations with an explicit membership or ownership record.", "description": "Each entry includes a `role` indicating the caller's relationship:\n- the caller's organization_users role, when they have a membership row\n- otherwise \"owner\": user is `Organization.ownerUid`\n- otherwise \"admin\": user is in `Organization.owners`\n\nCompany collaboration does not grant organization membership and must not\nadd that company's organization to the organization switcher." }, "post": { "tags": [ "Organizations" ], "operationId": "organizations_createMyOrganization", "parameters": [], "responses": { "400": { "description": "Invalid name", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Company API keys not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "201": { "description": "The created organization", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Organization ID" }, "name": { "type": "string", "description": "Organization name" }, "role": { "type": "string", "description": "Caller's relationship: 'owner', 'admin', or 'member'" }, "subscriptionType": { "type": "string", "description": "Organization subscription tier" }, "status": { "type": "string", "description": "Organization status" }, "creditLimit": { "type": "number", "description": "Monthly credit limit" }, "creditUsage": { "type": "number", "description": "Current month credit usage" }, "seats": { "type": "integer", "description": "Seat limit" }, "companyLimit": { "type": "integer", "description": "Company limit" } }, "description": "Organization summary entry" } } } } }, "summary": "Create a new organization owned by the authenticated user.", "description": "The organization starts on the free tier; the caller is its first owner.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Organization name (1-100 characters)" } }, "required": [ "name" ], "description": "New organization" } } }, "description": "New organization" } } }, "/api/v0/organizations/{orgId}": { "put": { "tags": [ "Organizations" ], "operationId": "organizations_updateMyOrganization", "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid name", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Organization not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "The updated organization", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Organization ID" }, "name": { "type": "string", "description": "Organization name" }, "role": { "type": "string", "description": "Caller's relationship: 'owner', 'admin', or 'member'" }, "subscriptionType": { "type": "string", "description": "Organization subscription tier" }, "status": { "type": "string", "description": "Organization status" }, "creditLimit": { "type": "number", "description": "Monthly credit limit" }, "creditUsage": { "type": "number", "description": "Current month credit usage" }, "seats": { "type": "integer", "description": "Seat limit" }, "companyLimit": { "type": "integer", "description": "Company limit" } }, "description": "Organization summary entry" } } } } }, "summary": "Rename an organization. Caller must be an owner or admin.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Organization name (1-100 characters)" } }, "required": [ "name" ], "description": "Organization changes" } } }, "description": "Organization changes" } } }, "/api/v0/organizations/{orgId}/members": { "get": { "tags": [ "Organizations" ], "operationId": "organizations_listOrganizationMembers", "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Organization not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Members of the organization", "content": { "application/json": { "schema": { "type": "object", "properties": { "members": { "type": "array", "items": { "type": "object", "properties": { "uid": { "type": "string", "description": "User ID" }, "email": { "type": "string", "description": "User email" }, "displayName": { "type": "string", "description": "User display name" }, "photo": { "type": "string", "description": "User photo URL" }, "role": { "type": "string", "description": "'owner', 'admin' or 'member'" }, "createdDate": { "type": "string", "description": "When the membership was created" } }, "description": "Organization member" } } }, "description": "Members of an organization" } } } } }, "summary": "List an organization's members. Caller must be an owner or admin." }, "post": { "tags": [ "Organizations" ], "operationId": "organizations_addOrganizationMember", "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Organization or user not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "201": { "description": "The added member", "content": { "application/json": { "schema": { "type": "object", "properties": { "uid": { "type": "string", "description": "User ID" }, "email": { "type": "string", "description": "User email" }, "displayName": { "type": "string", "description": "User display name" }, "photo": { "type": "string", "description": "User photo URL" }, "role": { "type": "string", "description": "'owner', 'admin' or 'member'" }, "createdDate": { "type": "string", "description": "When the membership was created" } }, "description": "Organization member" } } } } }, "summary": "Add an existing account to an organization by email.", "description": "Caller must be an owner or admin. Only owners may grant the owner role.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "Email of an existing account" }, "role": { "type": "string", "description": "'owner', 'admin' or 'member' (default 'member')" } }, "required": [ "email" ], "description": "Member to add" } } }, "description": "Member to add" } } }, "/api/v0/organizations/{orgId}/members/{memberUid}": { "put": { "tags": [ "Organizations" ], "operationId": "organizations_updateOrganizationMember", "parameters": [ { "name": "memberUid", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Organization or member not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "The updated member", "content": { "application/json": { "schema": { "type": "object", "properties": { "uid": { "type": "string", "description": "User ID" }, "email": { "type": "string", "description": "User email" }, "displayName": { "type": "string", "description": "User display name" }, "photo": { "type": "string", "description": "User photo URL" }, "role": { "type": "string", "description": "'owner', 'admin' or 'member'" }, "createdDate": { "type": "string", "description": "When the membership was created" } }, "description": "Organization member" } } } } }, "summary": "Change a member's role. Only owners may grant or revoke the owner role.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "string", "description": "'owner', 'admin' or 'member'" } }, "required": [ "role" ], "description": "Role change" } } }, "description": "Role change" } }, "delete": { "tags": [ "Organizations" ], "operationId": "organizations_removeOrganizationMember", "parameters": [ { "name": "memberUid", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Cannot remove the last owner", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Organization or member not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Remove a member. Only owners may remove other owners." } }, "/api/v0/models": { "get": { "tags": [ "Models" ], "operationId": "Models_listModels", "parameters": [ { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string", "description": "Company ID to filter models based on ZDR settings" }, "description": "Company ID to filter models based on ZDR settings" } ], "responses": { "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "List of available models", "content": { "application/json": { "schema": { "type": "object", "properties": { "models": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Model ID" }, "name": { "type": "string", "description": "Model display name" }, "label": { "type": "string", "description": "Model display label" }, "provider": { "type": "string", "description": "Model provider" }, "credits": { "type": "number", "description": "Credits per request" }, "free": { "type": "boolean", "description": "Whether model is free to use" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Model tags" }, "maxContext": { "type": "integer", "description": "Maximum context window size" }, "enabled": { "type": "boolean", "description": "Whether model is enabled" }, "zdrSupported": { "type": "boolean", "description": "Zero Data Retention support" }, "toolsModel": { "type": "boolean", "description": "Whether model supports function calling/tools" }, "visionModel": { "type": "boolean", "description": "Whether model supports vision/images" }, "writingModel": { "type": "boolean", "description": "Whether model is optimized for writing tasks" }, "benchmarkScores": { "type": "object", "description": "OpenRouter Artificial Analysis benchmark indexes" } }, "description": "Model object" }, "description": "Array of models" } }, "description": "List of available models" } } } } }, "summary": "List available AI models.", "description": "Returns a list of AI models available for chat completions.\nThis is a public endpoint - no authentication required.\nSome models may require Zero Data Retention (ZDR) settings based\non company configuration." } }, "/api/v0/mcp/tools/list": { "get": { "tags": [ "Mcp" ], "operationId": "MCP_mcpListTools", "parameters": [], "responses": { "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "List of available MCP tools", "content": { "application/json": { "schema": { "type": "object", "properties": { "tools": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Tool name" }, "description": { "type": "string", "description": "Tool description" }, "inputSchema": { "type": "object", "properties": { "type": { "type": "string", "description": "Schema type" }, "properties": { "type": "object", "description": "Property definitions" }, "required": { "type": "array", "items": { "type": "string" }, "description": "Required properties" } }, "description": "Input schema" }, "annotations": { "type": "object", "properties": { "readOnlyHint": { "type": "boolean", "description": "Tool does not modify its environment" }, "destructiveHint": { "type": "boolean", "description": "Tool may perform destructive updates" }, "idempotentHint": { "type": "boolean", "description": "Repeated calls with same args have no additional effect" }, "openWorldHint": { "type": "boolean", "description": "Tool may interact with external entities" } }, "description": "Behavior annotations" } }, "description": "MCP tool definition" }, "description": "Array of tools" } }, "description": "List of available MCP tools" } } } } }, "summary": "List available MCP tools.", "description": "Returns all available tool definitions in MCP format, including input schemas.\n\n**Available Tools:**\n\n- `platform_list_capabilities` - Browse API endpoints by category (Agents, Sequences, Lists, Documents, Content, Images, Audio, Video, Browser, etc.)\n- `platform_get_action_details` - Get full specification for an endpoint including required parameters and request body format\n- `platform_execute_action` - Execute any API endpoint with automatic authentication\n\n**Usage Flow:**\n\n1. Call `platform_list_capabilities` to discover available actions\n2. Call `platform_get_action_details` to understand the parameters needed\n3. Call `platform_execute_action` to perform the action\n\n**Authentication:**\n\n- **Company API Key**: Scoped to a single company. No company selection needed.\n- **Personal Access Key**: Can access multiple companies by specifying X-Company-ID header.\n\nThis gives MCP clients (Claude Desktop, Cursor, Windsurf, etc.) full access to the platform API." } }, "/api/v0/mcp/tools/call": { "post": { "tags": [ "Mcp" ], "operationId": "MCP_mcpCallTool", "parameters": [], "responses": { "400": { "description": "Invalid request or unknown tool", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Tool execution result", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Content type (text)" }, "text": { "type": "string", "description": "Text content" } }, "description": "MCP content block" }, "description": "Result content blocks" }, "data": { "type": "string", "description": "Structured data (optional)" }, "metadata": { "type": "object", "description": "Additional metadata (optional)" } }, "description": "MCP tool execution result" } } } } }, "summary": "Execute an MCP tool call.", "description": "Calls the specified tool with the provided arguments and returns the result in MCP format.\n\n**Example - List Sequences:**\n\n```json\n{\n\"name\": \"platform_list_capabilities\",\n\"arguments\": {\"category\": \"Sequences\"}\n}\n```\n\n**Example - Get Action Details:**\n\n```json\n{\n\"name\": \"platform_get_action_details\",\n\"arguments\": {\"operationId\": \"sequences_getSequences\"}\n}\n```\n\n**Example - Execute Action:**\n\n```json\n{\n\"name\": \"platform_execute_action\",\n\"arguments\": {\n\"operationId\": \"agents_listAgents\"\n}\n}\n```\n\nThe response follows MCP format with a `content` array containing the result.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the tool to call" }, "arguments": { "type": "object", "description": "Arguments for the tool", "default": {} } }, "required": [ "name" ], "description": "Request body for calling an MCP tool" } } }, "description": "Tool call parameters" } } }, "/api/v0/mcp/info": { "get": { "tags": [ "Mcp" ], "operationId": "MCP_mcpServerInfo", "parameters": [], "responses": { "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "MCP server information", "content": { "application/json": { "schema": { "type": "object", "properties": { "protocolVersion": { "type": "string", "description": "MCP protocol version" }, "capabilities": { "type": "object", "description": "Server capabilities" }, "serverInfo": { "type": "object", "description": "Server metadata { name, version }" } }, "description": "MCP server information" } } } } }, "summary": "Get MCP server information.", "description": "Returns server capabilities, protocol version, and metadata.\n\n**Connecting to this MCP Server:**\n\n**Claude Desktop** - Add to `claude_desktop_config.json`:\n\n```json\n{\n\"mcpServers\": {\n\"platform\": {\n\"command\": \"npx\",\n\"args\": [\"-y\", \"mcp-remote\", \"https://api.example.com/api/v0/mcp\"],\n\"env\": {\"API_KEY\": \"your_api_key\"}\n}\n}\n}\n```\n\n**Generic MCP Client:**\n\n```bash\nnpx mcp-remote https://api.example.com/api/v0/mcp --header \"Authorization: Bearer YOUR_API_KEY\"\n```\n\n**Protocol Version:** 2024-11-05" } }, "/api/v0/browser-integrations": { "get": { "tags": [ "Browser" ], "operationId": "Browser_listBrowserIntegrations", "parameters": [], "responses": { "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "List of browser integrations", "content": { "application/json": { "schema": { "type": "object", "properties": { "integrations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Integration ID" }, "name": { "type": "string", "description": "Integration name" }, "type": { "type": "string", "description": "Integration type (e.g., linkedin_login)" }, "status": { "type": "string", "description": "Integration status" } }, "description": "Browser integration object" }, "description": "Array of integrations" } }, "description": "List of browser integrations" } } } } }, "summary": "List available browser integrations.", "description": "Returns a list of browser session integrations (LinkedIn, Twitter, etc.)\nthat can be used for authenticated browser tasks." } }, "/api/v0/browser-task": { "post": { "tags": [ "Browser" ], "operationId": "Browser_submitBrowserTask", "parameters": [], "responses": { "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Task submission result with task ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "taskId": { "type": "string", "description": "Unique task ID for polling status" }, "status": { "type": "string", "description": "Initial task status (pending)" }, "message": { "type": "string", "description": "Submission confirmation message" } }, "description": "Browser task submission result" } } } } }, "summary": "Submit a browser automation task.", "description": "Submits a browser task for asynchronous execution. Returns a task ID\nthat can be used to poll for status and results.\n\nSupports three session types:\n- regular: Standard browser session\n- authenticated: Uses an integration for logged-in sessions\n- residential: Uses a residential proxy with specified zipcode", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "task": { "type": "string", "description": "Natural language description of the browser task" }, "sessionType": { "type": "string", "description": "Session type: regular, authenticated, or residential", "default": "regular" }, "integrationId": { "type": "string", "description": "Integration ID for authenticated sessions" }, "zipcode": { "type": "string", "description": "5-digit US zipcode for residential proxy" }, "useVision": { "type": "boolean", "description": "Enable vision-based automation", "default": false } }, "required": [ "task" ], "description": "Request body for submitting a browser task" } } }, "description": "Browser task parameters" } } }, "/api/v0/browser-task/{task_id}": { "get": { "tags": [ "Browser" ], "operationId": "Browser_getBrowserTaskStatus", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Task not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Task status and result", "content": { "application/json": { "schema": { "type": "object", "properties": { "taskId": { "type": "string", "description": "Unique task ID" }, "status": { "type": "string", "description": "Task status: pending, running, completed, failed, cancelled" }, "progressMessage": { "type": "string", "description": "Current progress message" }, "createdDate": { "type": "string", "description": "ISO timestamp when task was created" }, "startedDate": { "type": "string", "description": "ISO timestamp when task started running" }, "completedDate": { "type": "string", "description": "ISO timestamp when task completed" }, "result": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether task completed successfully" }, "result": { "type": "string", "description": "Extracted content or task result" }, "history": { "type": "array", "items": { "type": "string" }, "description": "Task execution history" }, "creditsCharged": { "type": "integer", "description": "Credits charged for task" } }, "description": "Task result (when completed)" }, "errorMessage": { "type": "string", "description": "Error message (when failed)" } }, "description": "Browser task status and result" } } } } }, "summary": "Get browser task status and result.", "description": "Poll this endpoint to check the status of a submitted browser task.\nWhen status is 'completed', the result will contain the task output.\nWhen status is 'failed', the errorMessage will contain the failure reason." }, "delete": { "tags": [ "Browser" ], "operationId": "Browser_cancelBrowserTask", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Task not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Cancel a pending or running browser task.", "description": "Cancels the specified browser task if it's still pending or running.\nCompleted or failed tasks cannot be cancelled." } }, "/api/v0/images": { "post": { "tags": [ "Images" ], "operationId": "images_createImage", "parameters": [], "responses": { "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "The generated image with its public URL", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "description": "Success message" }, "imageId": { "type": "string", "description": "ID of the generated image" }, "url": { "type": "string", "description": "Public URL of the generated image \u2014 use this directly in HTML, canvases, and content" } }, "description": "Generated image response" } } } } }, "summary": "Generate an AI image from a text prompt.", "description": "Creates an image using the specified model (GPT Image or Google) and\nreturns its ID and public URL when generation completes.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt": { "type": "string", "description": "Text prompt to generate image from" }, "companyId": { "type": "string", "description": "Company ID (optional, defaults to API key company)" }, "model": { "type": "string", "description": "Model to use (e.g., gpt-image-1, leonardo models, google models)" }, "size": { "type": "string", "description": "Size for GPT Image models (e.g., 1024x1024, 1792x1024)", "default": "1024x1024" }, "width": { "type": "integer", "description": "Image width for Leonardo/Google models" }, "height": { "type": "integer", "description": "Image height for Leonardo/Google models" }, "quality": { "type": "string", "description": "Quality setting: auto, standard, hd, low, medium, high", "default": "auto" }, "referenceImages": { "type": "array", "items": { "type": "string" }, "description": "List of reference image URLs for edit mode" }, "inputFidelity": { "type": "string", "description": "Input fidelity for GPT Image edit mode: low, medium, high", "default": "low" } }, "required": [ "prompt" ], "description": "Request body for generating an image" } } }, "description": "Image generation parameters" } }, "get": { "tags": [ "Images" ], "operationId": "images_listImages", "parameters": [ { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string", "description": "Company ID (optional, defaults to API key company)" }, "description": "Company ID (optional, defaults to API key company)" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Page number (default: 1)", "default": 1 }, "description": "Page number (default: 1)" }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "description": "Items per page (default: 10, max: 100)", "default": 10 }, "description": "Items per page (default: 10, max: 100)" } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Paginated list of images", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Image ID" }, "url": { "type": "string", "description": "Image URL (internal)" }, "publicUrl": { "type": "string", "description": "Public image URL" }, "prompt": { "type": "string", "description": "Generation prompt" }, "revisedPrompt": { "type": "string", "description": "Revised prompt from the model" }, "provider": { "type": "string", "description": "Image provider: openai, leonardo, google" }, "model": { "type": "string", "description": "Model used for generation" }, "created": { "type": "number", "description": "Creation timestamp" }, "updated": { "type": "number", "description": "Last update timestamp" }, "public": { "type": "boolean", "description": "Whether the image is publicly accessible" } }, "description": "Image object" }, "description": "List of images" }, "total": { "type": "integer", "description": "Total count of images" }, "page": { "type": "integer", "description": "Current page number" }, "pages": { "type": "integer", "description": "Total number of pages" }, "has_next": { "type": "boolean", "description": "Whether there are more pages" } }, "description": "Paginated list of images" } } } } }, "summary": "List all images for a company.", "description": "Returns a paginated list of images with their metadata." } }, "/api/v0/images/{imageId}": { "delete": { "tags": [ "Images" ], "operationId": "images_deleteImage", "parameters": [ { "name": "imageId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Image not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Image deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "description": "Success message" } }, "description": "Success response" } } } } }, "summary": "Delete an image by ID.", "description": "Permanently removes the image and any associated data." }, "get": { "tags": [ "Images" ], "operationId": "images_getImageById", "parameters": [ { "name": "imageId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID." }, "description": "Company ID." } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Image not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Image details", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Image ID" }, "url": { "type": "string", "description": "Image URL (internal)" }, "publicUrl": { "type": "string", "description": "Public image URL" }, "prompt": { "type": "string", "description": "Generation prompt" }, "revisedPrompt": { "type": "string", "description": "Revised prompt from the model" }, "provider": { "type": "string", "description": "Image provider: openai, leonardo, google" }, "model": { "type": "string", "description": "Model used for generation" }, "created": { "type": "number", "description": "Creation timestamp" }, "updated": { "type": "number", "description": "Last update timestamp" }, "public": { "type": "boolean", "description": "Whether the image is publicly accessible" } }, "description": "Image object" } } } } }, "summary": "Get an image by ID.", "description": "Returns the image metadata including URLs and generation details." } }, "/api/v0/images/upload": { "post": { "tags": [ "Images" ], "operationId": "images_uploadImage", "parameters": [], "responses": { "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Uploaded image details", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Image ID" }, "url": { "type": "string", "description": "Image URL" }, "publicUrl": { "type": "string", "description": "Public image URL" }, "prompt": { "type": "string", "description": "Image description" }, "provider": { "type": "string", "description": "Provider (upload)" }, "model": { "type": "string", "description": "Model (upload)" } }, "description": "Uploaded image response" } } } } }, "summary": "Upload an image file directly.", "description": "Accepts image files (PNG, JPG, JPEG, GIF, WEBP) up to 10MB.\nThe original image is stored as-is; format conversion happens at\nserve time via the ?format= query parameter.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "prompt": { "type": "string", "description": "Optional description/tags for the image (e.g., \"residents playing an activity\", \"food service\"). Stored on the image and returned as `prompt`. Alias: `description`." }, "description": { "type": "string", "description": "Alias for `prompt`. Optional description/tags for the image." } }, "required": [ "companyId" ], "description": "Form data for uploading an image" } } }, "description": "Image upload form data (multipart/form-data)" } } }, "/api/v0/images/apply-template": { "post": { "tags": [ "Images" ], "operationId": "images_applyTemplate", "parameters": [], "responses": { "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Template or brand image not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Resulting image with template applied", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Image ID" }, "url": { "type": "string", "description": "Image URL" }, "publicUrl": { "type": "string", "description": "Public image URL" }, "prompt": { "type": "string", "description": "Image description" }, "provider": { "type": "string", "description": "Provider (upload)" }, "model": { "type": "string", "description": "Model (upload)" } }, "description": "Uploaded image response" } } } } }, "summary": "Apply a template overlay to an existing image.", "description": "Takes a source image and applies a template overlay from a brand image,\nthen saves and returns the resulting image.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sourceImageUrl": { "type": "string", "description": "URL of the source image to apply template to" }, "templateId": { "type": "string", "description": "ID of the template within the brand image" }, "brandImageId": { "type": "string", "description": "ID of the brand image containing the template" }, "companyId": { "type": "string", "description": "Company ID (optional, defaults to API key company)" } }, "required": [ "sourceImageUrl", "templateId", "brandImageId" ], "description": "Request body for applying a template overlay" } } }, "description": "Template application parameters" } } }, "/api/v0/images/models": { "get": { "tags": [ "Images" ], "operationId": "images_listImageModels", "parameters": [], "responses": { "200": { "description": "List of available image models", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "description": "List of image models" } } } } }, "summary": "List all supported image models.", "description": "Returns a list of available image generation models with their\nIDs, names, and providers. This endpoint is public and does not\nrequire authentication." } }, "/api/v0/stock-images/search": { "get": { "tags": [ "Images" ], "operationId": "images_searchStockImages", "parameters": [ { "name": "query", "in": "query", "required": true, "schema": { "type": "string", "description": "Search query" }, "description": "Search query" }, { "name": "provider", "in": "query", "required": false, "schema": { "type": "string", "description": "Provider filter (unsplash, pexels, or all)" }, "description": "Provider filter (unsplash, pexels, or all)" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Page number" }, "description": "Page number" }, { "name": "perPage", "in": "query", "required": false, "schema": { "type": "integer", "description": "Results per page" }, "description": "Results per page" } ], "responses": { "400": { "description": "Missing query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Stock image search results", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Image ID" }, "provider": { "type": "string", "description": "Provider name" }, "url": { "type": "string", "description": "Image URL" }, "thumbnailUrl": { "type": "string", "description": "Thumbnail URL" }, "width": { "type": "integer", "description": "Image width" }, "height": { "type": "integer", "description": "Image height" }, "photographer": { "type": "string", "description": "Photographer name" }, "photographerUrl": { "type": "string", "description": "Photographer profile URL" } }, "description": "Stock image" }, "description": "Search results" }, "total": { "type": "integer", "description": "Total results" }, "page": { "type": "integer", "description": "Current page" } }, "description": "Stock image search results" } } } } }, "summary": "Search for stock images from Unsplash and/or Pexels." } }, "/api/v0/stock-images/download": { "post": { "tags": [ "Images" ], "operationId": "images_downloadStockImage", "parameters": [], "responses": { "400": { "description": "Missing required fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Downloaded image with S3 URL", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "S3 URL of downloaded image" }, "originalUrl": { "type": "string", "description": "Original image URL" } }, "description": "Downloaded stock image" } } } } }, "summary": "Download a stock image and save to S3.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "photoId": { "type": "string", "description": "Image ID from provider" }, "provider": { "type": "string", "description": "Provider name (unsplash or pexels)" } }, "required": [ "companyId", "photoId", "provider" ], "description": "Request body for downloading a stock image" } } }, "description": "Stock image to download" } } }, "/api/v0/stock-images/providers": { "get": { "tags": [ "Images" ], "operationId": "images_getStockImageProviders", "parameters": [], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Available providers", "content": { "application/json": { "schema": { "type": "object", "properties": { "providers": { "type": "array", "items": { "type": "string" }, "description": "Provider names" } }, "description": "Available stock image providers" } } } } }, "summary": "Get list of available stock image providers." } }, "/api/v0/audio": { "post": { "tags": [ "Audio" ], "operationId": "audio_createAudio", "parameters": [], "responses": { "400": { "description": "Invalid speech arguments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature or credit limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Audio generation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Created audio", "content": { "application/json": { "schema": { "type": "object", "properties": { "audioId": { "type": "string", "description": "Created audio ID" }, "audioUrl": { "type": "string", "description": "Permanent public audio URL" }, "duration": { "type": "number", "description": "Measured audio duration in seconds" }, "model": { "type": "string", "description": "Model used for generation" }, "creditsCharged": { "type": "number", "description": "Credits charged for this generation" }, "format": { "type": "string", "description": "Audio format" }, "msg": { "type": "string", "description": "Success message" } }, "description": "Audio creation response" } } } } }, "summary": "Create audio from text using text-to-speech.", "description": "Converts the provided text to speech using ElevenLabs.\nReturns the audio ID for retrieval via the /audio/p/ endpoint.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string", "description": "Text to convert to speech" }, "voiceId": { "type": "string", "description": "Voice ID for ElevenLabs (default: pNInz6obpgDQGcFmaJgB)" }, "speed": { "type": "number", "description": "Playback speed (default: 1.0)" }, "model": { "type": "string", "description": "Legacy alias for modelId. Defaults to configured speech model (Eleven v3 when unset)." }, "modelId": { "type": "string", "description": "ElevenLabs speech model; takes precedence over model. Uses the same generation and model-based pricing as create_speech." }, "companyId": { "type": "string", "description": "Company ID" } }, "required": [ "text" ], "description": "Request body for creating audio" } } }, "description": "Audio creation request" } }, "get": { "tags": [ "Audio" ], "operationId": "audio_listAudio", "parameters": [ { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string", "description": "Company ID" }, "description": "Company ID" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Page number (default: 1)" }, "description": "Page number (default: 1)" }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "description": "Items per page (default: 10)" }, "description": "Items per page (default: 10)" } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "List of audio items", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Audio ID" }, "text": { "type": "string", "description": "Text that was converted" }, "url": { "type": "string", "description": "Audio URL or S3 key" }, "format": { "type": "string", "description": "Audio format (mp3, etc.)" }, "voiceId": { "type": "string", "description": "Voice ID used" }, "model": { "type": "string", "description": "Model used" }, "duration": { "type": "number", "description": "Audio duration in seconds" }, "created": { "type": "number", "description": "Creation timestamp" } }, "description": "Audio item object" }, "description": "List of audio items" }, "total": { "type": "integer", "description": "Total count" }, "page": { "type": "integer", "description": "Current page" }, "pageSize": { "type": "integer", "description": "Items per page" } }, "description": "List of audio items" } } } } }, "summary": "List all audio files.", "description": "Returns a paginated list of audio files for the company." } }, "/api/v0/audio/{audioId}": { "delete": { "tags": [ "Audio" ], "operationId": "audio_deleteAudio", "parameters": [ { "name": "audioId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Audio not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Audio deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "description": "Success message" } }, "description": "Success response" } } } } }, "summary": "Delete an audio file by ID." } }, "/api/v0/audio/models": { "get": { "tags": [ "Audio" ], "operationId": "audio_getAudioModels", "parameters": [], "responses": { "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Available audio models", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Model ID" }, "name": { "type": "string", "description": "Model name" }, "provider": { "type": "string", "description": "Model provider (e.g., elevenlabs)" }, "category": { "type": "string", "description": "Model category (e.g., speech)" }, "description": { "type": "string", "description": "Model description" }, "character_limit": { "type": "integer", "description": "Maximum character limit" }, "duration_minutes": { "type": "integer", "description": "Maximum duration in minutes" }, "cost_credits": { "type": "integer", "description": "Cost in credits" } }, "description": "Audio model object" } } } } }, "summary": "Get available audio models.", "description": "Returns a list of available text-to-speech models and their capabilities.\nThis endpoint is public and does not require authentication." } }, "/api/v0/audio/voices": { "get": { "tags": [ "Audio" ], "operationId": "audio_getAudioVoices", "parameters": [ { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID." }, "description": "Company ID." } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Available voices", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Voice ID" }, "name": { "type": "string", "description": "Voice name" }, "description": { "type": "string", "description": "Voice description" }, "provider": { "type": "string", "description": "Voice provider" }, "isPublic": { "type": "boolean", "description": "Whether voice is public" } }, "description": "Voice object" }, "description": "List of voices" }, "total": { "type": "integer", "description": "Total count" } }, "description": "List of voices" } } } } }, "summary": "Get available voices for audio generation.", "description": "Returns both public voices and company-specific cloned voices." } }, "/api/v0/videos": { "post": { "tags": [ "Video" ], "operationId": "video_createVideo", "parameters": [], "responses": { "400": { "description": "Invalid video generation parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "202": { "description": "Video generation queued", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Video ID" }, "status": { "type": "string", "description": "Generation status (generating)" }, "msg": { "type": "string", "description": "Success message" } }, "description": "Video creation response" } } } } }, "summary": "Create a video using AI generation.", "description": "Queues a video generation job for the provided prompt and fal.ai model, and\nreturns immediately with the video id and a 'generating' status. Generation\ntakes minutes, so poll the status endpoint to find out when it is ready.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt": { "type": "string", "description": "Text prompt for video generation" }, "model": { "type": "string", "description": "fal.ai model (must start with fal-ai/)" }, "companyId": { "type": "string", "description": "Company ID" }, "duration": { "type": "integer", "description": "Video duration in seconds (default: 5)", "default": 5 }, "resolution": { "type": "string", "description": "Resolution, e.g. '720p' or '1080p'. Model-specific; omit to use the model's default." }, "motion_intensity": { "type": "string", "description": "Motion intensity (low, medium, high)", "default": "medium" }, "camera_motion": { "type": "string", "description": "Camera motion type: static, pan_left, pan_right, zoom_in, zoom_out, tilt_up, tilt_down", "default": "static" }, "style": { "type": "string", "description": "Video style: realistic, cinematic, animated, artistic", "default": "realistic" }, "aspect_ratio": { "type": "string", "description": "Aspect ratio: 16:9, 9:16, 1:1, 4:3 (default: 16:9)", "default": "16:9" }, "first_frame_url": { "type": "string", "description": "URL for first frame (for first-last-frame models)" }, "last_frame_url": { "type": "string", "description": "URL for last frame (for first-last-frame models)" }, "first_frame_id": { "type": "string", "description": "ID for first frame image" }, "last_frame_id": { "type": "string", "description": "ID for last frame image" }, "image_url": { "type": "string", "description": "URL for source image (for image-to-video models)" }, "image_id": { "type": "string", "description": "ID for source image (for image-to-video models)" }, "image_urls": { "type": "array", "items": { "type": "string" }, "description": "Reference image URLs for reference-to-video models (max 9). Refer to them in the prompt as @Image1, @Image2, ..." }, "video_urls": { "type": "array", "items": { "type": "string" }, "description": "Reference video URLs for reference-to-video models (max 3). Refer to them in the prompt as @Video1, @Video2, ..." }, "audio_urls": { "type": "array", "items": { "type": "string" }, "description": "Reference audio URLs for reference-to-video models (max 3). Refer to them in the prompt as @Audio1, @Audio2, ..." }, "end_image_url": { "type": "string", "description": "URL for the end frame (optional, image-to-video models)" }, "end_image_id": { "type": "string", "description": "ID for the end frame image (optional, image-to-video models)" }, "seed": { "type": "integer", "description": "Seed for reproducible generation" }, "generate_audio": { "type": "boolean", "description": "Whether the model should generate native audio" } }, "required": [ "prompt", "model" ], "description": "Request body for generating a video" } } }, "description": "Video generation request" } }, "get": { "tags": [ "Video" ], "operationId": "video_listVideos", "parameters": [ { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string", "description": "Company ID" }, "description": "Company ID" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Page number (default: 1)" }, "description": "Page number (default: 1)" }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "description": "Items per page (default: 10)" }, "description": "Items per page (default: 10)" } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "List of videos", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Video ID" }, "uid": { "type": "string", "description": "User ID" }, "companyId": { "type": "string", "description": "Company ID" }, "url": { "type": "string", "description": "Video URL" }, "thumbnailUrl": { "type": "string", "description": "Thumbnail URL" }, "publicUrl": { "type": "string", "description": "Public URL for sharing" }, "prompt": { "type": "string", "description": "Generation prompt" }, "revisedPrompt": { "type": "string", "description": "Revised prompt used by model" }, "provider": { "type": "string", "description": "Video provider (e.g., fal)" }, "model": { "type": "string", "description": "Model used for generation" }, "duration": { "type": "integer", "description": "Video duration in seconds" }, "resolution": { "type": "string", "description": "Video resolution" }, "format": { "type": "string", "description": "Video format (e.g., mp4)" }, "fileSize": { "type": "integer", "description": "File size in bytes" }, "status": { "type": "string", "description": "Generation status (generating, completed, failed)" }, "created": { "type": "number", "description": "Creation timestamp" }, "updated": { "type": "number", "description": "Last update timestamp" }, "public": { "type": "boolean", "description": "Whether video is public" } }, "description": "Video item object" }, "description": "List of video items" }, "total": { "type": "integer", "description": "Total count" }, "page": { "type": "integer", "description": "Current page" }, "pages": { "type": "integer", "description": "Total pages" }, "has_next": { "type": "boolean", "description": "Whether there are more pages" } }, "description": "List of videos" } } } } }, "summary": "List all videos.", "description": "Returns a paginated list of videos for the company." } }, "/api/v0/videos/{videoId}": { "delete": { "tags": [ "Video" ], "operationId": "video_deleteVideo", "parameters": [ { "name": "videoId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Video not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Video deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "description": "Success message" } }, "description": "Success response" } } } } }, "summary": "Delete a video by ID." }, "get": { "tags": [ "Video" ], "operationId": "video_getPublicVideoApi", "parameters": [ { "name": "videoId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "404": { "description": "Video not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Video details", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Video ID" }, "status": { "type": "string", "description": "Generation status" }, "url": { "type": "string", "description": "Video URL (if completed)" }, "error": { "type": "string", "description": "Failure reason (if failed)" } }, "description": "Video status response" } } } } }, "summary": "Get video by ID.", "description": "Returns the video data including URL and status.\nThis endpoint is public and does not require authentication." } }, "/api/v0/videos/{videoId}/status": { "get": { "tags": [ "Video" ], "operationId": "video_getVideoStatus", "parameters": [ { "name": "videoId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Video not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Video generation status", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Video ID" }, "status": { "type": "string", "description": "Generation status" }, "url": { "type": "string", "description": "Video URL (if completed)" }, "error": { "type": "string", "description": "Failure reason (if failed)" } }, "description": "Video status response" } } } } }, "summary": "Get video generation status.", "description": "Returns the current status of video generation. When complete,\nincludes the video URL." } }, "/api/v0/videos/models": { "get": { "tags": [ "Video" ], "operationId": "video_getVideoModels", "parameters": [], "responses": { "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Available video models", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Model ID" }, "name": { "type": "string", "description": "Model name" }, "provider": { "type": "string", "description": "Model provider" } }, "description": "Video model object" } } } } }, "summary": "Get available video models.", "description": "Returns a list of available video generation models from fal.ai.\nThis endpoint is public and does not require authentication." } }, "/api/v0/videos/styles": { "get": { "tags": [ "Video" ], "operationId": "video_getVideoStyles", "parameters": [], "responses": { "200": { "description": "Available video styles" } }, "summary": "Get available video styles (deprecated).", "description": "This endpoint is deprecated as fal.ai models handle styles internally.\nReturns an empty object for backwards compatibility.", "deprecated": true } }, "/api/v0/agents": { "post": { "tags": [ "Agents" ], "operationId": "agents_createAgent", "parameters": [], "responses": { "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "201": { "description": "The created agent", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Agent ID" }, "name": { "type": "string", "description": "Agent name" }, "avatarImage": { "type": "string", "description": "URL or base64 avatar image" }, "systemPrompt": { "type": "string", "description": "AI system instructions" }, "agentPrompt": { "type": "string", "description": "Agent-specific prompt" }, "customColors": { "type": "object", "description": "Branding colors configuration" }, "model": { "type": "string", "description": "AI model" }, "channelSettings": { "type": "object", "description": "Multi-channel configuration" }, "leadFields": { "type": "array", "items": { "type": "object" }, "description": "Lead field definitions" }, "contactListId": { "type": "string", "description": "Smart list ID" }, "aiContactCaptureEnabled": { "type": "boolean", "description": "Whether AI passively extracts contact info from conversations" }, "isActive": { "type": "boolean", "description": "Whether agent is active" }, "knowledgeBaseEnabled": { "type": "boolean", "description": "Whether the agent answers from the knowledge base" }, "knowledgeBaseScope": { "type": "string", "description": "Knowledge base folder the agent is limited to (e.g. / or /shared/Support)" }, "multiStepToolsEnabled": { "type": "boolean", "description": "Whether the agent can chain multiple tool-calling turns (knowledge base search, MCP servers, integration toolsets) instead of a single round" }, "multiStepMaxTurns": { "type": "integer", "description": "Tool-calling turns allowed before tools are removed and the agent must answer (1-10, default 5)" }, "shortCode": { "type": "string", "description": "Shareable URL code" }, "created": { "type": "number", "description": "Creation timestamp" }, "updated": { "type": "number", "description": "Last update timestamp" } }, "description": "Agent object" } } } } }, "summary": "Create a new AI agent.", "description": "Creates a new AI agent with the specified configuration. The agent can\nbe configured with multiple channels (website widget, email, SMS, WhatsApp, voice)\nand custom branding.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Agent name" }, "avatarImage": { "type": "string", "description": "URL or base64 avatar image" }, "systemPrompt": { "type": "string", "description": "AI system instructions" }, "agentPrompt": { "type": "string", "description": "Agent-specific prompt" }, "customColors": { "type": "object", "description": "Branding colors: {primary?: string (hex), secondary?: string (hex), background?: string (hex)}" }, "model": { "type": "string", "description": "AI model (default: gpt-5-nano)" }, "channelSettings": { "type": "object", "description": "Multi-channel configuration: {website?: {enabled: boolean}, email?: {enabled: boolean, address?: string}, sms?: {enabled: boolean, phoneNumber?: string}, whatsapp?: {enabled: boolean, phoneNumber?: string (Twilio WhatsApp-enabled number, E.164), integrationId?: string (Twilio integration ID), autoReply?: boolean}, voice?: {enabled: boolean}}" }, "leadFields": { "type": "array", "items": { "type": "object" }, "description": "Lead field definitions: [{name: string, type: string (text, email, phone, number), required?: boolean}]" }, "contactListId": { "type": "string", "description": "Smart list ID for contact collection" }, "aiContactCaptureEnabled": { "type": "boolean", "description": "Whether AI passively extracts contact info from conversations (default: true)" }, "isActive": { "type": "boolean", "description": "Whether agent is active (default: true)" }, "knowledgeBaseEnabled": { "type": "boolean", "description": "Whether the agent answers from the knowledge base" }, "knowledgeBaseScope": { "type": "string", "description": "Knowledge base folder the agent is limited to (e.g. / or /shared/Support)" }, "multiStepToolsEnabled": { "type": "boolean", "description": "Whether the agent can chain multiple tool-calling turns (knowledge base search, MCP servers, integration toolsets) instead of a single round" }, "multiStepMaxTurns": { "type": "integer", "description": "Tool-calling turns allowed before tools are removed and the agent must answer (1-10, default 5)" } }, "required": [ "name" ], "description": "Request body for creating a new agent" } } }, "description": "Agent configuration" } }, "get": { "tags": [ "Agents" ], "operationId": "agents_listAgents", "parameters": [ { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID." }, "description": "Company ID." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Page number (default: 1)", "default": 1 }, "description": "Page number (default: 1)" }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "description": "Items per page (default: 10, max: 100)", "default": 10 }, "description": "Items per page (default: 10, max: 100)" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "description": "Search by name, email, or phone" }, "description": "Search by name, email, or phone" } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Paginated list of agents", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Agent ID" }, "name": { "type": "string", "description": "Agent name" }, "avatarImage": { "type": "string", "description": "URL or base64 avatar image" }, "systemPrompt": { "type": "string", "description": "AI system instructions" }, "agentPrompt": { "type": "string", "description": "Agent-specific prompt" }, "customColors": { "type": "object", "description": "Branding colors configuration" }, "model": { "type": "string", "description": "AI model" }, "channelSettings": { "type": "object", "description": "Multi-channel configuration" }, "leadFields": { "type": "array", "items": { "type": "object" }, "description": "Lead field definitions" }, "contactListId": { "type": "string", "description": "Smart list ID" }, "aiContactCaptureEnabled": { "type": "boolean", "description": "Whether AI passively extracts contact info from conversations" }, "isActive": { "type": "boolean", "description": "Whether agent is active" }, "knowledgeBaseEnabled": { "type": "boolean", "description": "Whether the agent answers from the knowledge base" }, "knowledgeBaseScope": { "type": "string", "description": "Knowledge base folder the agent is limited to (e.g. / or /shared/Support)" }, "multiStepToolsEnabled": { "type": "boolean", "description": "Whether the agent can chain multiple tool-calling turns (knowledge base search, MCP servers, integration toolsets) instead of a single round" }, "multiStepMaxTurns": { "type": "integer", "description": "Tool-calling turns allowed before tools are removed and the agent must answer (1-10, default 5)" }, "shortCode": { "type": "string", "description": "Shareable URL code" }, "created": { "type": "number", "description": "Creation timestamp" }, "updated": { "type": "number", "description": "Last update timestamp" } }, "description": "Agent object" }, "description": "List of agents" }, "total": { "type": "integer", "description": "Total number of agents" }, "pages": { "type": "integer", "description": "Total number of pages" }, "hasNext": { "type": "boolean", "description": "Whether more pages exist" } }, "description": "Paginated list of agents" } } } } }, "summary": "List all agents for the current company.", "description": "Returns a paginated list of agents belonging to the company associated\nwith the API key. Use the search parameter to filter agents by name." } }, "/api/v0/agents/{agentId}": { "get": { "tags": [ "Agents" ], "operationId": "agents_getAgent", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID." }, "description": "Company ID." } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Agent not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Agent details", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Agent ID" }, "name": { "type": "string", "description": "Agent name" }, "avatarImage": { "type": "string", "description": "URL or base64 avatar image" }, "systemPrompt": { "type": "string", "description": "AI system instructions" }, "agentPrompt": { "type": "string", "description": "Agent-specific prompt" }, "customColors": { "type": "object", "description": "Branding colors configuration" }, "model": { "type": "string", "description": "AI model" }, "channelSettings": { "type": "object", "description": "Multi-channel configuration" }, "leadFields": { "type": "array", "items": { "type": "object" }, "description": "Lead field definitions" }, "contactListId": { "type": "string", "description": "Smart list ID" }, "aiContactCaptureEnabled": { "type": "boolean", "description": "Whether AI passively extracts contact info from conversations" }, "isActive": { "type": "boolean", "description": "Whether agent is active" }, "knowledgeBaseEnabled": { "type": "boolean", "description": "Whether the agent answers from the knowledge base" }, "knowledgeBaseScope": { "type": "string", "description": "Knowledge base folder the agent is limited to (e.g. / or /shared/Support)" }, "multiStepToolsEnabled": { "type": "boolean", "description": "Whether the agent can chain multiple tool-calling turns (knowledge base search, MCP servers, integration toolsets) instead of a single round" }, "multiStepMaxTurns": { "type": "integer", "description": "Tool-calling turns allowed before tools are removed and the agent must answer (1-10, default 5)" }, "shortCode": { "type": "string", "description": "Shareable URL code" }, "created": { "type": "number", "description": "Creation timestamp" }, "updated": { "type": "number", "description": "Last update timestamp" } }, "description": "Agent object" } } } } }, "summary": "Get a specific agent by ID.", "description": "Returns the full agent configuration including channel settings,\nlead fields, and branding options." }, "put": { "tags": [ "Agents" ], "operationId": "agents_updateAgent", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Agent not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "The updated agent", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Agent ID" }, "name": { "type": "string", "description": "Agent name" }, "avatarImage": { "type": "string", "description": "URL or base64 avatar image" }, "systemPrompt": { "type": "string", "description": "AI system instructions" }, "agentPrompt": { "type": "string", "description": "Agent-specific prompt" }, "customColors": { "type": "object", "description": "Branding colors configuration" }, "model": { "type": "string", "description": "AI model" }, "channelSettings": { "type": "object", "description": "Multi-channel configuration" }, "leadFields": { "type": "array", "items": { "type": "object" }, "description": "Lead field definitions" }, "contactListId": { "type": "string", "description": "Smart list ID" }, "aiContactCaptureEnabled": { "type": "boolean", "description": "Whether AI passively extracts contact info from conversations" }, "isActive": { "type": "boolean", "description": "Whether agent is active" }, "knowledgeBaseEnabled": { "type": "boolean", "description": "Whether the agent answers from the knowledge base" }, "knowledgeBaseScope": { "type": "string", "description": "Knowledge base folder the agent is limited to (e.g. / or /shared/Support)" }, "multiStepToolsEnabled": { "type": "boolean", "description": "Whether the agent can chain multiple tool-calling turns (knowledge base search, MCP servers, integration toolsets) instead of a single round" }, "multiStepMaxTurns": { "type": "integer", "description": "Tool-calling turns allowed before tools are removed and the agent must answer (1-10, default 5)" }, "shortCode": { "type": "string", "description": "Shareable URL code" }, "created": { "type": "number", "description": "Creation timestamp" }, "updated": { "type": "number", "description": "Last update timestamp" } }, "description": "Agent object" } } } } }, "summary": "Update an existing agent.", "description": "Updates the agent configuration. Only include fields that need to be\nchanged - unspecified fields will retain their current values.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Agent name" }, "avatarImage": { "type": "string", "description": "URL or base64 avatar image" }, "systemPrompt": { "type": "string", "description": "AI system instructions" }, "agentPrompt": { "type": "string", "description": "Agent-specific prompt" }, "customColors": { "type": "object", "description": "Branding colors: {primary?: string (hex), secondary?: string (hex), background?: string (hex)}" }, "model": { "type": "string", "description": "AI model (e.g., gpt-5-nano)" }, "channelSettings": { "type": "object", "description": "Multi-channel configuration: {website?: {enabled: boolean}, email?: {enabled: boolean, address?: string}, sms?: {enabled: boolean, phoneNumber?: string}, whatsapp?: {enabled: boolean, phoneNumber?: string (Twilio WhatsApp-enabled number, E.164), integrationId?: string (Twilio integration ID), autoReply?: boolean}, voice?: {enabled: boolean}}" }, "leadFields": { "type": "array", "items": { "type": "object" }, "description": "Lead field definitions: [{name: string, type: string (text, email, phone, number), required?: boolean}]" }, "contactListId": { "type": "string", "description": "Smart list ID for contact collection" }, "aiContactCaptureEnabled": { "type": "boolean", "description": "Whether AI passively extracts contact info from conversations" }, "isActive": { "type": "boolean", "description": "Whether agent is active" }, "knowledgeBaseEnabled": { "type": "boolean", "description": "Whether the agent answers from the knowledge base" }, "knowledgeBaseScope": { "type": "string", "description": "Knowledge base folder the agent is limited to (e.g. / or /shared/Support)" }, "multiStepToolsEnabled": { "type": "boolean", "description": "Whether the agent can chain multiple tool-calling turns (knowledge base search, MCP servers, integration toolsets) instead of a single round" }, "multiStepMaxTurns": { "type": "integer", "description": "Tool-calling turns allowed before tools are removed and the agent must answer (1-10, default 5)" } }, "description": "Request body for updating an agent (include only fields to update)" } } }, "description": "Fields to update" } }, "delete": { "tags": [ "Agents" ], "operationId": "agents_deleteAgent", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Agent not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Deletion result", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "description": "Success message" } }, "description": "Success response" } } } } }, "summary": "Delete an agent.", "description": "Permanently deletes the specified agent and all associated data." } }, "/api/v0/conversations": { "get": { "tags": [ "Agents" ], "operationId": "agents_getAllAgentConversations", "parameters": [ { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID." }, "description": "Company ID." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Page number (default: 1)", "default": 1 }, "description": "Page number (default: 1)" }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "description": "Items per page (default: 20, max: 100)", "default": 20 }, "description": "Items per page (default: 20, max: 100)" }, { "name": "channel", "in": "query", "required": false, "schema": { "type": "string", "description": "Filter by channel (single): website, email, sms, whatsapp, voice, outbound_voice" }, "description": "Filter by channel (single): website, email, sms, whatsapp, voice, outbound_voice" }, { "name": "channels", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" }, "description": "Filter by multiple channels: website, email, sms, whatsapp, voice, outbound_voice" }, "description": "Filter by multiple channels: website, email, sms, whatsapp, voice, outbound_voice" }, { "name": "startDate", "in": "query", "required": false, "schema": { "type": "number", "description": "Filter after this Unix timestamp" }, "description": "Filter after this Unix timestamp" }, { "name": "endDate", "in": "query", "required": false, "schema": { "type": "number", "description": "Filter before this Unix timestamp" }, "description": "Filter before this Unix timestamp" } ], "responses": { "400": { "description": "Invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Paginated list of conversations", "content": { "application/json": { "schema": { "type": "object", "properties": { "conversations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Conversation ID" }, "sessionId": { "type": "string", "description": "Session identifier" }, "agentId": { "type": "string", "description": "Agent ID" }, "channel": { "type": "string", "description": "Communication channel: website, email, sms, whatsapp, voice, outbound_voice" }, "contactInfo": { "type": "object", "description": "Contact details gathered" }, "status": { "type": "string", "description": "Status: active, ended, archived" }, "messageCount": { "type": "integer", "description": "Number of messages" }, "startedAt": { "type": "number", "description": "Start timestamp" }, "lastActivityAt": { "type": "number", "description": "Last activity timestamp" } }, "description": "Conversation object" }, "description": "List of conversations" }, "totalCount": { "type": "integer", "description": "Total number of conversations" }, "page": { "type": "integer", "description": "Current page" }, "pageSize": { "type": "integer", "description": "Page size" }, "totalPages": { "type": "integer", "description": "Total pages" } }, "description": "Paginated list of conversations" } } } } }, "summary": "Get all conversations across company agents with pagination and filtering.", "description": "Returns a paginated list of conversations for all agents in the company.\nFilter by agentId, channel, and date range using Unix timestamps." } }, "/api/v0/conversations/{agentId}/{sessionId}/check": { "get": { "tags": [ "Agents" ], "operationId": "agents_checkConversationActivity", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied or feature not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Conversation not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Cheap polling probe for whether a conversation has changed.", "description": "Returns when the conversation last changed, without loading any message\ncontent. Clients compare the values to what they already have and only\nrefetch the full conversation when they differ." } }, "/api/v0/conversations/{agentId}/{sessionId}": { "get": { "tags": [ "Agents" ], "operationId": "agents_getConversationDetails", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied or feature not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Conversation not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Conversation details with messages", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Conversation ID" }, "sessionId": { "type": "string", "description": "Session identifier" }, "agentId": { "type": "string", "description": "Agent ID" }, "agentName": { "type": "string", "description": "Agent name" }, "channel": { "type": "string", "description": "Communication channel: website, email, sms, whatsapp, voice, outbound_voice" }, "contactInfo": { "type": "object", "description": "Contact details gathered" }, "status": { "type": "string", "description": "Status: active, ended, archived" }, "startedAt": { "type": "number", "description": "Start timestamp" }, "lastActivityAt": { "type": "number", "description": "Last activity timestamp" }, "messages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Message ID" }, "conversationId": { "type": "string", "description": "Parent conversation ID" }, "messageType": { "type": "string", "description": "Message type: user, assistant, system" }, "messageContent": { "type": "string", "description": "Message text content" }, "timestamp": { "type": "number", "description": "Message timestamp (Unix ms)" }, "isSuccessful": { "type": "boolean", "description": "Whether agent response was successful" }, "metadata": { "type": "object", "description": "Additional message metadata" } }, "description": "Message object" }, "description": "Conversation messages" } }, "description": "Conversation details with messages" } } } } }, "summary": "Get full conversation details for a specific agent session.", "description": "Returns the full conversation including all messages exchanged between\nthe user and the agent. Messages are ordered chronologically." } }, "/api/v0/lists": { "get": { "tags": [ "Lists" ], "operationId": "lists_getLists", "parameters": [ { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID." }, "description": "Company ID." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Page number (default: 1)", "default": 1 }, "description": "Page number (default: 1)" }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "description": "Items per page (default: 50, max: 100)", "default": 50 }, "description": "Items per page (default: 50, max: 100)" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "description": "Search query to filter lists by name (case-insensitive substring match)" }, "description": "Search query to filter lists by name (case-insensitive substring match)" }, { "name": "minimal", "in": "query", "required": false, "schema": { "type": "boolean", "description": "If true, each item in the response only includes id, name, and type \u2014 useful for populating dropdowns without N+1 queries. Default: false", "default": false }, "description": "If true, each item in the response only includes id, name, and type \u2014 useful for populating dropdowns without N+1 queries. Default: false" }, { "name": "sortBy", "in": "query", "required": false, "schema": { "type": "string", "description": "Field to sort by: 'createdDate' (default) or 'updatedDate'", "enum": [ "createdDate", "updatedDate" ] }, "description": "Field to sort by: 'createdDate' (default) or 'updatedDate'" }, { "name": "sortOrder", "in": "query", "required": false, "schema": { "type": "string", "description": "Sort direction: 'asc' (default) or 'desc'", "enum": [ "asc", "desc" ] }, "description": "Sort direction: 'asc' (default) or 'desc'" } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Paginated list of lists", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "List ID (UUID)" }, "uid": { "type": "string", "description": "User ID of the list owner" }, "companyId": { "type": "string", "description": "Company that owns the list" }, "name": { "type": "string", "description": "List name" }, "type": { "type": "string", "description": "List type: \"leads\", \"companies\", or \"custom\"" }, "sharing": { "type": "string", "description": "Sharing visibility: \"Private\", \"Shared\", or \"Public\"" }, "departmentIds": { "type": "array", "items": { "type": "string" }, "description": "Department IDs this shared list is restricted to (null/empty = no restriction). Also used to group lists into folders in the UI." }, "indexParkedAt": { "type": "string", "description": "Index parking timestamp; null for active lists. Data remains searchable while parked." }, "count": { "type": "integer", "description": "Total number of non-deleted rows in the list" }, "scheduledAutomations": { "type": "integer", "description": "Count of auto-run column/list actions configured on this list" }, "newRowsSinceLastView": { "type": "integer", "description": "Number of rows added since the current user last viewed this list. 0 if never viewed or no new rows." }, "created_date": { "type": "string", "description": "Creation timestamp (ISO 8601)" }, "updated_date": { "type": "string", "description": "Last update timestamp (ISO 8601)" }, "deleted_date": { "type": "string", "description": "Soft-delete timestamp (ISO 8601). Null for active lists." } }, "description": "Smart list summary (one item from GET /lists)" }, "description": "Page of lists. See schema description for shape differences when minimal=true." }, "total": { "type": "integer", "description": "Total number of lists matching the query" }, "page": { "type": "integer", "description": "Current page number (1-indexed)" }, "pages": { "type": "integer", "description": "Total number of pages" }, "has_next": { "type": "boolean", "description": "Whether another page is available" } }, "description": "Paginated lists response. The shape of `items` depends on the `minimal` query parameter: by default each item is a ListSummary (with row count, automations count, etc.); when minimal=true each item is a ListMinimal (id, name, type only)." } } } } }, "summary": "List all smart lists for the current company." }, "post": { "tags": [ "Lists" ], "operationId": "lists_saveList", "parameters": [], "responses": { "400": { "description": "listDict and companyId are required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "201": { "description": "Newly-created list (id and name)", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID (UUID) of the newly created list" }, "name": { "type": "string", "description": "Name of the newly created list" }, "type": { "type": "string", "description": "List type: \"leads\", \"companies\", or \"custom\"" }, "headers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Column ID (UUID)" }, "listId": { "type": "string", "description": "Parent list ID (UUID)" }, "name": { "type": "string", "description": "Column name" }, "type": { "type": "string", "description": "Column type. Data types: text, long_text, url, image, email, phone, linkedin_url. Action types (server-managed): action, lookup, etc." }, "dataType": { "type": "string", "description": "Underlying data type used for storage and validation (e.g., string, number, boolean, json)" }, "order": { "type": "number", "description": "Display order within the list (smaller values appear first)" }, "actionParameters": { "type": "object", "description": "Parameters for action/lookup columns. Null for plain data columns." }, "autoRunEnabled": { "type": "boolean", "description": "For action/lookup columns: whether the action runs automatically on new rows." }, "autoRunEnabledDate": { "type": "string", "description": "Timestamp (ISO 8601) when autoRun was last enabled. Null if autoRun has never been enabled." }, "conditions": { "type": "object", "description": "Optional run conditions for action/lookup columns (free-form JSON). Null when no conditions are configured." }, "loading": { "type": "boolean", "description": "True while a column-wide action is currently executing for this column." }, "created_date": { "type": "string", "description": "Creation timestamp (ISO 8601)" }, "updated_date": { "type": "string", "description": "Last update timestamp (ISO 8601)" }, "deleted_date": { "type": "string", "description": "Soft-delete timestamp (ISO 8601). Null for active columns." } }, "description": "Column (header) on a list" }, "description": "Ordered column definitions created for the list. Use these column names when adding or updating rows." } }, "description": "Response returned after creating a list. Includes the list's column headers so callers know the exact column names/types to read or write rows against \u2014 no follow-up request is needed." } } } } }, "summary": "Create a new smart list.", "description": "Supply companyId via the query string, X-Company-ID header, or request body.\nA company-scoped API key supplies its company automatically.\n\nSet listDict.sharing to control who can see the list:\n- \"Private\" (default): only the creator.\n- \"Shared\": anyone in the company.\n- \"Public\": anyone with the list ID, via the unauthenticated\n/public/lists/ endpoints.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "listDict": { "type": "object", "description": "List properties. Required: name (string). Optional: type (string, one of \"leads\" | \"companies\" | \"custom\"; default \"custom\"), sharing (string controlling visibility \u2014 see below; default \"Private\"), fields (object of column definitions, only when not using a template), templateId (string, when creating from a template).\n\nsharing values:\n - \"Private\" (default): only the creating user can view or modify the list.\n - \"Shared\": any user in the same company can view and modify the list.\n - \"Public\": anyone with the list ID can read the list and its rows via the public endpoints (GET /public/lists/ and GET /public/lists//rows). Only the list owner can change sharing afterward.\n\ndepartmentIds (array of department ID strings, optional): only applies when sharing is \"Shared\". When set, only company members assigned to one of these departments (plus admins/owners and the list owner) can see the list. Leave empty/omitted for no department restriction. Also drives the folder grouping in the UI." }, "companyId": { "type": "string", "description": "Company ID." } }, "required": [ "listDict", "companyId" ], "description": "Request body for creating a new smart list. companyId must be supplied in the body, query string, or X-Company-ID header unless a company-scoped API key supplies it. JWT authentication does not infer an active company. Sharing visibility is controlled by listDict.sharing \u2014 see field description for the three modes." } } }, "description": "List data" } }, "put": { "tags": [ "Lists" ], "operationId": "lists_updateList", "parameters": [], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "List updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "description": "Human-readable success message (typically \"Success\")" } }, "description": "Generic success response" } } } } }, "summary": "Update an existing smart list.", "description": "The request body is the list object \u2014 include id plus any fields to change.\nOnly the list owner can change name or sharing. Set sharing to:\n- \"Private\": only the owner can view or modify.\n- \"Shared\": anyone in the owner's company can view and modify.\n- \"Public\": anyone with the list ID can read it via the unauthenticated\n/public/lists/ endpoints.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "List ID (UUID) to update" }, "name": { "type": "string", "description": "New list name. Only the list owner can change this." }, "type": { "type": "string", "description": "List type: \"leads\", \"companies\", or \"custom\"" }, "sharing": { "type": "string", "description": "Visibility of the list. Only the list owner can change this value. Allowed values:\n - \"Private\": only the owner can view or modify the list.\n - \"Shared\": any user in the owner's company can view and modify the list.\n - \"Public\": anyone (no auth required) can read the list and its rows via GET /public/lists/ and GET /public/lists//rows. Other endpoints still require auth." }, "departmentIds": { "type": "array", "items": { "type": "string" }, "description": "Department IDs restricting who can see this list (only applies when sharing is \"Shared\"). Only company members assigned to one of these departments \u2014 plus admins/owners and the list owner \u2014 can see it. Empty array or omitted means no restriction. Only the list owner can change this." } }, "required": [ "id" ], "description": "Request body for updating a smart list. The body is the list object itself \u2014 include id plus only the fields you want to change. To publish/unpublish a list, set sharing \u2014 see field description for the three modes." } } }, "description": "List data to update" } } }, "/api/v0/lists/actions": { "get": { "tags": [ "Lists" ], "operationId": "lists_getListActionsCatalog", "parameters": [ { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string", "description": "Company ID that owns the list. Required when authenticating with a personal access key (pak_\u2026) \u2014 the key is not tied to a specific company so the server cannot infer it. Required when authenticating with a company API key only if the key belongs to a user who has access to multiple companies; otherwise it defaults to the key's company. Optional for JWT (dashboard) auth \u2014 defaults to the user's active company." }, "description": "Company ID that owns the list. Required when authenticating with a personal access key (pak_\u2026) \u2014 the key is not tied to a specific company so the server cannot infer it. Required when authenticating with a company API key only if the key belongs to a user who has access to multiple companies; otherwise it defaults to the key's company. Optional for JWT (dashboard) auth \u2014 defaults to the user's active company." } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Catalog of available table actions", "content": { "application/json": { "schema": { "type": "object", "properties": { "actions": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "description": "Human-readable action name shown in the \"Add action\" menu." }, "type": { "type": "string", "description": "Action type identifier (or lookup type for lookup columns). See LIST_ACTION_TYPE_* / LOOKUP_TYPE_* constants." }, "description": { "type": "string", "description": "What the action does, suitable for showing to a user or an AI agent choosing an action." }, "icon": { "type": "object", "properties": { "type": { "type": "string", "description": "Icon source: \"mui\" (a Material UI icon name) or \"logo\" (an integration logo key)." }, "name": { "type": "string", "description": "Icon name \u2014 an MUI icon name when type is \"mui\", or an integration logo key when type is \"logo\"." } }, "description": "Icon reference for the action." }, "options": { "type": "object", "description": "Default options for the action. Contains `actionParameters`: a template of the parameters this action accepts, pre-filled with sensible defaults." }, "lookupType": { "type": "string", "description": "When present, this entry creates a lookup column (via POST /lists//lookup) instead of an action. Absent for regular actions." } }, "description": "An available table action (or lookup column) that can be attached to a smart list. Use `type` as the actionType and `options.actionParameters` as the default parameter values when creating the action via POST /lists//action (or POST /lists//lookup when lookupType is set)." }, "description": "Ordered list of available actions, in the order they should appear in the \"Add action\" menu." } }, "description": "The catalog of available smart-list table actions \u2014 the source of truth for which actions can be attached to a list, their descriptions, and their default parameters. Lead search and enrichment actions are funded by data credits." } } } } }, "summary": "List the available smart-list table actions (the action catalog).", "description": "Returns every action (and lookup column) that can be attached to a list \u2014\nits title, description, icon, and a template of default parameters. This is\nthe source of truth for the \"Add action\" menu and for AI agents deciding\nwhich action to configure on a column.\n\nLead search and enrichment actions are available to every smart-list user." } }, "/api/v0/lists/{listId}/duplicate": { "post": { "tags": [ "Lists" ], "operationId": "lists_duplicateList", "parameters": [ { "name": "listId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string", "description": "Company ID that owns the list. Required when authenticating with a personal access key (pak_\u2026) \u2014 the key is not tied to a specific company so the server cannot infer it. Required when authenticating with a company API key only if the key belongs to a user who has access to multiple companies; otherwise it defaults to the key's company. Optional for JWT (dashboard) auth \u2014 defaults to the user's active company." }, "description": "Company ID that owns the list. Required when authenticating with a personal access key (pak_\u2026) \u2014 the key is not tied to a specific company so the server cannot infer it. Required when authenticating with a company API key only if the key belongs to a user who has access to multiple companies; otherwise it defaults to the key's company. Optional for JWT (dashboard) auth \u2014 defaults to the user's active company." } ], "responses": { "400": { "description": "Invalid list ID or name", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "List access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "List not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "201": { "description": "Independent list copy with headers and copied row count", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID (UUID) of the newly created list" }, "name": { "type": "string", "description": "Name of the newly created list" }, "type": { "type": "string", "description": "List type: \"leads\", \"companies\", or \"custom\"" }, "headers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Column ID (UUID)" }, "listId": { "type": "string", "description": "Parent list ID (UUID)" }, "name": { "type": "string", "description": "Column name" }, "type": { "type": "string", "description": "Column type. Data types: text, long_text, url, image, email, phone, linkedin_url. Action types (server-managed): action, lookup, etc." }, "dataType": { "type": "string", "description": "Underlying data type used for storage and validation (e.g., string, number, boolean, json)" }, "order": { "type": "number", "description": "Display order within the list (smaller values appear first)" }, "actionParameters": { "type": "object", "description": "Parameters for action/lookup columns. Null for plain data columns." }, "autoRunEnabled": { "type": "boolean", "description": "For action/lookup columns: whether the action runs automatically on new rows." }, "autoRunEnabledDate": { "type": "string", "description": "Timestamp (ISO 8601) when autoRun was last enabled. Null if autoRun has never been enabled." }, "conditions": { "type": "object", "description": "Optional run conditions for action/lookup columns (free-form JSON). Null when no conditions are configured." }, "loading": { "type": "boolean", "description": "True while a column-wide action is currently executing for this column." }, "created_date": { "type": "string", "description": "Creation timestamp (ISO 8601)" }, "updated_date": { "type": "string", "description": "Last update timestamp (ISO 8601)" }, "deleted_date": { "type": "string", "description": "Soft-delete timestamp (ISO 8601). Null for active columns." } }, "description": "Column (header) on a list" }, "description": "Ordered column definitions created for the list. Use these column names when adding or updating rows." }, "count": { "type": "integer", "description": "Number of active rows copied, including rows with empty cells." }, "sharing": { "type": "string", "description": "Sharing visibility retained from the source list." }, "departmentIds": { "type": "array", "items": { "type": "string" }, "description": "Department restrictions retained from the source list." } }, "description": "Response returned after creating a list. Includes the list's column headers so callers know the exact column names/types to read or write rows against \u2014 no follow-up request is needed." } } } } }, "summary": "Duplicate a smart list and all its active row data.", "description": "Copies every active row, column definition, cell value, cell research and\ntimestamp, and table action configuration/results. New list, header, and\nrow IDs make the copy independent. Deleted rows/columns are excluded.\nThe caller owns the copy; sharing and department restrictions are retained.\nCopied automations start disabled. Running jobs, execution history, campaign\nrecipients, and sequence memberships remain attached to the original list.\nComputed lookup columns recalculate for the new list. The entire copy is\ncommitted atomically; an error leaves no partial list.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the copy (1\u2013100 characters). Defaults to the source name followed by \" (copy)\"." }, "companyId": { "type": "string", "description": "Company ID that owns the list. Required when authenticating with a personal access key (pak_\u2026) \u2014 the key is not tied to a specific company so the server cannot infer it. Required when authenticating with a company API key only if the key belongs to a user who has access to multiple companies; otherwise it defaults to the key's company. Optional for JWT (dashboard) auth \u2014 defaults to the user's active company." } } } } }, "description": "Optional copy name; send {} to use the default" } } }, "/api/v0/lists/{listId}": { "get": { "tags": [ "Lists" ], "operationId": "lists_getList", "parameters": [ { "name": "listId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID." }, "description": "Company ID." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Page number for rows (default: 1)", "default": 1 }, "description": "Page number for rows (default: 1)" }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "description": "Rows per page (default: 50, max: 100)", "default": 50 }, "description": "Rows per page (default: 50, max: 100)" }, { "name": "sortField", "in": "query", "required": false, "schema": { "type": "string", "description": "Column name to sort by. Use the reserved value \"dateAdded\" to sort by row creation time. Defaults to row creation time." }, "description": "Column name to sort by. Use the reserved value \"dateAdded\" to sort by row creation time. Defaults to row creation time." }, { "name": "sortOrder", "in": "query", "required": false, "schema": { "type": "string", "description": "Sort order: \"asc\" or \"desc\" (default: \"desc\")", "default": "desc" }, "description": "Sort order: \"asc\" or \"desc\" (default: \"desc\")" }, { "name": "searchQuery", "in": "query", "required": false, "schema": { "type": "string", "description": "Substring to match within row values" }, "description": "Substring to match within row values" }, { "name": "searchField", "in": "query", "required": false, "schema": { "type": "string", "description": "Column name to restrict the search to. Use \"all\" or omit to search across all columns." }, "description": "Column name to restrict the search to. Use \"all\" or omit to search across all columns." }, { "name": "filterModel", "in": "query", "required": false, "schema": { "type": "string", "description": "JSON-encoded MUI DataGrid filter model. Supported operators: contains, equals, startsWith, endsWith, notEquals, isEmpty, isNotEmpty." }, "description": "JSON-encoded MUI DataGrid filter model. Supported operators: contains, equals, startsWith, endsWith, notEquals, isEmpty, isNotEmpty." } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "List not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "List details with rows", "content": { "application/json": { "schema": { "type": "object", "properties": { "list": { "type": "object", "properties": { "id": { "type": "string", "description": "List ID (UUID)" }, "uid": { "type": "string", "description": "User ID of the list owner" }, "companyId": { "type": "string", "description": "Company that owns the list" }, "name": { "type": "string", "description": "List name" }, "type": { "type": "string", "description": "List type: \"leads\", \"companies\", or \"custom\"" }, "sharing": { "type": "string", "description": "Sharing visibility: \"Private\", \"Shared\", or \"Public\"" }, "departmentIds": { "type": "array", "items": { "type": "string" }, "description": "Department IDs this shared list is restricted to (null/empty = no restriction)." }, "headers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Column ID (UUID)" }, "listId": { "type": "string", "description": "Parent list ID (UUID)" }, "name": { "type": "string", "description": "Column name" }, "type": { "type": "string", "description": "Column type. Data types: text, long_text, url, image, email, phone, linkedin_url. Action types (server-managed): action, lookup, etc." }, "dataType": { "type": "string", "description": "Underlying data type used for storage and validation (e.g., string, number, boolean, json)" }, "order": { "type": "number", "description": "Display order within the list (smaller values appear first)" }, "actionParameters": { "type": "object", "description": "Parameters for action/lookup columns. Null for plain data columns." }, "autoRunEnabled": { "type": "boolean", "description": "For action/lookup columns: whether the action runs automatically on new rows." }, "autoRunEnabledDate": { "type": "string", "description": "Timestamp (ISO 8601) when autoRun was last enabled. Null if autoRun has never been enabled." }, "conditions": { "type": "object", "description": "Optional run conditions for action/lookup columns (free-form JSON). Null when no conditions are configured." }, "loading": { "type": "boolean", "description": "True while a column-wide action is currently executing for this column." }, "created_date": { "type": "string", "description": "Creation timestamp (ISO 8601)" }, "updated_date": { "type": "string", "description": "Last update timestamp (ISO 8601)" }, "deleted_date": { "type": "string", "description": "Soft-delete timestamp (ISO 8601). Null for active columns." } }, "description": "Column (header) on a list" }, "description": "Ordered column definitions" }, "actions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Action ID (UUID)" }, "listId": { "type": "string", "description": "Parent list ID (UUID)" }, "name": { "type": "string", "description": "Action name" }, "type": { "type": "string", "description": "Action type (see LIST_ACTION_TYPE_* constants)" }, "autoRunEnabled": { "type": "boolean", "description": "Whether the action runs automatically on new rows" } }, "description": "Automation configured on the list (column action or list-level action)" }, "description": "List- and column-level automations configured on this list" }, "rows": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "rowId": { "type": "string", "description": "Row ID (UUID)" }, "dateAdded": { "type": "string", "description": "Row creation timestamp (ISO 8601)" } }, "description": "A row in a smart list. The object is flat: keys are the list's column names (plus the special keys rowId and dateAdded). Column values are typed according to each column's dataType \u2014 usually strings." }, "description": "Rows on this page. Each row also contains arbitrary additional keys \u2014 one per column on the list." }, "total": { "type": "integer", "description": "Total number of rows matching the query" }, "page": { "type": "integer", "description": "Current page number (1-indexed)" }, "pages": { "type": "integer", "description": "Total number of pages" }, "has_next": { "type": "boolean", "description": "Whether another page is available" } }, "description": "Paginated rows for the current page/pageSize/filter combination" }, "created_date": { "type": "string", "description": "Creation timestamp (ISO 8601)" }, "updated_date": { "type": "string", "description": "Last update timestamp (ISO 8601)" }, "deleted_date": { "type": "string", "description": "Soft-delete timestamp (ISO 8601). Null for an active list." } }, "description": "List detail object" } }, "description": "Response envelope for GET /lists/" } } } } }, "summary": "Get a specific list with its rows and column headers." }, "delete": { "tags": [ "Lists" ], "operationId": "lists_deleteList", "parameters": [ { "name": "listId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string", "description": "Company ID that owns the list. Required when authenticating with a personal access key (pak_\u2026) \u2014 the key is not tied to a specific company so the server cannot infer it. Required when authenticating with a company API key only if the key belongs to a user who has access to multiple companies; otherwise it defaults to the key's company. Optional for JWT (dashboard) auth \u2014 defaults to the user's active company." }, "description": "Company ID that owns the list. Required when authenticating with a personal access key (pak_\u2026) \u2014 the key is not tied to a specific company so the server cannot infer it. Required when authenticating with a company API key only if the key belongs to a user who has access to multiple companies; otherwise it defaults to the key's company. Optional for JWT (dashboard) auth \u2014 defaults to the user's active company." } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "List not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "List deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "description": "Human-readable success message (typically \"Success\")" } }, "description": "Generic success response" } } } } }, "summary": "Delete a smart list." } }, "/api/v0/lists/{listId}/schema": { "get": { "tags": [ "Lists" ], "operationId": "lists_getListSchema", "parameters": [ { "name": "listId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string", "description": "Company ID that owns the list. Required when authenticating with a personal access key (pak_\u2026) \u2014 the key is not tied to a specific company so the server cannot infer it. Required when authenticating with a company API key only if the key belongs to a user who has access to multiple companies; otherwise it defaults to the key's company. Optional for JWT (dashboard) auth \u2014 defaults to the user's active company." }, "description": "Company ID that owns the list. Required when authenticating with a personal access key (pak_\u2026) \u2014 the key is not tied to a specific company so the server cannot infer it. Required when authenticating with a company API key only if the key belongs to a user who has access to multiple companies; otherwise it defaults to the key's company. Optional for JWT (dashboard) auth \u2014 defaults to the user's active company." } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "List not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "List metadata and column headers (no rows)", "content": { "application/json": { "schema": { "type": "object", "properties": { "list": { "type": "object", "properties": { "id": { "type": "string", "description": "List ID (UUID)" }, "uid": { "type": "string", "description": "User ID of the list owner" }, "companyId": { "type": "string", "description": "Company that owns the list" }, "name": { "type": "string", "description": "List name" }, "type": { "type": "string", "description": "List type: \"leads\", \"companies\", or \"custom\"" }, "sharing": { "type": "string", "description": "Sharing visibility: \"Private\", \"Shared\", or \"Public\"" }, "headers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Column ID (UUID)" }, "listId": { "type": "string", "description": "Parent list ID (UUID)" }, "name": { "type": "string", "description": "Column name" }, "type": { "type": "string", "description": "Column type. Data types: text, long_text, url, image, email, phone, linkedin_url. Action types (server-managed): action, lookup, etc." }, "dataType": { "type": "string", "description": "Underlying data type used for storage and validation (e.g., string, number, boolean, json)" }, "order": { "type": "number", "description": "Display order within the list (smaller values appear first)" }, "actionParameters": { "type": "object", "description": "Parameters for action/lookup columns. Null for plain data columns." }, "autoRunEnabled": { "type": "boolean", "description": "For action/lookup columns: whether the action runs automatically on new rows." }, "autoRunEnabledDate": { "type": "string", "description": "Timestamp (ISO 8601) when autoRun was last enabled. Null if autoRun has never been enabled." }, "conditions": { "type": "object", "description": "Optional run conditions for action/lookup columns (free-form JSON). Null when no conditions are configured." }, "loading": { "type": "boolean", "description": "True while a column-wide action is currently executing for this column." }, "created_date": { "type": "string", "description": "Creation timestamp (ISO 8601)" }, "updated_date": { "type": "string", "description": "Last update timestamp (ISO 8601)" }, "deleted_date": { "type": "string", "description": "Soft-delete timestamp (ISO 8601). Null for active columns." } }, "description": "Column (header) on a list" }, "description": "Ordered column definitions. Use these column names when adding or updating rows." }, "created_date": { "type": "string", "description": "Creation timestamp (ISO 8601)" }, "updated_date": { "type": "string", "description": "Last update timestamp (ISO 8601)" }, "deleted_date": { "type": "string", "description": "Soft-delete timestamp (ISO 8601). Null for an active list." } }, "description": "List metadata and column headers (no rows)" } }, "description": "Response envelope for GET /lists//schema. Returns the list's metadata and column headers only \u2014 no rows. Use this to discover column names/types before reading or writing rows." } } } } }, "summary": "Get a list's metadata and column headers without any row data.", "description": "Returns the list's name, type, and ordered column definitions (headers).\nUse this to discover the exact column names and types before reading or\nwriting rows \u2014 it avoids fetching the (potentially large) rows payload that\nGET /lists/ returns." } }, "/api/v0/lists/{listId}/rows": { "get": { "tags": [ "Lists" ], "operationId": "lists_getListRows", "parameters": [ { "name": "listId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID." }, "description": "Company ID." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Page number for rows (default: 1)", "default": 1 }, "description": "Page number for rows (default: 1)" }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "description": "Rows per page (default: 50, max: 100)", "default": 50 }, "description": "Rows per page (default: 50, max: 100)" }, { "name": "sortField", "in": "query", "required": false, "schema": { "type": "string", "description": "Column name to sort by. Use the reserved value \"dateAdded\" to sort by row creation time. Defaults to row creation time." }, "description": "Column name to sort by. Use the reserved value \"dateAdded\" to sort by row creation time. Defaults to row creation time." }, { "name": "sortOrder", "in": "query", "required": false, "schema": { "type": "string", "description": "Sort order: \"asc\" or \"desc\" (default: \"desc\")", "default": "desc" }, "description": "Sort order: \"asc\" or \"desc\" (default: \"desc\")" }, { "name": "searchQuery", "in": "query", "required": false, "schema": { "type": "string", "description": "Substring to match within row values" }, "description": "Substring to match within row values" }, { "name": "searchField", "in": "query", "required": false, "schema": { "type": "string", "description": "Column name to restrict the search to. Use \"all\" or omit to search across all columns." }, "description": "Column name to restrict the search to. Use \"all\" or omit to search across all columns." }, { "name": "filterModel", "in": "query", "required": false, "schema": { "type": "string", "description": "JSON-encoded MUI DataGrid filter model. Supported operators: contains, equals, startsWith, endsWith, notEquals, isEmpty, isNotEmpty." }, "description": "JSON-encoded MUI DataGrid filter model. Supported operators: contains, equals, startsWith, endsWith, notEquals, isEmpty, isNotEmpty." } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "List not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Paginated rows for the list (no headers/metadata)", "content": { "application/json": { "schema": { "type": "object", "properties": { "rows": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "rowId": { "type": "string", "description": "Row ID (UUID)" }, "dateAdded": { "type": "string", "description": "Row creation timestamp (ISO 8601)" } }, "description": "A row in a smart list. The object is flat: keys are the list's column names (plus the special keys rowId and dateAdded). Column values are typed according to each column's dataType \u2014 usually strings." }, "description": "Rows on this page. Each row also contains arbitrary additional keys \u2014 one per column on the list." }, "total": { "type": "integer", "description": "Total number of rows matching the query" }, "page": { "type": "integer", "description": "Current page number (1-indexed)" }, "pages": { "type": "integer", "description": "Total number of pages" }, "has_next": { "type": "boolean", "description": "Whether another page is available" } }, "description": "Paginated rows for the current page/pageSize/sort/search/filter combination" } }, "description": "Response envelope for GET /lists//rows. Returns only the paginated rows \u2014 no headers or list metadata. Supports the same pagination (page, pageSize), sorting (sortField, sortOrder), search (searchQuery, searchField), and filterModel parameters as GET /lists/." } } } } }, "summary": "Get a page of a list's rows without the headers or list metadata.", "description": "Returns only the paginated rows payload. Pair this with\nGET /lists//schema (column definitions) to read a list without the\nbundled GET /lists/ call. Supports the same pagination, sorting,\nsearch, and filterModel parameters as the list-detail endpoint." }, "put": { "tags": [ "Lists" ], "operationId": "lists_updateRows", "parameters": [ { "name": "listId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "set is required / unknown column / unrecognized where clause / unknown body key / no where without matchAll", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "List not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Counts of matched and updated rows", "content": { "application/json": { "schema": { "type": "object", "properties": { "matched": { "type": "integer", "description": "Number of rows that satisfied the WHERE clause (and were within `limit`)." }, "updated": { "type": "integer", "description": "Number of matched rows that actually changed (at least one cell differed). Re-running an already-applied update reports matched without inflating updated." } }, "description": "Result of a bulk row update." } } } } }, "summary": "Bulk-update rows, SQL-style: UPDATE SET WHERE .", "description": "Apply the same column\u2192value assignments (`set`) to every row matching the\n`where` conditions tree in a single call \u2014 instead of fetching ids and\nlooping single-row updates. `where` uses the same conditions shape as action\nrun-conditions, and may filter on the virtual `rowId` field to target a\nsingle row by id. Updating every row requires an explicit `matchAll: true`\n(with no `where`); a missing/empty `where` alone is a 400, never a\nmatch-all, and so is a present-but-malformed `where` or an unknown body\nkey. Returns how many rows matched and how many actually changed.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "set": { "type": "object", "description": "Column\u2192value assignments applied to each matching row, e.g. {\"Status\": \"qualified\", \"Tier\": \"A\"}. Keys are column NAMES (as in the list headers). Only data columns are writable \u2014 action and lookup columns are computed and rejected. An unknown column name returns a 400 listing the valid columns (no silent no-op)." }, "where": { "type": "object", "properties": { "combinator": { "type": "string", "description": "How the top-level filters and groups combine: \"AND\" (all must match) or \"OR\" (any may match). Uppercase. Defaults to \"AND\"." }, "filters": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "The column NAME to test (exactly as it appears in the list headers / row keys \u2014 not the column id). Lookup and system columns (those starting with \"__\", plus \"dateAdded\") are not valid filter fields." }, "operator": { "type": "string", "description": "Comparison operator. One of: equals, not_equals, contains, not_contains, starts_with, ends_with, is_empty, is_not_empty, greater_than, less_than, greater_than_or_equals, less_than_or_equals. String operators (contains/not_contains/starts_with/ends_with) require the cell to be a string. Numeric operators (greater_than/less_than/\u2026or_equals) compare numerically and fail closed (no match) if either side is non-numeric. For is_empty/is_not_empty the \"value\" is ignored." }, "value": { "type": "string", "description": "The value to compare against. Usually a string; use a number for numeric operators. Omit (or use \"\") for is_empty / is_not_empty." } }, "required": [ "field", "operator" ], "description": "A single condition: compare one column's value against `value` using `operator`." }, "description": "Top-level field comparisons." }, "groups": { "type": "array", "items": { "type": "object", "properties": { "combinator": { "type": "string", "description": "How this group's filters and sub-groups combine: \"AND\" (all must match) or \"OR\" (any may match). Uppercase. Defaults to \"AND\"." }, "filters": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "The column NAME to test (exactly as it appears in the list headers / row keys \u2014 not the column id). Lookup and system columns (those starting with \"__\", plus \"dateAdded\") are not valid filter fields." }, "operator": { "type": "string", "description": "Comparison operator. One of: equals, not_equals, contains, not_contains, starts_with, ends_with, is_empty, is_not_empty, greater_than, less_than, greater_than_or_equals, less_than_or_equals. String operators (contains/not_contains/starts_with/ends_with) require the cell to be a string. Numeric operators (greater_than/less_than/\u2026or_equals) compare numerically and fail closed (no match) if either side is non-numeric. For is_empty/is_not_empty the \"value\" is ignored." }, "value": { "type": "string", "description": "The value to compare against. Usually a string; use a number for numeric operators. Omit (or use \"\") for is_empty / is_not_empty." } }, "required": [ "field", "operator" ], "description": "A single condition: compare one column's value against `value` using `operator`." }, "description": "Field comparisons in this group." }, "groups": { "type": "array", "items": { "type": "object", "description": "Recursive reference (same schema)" }, "description": "Further nested groups (same shape). Nesting is unlimited." } }, "description": "A nested group of conditions combined by its own combinator. Groups let you mix AND and OR \u2014 e.g. outer AND with an inner OR group. Groups may themselves contain further groups." }, "description": "Nested condition groups, for mixing AND and OR logic." } }, "description": "Which rows to update \u2014 a conditions tree ({combinator, filters, groups}); see ConditionsSchema for operators and examples. Filters may target any column NAME plus the virtual field \"rowId\", which matches a row by its primary key (use operator \"equals\" with the row id as value). Required unless matchAll is true: a missing or condition-less where returns a 400 instead of matching everything, and so does a present-but-unrecognized where (e.g. the shorthand {\"rowId\": \"...\"})." }, "matchAll": { "type": "boolean", "description": "Explicit confirmation to update EVERY row in the list. Required (as true) when no `where` is given; must NOT be combined with a `where`. This is a safety latch \u2014 never set it when the intent is to update specific rows." }, "limit": { "type": "integer", "description": "Optional cap on how many matching rows to update (applied in row-creation order). Omit for no cap." }, "companyId": { "type": "string", "description": "Company ID that owns the list. Required when authenticating with a personal access key (pak_\u2026) \u2014 the key is not tied to a specific company so the server cannot infer it. Required when authenticating with a company API key only if the key belongs to a user who has access to multiple companies; otherwise it defaults to the key's company. Optional for JWT (dashboard) auth \u2014 defaults to the user's active company." } }, "required": [ "set" ], "description": "Bulk-update rows in one request, like SQL UPDATE SET WHERE . `set` is the column\u2192value assignment applied to every matching row; `where` is a conditions tree (the SAME shape used for action run-conditions) selecting which rows to update. Updating EVERY row requires passing `matchAll: true` explicitly (and no `where`) \u2014 a missing or condition-less `where` alone is a 400, never a match-all. A `where` that is present but is not a conditions tree is also a 400, and so is any body key other than set/where/limit/matchAll/companyId (e.g. a `rows` array \u2014 that is not how rows are targeted here).\n\nExample \u2014 set Status and Tier on all tech-industry rows:\n{\n \"set\": {\"Status\": \"qualified\", \"Tier\": \"A\"},\n \"where\": {\n \"combinator\": \"AND\",\n \"filters\": [{\"field\": \"Company Industry\", \"operator\": \"contains\", \"value\": \"Tech\"}],\n \"groups\": []\n }\n}\n\nExample \u2014 update exactly ONE row by its id. Use the virtual `rowId` field inside a normal filter; do NOT pass a bare {\"rowId\": \"...\"} shorthand as `where`:\n{\n \"set\": {\"Status\": \"CANNOT SUBMIT\"},\n \"where\": {\n \"combinator\": \"AND\",\n \"filters\": [{\"field\": \"rowId\", \"operator\": \"equals\", \"value\": \"6c9a36cc-0dae-41fd-9ccb-c5688c46bc7c\"}],\n \"groups\": []\n }\n}" } } }, "description": "SET assignments and WHERE conditions" } }, "post": { "tags": [ "Lists" ], "operationId": "lists_addRows", "parameters": [ { "name": "listId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string", "description": "Company ID that owns the list. Required when authenticating with a personal access key (pak_\u2026) \u2014 the key is not tied to a specific company so the server cannot infer it. Required when authenticating with a company API key only if the key belongs to a user who has access to multiple companies; otherwise it defaults to the key's company. Optional for JWT (dashboard) auth \u2014 defaults to the user's active company." }, "description": "Company ID that owns the list. Required when authenticating with a personal access key (pak_\u2026) \u2014 the key is not tied to a specific company so the server cannot infer it. Required when authenticating with a company API key only if the key belongs to a user who has access to multiple companies; otherwise it defaults to the key's company. Optional for JWT (dashboard) auth \u2014 defaults to the user's active company." }, { "name": "createColumns", "in": "query", "required": false, "schema": { "type": "boolean", "description": "If true, columns referenced in the rows that do not exist yet are auto-created on the list. Default: false (unknown fields are silently dropped).", "default": false }, "description": "If true, columns referenced in the rows that do not exist yet are auto-created on the list. Default: false (unknown fields are silently dropped)." }, { "name": "matchFields", "in": "query", "required": false, "schema": { "type": "string", "description": "Comma-separated (or caret-separated) field names used to match existing rows. When a row's values for these fields match an existing row, that row is updated in place instead of inserted; the result for that row will have updated=true." }, "description": "Comma-separated (or caret-separated) field names used to match existing rows. When a row's values for these fields match an existing row, that row is updated in place instead of inserted; the result for that row will have updated=true." } ], "responses": { "400": { "description": "rows is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Per-row insert results (preserves input order)", "content": { "application/json": { "schema": { "type": "object", "properties": { "rows": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID (UUID) of the inserted (or matched) row. Present on success." }, "success": { "type": "boolean", "description": "True when the row was inserted (or matched and updated). Absent on failure." }, "updated": { "type": "boolean", "description": "Present and true when an existing row was matched via matchFields and updated in place; absent when a new row was created." }, "error": { "type": "string", "description": "Error message if this row failed to insert. Present only on failure." }, "row_data": { "type": "object", "description": "Echo of the input row data. Present only on failure, to help locate the offending input." } }, "description": "Per-row result entry from a batch insert. On success the entry contains {id, success: true} (plus updated: true when an existing row was matched and updated). On failure the entry contains {error, row_data} echoing the offending input." }, "description": "Per-row results in the same order as the input rows." } }, "description": "Response for batch row insert. The `rows` array preserves the input order \u2014 each entry indicates whether that input row was inserted, matched, or failed." } } } } }, "summary": "Add multiple rows with data to a list.", "description": "Creates multiple rows with the provided data. Optionally creates new\ncolumns for fields that don't exist and matches existing rows based\non specified fields.\n\nQuery parameters:\n- createColumns: Create columns that don't exist (default: false)\n- matchFields: Comma-separated field names to match existing rows", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "rows": { "type": "array", "items": { "type": "object" }, "description": "Array of row data objects. Each object maps column names to values, e.g. {\"firstName\": \"John\", \"email\": \"john@example.com\"}. Unknown column names are silently dropped unless createColumns=true is set as a query parameter." }, "companyId": { "type": "string", "description": "Company ID that owns the list. Required when authenticating with a personal access key (pak_\u2026) \u2014 the key is not tied to a specific company so the server cannot infer it. Required when authenticating with a company API key only if the key belongs to a user who has access to multiple companies; otherwise it defaults to the key's company. Optional for JWT (dashboard) auth \u2014 defaults to the user's active company." } }, "required": [ "rows" ], "description": "Request body for bulk-adding rows" } } }, "description": "Rows to add" } } }, "/api/v0/lists/{listId}/rows/new": { "get": { "tags": [ "Lists" ], "operationId": "lists_getNewRows", "parameters": [ { "name": "listId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "since", "in": "query", "required": true, "schema": { "type": "string", "description": "ISO 8601 timestamp (e.g., 2023-04-01T12:00:00Z). Only rows created strictly after this time are returned." }, "description": "ISO 8601 timestamp (e.g., 2023-04-01T12:00:00Z). Only rows created strictly after this time are returned." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "description": "Maximum rows to return, newest first. Default 500, max 1000." }, "description": "Maximum rows to return, newest first. Default 500, max 1000." }, { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string", "description": "Company ID that owns the list. Required when authenticating with a personal access key (pak_\u2026) \u2014 the key is not tied to a specific company so the server cannot infer it. Required when authenticating with a company API key only if the key belongs to a user who has access to multiple companies; otherwise it defaults to the key's company. Optional for JWT (dashboard) auth \u2014 defaults to the user's active company. For JWT auth, the server falls back to the list owner's company if the user is a member." }, "description": "Company ID that owns the list. Required when authenticating with a personal access key (pak_\u2026) \u2014 the key is not tied to a specific company so the server cannot infer it. Required when authenticating with a company API key only if the key belongs to a user who has access to multiple companies; otherwise it defaults to the key's company. Optional for JWT (dashboard) auth \u2014 defaults to the user's active company. For JWT auth, the server falls back to the list owner's company if the user is a member." } ], "responses": { "400": { "description": "since parameter is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Rows created since the supplied timestamp", "content": { "application/json": { "schema": { "type": "object", "properties": { "rows": { "type": "array", "items": { "type": "object" }, "description": "Rows created strictly after the provided \"since\" timestamp, newest first. Each row is keyed by column name (plus rowId and dateAdded), matching the shape of items inside GET /lists/." }, "hasMore": { "type": "boolean", "description": "True when more rows were added since \"since\" than \"limit\" returned." } }, "description": "Response for incremental row sync since a timestamp" } } } } }, "summary": "Get rows added to a list since a given timestamp.", "description": "Returns all rows that were created after the specified ISO timestamp.\nUseful for incremental synchronization." } }, "/api/v0/lists/{listId}/export": { "get": { "tags": [ "Lists" ], "operationId": "lists_exportList", "parameters": [ { "name": "listId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID." }, "description": "Company ID." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Page number for rows (default: 1)", "default": 1 }, "description": "Page number for rows (default: 1)" }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "description": "Rows per page (default: 50, max: 100)", "default": 50 }, "description": "Rows per page (default: 50, max: 100)" }, { "name": "sortField", "in": "query", "required": false, "schema": { "type": "string", "description": "Column name to sort by. Use the reserved value \"dateAdded\" to sort by row creation time. Defaults to row creation time." }, "description": "Column name to sort by. Use the reserved value \"dateAdded\" to sort by row creation time. Defaults to row creation time." }, { "name": "sortOrder", "in": "query", "required": false, "schema": { "type": "string", "description": "Sort order: \"asc\" or \"desc\" (default: \"desc\")", "default": "desc" }, "description": "Sort order: \"asc\" or \"desc\" (default: \"desc\")" }, { "name": "searchQuery", "in": "query", "required": false, "schema": { "type": "string", "description": "Substring to match within row values" }, "description": "Substring to match within row values" }, { "name": "searchField", "in": "query", "required": false, "schema": { "type": "string", "description": "Column name to restrict the search to. Use \"all\" or omit to search across all columns." }, "description": "Column name to restrict the search to. Use \"all\" or omit to search across all columns." }, { "name": "filterModel", "in": "query", "required": false, "schema": { "type": "string", "description": "JSON-encoded MUI DataGrid filter model. Supported operators: contains, equals, startsWith, endsWith, notEquals, isEmpty, isNotEmpty." }, "description": "JSON-encoded MUI DataGrid filter model. Supported operators: contains, equals, startsWith, endsWith, notEquals, isEmpty, isNotEmpty." } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "List not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Export a list to CSV.", "description": "For lists under 10k rows, returns CSV directly.\nFor larger lists, creates a background task and emails the download link." } }, "/api/v0/lists/{listId}/import/preview": { "post": { "tags": [ "Lists" ], "operationId": "lists_importPreview", "parameters": [ { "name": "listId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "No file, an unsupported file type, or no rows", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "List or project file not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "File columns, sample rows and the suggested mapping", "content": { "application/json": { "schema": { "type": "object", "properties": { "headers": { "type": "array", "items": { "type": "string" }, "description": "File column names." }, "headerMapping": { "type": "object", "description": "Suggested mapping: file column name -> existing list column id, or \"new\"." }, "existingHeaders": { "type": "array", "items": { "type": "object" }, "description": "The list's current columns (id, name, type)." }, "preview": { "type": "array", "items": { "type": "object" }, "description": "The first 4 rows, keyed by column name." }, "rowCount": { "type": "integer", "description": "Number of rows in the file (the chosen sheet, for a workbook)." }, "sheets": { "type": "array", "items": { "type": "string" }, "description": "Sheet names, for a workbook. Pass one as sheet to read it instead of the first." }, "status": { "type": "string", "description": "Always \"success\"." } }, "description": "The file's columns, its first rows, and the suggested column mapping." } } } } }, "summary": "Preview a CSV or Excel import into a list.", "description": "Returns the file's columns, its first rows and a suggested headerMapping that\nmatches file columns to the list's existing columns. Review or adjust the\nmapping, then pass it to lists_importRecords.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "projectId": { "type": "string", "description": "Project (UUID) holding the file. Use with path instead of uploading a file." }, "path": { "type": "string", "description": "Path of the file in the project, e.g. \"/uploads/contacts.csv\"." }, "sheet": { "type": "string", "description": "Workbook sheet to read. Defaults to the first sheet; ignored for CSV." }, "companyId": { "type": "string", "description": "Company ID that owns the list. Required when authenticating with a personal access key (pak_\u2026) \u2014 the key is not tied to a specific company so the server cannot infer it. Required when authenticating with a company API key only if the key belongs to a user who has access to multiple companies; otherwise it defaults to the key's company. Optional for JWT (dashboard) auth \u2014 defaults to the user's active company." } }, "description": "Request body for previewing a CSV or Excel import into a list. Send a CSV or Excel file (.csv, .xlsx, .xls) as multipart `file`, or name one saved in a project with `projectId` and `path` (files uploaded to a chat are saved under /uploads/ in the chat's project). For a workbook, `sheet` picks the sheet; the first sheet is the default." } } }, "description": "The CSV or Excel file to preview" } } }, "/api/v0/lists/{listId}/import": { "post": { "tags": [ "Lists" ], "operationId": "lists_importRecords", "parameters": [ { "name": "listId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "No file, an unsupported file type, or no rows", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "List or project file not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "An import into this list is already running", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Import finished (200) or started in the background (202)", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "\"background\" when the import runs asynchronously." }, "taskId": { "type": "string", "description": "Background task ID (UUID). Poll it with lists_getTaskStatus until status is \"completed\", \"failed\", or \"cancelled\"." }, "message": { "type": "string", "description": "Human-readable status message." }, "rowCount": { "type": "integer", "description": "Number of rows being imported." }, "msg": { "type": "string", "description": "\"Success\" when a small import finished immediately." } }, "description": "Result of a file import: \"background\" with a taskId (202) for imports over 100 rows, otherwise msg \"Success\" (200) once the rows are imported." } } } } }, "summary": "Import CSV or Excel rows into a list.", "description": "Rows are added to the list, with file columns mapped by headerMapping. Imports\nover 100 rows run in the background: poll the returned taskId with\nlists_getTaskStatus. Confirm the mapping with lists_importPreview first.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "projectId": { "type": "string", "description": "Project (UUID) holding the file. Use with path instead of uploading a file." }, "path": { "type": "string", "description": "Path of the file in the project, e.g. \"/uploads/contacts.csv\"." }, "sheet": { "type": "string", "description": "Workbook sheet to read. Defaults to the first sheet; ignored for CSV." }, "companyId": { "type": "string", "description": "Company ID that owns the list. Required when authenticating with a personal access key (pak_\u2026) \u2014 the key is not tied to a specific company so the server cannot infer it. Required when authenticating with a company API key only if the key belongs to a user who has access to multiple companies; otherwise it defaults to the key's company. Optional for JWT (dashboard) auth \u2014 defaults to the user's active company." }, "headerMapping": { "type": "object", "description": "Maps each file column name to the id of an existing list column, \"new\" to add it as a new column, or \"ignore\" to skip it. Get the suggested mapping from lists_importPreview. When omitted, the suggested mapping is used. In multipart requests, send it as a JSON string." } }, "description": "Request body for importing CSV or Excel rows into a list. Send a CSV or Excel file (.csv, .xlsx, .xls) as multipart `file`, or name one saved in a project with `projectId` and `path` (files uploaded to a chat are saved under /uploads/ in the chat's project). For a workbook, `sheet` picks the sheet; the first sheet is the default. Imports over 100 rows run in the background and respond 202 with a taskId. Only one file import runs per list at a time (409 otherwise)." } } }, "description": "The CSV or Excel file to import and its column mapping" } } }, "/api/v0/lists/{listId}/action": { "post": { "tags": [ "Lists" ], "operationId": "lists_addTableAction", "parameters": [ { "name": "listId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "actionParameters is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Action created or updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "description": "Human-readable success message (typically \"Success\")" } }, "description": "Generic success response" } } } } }, "summary": "Add (or update) a table action on a list.", "description": "Table actions are automations attached to a list as an action column \u2014 e.g.\na research agent that enriches each row, an AI text generator, or an HTTP\nrequest. Set autoRunEnabled to run the action automatically on rows as they\nare added.\n\nDiscover the available actions and their default parameters via\nGET /lists/actions, then pass that template (customized) as actionParameters.\nProvide actionId to update an existing action instead of creating one.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "actionParameters": { "type": "object", "description": "Action configuration. Must include actionType (e.g. \"agent\", \"ai_text\", \"http_request\" \u2014 see GET /lists/actions) and a \"name\" for the action column. Other keys depend on the action type (e.g. an \"agent\" action takes \"goal\" and \"model\"). Actions run in \"update_rows\" mode, filling in a cell on each row." }, "actionId": { "type": "string", "description": "Existing action/column ID (UUID) to update. Omit to create a new action." }, "autoRunEnabled": { "type": "boolean", "description": "When true, the action runs automatically on rows as they are added to the list. Default: false. Pair with `conditions` to auto-run on only a subset of rows." }, "conditions": { "type": "object", "properties": { "combinator": { "type": "string", "description": "How the top-level filters and groups combine: \"AND\" (all must match) or \"OR\" (any may match). Uppercase. Defaults to \"AND\"." }, "filters": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "The column NAME to test (exactly as it appears in the list headers / row keys \u2014 not the column id). Lookup and system columns (those starting with \"__\", plus \"dateAdded\") are not valid filter fields." }, "operator": { "type": "string", "description": "Comparison operator. One of: equals, not_equals, contains, not_contains, starts_with, ends_with, is_empty, is_not_empty, greater_than, less_than, greater_than_or_equals, less_than_or_equals. String operators (contains/not_contains/starts_with/ends_with) require the cell to be a string. Numeric operators (greater_than/less_than/\u2026or_equals) compare numerically and fail closed (no match) if either side is non-numeric. For is_empty/is_not_empty the \"value\" is ignored." }, "value": { "type": "string", "description": "The value to compare against. Usually a string; use a number for numeric operators. Omit (or use \"\") for is_empty / is_not_empty." } }, "required": [ "field", "operator" ], "description": "A single condition: compare one column's value against `value` using `operator`." }, "description": "Top-level field comparisons." }, "groups": { "type": "array", "items": { "type": "object", "properties": { "combinator": { "type": "string", "description": "How this group's filters and sub-groups combine: \"AND\" (all must match) or \"OR\" (any may match). Uppercase. Defaults to \"AND\"." }, "filters": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "The column NAME to test (exactly as it appears in the list headers / row keys \u2014 not the column id). Lookup and system columns (those starting with \"__\", plus \"dateAdded\") are not valid filter fields." }, "operator": { "type": "string", "description": "Comparison operator. One of: equals, not_equals, contains, not_contains, starts_with, ends_with, is_empty, is_not_empty, greater_than, less_than, greater_than_or_equals, less_than_or_equals. String operators (contains/not_contains/starts_with/ends_with) require the cell to be a string. Numeric operators (greater_than/less_than/\u2026or_equals) compare numerically and fail closed (no match) if either side is non-numeric. For is_empty/is_not_empty the \"value\" is ignored." }, "value": { "type": "string", "description": "The value to compare against. Usually a string; use a number for numeric operators. Omit (or use \"\") for is_empty / is_not_empty." } }, "required": [ "field", "operator" ], "description": "A single condition: compare one column's value against `value` using `operator`." }, "description": "Field comparisons in this group." }, "groups": { "type": "array", "items": { "type": "object", "description": "Recursive reference (same schema)" }, "description": "Further nested groups (same shape). Nesting is unlimited." } }, "description": "A nested group of conditions combined by its own combinator. Groups let you mix AND and OR \u2014 e.g. outer AND with an inner OR group. Groups may themselves contain further groups." }, "description": "Nested condition groups, for mixing AND and OR logic." } }, "description": "Optional run conditions restricting which rows the action runs on (applies to both auto-run and manual runs). An AND/OR tree of field comparisons \u2014 see ConditionsSchema for the full shape, operators, and examples. Null/omitted (or an empty filters+groups) runs on every row. The \"field\" in each condition is a column NAME (as in the list headers), and the row must already have that column for the comparison to match (except is_empty/is_not_empty)." }, "companyId": { "type": "string", "description": "Company ID that owns the list. Required when authenticating with a personal access key (pak_\u2026) \u2014 the key is not tied to a specific company so the server cannot infer it. Required when authenticating with a company API key only if the key belongs to a user who has access to multiple companies; otherwise it defaults to the key's company. Optional for JWT (dashboard) auth \u2014 defaults to the user's active company." } }, "required": [ "actionParameters" ], "description": "Request body for adding (or updating) a table action \u2014 an automation attached to a list as an action column. Use GET /lists/actions to discover available actions and their default actionParameters; pass that template (with your customizations) as actionParameters here. Set autoRunEnabled=true to have the action fire automatically on new rows, and use `conditions` to restrict which rows it runs on." } } }, "description": "Table action configuration" } } }, "/api/v0/lists/{listId}/lookup": { "post": { "tags": [ "Lists" ], "operationId": "lists_addLookupColumn", "parameters": [ { "name": "listId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "lookupType is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "The created (or existing) lookup column", "content": { "application/json": { "schema": { "type": "object", "properties": { "header": { "type": "object", "properties": { "id": { "type": "string", "description": "Column ID (UUID)" }, "listId": { "type": "string", "description": "Parent list ID (UUID)" }, "name": { "type": "string", "description": "Column name" }, "type": { "type": "string", "description": "Column type. Data types: text, long_text, url, image, email, phone, linkedin_url. Action types (server-managed): action, lookup, etc." }, "dataType": { "type": "string", "description": "Underlying data type used for storage and validation (e.g., string, number, boolean, json)" }, "order": { "type": "number", "description": "Display order within the list (smaller values appear first)" }, "actionParameters": { "type": "object", "description": "Parameters for action/lookup columns. Null for plain data columns." }, "autoRunEnabled": { "type": "boolean", "description": "For action/lookup columns: whether the action runs automatically on new rows." }, "autoRunEnabledDate": { "type": "string", "description": "Timestamp (ISO 8601) when autoRun was last enabled. Null if autoRun has never been enabled." }, "conditions": { "type": "object", "description": "Optional run conditions for action/lookup columns (free-form JSON). Null when no conditions are configured." }, "loading": { "type": "boolean", "description": "True while a column-wide action is currently executing for this column." }, "created_date": { "type": "string", "description": "Creation timestamp (ISO 8601)" }, "updated_date": { "type": "string", "description": "Last update timestamp (ISO 8601)" }, "deleted_date": { "type": "string", "description": "Soft-delete timestamp (ISO 8601). Null for active columns." } }, "description": "The newly-created column" } }, "description": "Response returned after creating a column" } } } } }, "summary": "Add a lookup column to a list.", "description": "Lookup columns are computed, read-only columns whose values are derived live\n(no writes, no stale data) \u2014 e.g. each row's sequence status or agent\nconversation count. Adding the same lookup type twice is a no-op that\nreturns the existing column. Discover the available lookup types via\nGET /lists/actions (entries that carry a lookupType).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "lookupType": { "type": "string", "description": "The lookup type to add, e.g. \"sequence_status\" or \"agent_conversations\". See LOOKUP_TYPE_* constants / GET /lists/actions." }, "companyId": { "type": "string", "description": "Company ID that owns the list. Required when authenticating with a personal access key (pak_\u2026) \u2014 the key is not tied to a specific company so the server cannot infer it. Required when authenticating with a company API key only if the key belongs to a user who has access to multiple companies; otherwise it defaults to the key's company. Optional for JWT (dashboard) auth \u2014 defaults to the user's active company." } }, "required": [ "lookupType" ], "description": "Request body for adding a lookup column \u2014 a computed, read-only column whose values are derived live (no writes). Discover available lookup types via GET /lists/actions (entries that carry a lookupType)." } } }, "description": "Lookup column to add" } } }, "/api/v0/lists/{listId}/action/run": { "post": { "tags": [ "Lists" ], "operationId": "lists_runTableAction", "parameters": [ { "name": "listId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "List not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Action run started", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "description": "Human-readable success message (typically \"Success\")" } }, "description": "Generic success response" } } } } }, "summary": "Run a table action against some or all rows of a list.", "description": "Pass selectedRows to run on specific rows, or omit it to run on every row.\nThe action runs asynchronously \u2014 poll GET /lists//action//queue-status\n(or re-read the rows) to observe progress.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "actionId": { "type": "string", "description": "ID (UUID) of the action/column to run (from the list headers or actions)." }, "type": { "type": "string", "description": "Action type (see LIST_ACTION_TYPE_* constants). Matches the action's actionType." }, "selectedRows": { "type": "array", "items": { "type": "string" }, "description": "Row IDs (UUIDs) to run the action on. Omit or pass an empty list to run on every row in the list." }, "forceRun": { "type": "boolean", "description": "When true, re-runs the action on rows even if they already have a value / previously ran. Default: false." }, "companyId": { "type": "string", "description": "Company ID that owns the list. Required when authenticating with a personal access key (pak_\u2026) \u2014 the key is not tied to a specific company so the server cannot infer it. Required when authenticating with a company API key only if the key belongs to a user who has access to multiple companies; otherwise it defaults to the key's company. Optional for JWT (dashboard) auth \u2014 defaults to the user's active company." } }, "required": [ "actionId" ], "description": "Request body for running a table action against some or all rows of a list." } } }, "description": "Action to run and target rows" } } }, "/api/v0/lists/{listId}/action/stop": { "post": { "tags": [ "Lists" ], "operationId": "lists_stopTableAction", "parameters": [ { "name": "listId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "List not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Action stopped", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "description": "Human-readable success message (typically \"Success\")" } }, "description": "Generic success response" } } } } }, "summary": "Stop a currently-running table action, cancelling its remaining work.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "actionId": { "type": "string", "description": "ID (UUID) of the action/column to stop." }, "actionType": { "type": "string", "description": "Action type (see LIST_ACTION_TYPE_* constants)." }, "companyId": { "type": "string", "description": "Company ID that owns the list. Required when authenticating with a personal access key (pak_\u2026) \u2014 the key is not tied to a specific company so the server cannot infer it. Required when authenticating with a company API key only if the key belongs to a user who has access to multiple companies; otherwise it defaults to the key's company. Optional for JWT (dashboard) auth \u2014 defaults to the user's active company." } }, "required": [ "actionId" ], "description": "Request body for stopping a currently-running table action." } } }, "description": "Action to stop" } } }, "/api/v0/lists/{listId}/action/{actionId}": { "delete": { "tags": [ "Lists" ], "operationId": "lists_deleteTableAction", "parameters": [ { "name": "listId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "actionId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "actionType", "in": "query", "required": true, "schema": { "type": "string", "description": "Action type (see LIST_ACTION_TYPE_* constants). Required." }, "description": "Action type (see LIST_ACTION_TYPE_* constants). Required." }, { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string", "description": "Company ID that owns the list. Required when authenticating with a personal access key (pak_\u2026) \u2014 the key is not tied to a specific company so the server cannot infer it. Required when authenticating with a company API key only if the key belongs to a user who has access to multiple companies; otherwise it defaults to the key's company. Optional for JWT (dashboard) auth \u2014 defaults to the user's active company." }, "description": "Company ID that owns the list. Required when authenticating with a personal access key (pak_\u2026) \u2014 the key is not tied to a specific company so the server cannot infer it. Required when authenticating with a company API key only if the key belongs to a user who has access to multiple companies; otherwise it defaults to the key's company. Optional for JWT (dashboard) auth \u2014 defaults to the user's active company." } ], "responses": { "400": { "description": "actionType is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "List not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Action deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "description": "Human-readable success message (typically \"Success\")" } }, "description": "Generic success response" } } } } }, "summary": "Delete a table action (and its action column) from a list." } }, "/api/v0/lists/{listId}/action/{actionId}/summary": { "get": { "tags": [ "Lists" ], "operationId": "lists_getActionSummary", "parameters": [ { "name": "listId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "actionId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string", "description": "Company ID that owns the list. Required when authenticating with a personal access key (pak_\u2026) \u2014 the key is not tied to a specific company so the server cannot infer it. Required when authenticating with a company API key only if the key belongs to a user who has access to multiple companies; otherwise it defaults to the key's company. Optional for JWT (dashboard) auth \u2014 defaults to the user's active company." }, "description": "Company ID that owns the list. Required when authenticating with a personal access key (pak_\u2026) \u2014 the key is not tied to a specific company so the server cannot infer it. Required when authenticating with a company API key only if the key belongs to a user who has access to multiple companies; otherwise it defaults to the key's company. Optional for JWT (dashboard) auth \u2014 defaults to the user's active company." } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "List not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Research summary and steps for the action", "content": { "application/json": { "schema": { "type": "object", "properties": { "actionId": { "type": "string", "description": "Action/column ID (UUID)." }, "actionName": { "type": "string", "description": "Action (column) name." }, "actionType": { "type": "string", "description": "Action type (e.g. \"agent\", \"browser_task\"). See LIST_ACTION_TYPE_* constants." }, "rows": { "type": "array", "items": { "type": "object", "properties": { "rowId": { "type": "string", "description": "Row ID (UUID) this research output belongs to." }, "researchSummary": { "type": "string", "description": "The summary the action produced for this row (shape depends on the action type). May be null." }, "researchSteps": { "type": "string", "description": "The recorded research steps for this row (shape depends on the action type). May be an empty list." }, "updatedDate": { "type": "string", "description": "When this row's output was last updated (ISO 8601)." } }, "description": "Research output produced by the action for a single row." }, "description": "Per-row research output. Rows that produced no summary/steps are omitted." }, "createdDate": { "type": "string", "description": "When the action was created (ISO 8601)." }, "updatedDate": { "type": "string", "description": "When the action was last updated (ISO 8601)." } }, "description": "Research output for an agent/browser table action. The action writes a value into each row's cell along with a per-row summary and steps; this response returns those per-row outputs (only rows that produced output are included)." } } } } }, "summary": "Get the research summary and steps produced by an agent/browser action." } }, "/api/v0/lists/{listId}/action/{actionId}/queue-status": { "get": { "tags": [ "Lists" ], "operationId": "lists_getActionQueueStatus", "parameters": [ { "name": "listId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "actionId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "actionType", "in": "query", "required": true, "schema": { "type": "string", "description": "Action type (see LIST_ACTION_TYPE_* constants). Required." }, "description": "Action type (see LIST_ACTION_TYPE_* constants). Required." }, { "name": "includeDetails", "in": "query", "required": false, "schema": { "type": "boolean", "description": "When true, include per-item queue details in addition to the aggregate counts. Default: false.", "default": false }, "description": "When true, include per-item queue details in addition to the aggregate counts. Default: false." }, { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string", "description": "Company ID that owns the list. Required when authenticating with a personal access key (pak_\u2026) \u2014 the key is not tied to a specific company so the server cannot infer it. Required when authenticating with a company API key only if the key belongs to a user who has access to multiple companies; otherwise it defaults to the key's company. Optional for JWT (dashboard) auth \u2014 defaults to the user's active company." }, "description": "Company ID that owns the list. Required when authenticating with a personal access key (pak_\u2026) \u2014 the key is not tied to a specific company so the server cannot infer it. Required when authenticating with a company API key only if the key belongs to a user who has access to multiple companies; otherwise it defaults to the key's company. Optional for JWT (dashboard) auth \u2014 defaults to the user's active company." } ], "responses": { "400": { "description": "actionType is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "List not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Queue processing status for the action", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "integer", "description": "Total number of queued items for this action." }, "pending": { "type": "integer", "description": "Number of items still waiting to be processed." }, "processing": { "type": "integer", "description": "Number of items currently processing." }, "completed": { "type": "integer", "description": "Number of items that finished successfully." }, "failed": { "type": "integer", "description": "Number of items that failed." }, "details": { "type": "array", "items": { "type": "object" }, "description": "Per-item queue details. Present only when includeDetails=true." } }, "description": "Queue-processing status for a table action: aggregate counts of rows in each processing state, plus optional per-item details when includeDetails=true." } } } } }, "summary": "Get the queue-processing status for a table action.", "description": "Returns aggregate counts of how many rows are pending / processing /\ncompleted / failed for this action. Set includeDetails=true to also get\nper-item details. Useful for polling progress after running an action." } }, "/api/v0/lists/{listId}/row": { "put": { "tags": [ "Lists" ], "operationId": "lists_updateRow", "parameters": [ { "name": "listId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "row is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Row updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "description": "Human-readable success message (typically \"Success\")" } }, "description": "Generic success response" } } } } }, "summary": "Update an existing row in a list.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "row": { "type": "object", "description": "Row data object: {\"id\": \"\", \"\": , ...}. Include the row ID and any column values to update. Columns not included are left unchanged." }, "companyId": { "type": "string", "description": "Company ID that owns the list. Required when authenticating with a personal access key (pak_\u2026) \u2014 the key is not tied to a specific company so the server cannot infer it. Required when authenticating with a company API key only if the key belongs to a user who has access to multiple companies; otherwise it defaults to the key's company. Optional for JWT (dashboard) auth \u2014 defaults to the user's active company." } }, "required": [ "row" ], "description": "Request body for updating a row's column values" } } }, "description": "Row data to update" } }, "post": { "tags": [ "Lists" ], "operationId": "lists_addRow", "parameters": [ { "name": "listId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "201": { "description": "Newly-created (empty) row", "content": { "application/json": { "schema": { "type": "object", "properties": { "row": { "type": "object", "properties": { "id": { "type": "string", "description": "Row ID (UUID)" }, "listId": { "type": "string", "description": "Parent list ID (UUID)" }, "columns": { "type": "array", "items": { "type": "object" }, "description": "Initial column values (empty for a brand-new row)" }, "created_date": { "type": "string", "description": "Creation timestamp (ISO 8601)" }, "updated_date": { "type": "string", "description": "Last update timestamp (ISO 8601)" }, "deleted_date": { "type": "string", "description": "Soft-delete timestamp (ISO 8601). Null for an active row." } }, "description": "The newly-created (empty) row" } }, "description": "Response returned after adding a single empty row" } } } } }, "summary": "Add a new empty row to a list.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID that owns the list. Required when authenticating with a personal access key (pak_\u2026) \u2014 the key is not tied to a specific company so the server cannot infer it. Required when authenticating with a company API key only if the key belongs to a user who has access to multiple companies; otherwise it defaults to the key's company. Optional for JWT (dashboard) auth \u2014 defaults to the user's active company." } }, "description": "Optional request body for creating a single empty row. All fields are optional." } } }, "description": "Optional body. Only companyId is consumed; row data should be sent via PUT /lists//row after creation, or use POST /lists//rows to add rows with data in one call." } } }, "/api/v0/lists/{listId}/row/{rowId}/history": { "get": { "tags": [ "Lists" ], "operationId": "lists_getRowHistory", "parameters": [ { "name": "listId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "rowId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Row not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Get the change history for a single row." } }, "/api/v0/lists/{listId}/header": { "post": { "tags": [ "Lists" ], "operationId": "lists_addHeader", "parameters": [ { "name": "listId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string", "description": "Company ID that owns the list. Required when authenticating with a personal access key (pak_\u2026) \u2014 the key is not tied to a specific company so the server cannot infer it. Required when authenticating with a company API key only if the key belongs to a user who has access to multiple companies; otherwise it defaults to the key's company. Optional for JWT (dashboard) auth \u2014 defaults to the user's active company." }, "description": "Company ID that owns the list. Required when authenticating with a personal access key (pak_\u2026) \u2014 the key is not tied to a specific company so the server cannot infer it. Required when authenticating with a company API key only if the key belongs to a user who has access to multiple companies; otherwise it defaults to the key's company. Optional for JWT (dashboard) auth \u2014 defaults to the user's active company." } ], "responses": { "400": { "description": "name is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "201": { "description": "Column created", "content": { "application/json": { "schema": { "type": "object", "properties": { "header": { "type": "object", "properties": { "id": { "type": "string", "description": "Column ID (UUID)" }, "listId": { "type": "string", "description": "Parent list ID (UUID)" }, "name": { "type": "string", "description": "Column name" }, "type": { "type": "string", "description": "Column type. Data types: text, long_text, url, image, email, phone, linkedin_url. Action types (server-managed): action, lookup, etc." }, "dataType": { "type": "string", "description": "Underlying data type used for storage and validation (e.g., string, number, boolean, json)" }, "order": { "type": "number", "description": "Display order within the list (smaller values appear first)" }, "actionParameters": { "type": "object", "description": "Parameters for action/lookup columns. Null for plain data columns." }, "autoRunEnabled": { "type": "boolean", "description": "For action/lookup columns: whether the action runs automatically on new rows." }, "autoRunEnabledDate": { "type": "string", "description": "Timestamp (ISO 8601) when autoRun was last enabled. Null if autoRun has never been enabled." }, "conditions": { "type": "object", "description": "Optional run conditions for action/lookup columns (free-form JSON). Null when no conditions are configured." }, "loading": { "type": "boolean", "description": "True while a column-wide action is currently executing for this column." }, "created_date": { "type": "string", "description": "Creation timestamp (ISO 8601)" }, "updated_date": { "type": "string", "description": "Last update timestamp (ISO 8601)" }, "deleted_date": { "type": "string", "description": "Soft-delete timestamp (ISO 8601). Null for active columns." } }, "description": "The newly-created column" } }, "description": "Response returned after creating a column" } } } } }, "summary": "Add a new column to a list.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Column name. The server sanitizes this \u2014 it must be unique within the list." }, "companyId": { "type": "string", "description": "Company ID that owns the list. Required when authenticating with a personal access key (pak_\u2026) \u2014 the key is not tied to a specific company so the server cannot infer it. Required when authenticating with a company API key only if the key belongs to a user who has access to multiple companies; otherwise it defaults to the key's company. Optional for JWT (dashboard) auth \u2014 defaults to the user's active company. Also accepted via the companyId query parameter." } }, "required": [ "name" ], "description": "Request body for creating a column" } } }, "description": "Column data" } } }, "/api/v0/lists/{listId}/header/{headerId}": { "delete": { "tags": [ "Lists" ], "operationId": "lists_deleteHeader", "parameters": [ { "name": "listId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "headerId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string", "description": "Company ID that owns the list. Required when authenticating with a personal access key (pak_\u2026) \u2014 the key is not tied to a specific company so the server cannot infer it. Required when authenticating with a company API key only if the key belongs to a user who has access to multiple companies; otherwise it defaults to the key's company. Optional for JWT (dashboard) auth \u2014 defaults to the user's active company." }, "description": "Company ID that owns the list. Required when authenticating with a personal access key (pak_\u2026) \u2014 the key is not tied to a specific company so the server cannot infer it. Required when authenticating with a company API key only if the key belongs to a user who has access to multiple companies; otherwise it defaults to the key's company. Optional for JWT (dashboard) auth \u2014 defaults to the user's active company." } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Column deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "description": "Human-readable success message (typically \"Success\")" } }, "description": "Generic success response" } } } } }, "summary": "Delete a column from a list." }, "put": { "tags": [ "Lists" ], "operationId": "lists_editHeader", "parameters": [ { "name": "listId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "headerId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string", "description": "Company ID that owns the list. Required when authenticating with a personal access key (pak_\u2026) \u2014 the key is not tied to a specific company so the server cannot infer it. Required when authenticating with a company API key only if the key belongs to a user who has access to multiple companies; otherwise it defaults to the key's company. Optional for JWT (dashboard) auth \u2014 defaults to the user's active company." }, "description": "Company ID that owns the list. Required when authenticating with a personal access key (pak_\u2026) \u2014 the key is not tied to a specific company so the server cannot infer it. Required when authenticating with a company API key only if the key belongs to a user who has access to multiple companies; otherwise it defaults to the key's company. Optional for JWT (dashboard) auth \u2014 defaults to the user's active company." } ], "responses": { "400": { "description": "type is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Column updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "description": "Human-readable success message (typically \"Success\")" } }, "description": "Generic success response" } } } } }, "summary": "Update a column type in a list.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "Column type. One of: text, long_text, url, image, email, phone, linkedin_url." }, "companyId": { "type": "string", "description": "Company ID that owns the list. Required when authenticating with a personal access key (pak_\u2026) \u2014 the key is not tied to a specific company so the server cannot infer it. Required when authenticating with a company API key only if the key belongs to a user who has access to multiple companies; otherwise it defaults to the key's company. Optional for JWT (dashboard) auth \u2014 defaults to the user's active company. Also accepted via the companyId query parameter." } }, "required": [ "type" ], "description": "Request body for updating a column" } } }, "description": "Column type" } } }, "/api/v0/lists/{listId}/delete": { "post": { "tags": [ "Lists" ], "operationId": "lists_deleteRows", "parameters": [ { "name": "listId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "rowIds is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Rows deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "description": "Human-readable success message (typically \"Success\")" } }, "description": "Generic success response" } } } } }, "summary": "Delete multiple rows from a list.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "rowIds": { "type": "array", "items": { "type": "string" }, "description": "Array of row IDs (UUIDs) to soft-delete from the list" }, "companyId": { "type": "string", "description": "Company ID that owns the list. Required when authenticating with a personal access key (pak_\u2026) \u2014 the key is not tied to a specific company so the server cannot infer it. Required when authenticating with a company API key only if the key belongs to a user who has access to multiple companies; otherwise it defaults to the key's company. Optional for JWT (dashboard) auth \u2014 defaults to the user's active company." } }, "required": [ "rowIds" ], "description": "Request body for deleting rows" } } }, "description": "Rows to delete" } } }, "/api/v0/lists/{listId}/deduplicate": { "post": { "tags": [ "Lists" ], "operationId": "lists_deduplicateRows", "parameters": [ { "name": "listId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "columnNames required / unknown column / bad strategy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "List not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "202": { "description": "Deduplication started in the background", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Always \"background\" \u2014 the work runs asynchronously." }, "taskId": { "type": "string", "description": "ID (UUID) of the background task. Poll its status with GET /lists/tasks/{taskId} (operation lists_getTaskStatus) until status is \"completed\", \"failed\", or \"cancelled\"." }, "message": { "type": "string", "description": "Human-readable status message." } }, "description": "Acknowledgement that deduplication has started in the background." } } } } }, "summary": "Deduplicate rows by the combined value of one or more columns.", "description": "Rows are grouped by their values in `columnNames`; within each group the\noldest row is kept and the newer duplicates are removed (\"delete\") or have\ntheir values merged into the kept row first (\"merge\"). Every name in\n`columnNames` must be an existing column on the list \u2014 unknown columns\nreturn 400 with the list of valid columns. Runs asynchronously: responds\n202 with a taskId.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "columnNames": { "type": "array", "items": { "type": "string" }, "description": "Column NAMES (as in the list headers) whose combined value identifies a duplicate. Must be non-empty, and every name must exist on the list (else 400)." }, "strategy": { "type": "string", "description": "How to handle duplicates: \"delete\" (soft-delete the newer duplicates, default) or \"merge\" (combine field values into the kept row before deleting the others).", "default": "delete" }, "companyId": { "type": "string", "description": "Company ID that owns the list. Required when authenticating with a personal access key (pak_\u2026) \u2014 the key is not tied to a specific company so the server cannot infer it. Required when authenticating with a company API key only if the key belongs to a user who has access to multiple companies; otherwise it defaults to the key's company. Optional for JWT (dashboard) auth \u2014 defaults to the user's active company." } }, "required": [ "columnNames" ], "description": "Request body for deduplicating a list. Rows are grouped by their combined values in `columnNames`; within each duplicate group the OLDEST row is kept. All names in `columnNames` must be existing columns on the list \u2014 an unknown column returns 400. Runs asynchronously and responds 202 with a taskId." } } }, "description": "Columns to dedupe on and strategy" } } }, "/api/v0/lists/{listId}/import/linkedin-post": { "post": { "tags": [ "Lists" ], "operationId": "lists_importLinkedInPost", "parameters": [ { "name": "listId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "postUrl is required / invalid LinkedIn post URL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "List not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "202": { "description": "Import started in the background \u2014 poll the task for progress", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Always \"background\" \u2014 the import runs asynchronously." }, "taskId": { "type": "string", "description": "Background task ID (UUID) to poll for progress and the final result." }, "message": { "type": "string", "description": "Human-readable note that the import started." } }, "description": "Acknowledgement that a LinkedIn post import started in the background. Poll the background task by `taskId` until it reaches a terminal status; the completed task's `result` holds `imported` (rows inserted or enriched) and a `postData` summary (authorName, likesCount, commentsCount)." } } } } }, "summary": "Start importing the people who engaged with a LinkedIn post into a smart list.", "description": "Returns immediately with a background task ID; the scrape and import run\nasynchronously. Poll `GET /lists/{listId}/tasks` until the task reaches a\nterminal status \u2014 its `result` holds `imported` and the post summary\n(authorName, likesCount, commentsCount).\n\nScrapes the post's commenters and likers and adds each person to the list as\na lead row (firstName, lastName, linkedinUrl, headline, positionTitle,\ncompanyName, plus engagementType, commentText, sourcePostUrl and postAuthor).\nSomeone who both commented and liked is recorded once with engagementType\n\"commented_and_liked\".\n\nPeople already on the list are matched on linkedinUrl and enriched in place \u2014\nonly their empty fields are filled \u2014 so re-importing the same post does not\ncreate duplicates.\n\n`postUrl` must be a linkedin.com/posts/\u2026 or linkedin.com/feed/update/\u2026 URL;\nquery parameters are stripped.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "postUrl": { "type": "string", "description": "Full URL of the LinkedIn post. Must be a linkedin.com/posts/\u2026 or linkedin.com/feed/update/\u2026 URL; query parameters are stripped automatically." }, "companyId": { "type": "string", "description": "Company ID that owns the list. Required when authenticating with a personal access key (pak_\u2026) \u2014 the key is not tied to a specific company so the server cannot infer it. Required when authenticating with a company API key only if the key belongs to a user who has access to multiple companies; otherwise it defaults to the key's company. Optional for JWT (dashboard) auth \u2014 defaults to the user's active company." } }, "required": [ "postUrl" ], "description": "Request body for importing a LinkedIn post's engagers into a smart list. Scrapes the post's commenters and likers and adds each person as a lead row (firstName, lastName, linkedinUrl, headline, engagementType, commentText, \u2026). People already on the list \u2014 matched on linkedinUrl \u2014 are enriched in place rather than duplicated. Returns immediately with a background task ID; the scrape and import run asynchronously and can take a minute or two on a busy post. Costs 10 credits per call." } } }, "description": "LinkedIn post to import engagers from" } } }, "/api/v0/lead-searches/sales-navigator": { "post": { "tags": [ "Lists" ], "operationId": "lists_searchSalesNavigator", "parameters": [], "responses": { "400": { "description": "Invalid search \u2014 missing searchUrl, no filters set, or maxResults out of range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient data credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "202": { "description": "Search accepted \u2014 poll GET /lead-searches/{searchId} for results", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Always 'pending' \u2014 the search has started and has not finished yet." }, "searchId": { "type": "string", "description": "ID of the saved search. Poll GET /lead-searches/{searchId} with this to get the status and, once complete, the leads." }, "dataCredits": { "type": "number", "description": "The billing principal's data credit balance. The search has not been charged yet \u2014 leads are charged when it finishes." }, "priorityFields": { "type": "array", "items": { "type": "string" }, "description": "Field names to show first, in order, when rendering the results as a table." } }, "description": "A Sales Navigator search that has been accepted and is now running. The leads are NOT in this response: poll GET /lead-searches/{searchId} until its status is no longer 'pending', then read them from that response's `results`. Do not call the search endpoint again while a search is pending \u2014 each call runs and charges for a new search, while polling costs nothing." } } } } }, "summary": "Start a Sales Navigator search. Returns immediately with a search id.", "description": "**The search runs in the background \u2014 this does NOT return the leads.** It\nresponds 202 with a `searchId`; poll `GET /lead-searches/{searchId}` until\nits `status` is no longer \"pending\", then read the leads from `results`.\nA search takes minutes, because each matching profile is enriched\nindividually upstream.\n\n**Do not retry this endpoint while a search is pending.** Every call starts\na new search and charges for it again; polling the id you already have is\nfree. If a call appears to time out, the search is still running \u2014 find it\nin `GET /lead-searches?source=sales_navigator` rather than re-running it.\n\nNothing is written to a smart list: the caller reviews the results and adds\nthe ones it wants through `POST /lists/{listId}/rows`, which is what the\ndashboard does once the user has picked rows.\n\nThe search is specified either by a Sales Navigator people-search URL\n(`searchMode` \"url\") or by structured filters \u2014 jobTitle, location,\ncurrentCompany, school, keywords (`searchMode` \"filters\"). Each result is a\nlead row (firstName, lastName, linkedinUrl, headline, positionTitle,\ncompanyName, location, \u2026) ready to be added to a list as-is.\n\nNo LinkedIn account or session cookie is required: the search is resolved\nfrom public profile data.\n\nCosts 1 data credit per lead returned, charged when the search finishes \u2014\nthe same balance enrichment and People Search draw from. A search that\nmatches nobody or fails is free. Credits are checked against the requested\nceiling before the search starts.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "searchMode": { "type": "string", "description": "How the search is specified: 'url' to use searchUrl, 'filters' to use filters. Default: 'url'.", "enum": [ "url", "filters" ], "default": "url" }, "searchUrl": { "type": "string", "description": "Full Sales Navigator people-search URL (a linkedin.com/sales/search/people\u2026 link). Required when searchMode is 'url'." }, "filters": { "type": "object", "properties": { "jobTitle": { "type": "string", "description": "Job title to match, e.g. \"VP of Sales\"." }, "location": { "type": "string", "description": "City, region or country, e.g. \"London\"." }, "currentCompany": { "type": "string", "description": "Current employer name, e.g. \"Stripe\"." }, "school": { "type": "string", "description": "School or university attended." }, "keywords": { "type": "string", "description": "Free-text keywords to match anywhere on the profile." } }, "description": "Structured search filters. Required when searchMode is 'filters' \u2014 at least one filter must be non-empty." }, "maxResults": { "type": "integer", "description": "Maximum leads to return (1-500). Data credits are reserved against this ceiling but only the leads actually returned are charged. Default: 50.", "default": 50 }, "companyId": { "type": "string", "description": "Company ID that owns the list. Required when authenticating with a personal access key (pak_\u2026) \u2014 the key is not tied to a specific company so the server cannot infer it. Required when authenticating with a company API key only if the key belongs to a user who has access to multiple companies; otherwise it defaults to the key's company. Optional for JWT (dashboard) auth \u2014 defaults to the user's active company." } }, "description": "Request body for a Sales Navigator lead search. Either paste a Sales Navigator people-search URL (searchMode 'url') or supply structured filters (searchMode 'filters'). The search runs in the background: the response carries a searchId to poll, not the leads. Nothing is written to a smart list \u2014 once the search completes, add the leads you want with POST /lists/{listId}/rows. No LinkedIn account or session cookie is required. Costs 1 data credit per lead returned, charged when the search finishes \u2014 the same balance enrichment and People Search draw from; a search that matches nobody is free." } } }, "description": "Sales Navigator search to run" } } }, "/api/v0/lead-searches": { "get": { "tags": [ "Lists" ], "operationId": "lists_getLeadSearches", "parameters": [ { "name": "source", "in": "query", "required": false, "schema": { "type": "string", "description": "Only return searches from this surface. One of: sales_navigator, enrichment, people_search. Omit for all.", "enum": [ "sales_navigator", "enrichment", "people_search" ] }, "description": "Only return searches from this surface. One of: sales_navigator, enrichment, people_search. Omit for all." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Page number (default: 1)", "default": 1 }, "description": "Page number (default: 1)" }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "description": "Items per page (default: 20, max: 100)", "default": 20 }, "description": "Items per page (default: 20, max: 100)" }, { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string", "description": "Company ID that owns the list. Required when authenticating with a personal access key (pak_\u2026) \u2014 the key is not tied to a specific company so the server cannot infer it. Required when authenticating with a company API key only if the key belongs to a user who has access to multiple companies; otherwise it defaults to the key's company. Optional for JWT (dashboard) auth \u2014 defaults to the user's active company." }, "description": "Company ID that owns the list. Required when authenticating with a personal access key (pak_\u2026) \u2014 the key is not tied to a specific company so the server cannot infer it. Required when authenticating with a company API key only if the key belongs to a user who has access to multiple companies; otherwise it defaults to the key's company. Optional for JWT (dashboard) auth \u2014 defaults to the user's active company." } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "The saved searches, newest first", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Search ID (UUID)." }, "source": { "type": "string", "description": "Which surface ran the search. One of: sales_navigator, enrichment, people_search." }, "label": { "type": "string", "description": "Short human-readable summary of the query." }, "query": { "type": "object", "description": "The search as it was submitted, in the shape that surface accepts \u2014 enough to run it again." }, "status": { "type": "string", "description": "Where the search is up to. One of: pending, complete, failed. 'pending' means it is still running \u2014 poll until it changes. 'complete' means `results` is final (possibly empty, if nothing matched). 'failed' means it did not run to completion and nothing was charged; see `error`.", "enum": [ "pending", "complete", "failed" ] }, "error": { "type": "string", "description": "Why the search failed. Null unless status is 'failed'." }, "resultCount": { "type": "integer", "description": "How many results the search returned. May exceed the number of rows stored for very large searches." }, "creditsCharged": { "type": "integer", "description": "Data credits charged for this search." }, "createdBy": { "type": "string", "description": "User ID of whoever ran the search." }, "createdDate": { "type": "string", "description": "ISO 8601 timestamp of when the search ran." } }, "description": "A saved lead search, without its result rows. The listing carries only what a history panel needs; fetch the search by id to get its results." }, "description": "The saved searches on this page." }, "total": { "type": "integer", "description": "Total saved searches matching the filter." }, "page": { "type": "integer", "description": "Current page number." }, "pageSize": { "type": "integer", "description": "Items per page." } }, "description": "A page of the company's saved lead searches, newest first" } } } } }, "summary": "List saved lead searches for the company, newest first.", "description": "Result rows are omitted here \u2014 the listing carries the label, result count\nand cost so a history panel can render without pulling every stored row.\nFetch a single search by id to get its results back.\n\nFilter by `source` (\"sales_navigator\", \"enrichment\" or \"people_search\") to show one surface's\nhistory." } }, "/api/v0/lead-searches/{searchId}": { "get": { "tags": [ "Lists" ], "operationId": "lists_getLeadSearchDetail", "parameters": [ { "name": "searchId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string", "description": "Company ID that owns the list. Required when authenticating with a personal access key (pak_\u2026) \u2014 the key is not tied to a specific company so the server cannot infer it. Required when authenticating with a company API key only if the key belongs to a user who has access to multiple companies; otherwise it defaults to the key's company. Optional for JWT (dashboard) auth \u2014 defaults to the user's active company." }, "description": "Company ID that owns the list. Required when authenticating with a personal access key (pak_\u2026) \u2014 the key is not tied to a specific company so the server cannot infer it. Required when authenticating with a company API key only if the key belongs to a user who has access to multiple companies; otherwise it defaults to the key's company. Optional for JWT (dashboard) auth \u2014 defaults to the user's active company." } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Search not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "The saved search and its results", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Search ID (UUID)." }, "source": { "type": "string", "description": "Which surface ran the search. One of: sales_navigator, enrichment, people_search." }, "label": { "type": "string", "description": "Short human-readable summary of the query." }, "query": { "type": "object", "description": "The search as it was submitted, in the shape that surface accepts \u2014 enough to run it again." }, "status": { "type": "string", "description": "Where the search is up to. One of: pending, complete, failed. 'pending' means it is still running \u2014 poll until it changes. 'complete' means `results` is final (possibly empty, if nothing matched). 'failed' means it did not run to completion and nothing was charged; see `error`.", "enum": [ "pending", "complete", "failed" ] }, "error": { "type": "string", "description": "Why the search failed. Null unless status is 'failed'." }, "resultCount": { "type": "integer", "description": "How many results the search returned. May exceed the number of rows stored for very large searches." }, "creditsCharged": { "type": "integer", "description": "Data credits charged for this search." }, "createdBy": { "type": "string", "description": "User ID of whoever ran the search." }, "createdDate": { "type": "string", "description": "ISO 8601 timestamp of when the search ran." }, "results": { "type": "array", "items": { "type": "object" }, "description": "The stored result rows. Empty while status is 'pending'." }, "fieldLabels": { "type": "object", "description": "Display label for each field present in the results, for use as table column headers." }, "priorityFields": { "type": "array", "items": { "type": "string" }, "description": "Field names to show first, in order, when rendering the results as a table." } }, "description": "A saved lead search and the rows it returned, exactly as returned. Each row's keys are smart-list field names, so a selection can be posted straight to POST /lists/{listId}/rows with createColumns=true \u2014 no need to pay to run the search again. This is also the endpoint to poll while a search is running: check `status`, and treat `results` as final only once it is 'complete'." } } } } }, "summary": "Fetch one saved lead search, including the results it returned.", "description": "The results are returned exactly as they were when the search ran, so they\ncan be reviewed and added to a list without paying to run the search again." }, "delete": { "tags": [ "Lists" ], "operationId": "lists_deleteLeadSearch", "parameters": [ { "name": "searchId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string", "description": "Company ID that owns the list. Required when authenticating with a personal access key (pak_\u2026) \u2014 the key is not tied to a specific company so the server cannot infer it. Required when authenticating with a company API key only if the key belongs to a user who has access to multiple companies; otherwise it defaults to the key's company. Optional for JWT (dashboard) auth \u2014 defaults to the user's active company." }, "description": "Company ID that owns the list. Required when authenticating with a personal access key (pak_\u2026) \u2014 the key is not tied to a specific company so the server cannot infer it. Required when authenticating with a company API key only if the key belongs to a user who has access to multiple companies; otherwise it defaults to the key's company. Optional for JWT (dashboard) auth \u2014 defaults to the user's active company." } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Search not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Search removed from the history", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "description": "Human-readable success message (typically \"Success\")" } }, "description": "Generic success response" } } } } }, "summary": "Remove a saved lead search from the history.", "description": "Soft delete \u2014 the stored results are kept, so dismissing a search from the\npanel never destroys data the company paid for." } }, "/api/v0/lead-searches/{searchId}/import": { "post": { "tags": [ "Lists" ], "operationId": "lists_importLeadSearch", "parameters": [ { "name": "searchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "listId is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Search or list not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "The leads imported into the list", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Always \"ok\" for a successful import." }, "found": { "type": "integer", "description": "Stored results selected for import." }, "imported": { "type": "integer", "description": "Rows inserted or enriched in place on the list." }, "failed": { "type": "integer", "description": "Results that could not be written to the list." }, "searchId": { "type": "string", "description": "The saved search that was imported." }, "source": { "type": "string", "description": "Which surface produced the search. One of: sales_navigator, enrichment, people_search." } }, "description": "Outcome of importing a saved lead search into a smart list" } } } } }, "summary": "Import a saved search's results into a smart list \u2014 free.", "description": "Works for any saved search, whichever surface produced it (a Sales Navigator\nsearch or an enrichment lookup). The results were stored when the search ran\nand were paid for then, so this reuses them and **charges nothing** rather\nthan asking the vendor for the same leads twice.\n\nPeople already on the list are matched on linkedinUrl and enriched in place \u2014\nonly their empty fields are filled \u2014 so importing the same search twice does\nnot create duplicates. Missing columns are created automatically.\n\nPass `rowIndexes` to import only some of the results (0-based, indexing into\nthe search's stored `results`); omit it to import all of them.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "listId": { "type": "string", "description": "Smart list ID (UUID) to import the results into." }, "rowIndexes": { "type": "array", "items": { "type": "integer" }, "description": "Optional 0-based indexes into the search's stored `results`, to import only some of them. Omit to import every stored result." }, "companyId": { "type": "string", "description": "Company ID that owns the list. Required when authenticating with a personal access key (pak_\u2026) \u2014 the key is not tied to a specific company so the server cannot infer it. Required when authenticating with a company API key only if the key belongs to a user who has access to multiple companies; otherwise it defaults to the key's company. Optional for JWT (dashboard) auth \u2014 defaults to the user's active company." } }, "required": [ "listId" ], "description": "Request body for importing a saved lead search into a smart list. Works for any saved search, whichever surface produced it (Sales Navigator or enrichment). The results were paid for when the search ran, so this reuses them and charges nothing. People already on the list \u2014 matched on linkedinUrl \u2014 are enriched in place rather than duplicated, and missing columns are created automatically." } } }, "description": "Where to import the saved search results" } } }, "/api/v0/lists/tasks/{taskId}": { "get": { "tags": [ "Lists" ], "operationId": "lists_getTaskStatus", "parameters": [ { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Task not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Current status of the background task", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Task ID (UUID) \u2014 the taskId returned by the operation that started the task." }, "companyId": { "type": "string", "description": "Company that owns the task." }, "userId": { "type": "string", "description": "User who started the task." }, "listId": { "type": "string", "description": "List the task operates on (UUID), if any." }, "actionId": { "type": "string", "description": "Action the task relates to (UUID), if any." }, "taskType": { "type": "string", "description": "Kind of task, e.g. \"Deduplicate\", \"import\", \"people_search\"." }, "status": { "type": "string", "description": "Current status: \"pending\", \"running\", \"completed\", \"failed\", or \"cancelled\". The first two are non-terminal \u2014 keep polling; the last three are terminal." }, "totalItems": { "type": "integer", "description": "Total items the task will process (0 until known)." }, "processedItems": { "type": "integer", "description": "Items processed so far." }, "successItems": { "type": "integer", "description": "Items processed successfully." }, "failedItems": { "type": "integer", "description": "Items that failed." }, "progressPercentage": { "type": "number", "description": "processedItems / totalItems as a percentage (0 when total is unknown)." }, "progressMessage": { "type": "string", "description": "Human-readable progress note." }, "errorMessage": { "type": "string", "description": "Error detail when status is \"failed\"." }, "result": { "type": "string", "description": "Task-specific result payload, populated when completed (shape depends on taskType)." }, "taskMetadata": { "type": "string", "description": "Task-specific input/config (e.g. the columnNames a dedup ran on)." }, "nodeId": { "type": "string", "description": "Server node processing the task." }, "createdDate": { "type": "string", "description": "When the task was created (ISO 8601)." }, "startedDate": { "type": "string", "description": "When processing began (ISO 8601), if started." }, "completedDate": { "type": "string", "description": "When the task finished (ISO 8601), if terminal." }, "updatedDate": { "type": "string", "description": "Last update (ISO 8601)." } }, "description": "Status of an asynchronous background task (e.g. a deduplication or import). Poll until `status` is a terminal value: \"completed\", \"failed\", or \"cancelled\" (non-terminal: \"pending\", \"running\")." } } } } }, "summary": "Get the status of a background task by its taskId.", "description": "Use this to poll an asynchronous operation (e.g. deduplication) that\nreturned a taskId. Re-fetch until `status` is terminal \u2014 \"completed\",\n\"failed\", or \"cancelled\" (\"pending\" and \"running\" mean keep polling.)" } }, "/api/v0/lists/{listId}/move-to-sequence": { "post": { "tags": [ "Lists" ], "operationId": "lists_moveRowsToSequence", "parameters": [ { "name": "listId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "rowIds and sequenceId are required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "List or sequence not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Move result", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "description": "Human-readable success message" }, "addedCount": { "type": "integer", "description": "Number of rows successfully added to the target" }, "failedCount": { "type": "integer", "description": "Number of rows that failed to move" }, "failedRows": { "type": "array", "items": { "type": "object", "properties": { "rowId": { "type": "string", "description": "ID of the row that failed" }, "error": { "type": "string", "description": "Reason for the failure" } }, "description": "Information about a row that failed to move" }, "description": "Per-row failure details" }, "removedFromList": { "type": "boolean", "description": "True if rows were removed from the source list (only set when removeFromList=true was requested and at least one row was moved successfully)" } }, "description": "Result of a move-to-list or move-to-sequence operation" } } } } }, "summary": "Move multiple rows from a list to a sequence.", "description": "Adds the specified rows to a sequence as new members. Optionally\nremoves them from the source list and applies custom field mappings.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "rowIds": { "type": "array", "items": { "type": "string" }, "description": "Array of row IDs (UUIDs) to move" }, "sequenceId": { "type": "string", "description": "Target sequence ID (UUID). Must belong to the same company as the list." }, "removeFromList": { "type": "boolean", "description": "If true, successfully moved rows are deleted from the source list after being added to the sequence. Default: false (copy).", "default": false }, "fieldMappings": { "type": "object", "description": "Optional custom field mappings: {\"email\"?: string, \"phone\"?: string, \"linkedinUrl\"?: string}. Maps list column names to the corresponding sequence member fields." }, "companyId": { "type": "string", "description": "Company ID that owns the list. Required when authenticating with a personal access key (pak_\u2026) \u2014 the key is not tied to a specific company so the server cannot infer it. Required when authenticating with a company API key only if the key belongs to a user who has access to multiple companies; otherwise it defaults to the key's company. Optional for JWT (dashboard) auth \u2014 defaults to the user's active company." } }, "required": [ "rowIds", "sequenceId" ], "description": "Request body for moving rows from a list to a sequence" } } }, "description": "Move operation data" } } }, "/api/v0/lists/{listId}/move-to-list": { "post": { "tags": [ "Lists" ], "operationId": "lists_moveRowsToList", "parameters": [ { "name": "listId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "rowIds and targetListId are required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Move result", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "description": "Human-readable success message" }, "addedCount": { "type": "integer", "description": "Number of rows successfully added to the target" }, "failedCount": { "type": "integer", "description": "Number of rows that failed to move" }, "failedRows": { "type": "array", "items": { "type": "object", "properties": { "rowId": { "type": "string", "description": "ID of the row that failed" }, "error": { "type": "string", "description": "Reason for the failure" } }, "description": "Information about a row that failed to move" }, "description": "Per-row failure details" }, "removedFromList": { "type": "boolean", "description": "True if rows were removed from the source list (only set when removeFromList=true was requested and at least one row was moved successfully)" } }, "description": "Result of a move-to-list or move-to-sequence operation" } } } } }, "summary": "Move multiple rows from a list to another list.", "description": "Copies the specified rows to a target list. Optionally removes\nthem from the source list.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "rowIds": { "type": "array", "items": { "type": "string" }, "description": "Array of row IDs (UUIDs) to move" }, "targetListId": { "type": "string", "description": "Target list ID (UUID). Must belong to the same company as the source list, and must not equal the source listId." }, "removeFromList": { "type": "boolean", "description": "If true, successfully moved rows are deleted from the source list after being copied. Default: false (copy).", "default": false }, "companyId": { "type": "string", "description": "Company ID that owns the list. Required when authenticating with a personal access key (pak_\u2026) \u2014 the key is not tied to a specific company so the server cannot infer it. Required when authenticating with a company API key only if the key belongs to a user who has access to multiple companies; otherwise it defaults to the key's company. Optional for JWT (dashboard) auth \u2014 defaults to the user's active company." } }, "required": [ "rowIds", "targetListId" ], "description": "Request body for moving rows from one list to another" } } }, "description": "Move operation data" } } }, "/api/v0/public/lists/{listId}": { "get": { "tags": [ "Lists" ], "operationId": "lists_getPublicListMetadata", "parameters": [ { "name": "listId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "404": { "description": "List not found or not public", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Public smart list metadata and column headers", "content": { "application/json": { "schema": { "type": "object", "properties": { "list": { "type": "object", "properties": { "id": { "type": "string", "description": "List ID (UUID)" }, "name": { "type": "string", "description": "List name" }, "type": { "type": "string", "description": "List type: leads, companies, or custom" }, "headers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Column ID (UUID)" }, "listId": { "type": "string", "description": "Parent list ID (UUID)" }, "name": { "type": "string", "description": "Column name" }, "type": { "type": "string", "description": "Column type. Data types: text, long_text, url, image, email, phone, linkedin_url. Action types (server-managed): action, lookup, etc." }, "dataType": { "type": "string", "description": "Underlying data type used for storage and validation (e.g., string, number, boolean, json)" }, "order": { "type": "number", "description": "Display order within the list (smaller values appear first)" }, "actionParameters": { "type": "object", "description": "Parameters for action/lookup columns. Null for plain data columns." }, "autoRunEnabled": { "type": "boolean", "description": "For action/lookup columns: whether the action runs automatically on new rows." }, "autoRunEnabledDate": { "type": "string", "description": "Timestamp (ISO 8601) when autoRun was last enabled. Null if autoRun has never been enabled." }, "conditions": { "type": "object", "description": "Optional run conditions for action/lookup columns (free-form JSON). Null when no conditions are configured." }, "loading": { "type": "boolean", "description": "True while a column-wide action is currently executing for this column." }, "created_date": { "type": "string", "description": "Creation timestamp (ISO 8601)" }, "updated_date": { "type": "string", "description": "Last update timestamp (ISO 8601)" }, "deleted_date": { "type": "string", "description": "Soft-delete timestamp (ISO 8601). Null for active columns." } }, "description": "Column (header) on a list" }, "description": "Column definitions" }, "created_date": { "type": "string", "description": "Creation timestamp (ISO 8601)" }, "updated_date": { "type": "string", "description": "Last update timestamp (ISO 8601)" } }, "description": "Public list metadata" } }, "description": "Public smart list metadata response" } } } } }, "summary": "Get a public smart list's metadata and column definitions (no auth required)." } }, "/api/v0/public/lists/{listId}/rows": { "get": { "tags": [ "Lists" ], "operationId": "lists_getPublicListRows", "parameters": [ { "name": "listId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "1-indexed page number (default: 1)", "default": 1 }, "description": "1-indexed page number (default: 1)" }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "description": "Rows per page (default: 50, max: 100)", "default": 50 }, "description": "Rows per page (default: 50, max: 100)" }, { "name": "sortField", "in": "query", "required": false, "schema": { "type": "string", "description": "Column name to sort by, or the reserved value \"dateAdded\" to sort by row creation time. Defaults to \"dateAdded\"." }, "description": "Column name to sort by, or the reserved value \"dateAdded\" to sort by row creation time. Defaults to \"dateAdded\"." }, { "name": "sortOrder", "in": "query", "required": false, "schema": { "type": "string", "description": "Sort order: asc or desc. Defaults to \"desc\" so the most recently added rows are returned first.", "default": "desc" }, "description": "Sort order: asc or desc. Defaults to \"desc\" so the most recently added rows are returned first." }, { "name": "searchQuery", "in": "query", "required": false, "schema": { "type": "string", "description": "Substring to match within row values" }, "description": "Substring to match within row values" }, { "name": "searchField", "in": "query", "required": false, "schema": { "type": "string", "description": "Column name to restrict search to. Use \"all\" or omit to search across all columns." }, "description": "Column name to restrict search to. Use \"all\" or omit to search across all columns." }, { "name": "filterModel", "in": "query", "required": false, "schema": { "type": "string", "description": "JSON-encoded MUI DataGrid filter model. Operators: contains, equals, startsWith, endsWith, notEquals, isEmpty, isNotEmpty." }, "description": "JSON-encoded MUI DataGrid filter model. Operators: contains, equals, startsWith, endsWith, notEquals, isEmpty, isNotEmpty." } ], "responses": { "404": { "description": "List not found or not public", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Paginated rows of a public smart list", "content": { "application/json": { "schema": { "type": "object", "properties": { "headers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Column ID (UUID)" }, "listId": { "type": "string", "description": "Parent list ID (UUID)" }, "name": { "type": "string", "description": "Column name" }, "type": { "type": "string", "description": "Column type. Data types: text, long_text, url, image, email, phone, linkedin_url. Action types (server-managed): action, lookup, etc." }, "dataType": { "type": "string", "description": "Underlying data type used for storage and validation (e.g., string, number, boolean, json)" }, "order": { "type": "number", "description": "Display order within the list (smaller values appear first)" }, "actionParameters": { "type": "object", "description": "Parameters for action/lookup columns. Null for plain data columns." }, "autoRunEnabled": { "type": "boolean", "description": "For action/lookup columns: whether the action runs automatically on new rows." }, "autoRunEnabledDate": { "type": "string", "description": "Timestamp (ISO 8601) when autoRun was last enabled. Null if autoRun has never been enabled." }, "conditions": { "type": "object", "description": "Optional run conditions for action/lookup columns (free-form JSON). Null when no conditions are configured." }, "loading": { "type": "boolean", "description": "True while a column-wide action is currently executing for this column." }, "created_date": { "type": "string", "description": "Creation timestamp (ISO 8601)" }, "updated_date": { "type": "string", "description": "Last update timestamp (ISO 8601)" }, "deleted_date": { "type": "string", "description": "Soft-delete timestamp (ISO 8601). Null for active columns." } }, "description": "Column (header) on a list" }, "description": "Column definitions for the list" }, "rows": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "rowId": { "type": "string", "description": "Row ID (UUID)" }, "dateAdded": { "type": "string", "description": "Row creation timestamp (ISO 8601)" } }, "description": "A row in a smart list. The object is flat: keys are the list's column names (plus the special keys rowId and dateAdded). Column values are typed according to each column's dataType \u2014 usually strings." }, "description": "Array of rows. Each row is keyed by column name plus rowId and dateAdded." }, "total": { "type": "integer", "description": "Total number of rows matching the query" }, "page": { "type": "integer", "description": "Current page number (1-indexed)" }, "pages": { "type": "integer", "description": "Total number of pages" }, "has_next": { "type": "boolean", "description": "Whether another page is available" } }, "description": "Paginated rows payload" } }, "description": "Public smart list rows response" } } } } }, "summary": "Get paginated rows from a public smart list (no auth required)." } }, "/api/v0/sequences/generate": { "post": { "tags": [ "Sequences" ], "operationId": "sequences_generateSequence", "parameters": [], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "AI provider rejected the request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Generated sequence", "content": { "application/json": { "schema": { "type": "object", "properties": { "sequence": { "type": "object", "properties": { "id": { "type": "string", "description": "Sequence ID" }, "name": { "type": "string", "description": "Sequence name" }, "description": { "type": "string", "description": "Sequence description" }, "status": { "type": "string", "description": "Sequence status (active, paused, archived)" }, "memberCount": { "type": "integer", "description": "Number of members" }, "newMembersSinceLastView": { "type": "integer", "description": "Number of members added since the current user last opened this sequence. 0 if never opened or no new members." }, "created": { "type": "string", "description": "Creation timestamp" }, "updated": { "type": "string", "description": "Last update timestamp" }, "includeUnsubscribeText": { "type": "boolean", "description": "Whether a custom opt-out line is appended to the end of each email (independent of the unsubscribe link, and included on text-only emails). When true and unsubscribeText is empty, the default line is used." }, "unsubscribeText": { "type": "string", "description": "Custom opt-out line shown when includeUnsubscribeText is true. Empty/null means the default line is used: 'If this is not relevant, simply reply \"stop\".'" }, "steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Step ID" }, "sequenceId": { "type": "string", "description": "Parent sequence ID" }, "senderProfile": { "type": "string", "description": "Sender profile ID override for this step" }, "order": { "type": "integer", "description": "Step order within the sequence (0-based)" }, "daysAfterPrevious": { "type": "integer", "description": "Delay in days after the previous step" }, "actionType": { "type": "string", "description": "Action type. One of: email, sms, whatsapp, voice_message, browser_task, prosp_campaign, heyreach_campaign, salesforge_campaign, http_request, agent_conversation, linkedin_profile_visit, linkedin_connection_request, linkedin_message, thanksio, meta_ads_audience, auto_agent, add_to_sequence, add_to_list" }, "platform": { "type": "string", "description": "Platform (linkedin, twitter, facebook, instagram, etc.)" }, "stepName": { "type": "string", "description": "Display name for the step" }, "subject": { "type": "string", "description": "Email subject (email actions only)" }, "content": { "type": "string", "description": "Step content/message body. For auto_agent steps, this is the messaging guidance. For cold outreach sequences, avoid any URL or booking link in the first email: links in the first touch to a cold contact lower deliverability, so ask for a reply instead and save links for later steps." }, "actionParameters": { "type": "object", "description": "Platform-specific action parameters. For actionType=auto_agent, see SequenceStepAutoAgentParametersSchema." }, "autoAgentParameters": { "type": "object", "properties": { "goal": { "type": "string", "description": "Required. Goal the auto-agent should achieve for the member." }, "agentId": { "type": "string", "description": "Agent ID to drive the conversation (used when useSenderProfileAgent is False or sender profile has no agent)." }, "useSenderProfileAgent": { "type": "boolean", "description": "Prefer the sender profile's agent over agentId. Defaults to True." }, "abilities": { "type": "array", "items": { "type": "string" }, "description": "Channels the agent may use. Allowed values: email, sms, whatsapp, voice. Defaults to [email]." }, "autoAgentChannel": { "type": "string", "description": "Initial outbound channel for the first message. One of: email, sms, whatsapp, voice." }, "maxSteps": { "type": "integer", "description": "Maximum number of agent turns before stopping. Defaults to 5." }, "minResponseDelayMinutes": { "type": "integer", "description": "Minimum delay (minutes) before the agent responds, for human-like timing. Defaults to 15." }, "maxResponseDelayMinutes": { "type": "integer", "description": "Maximum delay (minutes) before the agent responds (jitter range). Defaults to 45." } }, "description": "Typed view of actionParameters when actionType=auto_agent. Documentation-only \u2014 the canonical store is actionParameters." }, "aiPersonalized": { "type": "boolean", "description": "Whether content is AI-personalized" }, "aiPersonalizedInstructions": { "type": "string", "description": "AI personalization instructions. For cold outreach sequences, avoid any URL or booking link in the first email: links in the first touch to a cold contact lower deliverability, so ask for a reply instead and save links for later steps." }, "trackCalendarBooking": { "type": "boolean", "description": "Whether to track calendar booking via unique schedule links. For cold outreach sequences, leave false on the first email: a booking link in the first touch to a cold contact lowers deliverability." }, "schedulingIntegrationId": { "type": "string", "description": "Scheduling integration ID for calendar booking. To find valid IDs, call integrations_getIntegrationsByType with path integration_type=scheduling." }, "abTestEnabled": { "type": "boolean", "description": "Whether A/B testing is enabled for this step" }, "abTestName": { "type": "string", "description": "A/B test display name" }, "variants": { "type": "array", "items": { "type": "object" }, "description": "A/B test variants array" }, "created_date": { "type": "string", "description": "Creation timestamp" }, "updated_date": { "type": "string", "description": "Last update timestamp" } }, "description": "Sequence step object" }, "description": "Ordered list of steps in this sequence" } }, "description": "Sequence object" } }, "description": "Sequence response" } } } } }, "summary": "Generate a sequence using AI based on a goal.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID." }, "goal": { "type": "string", "description": "Goal/objective for the sequence" } }, "required": [ "companyId", "goal" ], "description": "Request body for AI-generated sequence" } } }, "description": "Generation goal" } } }, "/api/v0/sequences/step-types": { "get": { "tags": [ "Sequences" ], "operationId": "sequences_listStepTypes", "parameters": [ { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID." }, "description": "Company ID." } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Available step types", "content": { "application/json": { "schema": { "type": "object", "properties": { "stepTypes": { "type": "array", "items": { "type": "object", "properties": { "actionType": { "type": "string", "description": "The value to put in a step's actionType." }, "label": { "type": "string", "description": "Display label." }, "description": { "type": "string", "description": "What this step does." }, "category": { "type": "string", "description": "Palette grouping (Messaging, Agent, Automation, Routing, LinkedIn, Third-party)." }, "platform": { "type": "string", "description": "The step.platform value to set, if any (e.g. linkedin); null otherwise." }, "usesEmailFields": { "type": "boolean", "description": "Whether the step uses the subject field." }, "usesContent": { "type": "boolean", "description": "Whether the step uses the content/message body." }, "supportsAiPersonalization": { "type": "boolean", "description": "Whether aiPersonalized/aiPersonalizedInstructions apply." }, "requiresIntegration": { "type": "object", "properties": { "integrationType": { "type": "string", "description": "Integration type the step needs (e.g. twilio, linkedin_login, prosp)." }, "label": { "type": "string", "description": "Human-friendly name of the integration." }, "findValidIdsHint": { "type": "string", "description": "How to discover valid integration IDs for this step." } }, "description": "Integration the step needs, or null." }, "actionParameters": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Parameter key inside actionParameters." }, "type": { "type": "string", "description": "Value type: string, integer, boolean, enum, array." }, "required": { "type": "boolean", "description": "Whether this parameter must be set for the step to run." }, "description": { "type": "string", "description": "What this parameter controls." }, "default": { "type": "string", "description": "Default value, if any." }, "findValidIdsHint": { "type": "string", "description": "For ID parameters, how to discover valid values." } }, "description": "An actionParameters field spec" }, "description": "The actionParameters fields this step type accepts." }, "defaultActionParameters": { "type": "object", "description": "Object to seed a new step's actionParameters with." }, "rateLimitPerRun": { "type": "integer", "description": "Per-run cap on this step type (null = dynamic/unbounded)." }, "beta": { "type": "boolean", "description": "Marked beta in the UI." } }, "description": "Available sequence step type" }, "description": "All step types available to the caller." } }, "description": "Catalog of available sequence step types" } } } } }, "summary": "List the available sequence step (action) types and how to configure each.", "description": "This is the source of truth for what steps a sequence can contain. Each entry\ndocuments the actionType to use, what it does, which integration it needs (and\nhow to find valid IDs), and the actionParameters fields it accepts \u2014 read it\nbefore building or editing steps." } }, "/api/v0/sequences": { "post": { "tags": [ "Sequences" ], "operationId": "sequences_saveSequence", "parameters": [], "responses": { "400": { "description": "name and companyId are required to create a sequence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Created sequence", "content": { "application/json": { "schema": { "type": "object", "properties": { "sequence": { "type": "object", "properties": { "id": { "type": "string", "description": "Sequence ID" }, "name": { "type": "string", "description": "Sequence name" }, "description": { "type": "string", "description": "Sequence description" }, "status": { "type": "string", "description": "Sequence status (active, paused, archived)" }, "memberCount": { "type": "integer", "description": "Number of members" }, "newMembersSinceLastView": { "type": "integer", "description": "Number of members added since the current user last opened this sequence. 0 if never opened or no new members." }, "created": { "type": "string", "description": "Creation timestamp" }, "updated": { "type": "string", "description": "Last update timestamp" }, "includeUnsubscribeText": { "type": "boolean", "description": "Whether a custom opt-out line is appended to the end of each email (independent of the unsubscribe link, and included on text-only emails). When true and unsubscribeText is empty, the default line is used." }, "unsubscribeText": { "type": "string", "description": "Custom opt-out line shown when includeUnsubscribeText is true. Empty/null means the default line is used: 'If this is not relevant, simply reply \"stop\".'" }, "steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Step ID" }, "sequenceId": { "type": "string", "description": "Parent sequence ID" }, "senderProfile": { "type": "string", "description": "Sender profile ID override for this step" }, "order": { "type": "integer", "description": "Step order within the sequence (0-based)" }, "daysAfterPrevious": { "type": "integer", "description": "Delay in days after the previous step" }, "actionType": { "type": "string", "description": "Action type. One of: email, sms, whatsapp, voice_message, browser_task, prosp_campaign, heyreach_campaign, salesforge_campaign, http_request, agent_conversation, linkedin_profile_visit, linkedin_connection_request, linkedin_message, thanksio, meta_ads_audience, auto_agent, add_to_sequence, add_to_list" }, "platform": { "type": "string", "description": "Platform (linkedin, twitter, facebook, instagram, etc.)" }, "stepName": { "type": "string", "description": "Display name for the step" }, "subject": { "type": "string", "description": "Email subject (email actions only)" }, "content": { "type": "string", "description": "Step content/message body. For auto_agent steps, this is the messaging guidance. For cold outreach sequences, avoid any URL or booking link in the first email: links in the first touch to a cold contact lower deliverability, so ask for a reply instead and save links for later steps." }, "actionParameters": { "type": "object", "description": "Platform-specific action parameters. For actionType=auto_agent, see SequenceStepAutoAgentParametersSchema." }, "autoAgentParameters": { "type": "object", "properties": { "goal": { "type": "string", "description": "Required. Goal the auto-agent should achieve for the member." }, "agentId": { "type": "string", "description": "Agent ID to drive the conversation (used when useSenderProfileAgent is False or sender profile has no agent)." }, "useSenderProfileAgent": { "type": "boolean", "description": "Prefer the sender profile's agent over agentId. Defaults to True." }, "abilities": { "type": "array", "items": { "type": "string" }, "description": "Channels the agent may use. Allowed values: email, sms, whatsapp, voice. Defaults to [email]." }, "autoAgentChannel": { "type": "string", "description": "Initial outbound channel for the first message. One of: email, sms, whatsapp, voice." }, "maxSteps": { "type": "integer", "description": "Maximum number of agent turns before stopping. Defaults to 5." }, "minResponseDelayMinutes": { "type": "integer", "description": "Minimum delay (minutes) before the agent responds, for human-like timing. Defaults to 15." }, "maxResponseDelayMinutes": { "type": "integer", "description": "Maximum delay (minutes) before the agent responds (jitter range). Defaults to 45." } }, "description": "Typed view of actionParameters when actionType=auto_agent. Documentation-only \u2014 the canonical store is actionParameters." }, "aiPersonalized": { "type": "boolean", "description": "Whether content is AI-personalized" }, "aiPersonalizedInstructions": { "type": "string", "description": "AI personalization instructions. For cold outreach sequences, avoid any URL or booking link in the first email: links in the first touch to a cold contact lower deliverability, so ask for a reply instead and save links for later steps." }, "trackCalendarBooking": { "type": "boolean", "description": "Whether to track calendar booking via unique schedule links. For cold outreach sequences, leave false on the first email: a booking link in the first touch to a cold contact lowers deliverability." }, "schedulingIntegrationId": { "type": "string", "description": "Scheduling integration ID for calendar booking. To find valid IDs, call integrations_getIntegrationsByType with path integration_type=scheduling." }, "abTestEnabled": { "type": "boolean", "description": "Whether A/B testing is enabled for this step" }, "abTestName": { "type": "string", "description": "A/B test display name" }, "variants": { "type": "array", "items": { "type": "object" }, "description": "A/B test variants array" }, "created_date": { "type": "string", "description": "Creation timestamp" }, "updated_date": { "type": "string", "description": "Last update timestamp" } }, "description": "Sequence step object" }, "description": "Ordered list of steps in this sequence" } }, "description": "Sequence object" } }, "description": "Sequence response" } } } } }, "summary": "Create or update a sequence.", "description": "By default (``partial`` omitted or true) only the fields present in the body\nare updated and every omitted field is left untouched -- this is the\nrecommended behavior for AI agents so a targeted edit never resets unrelated\nsettings. Send ``partial: false`` to do a full replace where omitted fields\nfall back to their defaults (the frontend does this). Including ``steps``\nreplaces the full step list; to change a single step, prefer the\n/sequences//steps endpoints. A ``steps`` array that drops every existing\nstep is rejected unless ``confirmDeleteAllSteps: true`` is also sent.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID." }, "id": { "type": "string", "description": "Sequence ID. Provide to update an existing sequence; omit to create a new one." }, "name": { "type": "string", "description": "Sequence name. Required when creating (no id); optional on update." }, "description": { "type": "string", "description": "Sequence description" }, "includeUnsubscribeText": { "type": "boolean", "description": "Append a custom opt-out line to the end of each email, where the unsubscribe link goes. Independent of includeUnsubscribeLink \u2014 use it in place of or in addition to the link, and it is also included on text-only emails (which have no link). When true and unsubscribeText is blank, the default line is used. Defaults to true for new sequences." }, "unsubscribeText": { "type": "string", "description": "The custom opt-out text shown when includeUnsubscribeText is true. Leave blank to use the default: 'If this is not relevant, simply reply \"stop\".' Has no effect unless includeUnsubscribeText is true." }, "active": { "type": "boolean", "description": "Whether the sequence may process members. Optional when creating; defaults to false so a new sequence is a draft. Set true only after the user explicitly approves activation." }, "partial": { "type": "boolean", "description": "Update only the fields present in this body and leave all omitted fields untouched. Recommended for AI agents making targeted edits so they never reset unrelated settings. Ignored when creating a new sequence. Defaults to false (full replace)." }, "steps": { "type": "array", "items": { "type": "object" }, "description": "Array of sequence step configurations. WARNING: this REPLACES the full step list \u2014 any existing step not included here is removed. Omit this key entirely to leave steps unchanged. To edit, add, or delete a single step, prefer the /sequences//steps endpoints instead." }, "confirmDeleteAllSteps": { "type": "boolean", "description": "Safety flag. Required to be true if \"steps\" is provided but keeps none of the existing steps (e.g. an empty array); otherwise the request is rejected to prevent accidentally wiping every step." }, "senderProfileIds": { "type": "array", "items": { "type": "string" }, "description": "PRIMARY channel configuration. Sender profile IDs to send as; each profile already carries its own email account, LinkedIn account, phone integration + number, voice, and agent, so usually this is the only channel field you need to set. To find valid IDs (and to see which channels each profile already has), call sequences_listProfiles. To attach a missing channel, edit the sender profile via sequences_updateProfile rather than setting the sequence-level fallbacks below." }, "senderProfileId": { "type": "string", "description": "Deprecated single sender profile ID; prefer senderProfileIds. To find valid IDs, call sequences_listProfiles." }, "linkedinIntegrationIds": { "type": "array", "items": { "type": "string" }, "description": "FALLBACK ONLY. LinkedIn account integration IDs used for a member whose selected sender profile has no linkedinIntegrationId of its own. If your sender profiles already have LinkedIn attached, leave this empty. To find valid IDs, call integrations_getIntegrationsByType with path integration_type=browser_session and query type=linkedin_login." }, "phoneIntegrationIds": { "type": "array", "items": { "type": "string" }, "description": "FALLBACK ONLY. Twilio/phone integration IDs for SMS/voice steps, used when the selected sender profile has no phoneIntegrationId. If your sender profiles already have phone attached, leave this empty. To find valid IDs, call integrations_getIntegrationsByType with path integration_type=sms." }, "phoneNumbers": { "type": "array", "items": { "type": "string" }, "description": "FALLBACK ONLY. Sending phone numbers (E.164) paired with the fallback phoneIntegrationIds, used when the sender profile has no phone number. To find available numbers for a phone integration, call integrations_getTwilioPhoneNumbers with that integration_id." }, "voiceId": { "type": "string", "description": "FALLBACK ONLY. Voice ID for voice-message steps, used when the selected sender profile has no voiceId. To find valid IDs, call voices_listVoices." }, "crmSyncEnabled": { "type": "boolean", "description": "Enable syncing replies/outcomes to a CRM. When true, also set crmIntegrationId." }, "crmIntegrationId": { "type": "string", "description": "CRM integration ID to sync to (used only when crmSyncEnabled is true). To find valid IDs, call crm_getCrmIntegrations." }, "notificationUserIds": { "type": "array", "items": { "type": "string" }, "description": "Company user IDs (uids) who should receive sequence notifications. To find valid IDs, call company_users_getCompanyUsers." } }, "required": [ "companyId" ], "description": "Request body for creating or updating a sequence" } } }, "description": "Sequence data" } }, "get": { "tags": [ "Sequences" ], "operationId": "sequences_getSequences", "parameters": [ { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID." }, "description": "Company ID." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Page number (default: 1)", "default": 1 }, "description": "Page number (default: 1)" }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "description": "Items per page (default: 50)", "default": 50 }, "description": "Items per page (default: 50)" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "description": "Search query to filter sequences by name" }, "description": "Search query to filter sequences by name" }, { "name": "minimal", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Return only id and name per item, without metrics (default: false)", "default": false }, "description": "Return only id and name per item, without metrics (default: false)" }, { "name": "sortBy", "in": "query", "required": false, "schema": { "type": "string", "description": "Field to sort by: 'createdDate' (default) or 'updatedDate'", "enum": [ "createdDate", "updatedDate" ] }, "description": "Field to sort by: 'createdDate' (default) or 'updatedDate'" }, { "name": "sortOrder", "in": "query", "required": false, "schema": { "type": "string", "description": "Sort direction: 'desc' (default) or 'asc'", "enum": [ "asc", "desc" ] }, "description": "Sort direction: 'desc' (default) or 'asc'" } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Paginated list of sequences", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Sequence ID" }, "name": { "type": "string", "description": "Sequence name" }, "description": { "type": "string", "description": "Sequence description" }, "status": { "type": "string", "description": "Sequence status (active, paused, archived)" }, "memberCount": { "type": "integer", "description": "Number of members" }, "newMembersSinceLastView": { "type": "integer", "description": "Number of members added since the current user last opened this sequence. 0 if never opened or no new members." }, "created": { "type": "string", "description": "Creation timestamp" }, "updated": { "type": "string", "description": "Last update timestamp" }, "includeUnsubscribeText": { "type": "boolean", "description": "Whether a custom opt-out line is appended to the end of each email (independent of the unsubscribe link, and included on text-only emails). When true and unsubscribeText is empty, the default line is used." }, "unsubscribeText": { "type": "string", "description": "Custom opt-out line shown when includeUnsubscribeText is true. Empty/null means the default line is used: 'If this is not relevant, simply reply \"stop\".'" }, "steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Step ID" }, "sequenceId": { "type": "string", "description": "Parent sequence ID" }, "senderProfile": { "type": "string", "description": "Sender profile ID override for this step" }, "order": { "type": "integer", "description": "Step order within the sequence (0-based)" }, "daysAfterPrevious": { "type": "integer", "description": "Delay in days after the previous step" }, "actionType": { "type": "string", "description": "Action type. One of: email, sms, whatsapp, voice_message, browser_task, prosp_campaign, heyreach_campaign, salesforge_campaign, http_request, agent_conversation, linkedin_profile_visit, linkedin_connection_request, linkedin_message, thanksio, meta_ads_audience, auto_agent, add_to_sequence, add_to_list" }, "platform": { "type": "string", "description": "Platform (linkedin, twitter, facebook, instagram, etc.)" }, "stepName": { "type": "string", "description": "Display name for the step" }, "subject": { "type": "string", "description": "Email subject (email actions only)" }, "content": { "type": "string", "description": "Step content/message body. For auto_agent steps, this is the messaging guidance. For cold outreach sequences, avoid any URL or booking link in the first email: links in the first touch to a cold contact lower deliverability, so ask for a reply instead and save links for later steps." }, "actionParameters": { "type": "object", "description": "Platform-specific action parameters. For actionType=auto_agent, see SequenceStepAutoAgentParametersSchema." }, "autoAgentParameters": { "type": "object", "properties": { "goal": { "type": "string", "description": "Required. Goal the auto-agent should achieve for the member." }, "agentId": { "type": "string", "description": "Agent ID to drive the conversation (used when useSenderProfileAgent is False or sender profile has no agent)." }, "useSenderProfileAgent": { "type": "boolean", "description": "Prefer the sender profile's agent over agentId. Defaults to True." }, "abilities": { "type": "array", "items": { "type": "string" }, "description": "Channels the agent may use. Allowed values: email, sms, whatsapp, voice. Defaults to [email]." }, "autoAgentChannel": { "type": "string", "description": "Initial outbound channel for the first message. One of: email, sms, whatsapp, voice." }, "maxSteps": { "type": "integer", "description": "Maximum number of agent turns before stopping. Defaults to 5." }, "minResponseDelayMinutes": { "type": "integer", "description": "Minimum delay (minutes) before the agent responds, for human-like timing. Defaults to 15." }, "maxResponseDelayMinutes": { "type": "integer", "description": "Maximum delay (minutes) before the agent responds (jitter range). Defaults to 45." } }, "description": "Typed view of actionParameters when actionType=auto_agent. Documentation-only \u2014 the canonical store is actionParameters." }, "aiPersonalized": { "type": "boolean", "description": "Whether content is AI-personalized" }, "aiPersonalizedInstructions": { "type": "string", "description": "AI personalization instructions. For cold outreach sequences, avoid any URL or booking link in the first email: links in the first touch to a cold contact lower deliverability, so ask for a reply instead and save links for later steps." }, "trackCalendarBooking": { "type": "boolean", "description": "Whether to track calendar booking via unique schedule links. For cold outreach sequences, leave false on the first email: a booking link in the first touch to a cold contact lowers deliverability." }, "schedulingIntegrationId": { "type": "string", "description": "Scheduling integration ID for calendar booking. To find valid IDs, call integrations_getIntegrationsByType with path integration_type=scheduling." }, "abTestEnabled": { "type": "boolean", "description": "Whether A/B testing is enabled for this step" }, "abTestName": { "type": "string", "description": "A/B test display name" }, "variants": { "type": "array", "items": { "type": "object" }, "description": "A/B test variants array" }, "created_date": { "type": "string", "description": "Creation timestamp" }, "updated_date": { "type": "string", "description": "Last update timestamp" } }, "description": "Sequence step object" }, "description": "Ordered list of steps in this sequence" } }, "description": "Sequence object" }, "description": "List of sequences" }, "total": { "type": "integer", "description": "Total count" }, "page": { "type": "integer", "description": "Current page" }, "pageSize": { "type": "integer", "description": "Items per page" } }, "description": "Paginated sequence list" } } } } }, "summary": "List all sequences for the current company." } }, "/api/v0/sequences/{sequenceId}": { "delete": { "tags": [ "Sequences" ], "operationId": "sequences_deleteSequence", "parameters": [ { "name": "sequenceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Sequence not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Sequence deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "description": "Success message" } }, "description": "Success response" } } } } }, "summary": "Delete a sequence by ID." }, "get": { "tags": [ "Sequences" ], "operationId": "sequences_getSequence", "parameters": [ { "name": "sequenceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID." }, "description": "Company ID." } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Sequence not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Sequence details", "content": { "application/json": { "schema": { "type": "object", "properties": { "sequence": { "type": "object", "properties": { "id": { "type": "string", "description": "Sequence ID" }, "name": { "type": "string", "description": "Sequence name" }, "description": { "type": "string", "description": "Sequence description" }, "status": { "type": "string", "description": "Sequence status (active, paused, archived)" }, "memberCount": { "type": "integer", "description": "Number of members" }, "newMembersSinceLastView": { "type": "integer", "description": "Number of members added since the current user last opened this sequence. 0 if never opened or no new members." }, "created": { "type": "string", "description": "Creation timestamp" }, "updated": { "type": "string", "description": "Last update timestamp" }, "includeUnsubscribeText": { "type": "boolean", "description": "Whether a custom opt-out line is appended to the end of each email (independent of the unsubscribe link, and included on text-only emails). When true and unsubscribeText is empty, the default line is used." }, "unsubscribeText": { "type": "string", "description": "Custom opt-out line shown when includeUnsubscribeText is true. Empty/null means the default line is used: 'If this is not relevant, simply reply \"stop\".'" }, "steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Step ID" }, "sequenceId": { "type": "string", "description": "Parent sequence ID" }, "senderProfile": { "type": "string", "description": "Sender profile ID override for this step" }, "order": { "type": "integer", "description": "Step order within the sequence (0-based)" }, "daysAfterPrevious": { "type": "integer", "description": "Delay in days after the previous step" }, "actionType": { "type": "string", "description": "Action type. One of: email, sms, whatsapp, voice_message, browser_task, prosp_campaign, heyreach_campaign, salesforge_campaign, http_request, agent_conversation, linkedin_profile_visit, linkedin_connection_request, linkedin_message, thanksio, meta_ads_audience, auto_agent, add_to_sequence, add_to_list" }, "platform": { "type": "string", "description": "Platform (linkedin, twitter, facebook, instagram, etc.)" }, "stepName": { "type": "string", "description": "Display name for the step" }, "subject": { "type": "string", "description": "Email subject (email actions only)" }, "content": { "type": "string", "description": "Step content/message body. For auto_agent steps, this is the messaging guidance. For cold outreach sequences, avoid any URL or booking link in the first email: links in the first touch to a cold contact lower deliverability, so ask for a reply instead and save links for later steps." }, "actionParameters": { "type": "object", "description": "Platform-specific action parameters. For actionType=auto_agent, see SequenceStepAutoAgentParametersSchema." }, "autoAgentParameters": { "type": "object", "properties": { "goal": { "type": "string", "description": "Required. Goal the auto-agent should achieve for the member." }, "agentId": { "type": "string", "description": "Agent ID to drive the conversation (used when useSenderProfileAgent is False or sender profile has no agent)." }, "useSenderProfileAgent": { "type": "boolean", "description": "Prefer the sender profile's agent over agentId. Defaults to True." }, "abilities": { "type": "array", "items": { "type": "string" }, "description": "Channels the agent may use. Allowed values: email, sms, whatsapp, voice. Defaults to [email]." }, "autoAgentChannel": { "type": "string", "description": "Initial outbound channel for the first message. One of: email, sms, whatsapp, voice." }, "maxSteps": { "type": "integer", "description": "Maximum number of agent turns before stopping. Defaults to 5." }, "minResponseDelayMinutes": { "type": "integer", "description": "Minimum delay (minutes) before the agent responds, for human-like timing. Defaults to 15." }, "maxResponseDelayMinutes": { "type": "integer", "description": "Maximum delay (minutes) before the agent responds (jitter range). Defaults to 45." } }, "description": "Typed view of actionParameters when actionType=auto_agent. Documentation-only \u2014 the canonical store is actionParameters." }, "aiPersonalized": { "type": "boolean", "description": "Whether content is AI-personalized" }, "aiPersonalizedInstructions": { "type": "string", "description": "AI personalization instructions. For cold outreach sequences, avoid any URL or booking link in the first email: links in the first touch to a cold contact lower deliverability, so ask for a reply instead and save links for later steps." }, "trackCalendarBooking": { "type": "boolean", "description": "Whether to track calendar booking via unique schedule links. For cold outreach sequences, leave false on the first email: a booking link in the first touch to a cold contact lowers deliverability." }, "schedulingIntegrationId": { "type": "string", "description": "Scheduling integration ID for calendar booking. To find valid IDs, call integrations_getIntegrationsByType with path integration_type=scheduling." }, "abTestEnabled": { "type": "boolean", "description": "Whether A/B testing is enabled for this step" }, "abTestName": { "type": "string", "description": "A/B test display name" }, "variants": { "type": "array", "items": { "type": "object" }, "description": "A/B test variants array" }, "created_date": { "type": "string", "description": "Creation timestamp" }, "updated_date": { "type": "string", "description": "Last update timestamp" } }, "description": "Sequence step object" }, "description": "Ordered list of steps in this sequence" } }, "description": "Sequence object" } }, "description": "Sequence response" } } } } }, "summary": "Get a specific sequence by ID." } }, "/api/v0/sequences/{sequenceId}/steps": { "post": { "tags": [ "Sequences" ], "operationId": "sequences_addSequenceStep", "parameters": [ { "name": "sequenceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid step value", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Sequence not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Created step", "content": { "application/json": { "schema": { "type": "object", "properties": { "step": { "type": "object", "properties": { "id": { "type": "string", "description": "Step ID" }, "sequenceId": { "type": "string", "description": "Parent sequence ID" }, "senderProfile": { "type": "string", "description": "Sender profile ID override for this step" }, "order": { "type": "integer", "description": "Step order within the sequence (0-based)" }, "daysAfterPrevious": { "type": "integer", "description": "Delay in days after the previous step" }, "actionType": { "type": "string", "description": "Action type. One of: email, sms, whatsapp, voice_message, browser_task, prosp_campaign, heyreach_campaign, salesforge_campaign, http_request, agent_conversation, linkedin_profile_visit, linkedin_connection_request, linkedin_message, thanksio, meta_ads_audience, auto_agent, add_to_sequence, add_to_list" }, "platform": { "type": "string", "description": "Platform (linkedin, twitter, facebook, instagram, etc.)" }, "stepName": { "type": "string", "description": "Display name for the step" }, "subject": { "type": "string", "description": "Email subject (email actions only)" }, "content": { "type": "string", "description": "Step content/message body. For auto_agent steps, this is the messaging guidance. For cold outreach sequences, avoid any URL or booking link in the first email: links in the first touch to a cold contact lower deliverability, so ask for a reply instead and save links for later steps." }, "actionParameters": { "type": "object", "description": "Platform-specific action parameters. For actionType=auto_agent, see SequenceStepAutoAgentParametersSchema." }, "autoAgentParameters": { "type": "object", "properties": { "goal": { "type": "string", "description": "Required. Goal the auto-agent should achieve for the member." }, "agentId": { "type": "string", "description": "Agent ID to drive the conversation (used when useSenderProfileAgent is False or sender profile has no agent)." }, "useSenderProfileAgent": { "type": "boolean", "description": "Prefer the sender profile's agent over agentId. Defaults to True." }, "abilities": { "type": "array", "items": { "type": "string" }, "description": "Channels the agent may use. Allowed values: email, sms, whatsapp, voice. Defaults to [email]." }, "autoAgentChannel": { "type": "string", "description": "Initial outbound channel for the first message. One of: email, sms, whatsapp, voice." }, "maxSteps": { "type": "integer", "description": "Maximum number of agent turns before stopping. Defaults to 5." }, "minResponseDelayMinutes": { "type": "integer", "description": "Minimum delay (minutes) before the agent responds, for human-like timing. Defaults to 15." }, "maxResponseDelayMinutes": { "type": "integer", "description": "Maximum delay (minutes) before the agent responds (jitter range). Defaults to 45." } }, "description": "Typed view of actionParameters when actionType=auto_agent. Documentation-only \u2014 the canonical store is actionParameters." }, "aiPersonalized": { "type": "boolean", "description": "Whether content is AI-personalized" }, "aiPersonalizedInstructions": { "type": "string", "description": "AI personalization instructions. For cold outreach sequences, avoid any URL or booking link in the first email: links in the first touch to a cold contact lower deliverability, so ask for a reply instead and save links for later steps." }, "trackCalendarBooking": { "type": "boolean", "description": "Whether to track calendar booking via unique schedule links. For cold outreach sequences, leave false on the first email: a booking link in the first touch to a cold contact lowers deliverability." }, "schedulingIntegrationId": { "type": "string", "description": "Scheduling integration ID for calendar booking. To find valid IDs, call integrations_getIntegrationsByType with path integration_type=scheduling." }, "abTestEnabled": { "type": "boolean", "description": "Whether A/B testing is enabled for this step" }, "abTestName": { "type": "string", "description": "A/B test display name" }, "variants": { "type": "array", "items": { "type": "object" }, "description": "A/B test variants array" }, "created_date": { "type": "string", "description": "Creation timestamp" }, "updated_date": { "type": "string", "description": "Last update timestamp" } }, "description": "The created or updated step" } }, "description": "Single sequence step response" } } } } }, "summary": "Append a single step to a sequence without resending the whole step list.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "order": { "type": "integer", "description": "Step order within the sequence; other steps are renumbered to stay contiguous" }, "senderProfile": { "type": "string", "description": "Sender profile ID override for this step. To find valid IDs, call sequences_listProfiles." }, "daysAfterPrevious": { "type": "integer", "description": "Delay in days after the previous step" }, "actionType": { "type": "string", "description": "Action type. Defaults to email. One of: email, sms, whatsapp, voice_message, browser_task, prosp_campaign, heyreach_campaign, salesforge_campaign, http_request, agent_conversation, linkedin_profile_visit, linkedin_connection_request, linkedin_message, thanksio, meta_ads_audience, auto_agent, add_to_sequence, add_to_list" }, "platform": { "type": "string", "description": "Platform (linkedin, twitter, facebook, instagram, etc.)" }, "stepName": { "type": "string", "description": "Display name for the step" }, "subject": { "type": "string", "description": "Email subject (email actions only)" }, "content": { "type": "string", "description": "Step content/message body" }, "actionParameters": { "type": "object", "description": "Platform-specific action parameters" }, "aiPersonalized": { "type": "boolean", "description": "Whether content is AI-personalized" }, "aiPersonalizedInstructions": { "type": "string", "description": "AI personalization instructions. For cold outreach sequences, avoid any URL or booking link in the first email: links in the first touch to a cold contact lower deliverability, so ask for a reply instead and save links for later steps." }, "trackCalendarBooking": { "type": "boolean", "description": "Whether to track calendar booking via unique schedule links. For cold outreach sequences, leave false on the first email: a booking link in the first touch to a cold contact lowers deliverability." }, "schedulingIntegrationId": { "type": "string", "description": "Scheduling integration ID for calendar booking. To find valid IDs, call integrations_getIntegrationsByType with path integration_type=scheduling." }, "abTestEnabled": { "type": "boolean", "description": "Whether A/B testing is enabled for this step" }, "abTestName": { "type": "string", "description": "A/B test display name" }, "variants": { "type": "array", "items": { "type": "object" }, "description": "A/B test variants array" } }, "description": "Request body for adding a single sequence step" } } }, "description": "Step data" } } }, "/api/v0/sequences/{sequenceId}/steps/{stepId}": { "patch": { "tags": [ "Sequences" ], "operationId": "sequences_updateSequenceStep", "parameters": [ { "name": "stepId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "sequenceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid step value", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Step not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Updated step", "content": { "application/json": { "schema": { "type": "object", "properties": { "step": { "type": "object", "properties": { "id": { "type": "string", "description": "Step ID" }, "sequenceId": { "type": "string", "description": "Parent sequence ID" }, "senderProfile": { "type": "string", "description": "Sender profile ID override for this step" }, "order": { "type": "integer", "description": "Step order within the sequence (0-based)" }, "daysAfterPrevious": { "type": "integer", "description": "Delay in days after the previous step" }, "actionType": { "type": "string", "description": "Action type. One of: email, sms, whatsapp, voice_message, browser_task, prosp_campaign, heyreach_campaign, salesforge_campaign, http_request, agent_conversation, linkedin_profile_visit, linkedin_connection_request, linkedin_message, thanksio, meta_ads_audience, auto_agent, add_to_sequence, add_to_list" }, "platform": { "type": "string", "description": "Platform (linkedin, twitter, facebook, instagram, etc.)" }, "stepName": { "type": "string", "description": "Display name for the step" }, "subject": { "type": "string", "description": "Email subject (email actions only)" }, "content": { "type": "string", "description": "Step content/message body. For auto_agent steps, this is the messaging guidance. For cold outreach sequences, avoid any URL or booking link in the first email: links in the first touch to a cold contact lower deliverability, so ask for a reply instead and save links for later steps." }, "actionParameters": { "type": "object", "description": "Platform-specific action parameters. For actionType=auto_agent, see SequenceStepAutoAgentParametersSchema." }, "autoAgentParameters": { "type": "object", "properties": { "goal": { "type": "string", "description": "Required. Goal the auto-agent should achieve for the member." }, "agentId": { "type": "string", "description": "Agent ID to drive the conversation (used when useSenderProfileAgent is False or sender profile has no agent)." }, "useSenderProfileAgent": { "type": "boolean", "description": "Prefer the sender profile's agent over agentId. Defaults to True." }, "abilities": { "type": "array", "items": { "type": "string" }, "description": "Channels the agent may use. Allowed values: email, sms, whatsapp, voice. Defaults to [email]." }, "autoAgentChannel": { "type": "string", "description": "Initial outbound channel for the first message. One of: email, sms, whatsapp, voice." }, "maxSteps": { "type": "integer", "description": "Maximum number of agent turns before stopping. Defaults to 5." }, "minResponseDelayMinutes": { "type": "integer", "description": "Minimum delay (minutes) before the agent responds, for human-like timing. Defaults to 15." }, "maxResponseDelayMinutes": { "type": "integer", "description": "Maximum delay (minutes) before the agent responds (jitter range). Defaults to 45." } }, "description": "Typed view of actionParameters when actionType=auto_agent. Documentation-only \u2014 the canonical store is actionParameters." }, "aiPersonalized": { "type": "boolean", "description": "Whether content is AI-personalized" }, "aiPersonalizedInstructions": { "type": "string", "description": "AI personalization instructions. For cold outreach sequences, avoid any URL or booking link in the first email: links in the first touch to a cold contact lower deliverability, so ask for a reply instead and save links for later steps." }, "trackCalendarBooking": { "type": "boolean", "description": "Whether to track calendar booking via unique schedule links. For cold outreach sequences, leave false on the first email: a booking link in the first touch to a cold contact lowers deliverability." }, "schedulingIntegrationId": { "type": "string", "description": "Scheduling integration ID for calendar booking. To find valid IDs, call integrations_getIntegrationsByType with path integration_type=scheduling." }, "abTestEnabled": { "type": "boolean", "description": "Whether A/B testing is enabled for this step" }, "abTestName": { "type": "string", "description": "A/B test display name" }, "variants": { "type": "array", "items": { "type": "object" }, "description": "A/B test variants array" }, "created_date": { "type": "string", "description": "Creation timestamp" }, "updated_date": { "type": "string", "description": "Last update timestamp" } }, "description": "The created or updated step" } }, "description": "Single sequence step response" } } } } }, "summary": "Partially update a single step. Only the fields present in the body are", "description": "changed; omitted fields keep their saved value, and the other steps in the\nsequence are left untouched.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "order": { "type": "integer", "description": "Step order within the sequence; other steps are renumbered to stay contiguous" }, "senderProfile": { "type": "string", "description": "Sender profile ID override for this step. To find valid IDs, call sequences_listProfiles." }, "daysAfterPrevious": { "type": "integer", "description": "Delay in days after the previous step" }, "actionType": { "type": "string", "description": "Action type. One of: email, sms, whatsapp, voice_message, browser_task, prosp_campaign, heyreach_campaign, salesforge_campaign, http_request, agent_conversation, linkedin_profile_visit, linkedin_connection_request, linkedin_message, thanksio, meta_ads_audience, auto_agent, add_to_sequence, add_to_list" }, "platform": { "type": "string", "description": "Platform (linkedin, twitter, facebook, instagram, etc.)" }, "stepName": { "type": "string", "description": "Display name for the step" }, "subject": { "type": "string", "description": "Email subject (email actions only)" }, "content": { "type": "string", "description": "Step content/message body" }, "actionParameters": { "type": "object", "description": "Platform-specific action parameters" }, "aiPersonalized": { "type": "boolean", "description": "Whether content is AI-personalized" }, "aiPersonalizedInstructions": { "type": "string", "description": "AI personalization instructions. For cold outreach sequences, avoid any URL or booking link in the first email: links in the first touch to a cold contact lower deliverability, so ask for a reply instead and save links for later steps." }, "trackCalendarBooking": { "type": "boolean", "description": "Whether to track calendar booking via unique schedule links. For cold outreach sequences, leave false on the first email: a booking link in the first touch to a cold contact lowers deliverability." }, "schedulingIntegrationId": { "type": "string", "description": "Scheduling integration ID for calendar booking. To find valid IDs, call integrations_getIntegrationsByType with path integration_type=scheduling." }, "abTestEnabled": { "type": "boolean", "description": "Whether A/B testing is enabled for this step" }, "abTestName": { "type": "string", "description": "A/B test display name" }, "variants": { "type": "array", "items": { "type": "object" }, "description": "A/B test variants array" } }, "description": "Request body for updating a single sequence step (partial \u2014 omitted fields are left unchanged)" } } }, "description": "Fields to update on the step" } }, "delete": { "tags": [ "Sequences" ], "operationId": "sequences_deleteSequenceStep", "parameters": [ { "name": "stepId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "sequenceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Step not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Step deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "description": "Success message" } }, "description": "Success response" } } } } }, "summary": "Soft-delete a single step and renumber the remaining steps.", "description": "Accepts an optional ``memberDisposition`` (with ``targetStepId`` for\n'specific_step') deciding what happens to active members sitting on the\nstep. Defaults to moving them to the next surviving step." } }, "/api/v0/sequences/{sequenceId}/steps/member-counts": { "get": { "tags": [ "Sequences" ], "operationId": "sequences_getSequenceStepMemberCounts", "parameters": [ { "name": "sequenceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID." }, "description": "Company ID." } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Sequence not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Count active members currently sitting on each of the given steps.", "description": "Powers the delete confirmation prompt, which has to tell the user how many\npeople are on a step before asking what should happen to them. Pass the step\nids as a repeated or comma-separated ``stepIds`` query param." } }, "/api/v0/sequences/{sequenceId}/duplicate": { "post": { "tags": [ "Sequences" ], "operationId": "sequences_duplicateSequenceRoute", "parameters": [ { "name": "sequenceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Sequence not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Duplicated sequence", "content": { "application/json": { "schema": { "type": "object", "properties": { "sequence": { "type": "object", "properties": { "id": { "type": "string", "description": "Sequence ID" }, "name": { "type": "string", "description": "Sequence name" }, "description": { "type": "string", "description": "Sequence description" }, "status": { "type": "string", "description": "Sequence status (active, paused, archived)" }, "memberCount": { "type": "integer", "description": "Number of members" }, "newMembersSinceLastView": { "type": "integer", "description": "Number of members added since the current user last opened this sequence. 0 if never opened or no new members." }, "created": { "type": "string", "description": "Creation timestamp" }, "updated": { "type": "string", "description": "Last update timestamp" }, "includeUnsubscribeText": { "type": "boolean", "description": "Whether a custom opt-out line is appended to the end of each email (independent of the unsubscribe link, and included on text-only emails). When true and unsubscribeText is empty, the default line is used." }, "unsubscribeText": { "type": "string", "description": "Custom opt-out line shown when includeUnsubscribeText is true. Empty/null means the default line is used: 'If this is not relevant, simply reply \"stop\".'" }, "steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Step ID" }, "sequenceId": { "type": "string", "description": "Parent sequence ID" }, "senderProfile": { "type": "string", "description": "Sender profile ID override for this step" }, "order": { "type": "integer", "description": "Step order within the sequence (0-based)" }, "daysAfterPrevious": { "type": "integer", "description": "Delay in days after the previous step" }, "actionType": { "type": "string", "description": "Action type. One of: email, sms, whatsapp, voice_message, browser_task, prosp_campaign, heyreach_campaign, salesforge_campaign, http_request, agent_conversation, linkedin_profile_visit, linkedin_connection_request, linkedin_message, thanksio, meta_ads_audience, auto_agent, add_to_sequence, add_to_list" }, "platform": { "type": "string", "description": "Platform (linkedin, twitter, facebook, instagram, etc.)" }, "stepName": { "type": "string", "description": "Display name for the step" }, "subject": { "type": "string", "description": "Email subject (email actions only)" }, "content": { "type": "string", "description": "Step content/message body. For auto_agent steps, this is the messaging guidance. For cold outreach sequences, avoid any URL or booking link in the first email: links in the first touch to a cold contact lower deliverability, so ask for a reply instead and save links for later steps." }, "actionParameters": { "type": "object", "description": "Platform-specific action parameters. For actionType=auto_agent, see SequenceStepAutoAgentParametersSchema." }, "autoAgentParameters": { "type": "object", "properties": { "goal": { "type": "string", "description": "Required. Goal the auto-agent should achieve for the member." }, "agentId": { "type": "string", "description": "Agent ID to drive the conversation (used when useSenderProfileAgent is False or sender profile has no agent)." }, "useSenderProfileAgent": { "type": "boolean", "description": "Prefer the sender profile's agent over agentId. Defaults to True." }, "abilities": { "type": "array", "items": { "type": "string" }, "description": "Channels the agent may use. Allowed values: email, sms, whatsapp, voice. Defaults to [email]." }, "autoAgentChannel": { "type": "string", "description": "Initial outbound channel for the first message. One of: email, sms, whatsapp, voice." }, "maxSteps": { "type": "integer", "description": "Maximum number of agent turns before stopping. Defaults to 5." }, "minResponseDelayMinutes": { "type": "integer", "description": "Minimum delay (minutes) before the agent responds, for human-like timing. Defaults to 15." }, "maxResponseDelayMinutes": { "type": "integer", "description": "Maximum delay (minutes) before the agent responds (jitter range). Defaults to 45." } }, "description": "Typed view of actionParameters when actionType=auto_agent. Documentation-only \u2014 the canonical store is actionParameters." }, "aiPersonalized": { "type": "boolean", "description": "Whether content is AI-personalized" }, "aiPersonalizedInstructions": { "type": "string", "description": "AI personalization instructions. For cold outreach sequences, avoid any URL or booking link in the first email: links in the first touch to a cold contact lower deliverability, so ask for a reply instead and save links for later steps." }, "trackCalendarBooking": { "type": "boolean", "description": "Whether to track calendar booking via unique schedule links. For cold outreach sequences, leave false on the first email: a booking link in the first touch to a cold contact lowers deliverability." }, "schedulingIntegrationId": { "type": "string", "description": "Scheduling integration ID for calendar booking. To find valid IDs, call integrations_getIntegrationsByType with path integration_type=scheduling." }, "abTestEnabled": { "type": "boolean", "description": "Whether A/B testing is enabled for this step" }, "abTestName": { "type": "string", "description": "A/B test display name" }, "variants": { "type": "array", "items": { "type": "object" }, "description": "A/B test variants array" }, "created_date": { "type": "string", "description": "Creation timestamp" }, "updated_date": { "type": "string", "description": "Last update timestamp" } }, "description": "Sequence step object" }, "description": "Ordered list of steps in this sequence" } }, "description": "Sequence object" } }, "description": "Sequence response" } } } } }, "summary": "Duplicate a sequence and its steps." } }, "/api/v0/sequences/{sequenceId}/members": { "get": { "tags": [ "Sequences" ], "operationId": "sequences_getSequenceMembers", "parameters": [ { "name": "sequenceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID." }, "description": "Company ID." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Page number (default: 1)", "default": 1 }, "description": "Page number (default: 1)" }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "description": "Items per page (default: 20)", "default": 20 }, "description": "Items per page (default: 20)" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "description": "Search by name, email, or phone" }, "description": "Search by name, email, or phone" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "description": "Filter by member status: active, paused, bounced, unsubscribed, removed" }, "description": "Filter by member status: active, paused, bounced, unsubscribed, removed" }, { "name": "stepId", "in": "query", "required": false, "schema": { "type": "string", "description": "Filter by current (last executed) step ID, or 'not_started' for members who haven't started" }, "description": "Filter by current (last executed) step ID, or 'not_started' for members who haven't started" } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Paginated list of sequence members", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Member ID" }, "email": { "type": "string", "description": "Email address" }, "firstName": { "type": "string", "description": "First name" }, "lastName": { "type": "string", "description": "Last name" }, "phone": { "type": "string", "description": "Phone number" }, "linkedinUrl": { "type": "string", "description": "LinkedIn profile URL" }, "status": { "type": "string", "description": "Member status: active, paused, bounced, unsubscribed, removed" }, "currentStep": { "type": "integer", "description": "Current step number" }, "userData": { "type": "object", "description": "Additional user data" }, "created": { "type": "string", "description": "Added timestamp" } }, "description": "Sequence member object" }, "description": "List of members" }, "total": { "type": "integer", "description": "Total count" } }, "description": "Paginated members list" } } } } }, "summary": "List all members of a sequence." }, "post": { "tags": [ "Sequences" ], "operationId": "sequences_addSequenceMembers", "parameters": [ { "name": "sequenceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Missing required fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "201": { "description": "Member added", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "description": "Success message" }, "memberId": { "type": "string", "description": "Created member ID" } }, "description": "Member added response" } } } } }, "summary": "Add a member to a sequence.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "Email address of the member" }, "firstName": { "type": "string", "description": "First name of the member" }, "lastName": { "type": "string", "description": "Last name of the member (optional)" }, "phone": { "type": "string", "description": "Phone number of the member (optional)" }, "linkedinUrl": { "type": "string", "description": "LinkedIn profile URL (optional)" }, "userData": { "type": "object", "description": "Additional user data (key-value pairs) that can be referenced in sequence templates using {{fieldName}} syntax" } }, "required": [ "email", "firstName" ], "description": "Request body for adding a sequence member" } } }, "description": "Member data" } } }, "/api/v0/sequences/{sequenceId}/import-from-list": { "post": { "tags": [ "Sequences" ], "operationId": "sequences_importFromSmartList", "parameters": [ { "name": "sequenceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "List ID is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "List or sequence not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "SSE stream with import progress" } }, "summary": "Import members from a smart list to a sequence with SSE progress.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "listId": { "type": "string", "description": "Source list ID" }, "fieldMappings": { "type": "object", "description": "Optional field mappings: {email?: string, firstName?: string, lastName?: string, phone?: string, linkedinUrl?: string} mapping list columns to sequence member fields" } }, "required": [ "listId" ], "description": "Request body for importing members from a smart list" } } }, "description": "Import parameters" } } }, "/api/v0/sequences/{sequenceId}/members/{sequenceMemberId}/timeline": { "get": { "tags": [ "Sequences" ], "operationId": "sequences_getSequenceMemberTimeline", "parameters": [ { "name": "sequenceMemberId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "sequenceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Member not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Member timeline with execution history" } }, "summary": "Get timeline of all actions for a sequence member." } }, "/api/v0/sequences/{sequenceId}/activity": { "get": { "tags": [ "Sequences" ], "operationId": "sequences_getSequenceActivity", "parameters": [ { "name": "sequenceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Page number (default: 1)", "default": 1 }, "description": "Page number (default: 1)" }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "description": "Items per page (default: 50, max: 100)", "default": 50 }, "description": "Items per page (default: 50, max: 100)" }, { "name": "eventType", "in": "query", "required": false, "schema": { "type": "string", "description": "Filter by event type: email_opened, email_clicked, email_reply, voice_call, schedule_view, schedule_booking" }, "description": "Filter by event type: email_opened, email_clicked, email_reply, voice_call, schedule_view, schedule_booking" }, { "name": "filterBots", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Filter out bot/security scanner traffic (default: false)", "default": false }, "description": "Filter out bot/security scanner traffic (default: false)" } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Sequence not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Paginated activity timeline", "content": { "application/json": { "schema": { "type": "object", "properties": { "timeline": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Event type: email_opened, email_clicked, email_reply, voice_call_completed, schedule_view, schedule_booking" }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }, "subject": { "type": "string", "description": "Email/message subject" }, "executionId": { "type": "string", "description": "Execution ID" }, "stepName": { "type": "string", "description": "Sequence step name" }, "platform": { "type": "string", "description": "Platform: email, voice, schedule" }, "actionType": { "type": "string", "description": "Action type" }, "ipAddress": { "type": "string", "description": "Client IP address" }, "userAgent": { "type": "string", "description": "Client user agent" }, "clickedUrl": { "type": "string", "description": "Clicked URL (for click events)" }, "isBot": { "type": "boolean", "description": "Whether the event is from a bot/security scanner" }, "botProvider": { "type": "string", "description": "Bot provider name if detected" }, "callIntelligence": { "type": "object", "properties": { "sentiment": { "type": "string", "description": "Call sentiment: positive, negative, neutral" }, "outcome": { "type": "string", "description": "Call outcome: meeting_booked, interested, not_interested, etc." }, "outcome_summary": { "type": "string", "description": "AI-generated summary of the call" }, "meeting_booked": { "type": "boolean", "description": "Whether a meeting was booked" }, "meeting_details": { "type": "string", "description": "Meeting details if booked" }, "interest_level": { "type": "string", "description": "Interest level: high, medium, low" } }, "description": "Call intelligence data (for voice calls)" }, "callDuration": { "type": "integer", "description": "Call duration in seconds" }, "callResult": { "type": "string", "description": "Call result" }, "member": { "type": "object", "properties": { "id": { "type": "string", "description": "Member ID" }, "firstName": { "type": "string", "description": "First name" }, "lastName": { "type": "string", "description": "Last name" }, "email": { "type": "string", "description": "Email address" }, "linkedinUrl": { "type": "string", "description": "LinkedIn profile URL" } }, "description": "Member information" } }, "description": "Activity timeline event" }, "description": "List of activity events" }, "totalCount": { "type": "integer", "description": "Total number of events" }, "page": { "type": "integer", "description": "Current page number" }, "pageSize": { "type": "integer", "description": "Items per page" }, "totalPages": { "type": "integer", "description": "Total number of pages" } }, "description": "Paginated activity response" } } } } }, "summary": "Get paginated timeline events for a sequence across all members.", "description": "Uses database-level pagination for efficiency with large datasets.\nIncludes detailed tracking events (opens, clicks) with IP, user agent, and clicked URLs." } }, "/api/v0/sequences/{sequenceId}/activity/export": { "get": { "tags": [ "Sequences" ], "operationId": "sequences_exportSequenceActivity", "parameters": [ { "name": "sequenceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Page number (default: 1)", "default": 1 }, "description": "Page number (default: 1)" }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "description": "Items per page (default: 50, max: 100)", "default": 50 }, "description": "Items per page (default: 50, max: 100)" }, { "name": "eventType", "in": "query", "required": false, "schema": { "type": "string", "description": "Filter by event type: email_opened, email_clicked, email_reply, voice_call, schedule_view, schedule_booking" }, "description": "Filter by event type: email_opened, email_clicked, email_reply, voice_call, schedule_view, schedule_booking" }, { "name": "filterBots", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Filter out bot/security scanner traffic (default: false)", "default": false }, "description": "Filter out bot/security scanner traffic (default: false)" } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Sequence not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "CSV file download" } }, "summary": "Export all timeline events for a sequence to CSV.", "description": "Efficiently collects all activity data without pagination limits\nand returns a downloadable CSV file." } }, "/api/v0/sequences/{sequenceId}/members/{sequenceMemberId}/trigger": { "post": { "tags": [ "Sequences" ], "operationId": "sequences_triggerSequenceMember", "parameters": [ { "name": "sequenceMemberId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "sequenceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Cannot trigger member", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Member triggered", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "description": "Success message" } }, "description": "Success response" } } } } }, "summary": "Trigger the next step for a sequence member." } }, "/api/v0/sequences/{sequenceId}/members/{sequenceMemberId}/remove": { "post": { "tags": [ "Sequences" ], "operationId": "sequences_removeSequenceMember", "parameters": [ { "name": "sequenceMemberId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "sequenceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Member removed", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "description": "Success message" } }, "description": "Success response" } } } } }, "summary": "Remove a member from a sequence.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "description": "Reason for removal (optional)" } }, "description": "Request body for removing a sequence member" } } }, "description": "Removal reason" } } }, "/api/v0/sequences/all/executions": { "get": { "tags": [ "Sequences" ], "operationId": "sequences_getSequenceExecutions", "parameters": [ { "name": "sequenceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Page number (default: 1)", "default": 1 }, "description": "Page number (default: 1)" }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "description": "Items per page (default: 20)", "default": 20 }, "description": "Items per page (default: 20)" }, { "name": "executionState", "in": "query", "required": false, "schema": { "type": "string", "description": "Filter by execution state (pending, approved, executed, failed)" }, "description": "Filter by execution state (pending, approved, executed, failed)" }, { "name": "sequenceStepId", "in": "query", "required": false, "schema": { "type": "string", "description": "Filter by specific step ID" }, "description": "Filter by specific step ID" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "description": "Search query" }, "description": "Search query" } ], "responses": { "400": { "description": "Invalid sequence ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Paginated list of executions", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Execution ID" }, "sequenceId": { "type": "string", "description": "Sequence ID" }, "sequenceStepId": { "type": "string", "description": "Step ID" }, "sequenceMemberId": { "type": "string", "description": "Member ID" }, "subject": { "type": "string", "description": "Email/message subject" }, "content": { "type": "string", "description": "Email/message content" }, "executed": { "type": "boolean", "description": "Whether executed" }, "executedDate": { "type": "string", "description": "Execution timestamp" }, "approved": { "type": "boolean", "description": "Whether approved" }, "failed": { "type": "boolean", "description": "Whether failed" }, "failureReason": { "type": "string", "description": "Failure reason if failed" } }, "description": "Sequence step execution object" }, "description": "List of executions" }, "total": { "type": "integer", "description": "Total count" } }, "description": "Paginated executions list" } } } } }, "summary": "List all executions for a sequence." } }, "/api/v0/sequences/{sequenceId}/executions": { "get": { "tags": [ "Sequences" ], "operationId": "sequences_getSequenceExecutions", "parameters": [ { "name": "sequenceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Page number (default: 1)", "default": 1 }, "description": "Page number (default: 1)" }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "description": "Items per page (default: 20)", "default": 20 }, "description": "Items per page (default: 20)" }, { "name": "executionState", "in": "query", "required": false, "schema": { "type": "string", "description": "Filter by execution state (pending, approved, executed, failed)" }, "description": "Filter by execution state (pending, approved, executed, failed)" }, { "name": "sequenceStepId", "in": "query", "required": false, "schema": { "type": "string", "description": "Filter by specific step ID" }, "description": "Filter by specific step ID" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "description": "Search query" }, "description": "Search query" } ], "responses": { "400": { "description": "Invalid sequence ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Paginated list of executions", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Execution ID" }, "sequenceId": { "type": "string", "description": "Sequence ID" }, "sequenceStepId": { "type": "string", "description": "Step ID" }, "sequenceMemberId": { "type": "string", "description": "Member ID" }, "subject": { "type": "string", "description": "Email/message subject" }, "content": { "type": "string", "description": "Email/message content" }, "executed": { "type": "boolean", "description": "Whether executed" }, "executedDate": { "type": "string", "description": "Execution timestamp" }, "approved": { "type": "boolean", "description": "Whether approved" }, "failed": { "type": "boolean", "description": "Whether failed" }, "failureReason": { "type": "string", "description": "Failure reason if failed" } }, "description": "Sequence step execution object" }, "description": "List of executions" }, "total": { "type": "integer", "description": "Total count" } }, "description": "Paginated executions list" } } } } }, "summary": "List all executions for a sequence." } }, "/api/v0/sequences/{sequenceId}/executions/delete": { "post": { "tags": [ "Sequences" ], "operationId": "sequences_deleteSequenceExecutions", "parameters": [ { "name": "sequenceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid executionIds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Executions deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "description": "Success message" } }, "description": "Success response" } } } } }, "summary": "Delete multiple executions.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "executionIds": { "type": "array", "items": { "type": "string" }, "description": "Array of execution IDs" } }, "required": [ "executionIds" ], "description": "Request body for bulk execution operations" } } }, "description": "Execution IDs to delete" } } }, "/api/v0/sequences/{sequenceId}/executions/approve": { "post": { "tags": [ "Sequences" ], "operationId": "sequences_approveSequenceExecutions", "parameters": [ { "name": "sequenceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid executionIds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Executions approved", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "description": "Success message" } }, "description": "Success response" } } } } }, "summary": "Approve multiple executions for sending.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "executionIds": { "type": "array", "items": { "type": "string" }, "description": "Array of execution IDs" } }, "required": [ "executionIds" ], "description": "Request body for bulk execution operations" } } }, "description": "Execution IDs to approve" } } }, "/api/v0/sequences/{sequenceId}/executions/execute": { "post": { "tags": [ "Sequences" ], "operationId": "sequences_executeSequenceExecutions", "parameters": [ { "name": "sequenceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid executionIds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Executions sent", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "description": "Success message" } }, "description": "Success response" } } } } }, "summary": "Execute (send) multiple approved executions.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "executionIds": { "type": "array", "items": { "type": "string" }, "description": "Array of execution IDs" } }, "required": [ "executionIds" ], "description": "Request body for bulk execution operations" } } }, "description": "Execution IDs to execute" } } }, "/api/v0/sequences/{sequenceId}/executions/regenerate": { "post": { "tags": [ "Sequences" ], "operationId": "sequences_regenerateSequenceExecutions", "parameters": [ { "name": "sequenceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid executionIds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Failed executions regenerated as drafts", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "description": "Success message" } }, "description": "Success response" } } } } }, "summary": "Regenerate failed executions for a sequence as unapproved drafts.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "executionIds": { "type": "array", "items": { "type": "string" }, "description": "Array of execution IDs" } }, "required": [ "executionIds" ], "description": "Request body for bulk execution operations" } } }, "description": "Failed execution IDs to regenerate" } } }, "/api/v0/sequences/{sequenceId}/executions/{executionId}": { "post": { "tags": [ "Sequences" ], "operationId": "sequences_editSequenceExecution", "parameters": [ { "name": "executionId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "sequenceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid execution data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Execution not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Execution updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "description": "Success message" } }, "description": "Success response" } } } } }, "summary": "Edit an execution's subject or content.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "execution": { "type": "object", "description": "Execution data: {id: string (required), subject?: string, content?: string} to update the execution content" } }, "required": [ "execution" ], "description": "Request body for editing an execution" } } }, "description": "Execution data to update" } } }, "/api/v0/sequences/{sequenceId}/executions/{executionId}/preview": { "get": { "tags": [ "Sequences" ], "operationId": "sequences_previewSequenceExecution", "parameters": [ { "name": "executionId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "sequenceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Execution not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Execution preview" } }, "summary": "Preview an execution's rendered content." } }, "/api/v0/sequences/executions/all": { "get": { "tags": [ "Sequences" ], "operationId": "sequences_getAllCompanyExecutions", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Page number (default: 1)", "default": 1 }, "description": "Page number (default: 1)" }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "description": "Items per page (default: 20)", "default": 20 }, "description": "Items per page (default: 20)" }, { "name": "executionState", "in": "query", "required": false, "schema": { "type": "string", "description": "Filter by execution state (pending, approved, executed, failed)" }, "description": "Filter by execution state (pending, approved, executed, failed)" }, { "name": "sequenceStepId", "in": "query", "required": false, "schema": { "type": "string", "description": "Filter by specific step ID" }, "description": "Filter by specific step ID" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "description": "Search query" }, "description": "Search query" } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "All company executions", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Execution ID" }, "sequenceId": { "type": "string", "description": "Sequence ID" }, "sequenceStepId": { "type": "string", "description": "Step ID" }, "sequenceMemberId": { "type": "string", "description": "Member ID" }, "subject": { "type": "string", "description": "Email/message subject" }, "content": { "type": "string", "description": "Email/message content" }, "executed": { "type": "boolean", "description": "Whether executed" }, "executedDate": { "type": "string", "description": "Execution timestamp" }, "approved": { "type": "boolean", "description": "Whether approved" }, "failed": { "type": "boolean", "description": "Whether failed" }, "failureReason": { "type": "string", "description": "Failure reason if failed" } }, "description": "Sequence step execution object" }, "description": "List of executions" }, "total": { "type": "integer", "description": "Total count" } }, "description": "Paginated executions list" } } } } }, "summary": "Get all executions across all sequences for a company." } }, "/api/v0/sequences/executions/approve": { "post": { "tags": [ "Sequences" ], "operationId": "sequences_approveAllCompanyExecutions", "parameters": [], "responses": { "400": { "description": "Invalid executionIds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Executions approved", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "description": "Success message" } }, "description": "Success response" } } } } }, "summary": "Approve executions across multiple sequences.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "executionIds": { "type": "array", "items": { "type": "string" }, "description": "Array of execution IDs" } }, "required": [ "executionIds" ], "description": "Request body for bulk execution operations" } } }, "description": "Execution IDs to approve" } } }, "/api/v0/sequences/executions/execute": { "post": { "tags": [ "Sequences" ], "operationId": "sequences_executeAllCompanyExecutions", "parameters": [], "responses": { "400": { "description": "Invalid executionIds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Executions sent", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "description": "Success message" } }, "description": "Success response" } } } } }, "summary": "Execute approved executions across multiple sequences.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "executionIds": { "type": "array", "items": { "type": "string" }, "description": "Array of execution IDs" } }, "required": [ "executionIds" ], "description": "Request body for bulk execution operations" } } }, "description": "Execution IDs to execute" } } }, "/api/v0/sequences/executions/regenerate": { "post": { "tags": [ "Sequences" ], "operationId": "sequences_regenerateAllCompanyExecutions", "parameters": [], "responses": { "400": { "description": "Invalid executionIds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Failed executions regenerated as drafts", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "description": "Success message" } }, "description": "Success response" } } } } }, "summary": "Regenerate failed executions across sequences as unapproved drafts.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "executionIds": { "type": "array", "items": { "type": "string" }, "description": "Array of execution IDs" } }, "required": [ "executionIds" ], "description": "Request body for bulk execution operations" } } }, "description": "Failed execution IDs to regenerate" } } }, "/api/v0/sequences/executions/delete": { "post": { "tags": [ "Sequences" ], "operationId": "sequences_deleteAllCompanyExecutions", "parameters": [], "responses": { "400": { "description": "Invalid executionIds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Executions deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "description": "Success message" } }, "description": "Success response" } } } } }, "summary": "Delete executions across multiple sequences.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "executionIds": { "type": "array", "items": { "type": "string" }, "description": "Array of execution IDs" } }, "required": [ "executionIds" ], "description": "Request body for bulk execution operations" } } }, "description": "Execution IDs to delete" } } }, "/api/v0/sequences/executions/skip": { "post": { "tags": [ "Sequences" ], "operationId": "sequences_skipExecutions", "parameters": [], "responses": { "400": { "description": "Invalid executionIds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Executions skipped", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "description": "Success message" } }, "description": "Success response" } } } } }, "summary": "Skip executions (typically validation failures).", "description": "Marks them as executed so the sequence can continue,\nbut also marks them as failed with the skip reason.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "executionIds": { "type": "array", "items": { "type": "string" }, "description": "Array of execution IDs" } }, "required": [ "executionIds" ], "description": "Request body for bulk execution operations" } } }, "description": "Execution IDs to skip" } } }, "/api/v0/sequences/executions/{executionId}/rebuild": { "post": { "tags": [ "Sequences" ], "operationId": "sequences_rebuildExecution", "parameters": [ { "name": "executionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Cannot rebuild executed step", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Execution not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Rebuilt execution with new content" } }, "summary": "Rebuild an execution's content using AI personalization.", "description": "Regenerates the subject and content for the execution based on the step's settings." } }, "/api/v0/sequences/executions/{executionId}/rerun": { "post": { "tags": [ "Sequences" ], "operationId": "sequences_rerunExecution", "parameters": [ { "name": "executionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Execution not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Rerun execution result" } }, "summary": "Rerun an execution - reset its status and optionally regenerate content.", "description": "This allows failed or executed steps to be retried." } }, "/api/v0/sequences/profiles": { "get": { "tags": [ "Sequences" ], "operationId": "sequences_listProfiles", "parameters": [ { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID." }, "description": "Company ID." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Page number (default: 1)", "default": 1 }, "description": "Page number (default: 1)" }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "description": "Items per page (default: 50)", "default": 50 }, "description": "Items per page (default: 50)" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "description": "Search by name or email" }, "description": "Search by name or email" } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Paginated list of sender profiles", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Profile ID" }, "name": { "type": "string", "description": "Profile name" }, "email": { "type": "string", "description": "Sender email" }, "signature": { "type": "string", "description": "Email signature" }, "dailySendingLimit": { "type": "integer", "description": "Daily sending limit" }, "slowRampEnabled": { "type": "boolean", "description": "Whether slow ramp is enabled for this profile" }, "rampStartDate": { "type": "string", "description": "When the slow ramp was first enabled (server-managed; the ramp runs once and is never reset)" }, "effectiveDailyLimit": { "type": "integer", "description": "Daily limit currently in effect after applying the slow ramp" }, "integrationId": { "type": "string", "description": "Email integration ID" } }, "description": "Sender profile object" }, "description": "List of profiles" }, "total": { "type": "integer", "description": "Total count" } }, "description": "Paginated profiles list" } } } } }, "summary": "List all sender profiles for a company." }, "post": { "tags": [ "Sequences" ], "operationId": "sequences_createProfile", "parameters": [], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Created profile" } }, "summary": "Create a new sender profile.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Profile name" }, "email": { "type": "string", "description": "Sender email address" }, "signature": { "type": "string", "description": "Email signature HTML" }, "integrationId": { "type": "string", "description": "Email integration ID this profile sends from. To find valid IDs, call integrations_getIntegrationsByType with path integration_type=email." }, "dailySendingLimit": { "type": "integer", "description": "Daily email sending limit" }, "slowRampEnabled": { "type": "boolean", "description": "Gradually increase the number of emails sent per day until the daily sending limit is reached" }, "linkedinIntegrationId": { "type": "string", "description": "This profile's LinkedIn account for LinkedIn steps. To find valid IDs, call integrations_getIntegrationsByType with path integration_type=browser_session and query type=linkedin_login." }, "phoneIntegrationId": { "type": "string", "description": "This profile's Twilio/phone integration for SMS and voice steps. To find valid IDs, call integrations_getIntegrationsByType with path integration_type=sms." }, "phone": { "type": "string", "description": "Sending phone number (E.164) for this profile, drawn from phoneIntegrationId. To find available numbers, call integrations_getTwilioPhoneNumbers with that integration_id." }, "voiceId": { "type": "string", "description": "Voice ID for this profile's voice-message steps. To find valid IDs, call voices_listVoices." }, "agentId": { "type": "string", "description": "Agent ID that drives this profile's agent-conversation steps. To find valid IDs, call agents_listAgents." }, "employeeId": { "type": "string", "description": "Optional employee persona to associate with this profile." } }, "required": [ "name", "email" ], "description": "Request body for creating a sender profile" } } }, "description": "Profile data" } } }, "/api/v0/sequences/profiles/{profileId}": { "put": { "tags": [ "Sequences" ], "operationId": "sequences_updateProfile", "parameters": [ { "name": "profileId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Profile not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Updated profile" } }, "summary": "Update a sender profile.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Profile name" }, "email": { "type": "string", "description": "Sender email address" }, "signature": { "type": "string", "description": "Email signature HTML" }, "integrationId": { "type": "string", "description": "Email integration ID this profile sends from. To find valid IDs, call integrations_getIntegrationsByType with path integration_type=email." }, "dailySendingLimit": { "type": "integer", "description": "Daily email sending limit" }, "slowRampEnabled": { "type": "boolean", "description": "Gradually increase the number of emails sent per day until the daily sending limit is reached" }, "linkedinIntegrationId": { "type": "string", "description": "This profile's LinkedIn account for LinkedIn steps. To find valid IDs, call integrations_getIntegrationsByType with path integration_type=browser_session and query type=linkedin_login." }, "phoneIntegrationId": { "type": "string", "description": "This profile's Twilio/phone integration for SMS and voice steps. To find valid IDs, call integrations_getIntegrationsByType with path integration_type=sms." }, "phone": { "type": "string", "description": "Sending phone number (E.164) for this profile, drawn from phoneIntegrationId. To find available numbers, call integrations_getTwilioPhoneNumbers with that integration_id." }, "voiceId": { "type": "string", "description": "Voice ID for this profile's voice-message steps. To find valid IDs, call voices_listVoices." }, "agentId": { "type": "string", "description": "Agent ID that drives this profile's agent-conversation steps. To find valid IDs, call agents_listAgents." }, "employeeId": { "type": "string", "description": "Optional employee persona to associate with this profile." } }, "required": [ "name", "email" ], "description": "Request body for creating a sender profile" } } }, "description": "Profile data to update" } }, "delete": { "tags": [ "Sequences" ], "operationId": "sequences_deleteProfile", "parameters": [ { "name": "profileId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Profile not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Profile deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "description": "Success message" } }, "description": "Success response" } } } } }, "summary": "Delete a sender profile." } }, "/api/v0/sequences/profiles/bulk-update": { "post": { "tags": [ "Sequences" ], "operationId": "sequences_bulkUpdateProfiles", "parameters": [], "responses": { "400": { "description": "Missing required fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Number of profiles updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "updated": { "type": "integer", "description": "Number of items updated" } }, "description": "Bulk update result" } } } } }, "summary": "Bulk update multiple sender profiles with the same values.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "profileIds": { "type": "array", "items": { "type": "string" }, "description": "Array of profile IDs to update" }, "updates": { "type": "object", "description": "Fields to update: {dailySendingLimit?: number, trackingDomainId?: string, signature?: string, slowRampEnabled?: boolean}" } }, "required": [ "profileIds", "updates" ], "description": "Request body for bulk updating sender profiles" } } }, "description": "Bulk update parameters" } } }, "/api/v0/sequences/profiles/bulk-update-signature": { "post": { "tags": [ "Sequences" ], "operationId": "sequences_bulkUpdateSignature", "parameters": [], "responses": { "400": { "description": "Missing required fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Number of profiles updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "updated": { "type": "integer", "description": "Number of items updated" } }, "description": "Bulk update result" } } } } }, "summary": "Bulk update signatures for multiple sender profiles with variable replacement.", "description": "Supported variables:\n{{name}} - The sender profile's name\n{{email}} - The sender profile's email address\n{{first_name}} - First word of the name\n{{last_name}} - Last word of the name (if multiple words)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "profileIds": { "type": "array", "items": { "type": "string" }, "description": "Array of profile IDs" }, "signatureTemplate": { "type": "string", "description": "Signature template with variables: {{name}}, {{email}}, {{first_name}}, {{last_name}}" } }, "required": [ "profileIds", "signatureTemplate" ], "description": "Request body for bulk updating profile signatures" } } }, "description": "Bulk signature update parameters" } } }, "/api/v0/sequences/{sequenceId}/step-metrics": { "get": { "tags": [ "Sequences" ], "operationId": "sequences_getSequenceStepMetrics", "parameters": [ { "name": "sequenceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Step-level metrics for a sequence" } }, "summary": "Get metrics broken down by step for a sequence." } }, "/api/v0/sequences/{sequenceId}/manual-metric": { "post": { "tags": [ "Sequences" ], "operationId": "sequences_addSequenceManualMetric", "parameters": [ { "name": "sequenceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Member or step not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Manually record a metric (booking or reply) for a member at a specific step.", "description": "Used when a recipient takes a tracked action off-channel and the user wants to\ncredit it to the correct sequence step for attribution." } }, "/api/v0/sequences/metrics": { "get": { "tags": [ "Sequences" ], "operationId": "sequences_getSequenceMetrics", "parameters": [], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Aggregate sequence metrics", "content": { "application/json": { "schema": { "type": "object", "properties": { "sent": { "type": "integer", "description": "Total messages sent" }, "delivered": { "type": "integer", "description": "Total delivered" }, "opened": { "type": "integer", "description": "Total opened" }, "clicked": { "type": "integer", "description": "Total clicked" }, "replied": { "type": "integer", "description": "Total replied" }, "bounced": { "type": "integer", "description": "Total bounced" } }, "description": "Sequence metrics" } } } } }, "summary": "Get aggregate metrics for all sequences." } }, "/api/v0/sequences/executions/{executionId}": { "get": { "tags": [ "Sequences" ], "operationId": "sequences_getSequenceExecution", "parameters": [ { "name": "executionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Execution not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Execution with sequence and member details" } }, "summary": "Get a single execution with its sequence and member details." } }, "/api/v0/sequence-steps/{stepId}/details": { "get": { "tags": [ "Sequences" ], "operationId": "sequences_getSequenceStepDetails", "parameters": [ { "name": "stepId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Step not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Step with sender profile and integration details" } }, "summary": "Get sequence step with sender profile and integration details." } }, "/api/v0/sequences/hourly-metrics": { "get": { "tags": [ "Sequences" ], "operationId": "sequences_getAllSequencesHourlyMetrics", "parameters": [], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Hourly execution metrics for all sequences" } }, "summary": "Get hourly execution metrics for all sequences in a company." } }, "/api/v0/sequences/{sequenceId}/hourly-metrics": { "get": { "tags": [ "Sequences" ], "operationId": "sequences_getSequenceHourlyMetrics", "parameters": [ { "name": "sequenceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Hourly execution metrics for a specific sequence" } }, "summary": "Get hourly execution metrics for a specific sequence." } }, "/api/v0/sequences/{sequenceId}/steps/{stepId}/test": { "post": { "tags": [ "Sequences" ], "operationId": "sequences_testSequenceStep", "parameters": [ { "name": "stepId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "sequenceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Step or member not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Test step content preview" } }, "summary": "Test a sequence step with a specific member to preview AI-generated content." } }, "/api/v0/sequences/{sequenceId}/steps/{stepId}/test/send": { "post": { "tags": [ "Sequences" ], "operationId": "sequences_sendTestEmail", "parameters": [ { "name": "stepId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "sequenceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Missing required fields or no sender profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Sequence or step not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Test email sent", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "description": "Success message" } }, "description": "Success response" } } } } }, "summary": "Send a test email to a specified address with pre-generated content." } }, "/api/v0/sequences/{sequenceId}/members/{memberId}/profile": { "get": { "tags": [ "Sequences" ], "operationId": "sequences_getMemberProfile", "parameters": [ { "name": "sequenceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "memberId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Member not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Comprehensive member profile across platform" } }, "summary": "Get comprehensive profile data for a sequence member.", "description": "Finds the member across different parts of the platform:\n- Sequence member data\n- Smart list appearances\n- Agent conversations\n- Other sequences" } }, "/api/v0/sequences/{sequenceId}/available-fields": { "get": { "tags": [ "Sequences" ], "operationId": "sequences_getAvailableFields", "parameters": [ { "name": "sequenceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Sequence not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Available fields for variable insertion" } }, "summary": "Get all available fields for variable insertion in a sequence.", "description": "This includes standard member fields and custom userData fields from sequence members.\n\nReturns:\n- standardFields: List of standard member fields\n- customFields: List of unique custom fields found in member userData" } }, "/api/v0/unsubscribes/check": { "post": { "tags": [ "Sequences" ], "operationId": "sequences_checkEmailUnsubscribe", "parameters": [], "responses": { "400": { "description": "Missing required fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Unsubscribe status", "content": { "application/json": { "schema": { "type": "object", "properties": { "unsubscribed": { "type": "boolean", "description": "Whether email is unsubscribed" }, "reason": { "type": "string", "description": "Reason for unsubscribe" } }, "description": "Unsubscribe check response" } } } } }, "summary": "Check if an email is unsubscribed from a company.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "Email to check" }, "companyId": { "type": "string", "description": "Company ID" } }, "required": [ "email", "companyId" ], "description": "Request body for checking unsubscribe status" } } }, "description": "Email and company to check" } } }, "/api/v0/unsubscribes": { "post": { "tags": [ "Sequences" ], "operationId": "sequences_addUnsubscribe", "parameters": [], "responses": { "400": { "description": "Missing required fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Created unsubscribe record", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unsubscribe ID" }, "email": { "type": "string", "description": "Email address" }, "companyId": { "type": "string", "description": "Company ID" }, "created": { "type": "string", "description": "Creation date" } }, "description": "Created unsubscribe response" } } } } }, "summary": "Add a company-specific unsubscribe.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "Email to unsubscribe" }, "companyId": { "type": "string", "description": "Company ID" }, "reason": { "type": "string", "description": "Reason for unsubscribe" } }, "required": [ "email", "companyId" ], "description": "Request body for adding an unsubscribe" } } }, "description": "Email to unsubscribe" } }, "get": { "tags": [ "Sequences" ], "operationId": "sequences_getUnsubscribes", "parameters": [ { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID" }, "description": "Company ID" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "description": "Maximum number of results" }, "description": "Maximum number of results" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "description": "Offset for pagination" }, "description": "Offset for pagination" } ], "responses": { "400": { "description": "Missing companyId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "List of unsubscribed emails", "content": { "application/json": { "schema": { "type": "object", "properties": { "unsubscribes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unsubscribe ID" }, "email": { "type": "string", "description": "Email address" }, "reason": { "type": "string", "description": "Reason for unsubscribe" }, "source": { "type": "string", "description": "Source of unsubscribe" }, "created": { "type": "string", "description": "Creation date" } }, "description": "Unsubscribe record" }, "description": "List of unsubscribes" }, "stats": { "type": "object", "properties": { "total": { "type": "integer", "description": "Total unsubscribes" } }, "description": "Suppression stats" }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "description": "Limit" }, "offset": { "type": "integer", "description": "Offset" }, "total": { "type": "integer", "description": "Total count" } }, "description": "Pagination info" } }, "description": "List of unsubscribes" } } } } }, "summary": "Get list of unsubscribed emails for a company." } }, "/api/v0/unsubscribes/bulk": { "post": { "tags": [ "Sequences" ], "operationId": "sequences_bulkAddUnsubscribes", "parameters": [], "responses": { "400": { "description": "Missing required fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Bulk unsubscribe results", "content": { "application/json": { "schema": { "type": "object", "properties": { "added": { "type": "integer", "description": "Number of new unsubscribes added" }, "skipped": { "type": "integer", "description": "Number of emails already unsubscribed" }, "failed": { "type": "integer", "description": "Number of emails that failed" }, "results": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "description": "Email address" }, "success": { "type": "boolean", "description": "Whether the operation succeeded" }, "error": { "type": "string", "description": "Error message if failed" } }, "description": "Bulk unsubscribe result" }, "description": "Per-email results" } }, "description": "Bulk unsubscribes response" } } } } }, "summary": "Add multiple company-specific unsubscribes from a CSV import.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "emails": { "type": "array", "items": { "type": "string" }, "description": "List of emails to unsubscribe" }, "companyId": { "type": "string", "description": "Company ID" }, "reason": { "type": "string", "description": "Reason for unsubscribe" } }, "required": [ "emails", "companyId" ], "description": "Request body for bulk adding unsubscribes" } } }, "description": "Emails to unsubscribe in bulk" } } }, "/api/v0/unsubscribes/{unsubscribeId}": { "delete": { "tags": [ "Sequences" ], "operationId": "sequences_removeUnsubscribe", "parameters": [ { "name": "unsubscribeId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Unsubscribe removed", "content": { "application/json": { "schema": { "type": "object", "properties": { "removed": { "type": "integer", "description": "Number of records removed" }, "message": { "type": "string", "description": "Status message" } }, "description": "Unsubscribe removed response" } } } } }, "summary": "Remove an email from the unsubscribe list (resubscribe)." } }, "/api/v0/people/search": { "get": { "tags": [ "People" ], "operationId": "people_peopleSearch", "parameters": [ { "name": "query", "in": "query", "required": true, "schema": { "type": "string", "description": "Name or email fragment to search for (case-insensitive substring)" }, "description": "Name or email fragment to search for (case-insensitive substring)" }, { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string", "description": "Company ID to scope the search. Required for PAK/API key auth; optional for JWT auth." }, "description": "Company ID to scope the search. Required for PAK/API key auth; optional for JWT auth." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "description": "Max results per source (sequenceMembers, listRows, agentConversations, marketingCampaignRecipients). Default 50, max 200.", "default": 50 }, "description": "Max results per source (sequenceMembers, listRows, agentConversations, marketingCampaignRecipients). Default 50, max 200." } ], "responses": { "400": { "description": "Missing query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Unified people search results across sequences, lists, agent conversations, and campaigns", "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "description": "Echo of the search query" }, "people": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Person ID" }, "displayName": { "type": "string", "description": "Best-known display name" }, "firstName": { "type": "string", "description": "First name" }, "lastName": { "type": "string", "description": "Last name" }, "email": { "type": "string", "description": "Primary email (normalized)" }, "contactEmails": { "type": "array", "items": { "type": "string" }, "description": "Contact addresses from accessible linked lists and sequences, including role mailboxes." }, "phone": { "type": "string", "description": "Primary phone (E.164)" }, "linkedinUrl": { "type": "string", "description": "LinkedIn vanity slug" }, "companyName": { "type": "string", "description": "Company name" }, "jobTitle": { "type": "string", "description": "Job title" }, "website": { "type": "string", "description": "Website" }, "photoUrl": { "type": "string", "description": "Company photo derived from the website at read time" }, "city": { "type": "string", "description": "City" }, "state": { "type": "string", "description": "State" }, "country": { "type": "string", "description": "Country" }, "companyIndustry": { "type": "string", "description": "Industry of the person's company" }, "companySize": { "type": "string", "description": "Employee count or size range of the person's company" }, "companyDescription": { "type": "string", "description": "Description of the person's company" }, "sourceCounts": { "type": "object", "description": "Touchpoint count per source type, e.g. {\"sequence_member\": 3}" }, "touchpointCount": { "type": "integer", "description": "Total touchpoints across all sources" }, "needsReview": { "type": "boolean", "description": "True when a weak (name+company) key contributed to this profile and the merge should be confirmed" }, "firstSeenDate": { "type": "string", "description": "Earliest touchpoint (ISO 8601)" }, "lastSeenDate": { "type": "string", "description": "Latest touchpoint (ISO 8601)" }, "lastEngagementDate": { "type": "string", "description": "Latest qualifying inbound or bot-filtered engagement; outbound and opens excluded" }, "lastEngagementType": { "type": "string" }, "identifiers": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Key type: email, phone, linkedin, or name_company" }, "value": { "type": "string", "description": "The normalized key value (e.g. \"+14155551234\", not \"(415) 555-1234\")" }, "tier": { "type": "string", "description": "strong (email/phone/linkedin \u2014 uniquely identifies a person) or weak (name_company \u2014 may collide)" }, "disabled": { "type": "boolean", "description": "True when a reviewer has excluded this value from identity matching" }, "linkCount": { "type": "integer", "description": "Number of source records currently linked using this key" } }, "description": "Normalized identity key" }, "description": "Every key resolving to this person (detail view only)" } }, "description": "A person resolved across every source in the company" }, "description": "Resolved people matching the query. Each per-source match below carries the personId it resolved to, so matches across buckets can be attributed to the same human. Empty when the company has not yet built its identity graph, in which case the buckets fall back to a direct scan." }, "sequenceMembers": { "type": "array", "items": { "type": "object", "properties": { "memberId": { "type": "string", "description": "Sequence member ID" }, "sequenceId": { "type": "string", "description": "Parent sequence ID" }, "sequenceName": { "type": "string", "description": "Parent sequence name" }, "firstName": { "type": "string", "description": "First name" }, "lastName": { "type": "string", "description": "Last name" }, "email": { "type": "string", "description": "Email" }, "phone": { "type": "string", "description": "Phone" }, "status": { "type": "string", "description": "Member status (active, unsubscribed, bounced, paused, removed)" } }, "description": "Sequence member match" }, "description": "Matches from sequence members" }, "listRows": { "type": "array", "items": { "type": "object", "properties": { "rowId": { "type": "string", "description": "List row ID" }, "listId": { "type": "string", "description": "Parent list ID" }, "listName": { "type": "string", "description": "Parent list name" }, "matchedColumn": { "type": "string", "description": "Name of the column whose value matched the query" }, "matchedValue": { "type": "string", "description": "The value that matched (truncated to 500 chars)" } }, "description": "List row match" }, "description": "Matches from list rows" }, "agentConversations": { "type": "array", "items": { "type": "object", "properties": { "conversationId": { "type": "string", "description": "Agent conversation ID" }, "agentId": { "type": "string", "description": "Parent agent ID" }, "agentName": { "type": "string", "description": "Parent agent name" }, "sessionId": { "type": "string", "description": "Session identifier on the conversation" }, "channel": { "type": "string", "description": "Conversation channel (website, email, sms, etc.)" }, "status": { "type": "string", "description": "Conversation status (active, ended, archived)" }, "contactName": { "type": "string", "description": "Contact name from contactInfo" }, "contactEmail": { "type": "string", "description": "Contact email from contactInfo" }, "contactPhone": { "type": "string", "description": "Contact phone from contactInfo" }, "lastActivityAt": { "type": "number", "description": "Unix timestamp of last activity" } }, "description": "Agent conversation match" }, "description": "Matches from agent conversations (via contactInfo on AgentConversationV2)" }, "marketingCampaignRecipients": { "type": "array", "items": { "type": "object", "properties": {}, "description": "Marketing campaign recipient match (full row + campaignName)" }, "description": "Matches from marketing campaign recipients (email match across every campaign in the company \u2014 no campaign ID required)" } }, "description": "Unified people search results" } } } } }, "summary": "Search for people by name, email, or phone across every source in one call.", "description": "Resolves matches through the identity graph, so records that belong to the\nsame human are attributed to one person rather than returned as unrelated\nhits. Each per-source match carries the `personId` it resolved to, and the\n`people` array holds the resolved profiles.\n\nFalls back to a direct per-source scan for companies that have not yet built\ntheir identity graph (populated by a nightly background job)." } }, "/api/v0/people": { "get": { "tags": [ "People" ], "operationId": "people_getPeople", "parameters": [ { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string", "description": "Company ID to scope the query. Required for PAK/API key auth; optional for JWT auth." }, "description": "Company ID to scope the query. Required for PAK/API key auth; optional for JWT auth." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "1-indexed page number", "default": 1 }, "description": "1-indexed page number" }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "description": "Results per page. Default 50, max 200.", "default": 50 }, "description": "Results per page. Default 50, max 200." }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "description": "Search name, email, company, or any normalized identifier" }, "description": "Search name, email, company, or any normalized identifier" }, { "name": "sourceType", "in": "query", "required": false, "schema": { "type": "string", "description": "Only people with at least one touchpoint of this source type" }, "description": "Only people with at least one touchpoint of this source type" }, { "name": "needsReview", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Filter to people whose identity merge needs confirmation" }, "description": "Filter to people whose identity merge needs confirmation" }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "engagement", "name" ], "default": "engagement" } }, { "name": "engaged", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Filter by presence of qualifying engagement" }, "description": "Filter by presence of qualifying engagement" } ], "responses": { "400": { "description": "Missing companyId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Paginated resolved people", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Person ID" }, "displayName": { "type": "string", "description": "Best-known display name" }, "firstName": { "type": "string", "description": "First name" }, "lastName": { "type": "string", "description": "Last name" }, "email": { "type": "string", "description": "Primary email (normalized)" }, "contactEmails": { "type": "array", "items": { "type": "string" }, "description": "Contact addresses from accessible linked lists and sequences, including role mailboxes." }, "phone": { "type": "string", "description": "Primary phone (E.164)" }, "linkedinUrl": { "type": "string", "description": "LinkedIn vanity slug" }, "companyName": { "type": "string", "description": "Company name" }, "jobTitle": { "type": "string", "description": "Job title" }, "website": { "type": "string", "description": "Website" }, "photoUrl": { "type": "string", "description": "Company photo derived from the website at read time" }, "city": { "type": "string", "description": "City" }, "state": { "type": "string", "description": "State" }, "country": { "type": "string", "description": "Country" }, "companyIndustry": { "type": "string", "description": "Industry of the person's company" }, "companySize": { "type": "string", "description": "Employee count or size range of the person's company" }, "companyDescription": { "type": "string", "description": "Description of the person's company" }, "sourceCounts": { "type": "object", "description": "Touchpoint count per source type, e.g. {\"sequence_member\": 3}" }, "touchpointCount": { "type": "integer", "description": "Total touchpoints across all sources" }, "needsReview": { "type": "boolean", "description": "True when a weak (name+company) key contributed to this profile and the merge should be confirmed" }, "firstSeenDate": { "type": "string", "description": "Earliest touchpoint (ISO 8601)" }, "lastSeenDate": { "type": "string", "description": "Latest touchpoint (ISO 8601)" }, "lastEngagementDate": { "type": "string", "description": "Latest qualifying inbound or bot-filtered engagement; outbound and opens excluded" }, "lastEngagementType": { "type": "string" }, "identifiers": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Key type: email, phone, linkedin, or name_company" }, "value": { "type": "string", "description": "The normalized key value (e.g. \"+14155551234\", not \"(415) 555-1234\")" }, "tier": { "type": "string", "description": "strong (email/phone/linkedin \u2014 uniquely identifies a person) or weak (name_company \u2014 may collide)" }, "disabled": { "type": "boolean", "description": "True when a reviewer has excluded this value from identity matching" }, "linkCount": { "type": "integer", "description": "Number of source records currently linked using this key" } }, "description": "Normalized identity key" }, "description": "Every key resolving to this person (detail view only)" } }, "description": "A person resolved across every source in the company" }, "description": "People on this page" }, "total": { "type": "integer", "description": "Total people matching the query" }, "page": { "type": "integer", "description": "Current page (1-indexed)" }, "pageSize": { "type": "integer", "description": "Results per page" } }, "description": "Paginated resolved people" } } } } }, "summary": "List resolved people for the company.", "description": "Each person unifies every touchpoint across smart lists, sequences,\nmarketing campaigns, agent conversations, and the inbox. Server-side\npaginated; `search` matches names, emails, companies, and any normalized\nidentifier (so \"(415) 555-1234\" finds a person stored as \"+14155551234\")." } }, "/api/v0/people/stats": { "get": { "tags": [ "People" ], "operationId": "people_getPeopleStats", "parameters": [], "responses": { "400": { "description": "Missing companyId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Identity graph stats for the company", "content": { "application/json": { "schema": { "type": "object", "properties": { "totalPeople": { "type": "integer", "description": "Resolved people" }, "needsReview": { "type": "integer", "description": "People whose merge needs confirmation" }, "totalTouchpoints": { "type": "integer", "description": "Total links across all sources" }, "touchpointsBySource": { "type": "object", "description": "Link count per source type" }, "lastRun": { "type": "object", "description": "The most recent backfill run, or null if never run" } }, "description": "Identity graph stats" } } } } }, "summary": "Summary of the company's identity graph, plus its most recent backfill run." } }, "/api/v0/people/sync": { "post": { "tags": [ "People" ], "operationId": "people_syncPeople", "parameters": [], "responses": { "400": { "description": "Missing companyId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Queue the normal identity refresh, including connected CRM sources." } }, "/api/v0/people/graph": { "get": { "tags": [ "People" ], "operationId": "people_getCompanyGraph", "parameters": [], "responses": { "400": { "description": "Missing companyId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "A bounded account \u2192 person \u2192 source map for the interactive graph view." } }, "/api/v0/people/{personId}/activity": { "get": { "tags": [ "People" ], "operationId": "people_getPersonActivity", "parameters": [ { "name": "personId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string", "description": "Company ID. Required for PAK/API key auth; optional for JWT auth." }, "description": "Company ID. Required for PAK/API key auth; optional for JWT auth." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "1-indexed page number", "default": 1 }, "description": "1-indexed page number" }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "description": "Events per page. Default 50, max 200.", "default": 50 }, "description": "Events per page. Default 50, max 200." }, { "name": "eventTypes", "in": "query", "required": false, "schema": { "type": "string", "description": "Comma-separated event types to include. Any of: open, click, schedule_view, schedule_booking, status_change, voice_call_completed. Omit for all." }, "description": "Comma-separated event types to include. Any of: open, click, schedule_view, schedule_booking, status_change, voice_call_completed. Omit for all." }, { "name": "engagementOnly", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Use the server-paginated engagement feed, including complete inbound and outbound email conversations" }, "description": "Use the server-paginated engagement feed, including complete inbound and outbound email conversations" }, { "name": "includeBots", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Include events attributed to scanners and mail-proxy prefetchers (Microsoft Safe Links, GoogleImageProxy, etc.). Excluded by default because they are not human actions.", "default": false }, "description": "Include events attributed to scanners and mail-proxy prefetchers (Microsoft Safe Links, GoogleImageProxy, etc.). Excluded by default because they are not human actions." } ], "responses": { "400": { "description": "Missing companyId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Person not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Paginated engagement timeline for one person", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Tracking event ID" }, "type": { "type": "string", "description": "Raw event type", "enum": [ "open", "click", "schedule_view", "schedule_booking", "status_change", "voice_call_completed" ] }, "label": { "type": "string", "description": "Human-readable label, e.g. \"Opened email\"" }, "channel": { "type": "string", "description": "Broad channel: email, schedule, voice, or sequence" }, "occurredAt": { "type": "string", "description": "UTC ISO-8601 timestamp with microsecond precision" }, "subject": { "type": "string", "description": "Subject of the email the event belongs to" }, "content": { "type": "string", "description": "Message content, when available for an engagement event" }, "sequenceId": { "type": "string", "description": "Parent sequence ID" }, "sequenceName": { "type": "string", "description": "Parent sequence name" }, "executionId": { "type": "string", "description": "Sequence step execution ID" }, "memberId": { "type": "string", "description": "Sequence member ID this event belongs to" }, "url": { "type": "string", "description": "Destination URL, on click events only" }, "fromStatus": { "type": "string", "description": "Previous status, on status_change events only" }, "toStatus": { "type": "string", "description": "New status, on status_change events only" }, "isBot": { "type": "boolean", "description": "True when attributed to a scanner or prefetcher rather than a human" }, "botProvider": { "type": "string", "description": "Which scanner was identified, when isBot is true" }, "ipAddress": { "type": "string", "description": "Originating IP" }, "userAgent": { "type": "string", "description": "Originating user agent" }, "referrer": { "type": "string", "description": "Referrer, when present" } }, "description": "A single activity event" }, "description": "Events, newest first" }, "total": { "type": "integer", "description": "Total events matching the current filters" }, "page": { "type": "integer", "description": "Current page" }, "pageSize": { "type": "integer", "description": "Events per page" }, "botCount": { "type": "integer", "description": "Bot events excluded from (or included in) this filter set" }, "truncated": { "type": "boolean", "description": "True when the person has more events than one scan covers, so older history is omitted" } }, "description": "Paginated person activity timeline" } } } } }, "summary": "What this person actually did, newest first, to the microsecond.", "description": "Where the profile's touchpoints say where a person *appears*, this says how\nthey *behaved*: opens, link clicks, scheduling-page views, bookings, calls\nand sequence status changes, merged into one time-ordered stream.\n\nCurrently covers sequence engagement. Marketing campaigns record only\nfirst/last open and click counters rather than individual events, and the\nwebsite pixel keeps one row per person rather than one per visit, so\nneither can contribute a real event stream yet.\n\nEvents attributed to scanners and mail-proxy prefetchers (Microsoft Safe\nLinks, GoogleImageProxy) are excluded by default -- they are not human\nactions, and counting them would overstate engagement. `botCount` reports\nhow many were held back; pass `includeBots=true` to see them, each flagged\nwith `isBot` and the provider that was identified." } }, "/api/v0/people/{personId}/activities": { "get": { "tags": [ "People" ], "operationId": "people_getPersonActivities", "parameters": [ { "name": "personId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string", "description": "Company ID. Required for PAK/API key auth; optional for JWT auth." }, "description": "Company ID. Required for PAK/API key auth; optional for JWT auth." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "1-indexed page number", "default": 1 }, "description": "1-indexed page number" }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "description": "Activities per page. Default 50, max 200.", "default": 50 }, "description": "Activities per page. Default 50, max 200." } ], "responses": { "400": { "description": "Missing companyId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Person not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Paginated unified activity timeline for one person", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object" }, "description": "Chronological activity entries. Every item has kind, type, and occurredAt; custom entries also include text, data, source, and externalId." }, "total": { "type": "integer", "description": "Activities available in this bounded timeline scan" }, "page": { "type": "integer", "description": "Current page" }, "pageSize": { "type": "integer", "description": "Activities per page" }, "botCount": { "type": "integer", "description": "Bot-attributed engagement events excluded from the feed" }, "truncated": { "type": "boolean", "description": "True when an activity source exceeded its bounded timeline scan" } } } } } } }, "summary": "List every available person activity: engagement events and custom entries." }, "post": { "tags": [ "People" ], "operationId": "people_createPersonActivity", "parameters": [ { "name": "personId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Missing companyId or invalid activity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Person not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "201": { "description": "Custom activity added to the person", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Activity ID" }, "personId": { "type": "string", "description": "Resolved person ID" }, "activityType": { "type": "string", "description": "Activity category; can be a recommended or custom value" }, "text": { "type": "string", "description": "Human-readable activity text" }, "url": { "type": "string", "description": "Related URL, when supplied" }, "externalId": { "type": "string", "description": "Source-system activity ID, when supplied" }, "source": { "type": "string", "description": "Source-system name, when supplied" }, "data": { "type": "object", "description": "Source-specific JSON object" }, "occurredAt": { "type": "string", "description": "UTC ISO-8601 occurrence timestamp; falls back to createdAt for legacy or authored activities" }, "createdAt": { "type": "string", "description": "UTC ISO-8601 creation timestamp" }, "updatedAt": { "type": "string", "description": "UTC ISO-8601 update timestamp" } }, "description": "A custom activity attached to a resolved person" } } } } }, "summary": "Append a text activity to a resolved person.", "description": "When both ``source`` and ``externalId`` are supplied, repeated requests are\nidempotent and return the original activity instead of adding a duplicate.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID. Required for PAK/API key auth; optional for JWT auth." }, "activityType": { "type": "string", "description": "Activity category used for display. Recommended values: note, call, meeting, email, message, task, event, research; custom values are allowed." }, "text": { "type": "string", "description": "Human-readable activity text" }, "url": { "type": "string", "description": "Optional related URL" }, "externalId": { "type": "string", "description": "Optional source-system activity ID. Deduplicates when source is also supplied." }, "source": { "type": "string", "description": "Optional source-system name. Used with externalId as an idempotency key." }, "data": { "type": "object", "description": "Optional source-specific JSON object, such as accountId or provider metadata" }, "occurredAt": { "type": "string", "description": "Optional ISO-8601 timestamp for when the activity occurred. Must include a UTC offset; defaults to the creation time when omitted." } }, "required": [ "activityType", "text" ], "description": "A custom person activity" } } } } } }, "/api/v0/people/{personId}/activities/{activityId}": { "patch": { "tags": [ "People" ], "operationId": "people_updatePersonActivity", "parameters": [ { "name": "personId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "activityId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Missing companyId or invalid update", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Person or activity not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Updated custom person activity", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Activity ID" }, "personId": { "type": "string", "description": "Resolved person ID" }, "activityType": { "type": "string", "description": "Activity category; can be a recommended or custom value" }, "text": { "type": "string", "description": "Human-readable activity text" }, "url": { "type": "string", "description": "Related URL, when supplied" }, "externalId": { "type": "string", "description": "Source-system activity ID, when supplied" }, "source": { "type": "string", "description": "Source-system name, when supplied" }, "data": { "type": "object", "description": "Source-specific JSON object" }, "occurredAt": { "type": "string", "description": "UTC ISO-8601 occurrence timestamp; falls back to createdAt for legacy or authored activities" }, "createdAt": { "type": "string", "description": "UTC ISO-8601 creation timestamp" }, "updatedAt": { "type": "string", "description": "UTC ISO-8601 update timestamp" } }, "description": "A custom activity attached to a resolved person" } } } } }, "summary": "Update display and content fields without changing source idempotency.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "activityType": { "type": "string", "description": "Activity category. Recommended values: note, call, meeting, email, message, task, event, research; custom values are allowed." }, "text": { "type": "string", "description": "Human-readable activity text" }, "url": { "type": "string", "description": "Related URL; null clears it" }, "data": { "type": "object", "description": "Source-specific JSON object; null clears it" }, "occurredAt": { "type": "string", "description": "ISO-8601 occurrence timestamp. Null clears it and falls back to createdAt." } } } } } } }, "delete": { "tags": [ "People" ], "operationId": "people_deletePersonActivity", "parameters": [ { "name": "personId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "activityId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Missing companyId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Person or activity not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Delete one authored/imported activity; source events are read-only." } }, "/api/v0/people/{personId}": { "get": { "tags": [ "People" ], "operationId": "people_getPerson", "parameters": [ { "name": "personId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Missing companyId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Person not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Full person profile with touchpoints grouped by source", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Person ID" }, "displayName": { "type": "string", "description": "Best-known display name" }, "lastEngagementDate": { "type": "string", "description": "Latest qualifying inbound or bot-filtered engagement; outbound and opens excluded" }, "lastEngagementType": { "type": "string" }, "identifiers": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Key type: email, phone, linkedin, or name_company" }, "value": { "type": "string", "description": "The normalized key value (e.g. \"+14155551234\", not \"(415) 555-1234\")" }, "tier": { "type": "string", "description": "strong (email/phone/linkedin \u2014 uniquely identifies a person) or weak (name_company \u2014 may collide)" }, "disabled": { "type": "boolean", "description": "True when a reviewer has excluded this value from identity matching" }, "linkCount": { "type": "integer", "description": "Number of source records currently linked using this key" } }, "description": "Normalized identity key" }, "description": "Every key resolving to this person" }, "touchpoints": { "type": "object", "description": "Touchpoints grouped by source type, each a list of PersonTouchpoint" }, "touchpointsTruncated": { "type": "boolean", "description": "True when the touchpoint limit was hit and more exist" } }, "description": "Full person profile with touchpoints grouped by source" } } } } }, "summary": "One person's full profile: every identifier and every touchpoint.", "description": "Touchpoints are grouped by source type and ordered newest first. This is the\nview that answers \"everywhere this human appears\" without checking each\nfeature by hand." } }, "/api/v0/inboxes": { "post": { "tags": [ "Inbox" ], "operationId": "inbox_saveInbox", "parameters": [], "responses": { "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Created inbox", "content": { "application/json": { "schema": { "type": "object", "properties": { "inbox": { "type": "object", "properties": { "id": { "type": "string", "description": "Inbox ID" }, "name": { "type": "string", "description": "Inbox name" }, "domain": { "type": "string", "description": "Email domain" }, "integrationId": { "type": "string", "description": "Integration ID" }, "companyId": { "type": "string", "description": "Company ID" }, "ownerId": { "type": "string", "description": "Owner user ID" }, "sharing": { "type": "string", "description": "Sharing mode: \"private\" or \"shared\"" }, "created": { "type": "number", "description": "Creation timestamp" }, "warmupEnabled": { "type": "boolean", "description": "Whether warmup is enabled" }, "syncEnabled": { "type": "boolean", "description": "User preference for inbox sync" }, "syncPolicyPaused": { "type": "boolean", "description": "Whether free-plan policy pauses automatic sync" }, "syncPolicyReason": { "type": "string", "description": "Reason for a free-plan sync pause" }, "freeSyncResumed": { "type": "boolean", "description": "Whether a free user has resumed hourly sync" }, "syncPolicyWarning": { "type": "boolean", "description": "Whether automatic sync will pause within seven days" }, "syncPolicyPausesAt": { "type": "string", "description": "Scheduled automatic sync pause time" } }, "description": "Inbox object" } }, "description": "Single inbox response" } } } } }, "summary": "Create a new inbox.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "name": { "type": "string", "description": "Inbox name" }, "domain": { "type": "string", "description": "Email domain" }, "integrationId": { "type": "string", "description": "Integration ID for email sending" }, "sharing": { "type": "string", "description": "Sharing mode: \"private\" or \"shared\"" } }, "required": [ "companyId" ], "description": "Request body for creating an inbox" } } }, "description": "Inbox creation data" } }, "get": { "tags": [ "Inbox" ], "operationId": "inbox_listInboxes", "parameters": [ { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string", "description": "Company ID" }, "description": "Company ID" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Page number" }, "description": "Page number" }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "description": "Items per page" }, "description": "Items per page" }, { "name": "query", "in": "query", "required": false, "schema": { "type": "string", "description": "Search query to filter inboxes by name or email" }, "description": "Search query to filter inboxes by name or email" } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "List of inboxes", "content": { "application/json": { "schema": { "type": "object", "properties": { "inboxes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Inbox ID" }, "name": { "type": "string", "description": "Inbox name" }, "domain": { "type": "string", "description": "Email domain" }, "integrationId": { "type": "string", "description": "Integration ID" }, "companyId": { "type": "string", "description": "Company ID" }, "ownerId": { "type": "string", "description": "Owner user ID" }, "sharing": { "type": "string", "description": "Sharing mode: \"private\" or \"shared\"" }, "created": { "type": "number", "description": "Creation timestamp" }, "warmupEnabled": { "type": "boolean", "description": "Whether warmup is enabled" }, "syncEnabled": { "type": "boolean", "description": "User preference for inbox sync" }, "syncPolicyPaused": { "type": "boolean", "description": "Whether free-plan policy pauses automatic sync" }, "syncPolicyReason": { "type": "string", "description": "Reason for a free-plan sync pause" }, "freeSyncResumed": { "type": "boolean", "description": "Whether a free user has resumed hourly sync" }, "syncPolicyWarning": { "type": "boolean", "description": "Whether automatic sync will pause within seven days" }, "syncPolicyPausesAt": { "type": "string", "description": "Scheduled automatic sync pause time" } }, "description": "Inbox object" }, "description": "List of inboxes" }, "total": { "type": "integer", "description": "Total count" } }, "description": "List of inboxes" } } } } }, "summary": "List inboxes visible to the user.", "description": "Only returns shared inboxes or private inboxes owned by the user.\nSupports optional 'query' parameter to search by name or email." } }, "/api/v0/inboxes/{inboxId}": { "put": { "tags": [ "Inbox" ], "operationId": "inbox_updateInbox", "parameters": [ { "name": "inboxId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Inbox not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Updated inbox", "content": { "application/json": { "schema": { "type": "object", "properties": { "inbox": { "type": "object", "properties": { "id": { "type": "string", "description": "Inbox ID" }, "name": { "type": "string", "description": "Inbox name" }, "domain": { "type": "string", "description": "Email domain" }, "integrationId": { "type": "string", "description": "Integration ID" }, "companyId": { "type": "string", "description": "Company ID" }, "ownerId": { "type": "string", "description": "Owner user ID" }, "sharing": { "type": "string", "description": "Sharing mode: \"private\" or \"shared\"" }, "created": { "type": "number", "description": "Creation timestamp" }, "warmupEnabled": { "type": "boolean", "description": "Whether warmup is enabled" }, "syncEnabled": { "type": "boolean", "description": "User preference for inbox sync" }, "syncPolicyPaused": { "type": "boolean", "description": "Whether free-plan policy pauses automatic sync" }, "syncPolicyReason": { "type": "string", "description": "Reason for a free-plan sync pause" }, "freeSyncResumed": { "type": "boolean", "description": "Whether a free user has resumed hourly sync" }, "syncPolicyWarning": { "type": "boolean", "description": "Whether automatic sync will pause within seven days" }, "syncPolicyPausesAt": { "type": "string", "description": "Scheduled automatic sync pause time" } }, "description": "Inbox object" } }, "description": "Single inbox response" } } } } }, "summary": "Update an existing inbox.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "name": { "type": "string", "description": "Inbox name" }, "domain": { "type": "string", "description": "Email domain" }, "integrationId": { "type": "string", "description": "Integration ID" }, "sharing": { "type": "string", "description": "Sharing mode: \"private\" or \"shared\"" }, "syncEnabled": { "type": "boolean", "description": "User preference for inbox sync" } }, "required": [ "companyId" ], "description": "Request body for updating an inbox" } } }, "description": "Inbox update data" } }, "delete": { "tags": [ "Inbox" ], "operationId": "inbox_deleteInbox", "parameters": [ { "name": "inboxId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string", "description": "Company ID" }, "description": "Company ID" } ], "responses": { "400": { "description": "Invalid UUID in URL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Inbox not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Deleted inbox", "content": { "application/json": { "schema": { "type": "object", "properties": { "inbox": { "type": "object", "properties": { "id": { "type": "string", "description": "Inbox ID" }, "name": { "type": "string", "description": "Inbox name" }, "domain": { "type": "string", "description": "Email domain" }, "integrationId": { "type": "string", "description": "Integration ID" }, "companyId": { "type": "string", "description": "Company ID" }, "ownerId": { "type": "string", "description": "Owner user ID" }, "sharing": { "type": "string", "description": "Sharing mode: \"private\" or \"shared\"" }, "created": { "type": "number", "description": "Creation timestamp" }, "warmupEnabled": { "type": "boolean", "description": "Whether warmup is enabled" }, "syncEnabled": { "type": "boolean", "description": "User preference for inbox sync" }, "syncPolicyPaused": { "type": "boolean", "description": "Whether free-plan policy pauses automatic sync" }, "syncPolicyReason": { "type": "string", "description": "Reason for a free-plan sync pause" }, "freeSyncResumed": { "type": "boolean", "description": "Whether a free user has resumed hourly sync" }, "syncPolicyWarning": { "type": "boolean", "description": "Whether automatic sync will pause within seven days" }, "syncPolicyPausesAt": { "type": "string", "description": "Scheduled automatic sync pause time" } }, "description": "Inbox object" } }, "description": "Single inbox response" } } } } }, "summary": "Delete an inbox." } }, "/api/v0/inboxes/{inboxId}/transfer": { "post": { "tags": [ "Inbox" ], "operationId": "inbox_transferInboxOwnership", "parameters": [ { "name": "inboxId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Inbox not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Transfer result", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether transfer was successful" }, "message": { "type": "string", "description": "Status message" }, "newOwnerId": { "type": "string", "description": "New owner user ID" } }, "description": "Transfer ownership response" } } } } }, "summary": "Transfer ownership of an inbox to another user in the company.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "newOwnerEmail": { "type": "string", "description": "Email of the new owner" } }, "required": [ "companyId", "newOwnerEmail" ], "description": "Request body for transferring inbox ownership" } } }, "description": "Transfer ownership data" } } }, "/api/v0/inboxes/for-selection": { "get": { "tags": [ "Inbox" ], "operationId": "inbox_listInboxesForSelection", "parameters": [ { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string", "description": "Company ID" }, "description": "Company ID" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Page number" }, "description": "Page number" }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "description": "Items per page" }, "description": "Items per page" } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "List of all inboxes for selection", "content": { "application/json": { "schema": { "type": "object", "properties": { "inboxes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Inbox ID" }, "name": { "type": "string", "description": "Inbox name" }, "domain": { "type": "string", "description": "Email domain" }, "integrationId": { "type": "string", "description": "Integration ID" }, "companyId": { "type": "string", "description": "Company ID" }, "ownerId": { "type": "string", "description": "Owner user ID" }, "sharing": { "type": "string", "description": "Sharing mode: \"private\" or \"shared\"" }, "created": { "type": "number", "description": "Creation timestamp" }, "warmupEnabled": { "type": "boolean", "description": "Whether warmup is enabled" }, "syncEnabled": { "type": "boolean", "description": "User preference for inbox sync" }, "syncPolicyPaused": { "type": "boolean", "description": "Whether free-plan policy pauses automatic sync" }, "syncPolicyReason": { "type": "string", "description": "Reason for a free-plan sync pause" }, "freeSyncResumed": { "type": "boolean", "description": "Whether a free user has resumed hourly sync" }, "syncPolicyWarning": { "type": "boolean", "description": "Whether automatic sync will pause within seven days" }, "syncPolicyPausesAt": { "type": "string", "description": "Scheduled automatic sync pause time" } }, "description": "Inbox object" }, "description": "List of inboxes" }, "total": { "type": "integer", "description": "Total count" } }, "description": "List of inboxes" } } } } }, "summary": "List all inboxes in the company for selection purposes.", "description": "Returns all inboxes regardless of sharing status, useful for sender profile dropdowns." } }, "/api/v0/inboxes/messages": { "get": { "tags": [ "Inbox" ], "operationId": "inbox_listAllMessages", "parameters": [ { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string", "description": "Company ID" }, "description": "Company ID" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Page number" }, "description": "Page number" }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "description": "Items per page" }, "description": "Items per page" }, { "name": "query", "in": "query", "required": false, "schema": { "type": "string", "description": "Search query to filter messages" }, "description": "Search query to filter messages" }, { "name": "messageTypes", "in": "query", "required": false, "schema": { "type": "string", "description": "Comma-separated message types: received, sent_compose, sent_reply, draft" }, "description": "Comma-separated message types: received, sent_compose, sent_reply, draft" }, { "name": "inboxIds", "in": "query", "required": false, "schema": { "type": "string", "description": "Comma-separated inbox IDs to filter by" }, "description": "Comma-separated inbox IDs to filter by" } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "List of messages", "content": { "application/json": { "schema": { "type": "object", "properties": { "messages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Message ID" }, "inboxId": { "type": "string", "description": "Inbox ID" }, "sender": { "type": "string", "description": "Sender email" }, "senderName": { "type": "string", "description": "Sender name" }, "recipient": { "type": "string", "description": "Recipient email" }, "subject": { "type": "string", "description": "Message subject" }, "body": { "type": "string", "description": "Message body (only in details)" }, "messageType": { "type": "string", "description": "Message type: received, sent_compose, sent_reply" }, "replied": { "type": "boolean", "description": "Whether the message has been replied to" }, "repliedDate": { "type": "number", "description": "Date message was replied to" }, "created": { "type": "number", "description": "Creation timestamp" } }, "description": "Inbox message object" }, "description": "List of messages" }, "total": { "type": "integer", "description": "Total count" }, "fresh": { "type": "boolean", "description": "For liveSync requests, whether every provider sync succeeded" }, "liveSync": { "type": "object", "description": "For liveSync requests, per-inbox provider sync results" } }, "description": "List of inbox messages" } } } } }, "summary": "Get messages from all inboxes or filtered by inbox IDs.", "description": "Supports filtering by message types (comma-separated) and inbox IDs." } }, "/api/v0/inboxes/{inboxId}/messages": { "get": { "tags": [ "Inbox" ], "operationId": "inbox_listMessages", "parameters": [ { "name": "inboxId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string", "description": "Company ID" }, "description": "Company ID" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Page number" }, "description": "Page number" }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "description": "Items per page" }, "description": "Items per page" }, { "name": "query", "in": "query", "required": false, "schema": { "type": "string", "description": "Search query to filter messages" }, "description": "Search query to filter messages" }, { "name": "messageTypes", "in": "query", "required": false, "schema": { "type": "string", "description": "Comma-separated message types: received, sent_compose, sent_reply, draft" }, "description": "Comma-separated message types: received, sent_compose, sent_reply, draft" }, { "name": "inboxIds", "in": "query", "required": false, "schema": { "type": "string", "description": "Comma-separated inbox IDs to filter by" }, "description": "Comma-separated inbox IDs to filter by" }, { "name": "liveSync", "in": "query", "required": false, "schema": { "type": "boolean", "description": "When true, synchronizes this inbox from its email provider before reading messages from the database" }, "description": "When true, synchronizes this inbox from its email provider before reading messages from the database" } ], "responses": { "400": { "description": "Invalid inbox ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Inbox not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "List of messages for inbox", "content": { "application/json": { "schema": { "type": "object", "properties": { "messages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Message ID" }, "inboxId": { "type": "string", "description": "Inbox ID" }, "sender": { "type": "string", "description": "Sender email" }, "senderName": { "type": "string", "description": "Sender name" }, "recipient": { "type": "string", "description": "Recipient email" }, "subject": { "type": "string", "description": "Message subject" }, "body": { "type": "string", "description": "Message body (only in details)" }, "messageType": { "type": "string", "description": "Message type: received, sent_compose, sent_reply" }, "replied": { "type": "boolean", "description": "Whether the message has been replied to" }, "repliedDate": { "type": "number", "description": "Date message was replied to" }, "created": { "type": "number", "description": "Creation timestamp" } }, "description": "Inbox message object" }, "description": "List of messages" }, "total": { "type": "integer", "description": "Total count" }, "fresh": { "type": "boolean", "description": "For liveSync requests, whether every provider sync succeeded" }, "liveSync": { "type": "object", "description": "For liveSync requests, per-inbox provider sync results" } }, "description": "List of inbox messages" } } } } }, "summary": "Get messages for a specific inbox.", "description": "Pass ``liveSync=true`` to synchronize the mailbox from its provider before\nquerying the canonical message database. A sync failure does not hide\ncached rows; inspect ``fresh`` and ``liveSync`` in the response." } }, "/api/v0/inboxes/messages/{messageId}": { "get": { "tags": [ "Inbox" ], "operationId": "inbox_getMessageDetails", "parameters": [ { "name": "messageId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string", "description": "Company ID" }, "description": "Company ID" } ], "responses": { "400": { "description": "Invalid message ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Message not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Message details", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "object", "properties": { "id": { "type": "string", "description": "Message ID" }, "inboxId": { "type": "string", "description": "Inbox ID" }, "sender": { "type": "string", "description": "Sender email" }, "senderName": { "type": "string", "description": "Sender name" }, "recipient": { "type": "string", "description": "Recipient email" }, "subject": { "type": "string", "description": "Message subject" }, "body": { "type": "string", "description": "Message body (only in details)" }, "messageType": { "type": "string", "description": "Message type: received, sent_compose, sent_reply" }, "replied": { "type": "boolean", "description": "Whether the message has been replied to" }, "repliedDate": { "type": "number", "description": "Date message was replied to" }, "created": { "type": "number", "description": "Creation timestamp" } }, "description": "Message with full details" } }, "description": "Inbox message details" } } } } }, "summary": "Get full message details including body." } }, "/api/v0/inboxes/statistics": { "get": { "tags": [ "Inbox" ], "operationId": "inbox_getInboxStatistics", "parameters": [ { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string", "description": "Company ID" }, "description": "Company ID" } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Inbox statistics", "content": { "application/json": { "schema": { "type": "object", "properties": { "totalInboxes": { "type": "integer", "description": "Total number of inboxes" }, "totalMessages": { "type": "integer", "description": "Total number of messages" }, "receivedMessages": { "type": "integer", "description": "Number of received messages" }, "sentMessages": { "type": "integer", "description": "Number of sent messages" }, "repliedMessages": { "type": "integer", "description": "Number of replied messages" } }, "description": "Inbox statistics" } } } } }, "summary": "Get overall statistics for inboxes." } }, "/api/v0/inbox/messages/{messageId}/generate-reply": { "post": { "tags": [ "Inbox" ], "operationId": "inbox_generateReply", "parameters": [ { "name": "messageId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Message not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "AI-generated reply", "content": { "application/json": { "schema": { "type": "object", "properties": { "subject": { "type": "string", "description": "Generated reply subject" }, "content": { "type": "string", "description": "Generated reply content" } }, "description": "AI-generated reply" } } } } }, "summary": "Generate an AI reply to a message using the shared email prompt system.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "originalSubject": { "type": "string", "description": "Subject of the original message" }, "originalContent": { "type": "string", "description": "Content of the original message" }, "replyClassification": { "type": "string", "description": "Classification type for the reply" }, "replyGuidance": { "type": "string", "description": "Additional guidance for generating the reply" }, "senderProfileId": { "type": "string", "description": "Sender profile ID for context" } }, "required": [ "companyId" ], "description": "Request body for generating an AI reply to a message" } } }, "description": "Reply generation parameters" } } }, "/api/v0/inbox/messages/{messageId}/edit-reply": { "post": { "tags": [ "Inbox" ], "operationId": "inbox_editReplyWithAI", "parameters": [ { "name": "messageId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Message not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "AI-edited reply", "content": { "application/json": { "schema": { "type": "object", "properties": { "subject": { "type": "string", "description": "Generated reply subject" }, "content": { "type": "string", "description": "Generated reply content" } }, "description": "AI-generated reply" } } } } }, "summary": "Edit an existing reply draft using AI based on user instructions.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "currentSubject": { "type": "string", "description": "Current draft subject" }, "currentContent": { "type": "string", "description": "Current draft content" }, "editInstructions": { "type": "string", "description": "Instructions for editing the reply" }, "originalSubject": { "type": "string", "description": "Subject of the original message" }, "originalContent": { "type": "string", "description": "Content of the original message" } }, "required": [ "companyId", "currentContent", "editInstructions" ], "description": "Request body for editing a reply using AI" } } }, "description": "Edit reply parameters" } } }, "/api/v0/inbox/messages/{messageId}/reply": { "post": { "tags": [ "Inbox" ], "operationId": "inbox_sendReply", "parameters": [ { "name": "messageId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Message or sender profile not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Reply sent successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message" }, "msg": { "type": "string", "description": "Success message (alternate key)" } }, "description": "Success message response" } } } } }, "summary": "Send a reply to a message.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "senderProfileId": { "type": "string", "description": "Sender profile ID" }, "subject": { "type": "string", "description": "Reply subject" }, "content": { "type": "string", "description": "Reply content" } }, "required": [ "companyId", "senderProfileId", "subject", "content" ], "description": "Request body for sending a reply" } } }, "description": "Reply data" } } }, "/api/v0/inbox/{inboxId}/compose": { "post": { "tags": [ "Inbox" ], "operationId": "inbox_sendComposedEmail", "parameters": [ { "name": "inboxId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Inbox or integration not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Email sent successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message" }, "msg": { "type": "string", "description": "Success message (alternate key)" } }, "description": "Success message response" } } } } }, "summary": "Send a new composed email via inbox.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "to": { "type": "string", "description": "Recipient email address" }, "subject": { "type": "string", "description": "Email subject" }, "content": { "type": "string", "description": "Email content" }, "profileId": { "type": "string", "description": "Sender profile ID" }, "integrationId": { "type": "string", "description": "Integration ID" }, "fromEmail": { "type": "string", "description": "Sender email address" }, "fromName": { "type": "string", "description": "Sender name" } }, "required": [ "companyId", "to", "subject", "content" ], "description": "Request body for composing and sending an email" } } }, "description": "Email composition data" } } }, "/api/v0/inbox/compose/generate": { "post": { "tags": [ "Inbox" ], "operationId": "inbox_generateComposeContent", "parameters": [], "responses": { "400": { "description": "Subject is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "AI-generated email content", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "description": "Generated email content" } }, "description": "AI-generated email content" } } } } }, "summary": "Generate AI content for a new email composition.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "to": { "type": "string", "description": "Recipient email address" }, "subject": { "type": "string", "description": "Email subject for content generation" } }, "required": [ "companyId", "subject" ], "description": "Request body for generating email content with AI" } } }, "description": "Compose generation parameters" } } }, "/api/v0/inboxes/{inboxId}/drafts": { "get": { "tags": [ "Inbox" ], "operationId": "inbox_getDrafts", "parameters": [ { "name": "inboxId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string", "description": "Company ID" }, "description": "Company ID" } ], "responses": { "400": { "description": "Invalid UUID in URL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Inbox not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "List of drafts", "content": { "application/json": { "schema": { "type": "object", "properties": { "drafts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Draft ID" }, "inboxId": { "type": "string", "description": "Inbox ID" }, "to": { "type": "string", "description": "Recipient email" }, "subject": { "type": "string", "description": "Draft subject" }, "content": { "type": "string", "description": "Draft content" }, "created": { "type": "number", "description": "Creation timestamp" } }, "description": "Draft object" }, "description": "List of drafts" } }, "description": "List of drafts" } } } } }, "summary": "Get all draft messages for an inbox." } }, "/api/v0/inboxes/{inboxId}/drafts/{draftId}/send": { "post": { "tags": [ "Inbox" ], "operationId": "inbox_sendDraft", "parameters": [ { "name": "inboxId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "draftId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid UUID in URL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Draft not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Draft sent successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message" }, "msg": { "type": "string", "description": "Success message (alternate key)" } }, "description": "Success message response" } } } } }, "summary": "Send a draft message.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" } }, "required": [ "companyId" ], "description": "Request body for draft actions" } } }, "description": "Draft send parameters" } } }, "/api/v0/inboxes/{inboxId}/drafts/{draftId}": { "delete": { "tags": [ "Inbox" ], "operationId": "inbox_deleteDraft", "parameters": [ { "name": "inboxId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "draftId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid UUID in URL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Draft not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Draft deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message" }, "msg": { "type": "string", "description": "Success message (alternate key)" } }, "description": "Success message response" } } } } }, "summary": "Delete a draft message.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" } }, "required": [ "companyId" ], "description": "Request body for draft actions" } } }, "description": "Draft delete parameters" } } }, "/api/v0/inboxes/{inboxId}/warmup": { "post": { "tags": [ "Inbox" ], "operationId": "inbox_enableWarmup", "parameters": [ { "name": "inboxId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Inbox not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Warmup enabled", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message" }, "msg": { "type": "string", "description": "Success message (alternate key)" } }, "description": "Success message response" } } } } }, "summary": "Enable warmup for an IMAP inbox.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" } }, "required": [ "companyId" ], "description": "Request body for enabling inbox warmup" } } }, "description": "Warmup enable parameters" } }, "delete": { "tags": [ "Inbox" ], "operationId": "inbox_disableWarmup", "parameters": [ { "name": "inboxId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string", "description": "Company ID" }, "description": "Company ID" } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Inbox not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Warmup disabled", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message" }, "msg": { "type": "string", "description": "Success message (alternate key)" } }, "description": "Success message response" } } } } }, "summary": "Disable warmup for an IMAP inbox." } }, "/api/v0/inboxes/warmup/list": { "get": { "tags": [ "Inbox" ], "operationId": "inbox_listWarmupInboxes", "parameters": [ { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string", "description": "Company ID" }, "description": "Company ID" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Page number" }, "description": "Page number" }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "description": "Items per page" }, "description": "Items per page" } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "List of warmup-capable inboxes", "content": { "application/json": { "schema": { "type": "object", "properties": { "inboxes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Inbox ID" }, "email": { "type": "string", "description": "Email address" }, "name": { "type": "string", "description": "Inbox name" }, "warmupEnabled": { "type": "boolean", "description": "Whether warmup is enabled" }, "filterTag": { "type": "string", "description": "Custom warmup filter tag" } }, "description": "Warmup inbox information" }, "description": "List of inboxes" }, "total": { "type": "integer", "description": "Total count" } }, "description": "List of warmup-capable inboxes" } } } } }, "summary": "List all IMAP inboxes that can be used for warmup." } }, "/api/v0/inboxes/warmup/analytics": { "post": { "tags": [ "Inbox" ], "operationId": "inbox_getWarmupAnalytics", "parameters": [], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Warmup analytics data", "content": { "application/json": { "schema": { "type": "object", "properties": { "analytics": { "type": "object", "description": "Analytics data keyed by email" } }, "description": "Warmup analytics data" } } } } }, "summary": "Get warmup analytics for enabled inboxes.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "emails": { "type": "array", "items": { "type": "string" }, "description": "List of email addresses to get analytics for" } }, "required": [ "companyId" ], "description": "Request body for getting warmup analytics" } } }, "description": "Warmup analytics request" } } }, "/api/v0/inboxes/warmup/filter-tag": { "post": { "tags": [ "Inbox" ], "operationId": "inbox_setWarmupFilterTag", "parameters": [], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Filter tag set successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message" }, "msg": { "type": "string", "description": "Success message (alternate key)" } }, "description": "Success message response" } } } } }, "summary": "Set a custom warmup filter tag for selected inboxes in a company.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "filterTag": { "type": "string", "description": "Custom filter tag for warmup emails" }, "inboxIds": { "type": "array", "items": { "type": "string" }, "description": "List of inbox IDs to update" } }, "required": [ "companyId" ], "description": "Request body for setting warmup filter tag" } } }, "description": "Warmup filter tag settings" } } }, "/api/v0/inboxes/bulk-import": { "post": { "tags": [ "Inbox" ], "operationId": "inbox_bulkImportInboxes", "parameters": [], "responses": { "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Bulk import results", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "description": "Email address" }, "success": { "type": "boolean", "description": "Whether import was successful" }, "inboxId": { "type": "string", "description": "Created inbox ID (if successful)" }, "senderProfileId": { "type": "string", "description": "Created sender profile ID (if successful)" }, "error": { "type": "string", "description": "Error message (if failed)" } }, "description": "Result for a single inbox import" }, "description": "Results for each inbox" }, "summary": { "type": "object", "properties": { "total": { "type": "integer", "description": "Total number of inboxes processed" }, "success": { "type": "integer", "description": "Number of successful imports" }, "failed": { "type": "integer", "description": "Number of failed imports" } }, "description": "Import summary" } }, "description": "Bulk import response" } } } } }, "summary": "Bulk import IMAP inboxes from CSV data (Instantly.ai compliant format).", "description": "Creates integrations, inbox records, and sender profiles for each inbox.\nOptionally enables warmup for imported inboxes.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "inboxes": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "description": "Email address" }, "firstName": { "type": "string", "description": "First name" }, "lastName": { "type": "string", "description": "Last name" }, "imapUsername": { "type": "string", "description": "IMAP username (defaults to email)" }, "imapPassword": { "type": "string", "description": "IMAP password" }, "imapHost": { "type": "string", "description": "IMAP server host" }, "imapPort": { "type": "integer", "description": "IMAP server port (default: 993)" }, "smtpUsername": { "type": "string", "description": "SMTP username (defaults to IMAP username)" }, "smtpPassword": { "type": "string", "description": "SMTP password (defaults to IMAP password)" }, "smtpHost": { "type": "string", "description": "SMTP server host" }, "smtpPort": { "type": "integer", "description": "SMTP server port (default: 587)" }, "dailyLimit": { "type": "integer", "description": "Daily sending limit for sender profile" }, "warmupEnabled": { "type": "boolean", "description": "Whether to enable warmup" }, "warmupLimit": { "type": "integer", "description": "Warmup daily limit" }, "warmupIncrement": { "type": "integer", "description": "Warmup increment" } }, "required": [ "email", "imapPassword", "imapHost", "smtpHost" ], "description": "Schema for a single inbox in bulk import" }, "description": "List of inboxes to import" } }, "required": [ "companyId", "inboxes" ], "description": "Request body for bulk importing IMAP inboxes" } } }, "description": "Bulk import inbox data" } } }, "/api/v0/domain-connections": { "get": { "tags": [ "Domains" ], "operationId": "inbox_apiListDomainConnections", "parameters": [ { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company that owns the connections" }, "description": "Company that owns the connections" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "One-indexed page number (default: 1)", "default": 1 }, "description": "One-indexed page number (default: 1)" }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "description": "Items per page (default: 20)", "default": 20 }, "description": "Items per page (default: 20)" } ], "responses": { "400": { "description": "companyId is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No company access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Paginated branded-domain connections and the available connection-slot limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object" }, "description": "Branded-domain connections for this page" }, "total": { "type": "integer", "description": "Total number of branded-domain connections" }, "page": { "type": "integer", "description": "Current one-indexed page" }, "pages": { "type": "integer", "description": "Total pages" }, "has_next": { "type": "boolean", "description": "Whether another page is available" }, "domainLimit": { "type": "integer", "description": "Number of branded-domain connection slots available to the company" } } } } } } }, "summary": "List branded-domain connections and the connection-slot limit.", "description": "A connection attaches a domain or subdomain the customer already owns to\nSSL termination and routing for tracking links, landing pages, and published\nwebsites. It does not purchase or register a domain." }, "post": { "tags": [ "Domains" ], "operationId": "inbox_apiCreateDomainConnection", "parameters": [], "responses": { "400": { "description": "Invalid hostname, missing companyId, or connection limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No company access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "201": { "description": "Branded-domain connection and DNS A-record instructions", "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "object", "description": "Created branded-domain connection" }, "dnsRecord": { "type": "object", "description": "A record to create at the customer\u2019s existing DNS host" }, "approximatedRegistered": { "type": "boolean", "description": "Whether SSL-routing provisioning was accepted" }, "approximatedError": { "type": "string", "description": "Provisioning warning, if any. The connection remains available for DNS setup." } } } } } } }, "summary": "Connect a customer-owned domain or subdomain for SSL termination.", "description": "This consumes one branded-domain connection slot. Additional slots are a\n$5/month add-on. It does not purchase, register, or move DNS for the domain;\ncreate the returned A record at the domain's existing DNS host.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company that owns the connection slot" }, "subdomain": { "type": "string", "description": "Customer-owned domain or subdomain to connect, e.g. track.example.com. Do not include https://." } }, "required": [ "companyId", "subdomain" ], "description": "Create a branded-domain connection for a domain or subdomain you already own. This uses one domain-connection slot; additional slots are available as a $5/month add-on. It does not purchase or register a domain." } } }, "description": "Connect a customer-owned domain or subdomain for SSL termination and routing" } } }, "/api/v0/domains": { "get": { "tags": [ "Domains" ], "operationId": "inbox_apiListPurchasedDomains", "parameters": [ { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company whose purchased domains to list" }, "description": "Company whose purchased domains to list" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Page number, starting at 1", "default": 1 }, "description": "Page number, starting at 1" }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "description": "Domains per page, up to 100", "default": 20 }, "description": "Domains per page, up to 100" } ], "responses": { "400": { "description": "companyId is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No company access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Domains purchased by the company", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object" }, "description": "Purchased domains: id, domain, companyId, created_date" }, "total": { "type": "integer" }, "page": { "type": "integer" }, "pages": { "type": "integer" }, "has_next": { "type": "boolean" } } } } } } }, "summary": "List domains the company purchased on the platform.", "description": "These are registrations, not branded-domain connections. Use their IDs with\nthe DNS endpoints and with hosted email sending domains." } }, "/api/v0/domains/check-availability": { "post": { "tags": [ "Domains" ], "operationId": "inbox_apiCheckDomainAvailability", "parameters": [], "responses": { "400": { "description": "Invalid domain or missing companyId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No company access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Domain availability check failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Check a root-domain registration's availability and price.", "description": "This read-only endpoint is only for a domain registration purchase. It does\nnot connect a domain the customer already owns; use domain-connections for\nSSL termination and routing instead.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company that will own the registered domain" }, "domain": { "type": "string", "description": "Root domain to check, e.g. example.com. Premium names, https://, and subdomains are not supported." } }, "required": [ "companyId", "domain" ], "description": "Read-only availability check for a root-domain registration; it does not connect an existing domain" } } }, "description": "Root domain to check before requesting purchase approval" } } }, "/api/v0/domains/pricing": { "get": { "tags": [ "Domains" ], "operationId": "inbox_apiGetDomainPricing", "parameters": [ { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company that will own the registered domain" }, "description": "Company that will own the registered domain" }, { "name": "domain", "in": "query", "required": true, "schema": { "type": "string", "description": "Root domain to price, e.g. example.com or example.ai" }, "description": "Root domain to price, e.g. example.com or example.ai" } ], "responses": { "400": { "description": "companyId missing, invalid domain, or domain unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No company access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Get the price to register one root domain.", "description": "customerPrice is the first payment, covering the registration term;\nrenewalPrice is then billed yearly until cancelled. Both apply the same\nrequest-scoped whitelabel add-on multiplier as mailbox orders. Neither is\nthe $5/month branded-domain connection add-on price. Use it before asking\nthe user to approve a purchase." } }, "/api/v0/domains/purchase": { "post": { "tags": [ "Domains" ], "operationId": "inbox_apiPurchaseDomain", "parameters": [], "responses": { "400": { "description": "Invalid domain, registration details, or missing purchase confirmation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No company access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Domain purchase could not be completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "201": { "description": "The registered domain", "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "object", "description": "The newly registered domain, unconnected until the customer connects it; it uses no connection slot until then" }, "pricing": { "type": "object", "description": "Registration price in USD: customerPrice (first payment) and renewalPrice (billed yearly), with basePrice, renewalBasePrice, and priceMultiplier. This is not the monthly connection add-on price." }, "providerStatus": { "type": "string", "description": "Registration status from the managed domain service" } } } } } } }, "summary": "Purchase a root-domain registration.", "description": "This is a financial action and requires a successful Stripe PaymentIntent\ncreated for the same user, company, and domain. The purchase starts a yearly\nrenewal subscription on the same card. The domain is not connected for SSL\nrouting; create a domain-connection for a hostname under it when needed.\nNever blindly retry a provider timeout; check the domain list first.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company that will own the registered domain and connection" }, "domain": { "type": "string", "description": "Available root domain to purchase, e.g. example.com. Premium names, https://, and subdomains are not supported." }, "contactDetails": { "type": "object", "description": "Registrant data: firstName, lastName, email, phone, address1, city, province, postalCode, and country; organization is optional. The registrant email is reused for DMARC reports. Domain forwarding is not configured by this purchase path." }, "paymentIntentId": { "type": "string", "description": "Successful Stripe PaymentIntent created for this exact company and domain." }, "connectedAccount": { "type": "string", "description": "Stripe connected account returned when the payment was created, if applicable." } }, "required": [ "companyId", "domain", "contactDetails", "paymentIntentId" ], "description": "Root-domain registration for email infrastructure, renewed yearly. This is separate from the $5/month branded-domain connection add-on for SSL termination and routing." } } }, "description": "Confirmed root-domain registration purchase with yearly renewal" } } }, "/api/v0/domains/{domainId}/dns": { "get": { "tags": [ "Domains" ], "operationId": "inbox_apiGetDomainDns", "parameters": [ { "name": "domainId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company that owns the domain" }, "description": "Company that owns the domain" } ], "responses": { "400": { "description": "companyId missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Domain not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "DNS provider unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Current DNS records", "content": { "application/json": { "schema": { "type": "object", "properties": { "records": { "type": "array", "items": { "type": "object" } } } } } } } }, "summary": "List DNS records for a domain purchased on the platform.", "description": "Customer-owned domains connected for SSL termination keep DNS at their\nexisting DNS host. Read records before proposing any change." }, "put": { "tags": [ "Domains" ], "operationId": "inbox_apiUpdateDomainDns", "parameters": [ { "name": "domainId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid records or missing confirmation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Domain not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "DNS update failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Records after the update", "content": { "application/json": { "schema": { "type": "object", "properties": { "records": { "type": "array", "items": { "type": "object" } } } } } } } }, "summary": "Replace the DNS records of a domain purchased on the platform.", "description": "Records not in the request are deleted. This is an irreversible\ninfrastructure change: read the current records, keep those you are not\nintentionally changing, obtain approval, and set dnsChangeConfirmed to true.\nNever blindly retry a timeout.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company that owns the domain" }, "records": { "type": "array", "items": { "type": "object" }, "description": "DNS records to update. Each record needs name, type, and value; include editable: true for editable records." }, "dnsChangeConfirmed": { "type": "boolean", "description": "Must be true. DNS changes can interrupt website and email delivery." } }, "required": [ "companyId", "records", "dnsChangeConfirmed" ], "description": "Confirmed DNS record update for a domain registered through this platform. Customer-owned external domains keep DNS at their existing DNS host." } } }, "description": "Confirmed DNS update" } } }, "/api/v0/content": { "get": { "tags": [ "Content" ], "operationId": "content_listContent", "parameters": [ { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID" }, "description": "Company ID" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Page number" }, "description": "Page number" }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "description": "Items per page" }, "description": "Items per page" }, { "name": "campaignId", "in": "query", "required": false, "schema": { "type": "string", "description": "Filter by campaign ID" }, "description": "Filter by campaign ID" }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "description": "Filter by content type: blog_post, linkedin_post, facebook_post, instagram_post, twitter_post, ad_copy, email_template, tiktok_idea, newsletter, whitepaper" }, "description": "Filter by content type: blog_post, linkedin_post, facebook_post, instagram_post, twitter_post, ad_copy, email_template, tiktok_idea, newsletter, whitepaper" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "description": "Filter by status (ideated, queued, generating, draft, scheduled, published, archived)" }, "description": "Filter by status (ideated, queued, generating, draft, scheduled, published, archived)" }, { "name": "approvalStatus", "in": "query", "required": false, "schema": { "type": "string", "description": "Filter by approval status" }, "description": "Filter by approval status" }, { "name": "funnelStage", "in": "query", "required": false, "schema": { "type": "string", "description": "Filter by funnel stage: N/A, tofu, mofu, bofu" }, "description": "Filter by funnel stage: N/A, tofu, mofu, bofu" }, { "name": "startDate", "in": "query", "required": false, "schema": { "type": "string", "description": "Filter by start date" }, "description": "Filter by start date" }, { "name": "endDate", "in": "query", "required": false, "schema": { "type": "string", "description": "Filter by end date" }, "description": "Filter by end date" }, { "name": "startPublishDate", "in": "query", "required": false, "schema": { "type": "string", "description": "Filter by start publish date" }, "description": "Filter by start publish date" }, { "name": "endPublishDate", "in": "query", "required": false, "schema": { "type": "string", "description": "Filter by end publish date" }, "description": "Filter by end publish date" }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "description": "Sort order (default: publish_date_desc)" }, "description": "Sort order (default: publish_date_desc)" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "description": "Search query" }, "description": "Search query" } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "List of content items", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "campaignIsAutopilot": { "type": "boolean", "description": "Uses the shared multicolor Autopilot campaign accent." }, "id": { "type": "string", "description": "Content ID" }, "title": { "type": "string", "description": "Content title" }, "type": { "type": "string", "description": "Content type: blog_post, linkedin_post, facebook_post, instagram_post, twitter_post, ad_copy, email_template, tiktok_idea, newsletter, whitepaper" }, "status": { "type": "string", "description": "Content status: ideated, queued, generating, draft, scheduled, published, archived" }, "funnelStage": { "type": "string", "description": "Funnel stage: N/A, tofu, mofu, bofu" }, "topicSummary": { "type": "string", "description": "Topic summary" }, "hookOptions": { "type": "array", "items": { "type": "string" }, "description": "Hook options" }, "selectedHook": { "type": "string", "description": "Selected hook" }, "variants": { "type": "object", "description": "Content variants" }, "publishDate": { "type": "string", "description": "Publish date" }, "created": { "type": "number", "description": "Creation timestamp" } }, "description": "Content object" }, "description": "List of content items" }, "total": { "type": "integer", "description": "Total count" }, "page": { "type": "integer", "description": "Current page" }, "pageSize": { "type": "integer", "description": "Items per page" } }, "description": "List of content items" } } } } }, "summary": "List all content items with optional filtering." }, "post": { "tags": [ "Content" ], "operationId": "content_createContent", "parameters": [], "responses": { "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Created content record", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Operation success status" }, "id": { "type": "string", "description": "ID of the newly created content record" }, "content": { "type": "object", "description": "The full content object" } }, "description": "Created content response" } } } } }, "summary": "Manually create a new content engine record.", "description": "Use this to insert a content piece directly (skipping AI ideation/generation),\ne.g. to import an existing post or log content authored elsewhere. The body\nis set via either `variants.default` or the `body` convenience field. For\n`blog_post`, both fields must contain Markdown source, never rendered HTML;\npublishing converts the Markdown to HTML for the destination.\n\nExample: `{\"type\":\"blog_post\",\"title\":\"A practical guide\",\"body\":\"# Start here\\n\\nWrite the article in Markdown.\"}`", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "title": { "type": "string", "description": "Content title" }, "type": { "type": "string", "description": "Content type. One of: blog_post, facebook_post, linkedin_post, instagram_post, x_post, youtube_video, tiktok_video, email_newsletter, podcast_episode, website_copy, marketing_email, ad_copy, press_release" }, "status": { "type": "string", "description": "Content status (default: draft). One of: ideated, queued, generating, draft, scheduled, published, archived" }, "category": { "type": "string", "description": "Content category" }, "topicSummary": { "type": "string", "description": "Topic summary" }, "hookOptions": { "type": "array", "items": { "type": "string" }, "description": "List of hook options" }, "selectedHook": { "type": "string", "description": "Selected hook" }, "funnelStage": { "type": "string", "description": "Funnel stage: N/A, tofu, mofu, bofu" }, "metaDescription": { "type": "string", "description": "Meta description (used for SEO and social previews)" }, "focusKeyword": { "type": "string", "description": "Search phrase the post targets (blog posts only; blank for idea-only posts)" }, "seoTitle": { "type": "string", "description": "SERP , distinct from the article title (<=60 chars; blog posts only)" }, "slug": { "type": "string", "description": "Short URL slug for the published post (blog posts only)" }, "variants": { "type": "object", "description": "Content variants. For type=blog_post, set default to the article body as Markdown source (for example, \"# Heading\\n\\nParagraph **text**\"). Do not send rendered HTML such as <h1> or <p> tags. The publisher converts Markdown to destination HTML." }, "body": { "type": "string", "description": "Convenience field for the main body. For type=blog_post, send Markdown source only; do not send HTML. Stored at variants.default and ignored if variants is provided." }, "publishDate": { "type": "string", "description": "Planned publish date (ISO 8601 datetime)" }, "publishedDate": { "type": "string", "description": "Actual publish date when status is published (ISO 8601)" }, "publishedUrl": { "type": "string", "description": "Public URL of the published content" }, "externalId": { "type": "string", "description": "External platform identifier" }, "platformType": { "type": "string", "description": "Platform the content was published to (e.g., wordpress, linkedin)" }, "campaignId": { "type": "string", "description": "Campaign ID to associate this content with" } }, "required": [ "companyId", "title", "type" ], "description": "Request body for manually creating a content engine record" } } }, "description": "Content fields for the new record" } } }, "/api/v0/content/seo-score": { "post": { "tags": [ "Content" ], "operationId": "content_contentSeoScore", "parameters": [], "responses": { "400": { "description": "Missing focus keyword", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Formula-based SEO report", "content": { "application/json": { "schema": { "type": "object", "properties": { "focusKeyword": { "type": "string", "description": "Keyword the report was computed for" }, "score": { "type": "integer", "description": "Overall score 0-100" }, "checks": { "type": "array", "items": { "type": "object" }, "description": "Per-check results: {id, status (good/ok/bad), message}" } }, "description": "Formula-based SEO report" } } } } }, "summary": "Score content against its focus keyword with the formula-based SEO checks.", "description": "Pure text analysis (the same checks WordPress SEO plugins run) - no model\ncall, so it is safe to invoke on every edit. Returns the overall 0-100\nscore and one entry per check with a status and an actionable message.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "focusKeyword": { "type": "string", "description": "Search phrase the post targets" }, "title": { "type": "string", "description": "Article title" }, "content": { "type": "string", "description": "Article body (markdown)" }, "metaDescription": { "type": "string", "description": "Meta description" }, "seoTitle": { "type": "string", "description": "SERP <title>" }, "slug": { "type": "string", "description": "URL slug" } }, "required": [ "focusKeyword" ], "description": "Fields to score against a focus keyword" } } }, "description": "Fields to score" } } }, "/api/v0/content/{contentId}": { "delete": { "tags": [ "Content" ], "operationId": "content_deleteContent", "parameters": [ { "name": "contentId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID" }, "description": "Company ID" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Page number (default: 1)" }, "description": "Page number (default: 1)" }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "description": "Items per page (default: 50)" }, "description": "Items per page (default: 50)" } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Content not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "description": "Success message" } }, "description": "Success response" } } } } }, "summary": "Delete a content item." }, "post": { "tags": [ "Content" ], "operationId": "content_saveContent", "parameters": [ { "name": "contentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "description": "Success message" } }, "description": "Success response" } } } } }, "summary": "Save/update a content item.", "description": "For `blog_post`, keep `content.variants.default` in Markdown source format.\nDo not store rendered HTML; publishing renders the Markdown for the destination.\n\nExample: `{\"content\":{\"id\":\"<contentId>\",\"type\":\"blog_post\",\"variants\":{\"default\":\"# Start here\\n\\nWrite the article in Markdown.\"}}}`", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "content": { "type": "object", "description": "Content data object. For type=blog_post, variants.default MUST contain the article body as Markdown source (for example, \"# Heading\\n\\nParagraph **text**\"). Do not send HTML such as <h1> or <p> tags. Publishing converts Markdown to destination HTML; keep the stored body in Markdown. Other fields: id (required), title, type, status, category, topicSummary, hookOptions, selectedHook, funnelStage, metaDescription, focusKeyword, seoTitle, slug, publishDate, campaignId." } }, "required": [ "companyId", "content" ], "description": "Request body for saving content" } } }, "description": "Content data to save" } } }, "/api/v0/content/{contentId}/select-hook": { "post": { "tags": [ "Content" ], "operationId": "content_selectHookAndGenerate", "parameters": [ { "name": "contentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Content with generated body", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Operation success status" }, "content": { "type": "object", "properties": { "campaignIsAutopilot": { "type": "boolean", "description": "Uses the shared multicolor Autopilot campaign accent." }, "id": { "type": "string", "description": "Content ID" }, "title": { "type": "string", "description": "Content title" }, "type": { "type": "string", "description": "Content type: blog_post, linkedin_post, facebook_post, instagram_post, twitter_post, ad_copy, email_template, tiktok_idea, newsletter, whitepaper" }, "status": { "type": "string", "description": "Content status: ideated, queued, generating, draft, scheduled, published, archived" }, "funnelStage": { "type": "string", "description": "Funnel stage: N/A, tofu, mofu, bofu" }, "topicSummary": { "type": "string", "description": "Topic summary" }, "hookOptions": { "type": "array", "items": { "type": "string" }, "description": "Hook options" }, "selectedHook": { "type": "string", "description": "Selected hook" }, "variants": { "type": "object", "description": "Content variants" }, "publishDate": { "type": "string", "description": "Publish date" }, "created": { "type": "number", "description": "Creation timestamp" } }, "description": "The content object" } }, "description": "Content operation success response" } } } } }, "summary": "Selects a hook from ideated content and generates full content.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "selectedHook": { "type": "string", "description": "The selected hook text" } }, "required": [ "companyId", "selectedHook" ], "description": "Request body for selecting a hook" } } }, "description": "Selected hook data" } } }, "/api/v0/content/{contentId}/assign": { "post": { "tags": [ "Content" ], "operationId": "content_assignContent", "parameters": [ { "name": "contentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Content with assignment", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Operation success status" }, "content": { "type": "object", "properties": { "campaignIsAutopilot": { "type": "boolean", "description": "Uses the shared multicolor Autopilot campaign accent." }, "id": { "type": "string", "description": "Content ID" }, "title": { "type": "string", "description": "Content title" }, "type": { "type": "string", "description": "Content type: blog_post, linkedin_post, facebook_post, instagram_post, twitter_post, ad_copy, email_template, tiktok_idea, newsletter, whitepaper" }, "status": { "type": "string", "description": "Content status: ideated, queued, generating, draft, scheduled, published, archived" }, "funnelStage": { "type": "string", "description": "Funnel stage: N/A, tofu, mofu, bofu" }, "topicSummary": { "type": "string", "description": "Topic summary" }, "hookOptions": { "type": "array", "items": { "type": "string" }, "description": "Hook options" }, "selectedHook": { "type": "string", "description": "Selected hook" }, "variants": { "type": "object", "description": "Content variants" }, "publishDate": { "type": "string", "description": "Publish date" }, "created": { "type": "number", "description": "Creation timestamp" } }, "description": "The content object" } }, "description": "Content operation success response" } } } } }, "summary": "Assign content to a collaborator for review/edit/approval.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "assigneeEmail": { "type": "string", "description": "Email of the assignee" }, "notes": { "type": "string", "description": "Notes for the assignee" } }, "required": [ "companyId", "assigneeEmail" ], "description": "Request body for assigning content" } } }, "description": "Assignment data" } } }, "/api/v0/content/{contentId}/assignment-status": { "put": { "tags": [ "Content" ], "operationId": "content_updateAssignmentStatus", "parameters": [ { "name": "contentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Content with updated status", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Operation success status" }, "content": { "type": "object", "properties": { "campaignIsAutopilot": { "type": "boolean", "description": "Uses the shared multicolor Autopilot campaign accent." }, "id": { "type": "string", "description": "Content ID" }, "title": { "type": "string", "description": "Content title" }, "type": { "type": "string", "description": "Content type: blog_post, linkedin_post, facebook_post, instagram_post, twitter_post, ad_copy, email_template, tiktok_idea, newsletter, whitepaper" }, "status": { "type": "string", "description": "Content status: ideated, queued, generating, draft, scheduled, published, archived" }, "funnelStage": { "type": "string", "description": "Funnel stage: N/A, tofu, mofu, bofu" }, "topicSummary": { "type": "string", "description": "Topic summary" }, "hookOptions": { "type": "array", "items": { "type": "string" }, "description": "Hook options" }, "selectedHook": { "type": "string", "description": "Selected hook" }, "variants": { "type": "object", "description": "Content variants" }, "publishDate": { "type": "string", "description": "Publish date" }, "created": { "type": "number", "description": "Creation timestamp" } }, "description": "The content object" } }, "description": "Content operation success response" } } } } }, "summary": "Update the assignment status of a content item (for reviewers).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "status": { "type": "string", "description": "Assignment status (pending, in_review, approved, rejected)" }, "notes": { "type": "string", "description": "Status update notes" } }, "required": [ "companyId", "status" ], "description": "Request body for updating assignment status" } } }, "description": "Assignment status update" } } }, "/api/v0/content/assigned": { "get": { "tags": [ "Content" ], "operationId": "content_getAssignedContent", "parameters": [ { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID" }, "description": "Company ID" }, { "name": "assigneeEmail", "in": "query", "required": false, "schema": { "type": "string", "description": "Filter by assignee email" }, "description": "Filter by assignee email" }, { "name": "includeAll", "in": "query", "required": false, "schema": { "type": "string", "description": "Include all assigned content (true/false)" }, "description": "Include all assigned content (true/false)" } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Assigned content items", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "campaignIsAutopilot": { "type": "boolean", "description": "Uses the shared multicolor Autopilot campaign accent." }, "id": { "type": "string", "description": "Content ID" }, "title": { "type": "string", "description": "Content title" }, "type": { "type": "string", "description": "Content type: blog_post, linkedin_post, facebook_post, instagram_post, twitter_post, ad_copy, email_template, tiktok_idea, newsletter, whitepaper" }, "status": { "type": "string", "description": "Content status: ideated, queued, generating, draft, scheduled, published, archived" }, "funnelStage": { "type": "string", "description": "Funnel stage: N/A, tofu, mofu, bofu" }, "topicSummary": { "type": "string", "description": "Topic summary" }, "hookOptions": { "type": "array", "items": { "type": "string" }, "description": "Hook options" }, "selectedHook": { "type": "string", "description": "Selected hook" }, "variants": { "type": "object", "description": "Content variants" }, "publishDate": { "type": "string", "description": "Publish date" }, "created": { "type": "number", "description": "Creation timestamp" } }, "description": "Content object" }, "description": "List of content items" }, "total": { "type": "integer", "description": "Total count" }, "page": { "type": "integer", "description": "Current page" }, "pageSize": { "type": "integer", "description": "Items per page" } }, "description": "List of content items" } } } } }, "summary": "Get content assigned to the current user or all assigned content." } }, "/api/v0/content/{contentId}/status": { "put": { "tags": [ "Content" ], "operationId": "content_updateContentStatus", "parameters": [ { "name": "contentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Content with updated status", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Operation success status" }, "content": { "type": "object", "properties": { "campaignIsAutopilot": { "type": "boolean", "description": "Uses the shared multicolor Autopilot campaign accent." }, "id": { "type": "string", "description": "Content ID" }, "title": { "type": "string", "description": "Content title" }, "type": { "type": "string", "description": "Content type: blog_post, linkedin_post, facebook_post, instagram_post, twitter_post, ad_copy, email_template, tiktok_idea, newsletter, whitepaper" }, "status": { "type": "string", "description": "Content status: ideated, queued, generating, draft, scheduled, published, archived" }, "funnelStage": { "type": "string", "description": "Funnel stage: N/A, tofu, mofu, bofu" }, "topicSummary": { "type": "string", "description": "Topic summary" }, "hookOptions": { "type": "array", "items": { "type": "string" }, "description": "Hook options" }, "selectedHook": { "type": "string", "description": "Selected hook" }, "variants": { "type": "object", "description": "Content variants" }, "publishDate": { "type": "string", "description": "Publish date" }, "created": { "type": "number", "description": "Creation timestamp" } }, "description": "The content object" } }, "description": "Content operation success response" } } } } }, "summary": "Update the status of a content item.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "status": { "type": "string", "description": "Content status (ideated, queued, generating, draft, scheduled, published, archived)" } }, "required": [ "companyId", "status" ], "description": "Request body for updating content status" } } }, "description": "Status update data" } } }, "/api/v0/content/{contentId}/publish": { "post": { "tags": [ "Content" ], "operationId": "content_publishContent", "parameters": [ { "name": "contentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Published content", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Operation success status" }, "content": { "type": "object", "properties": { "campaignIsAutopilot": { "type": "boolean", "description": "Uses the shared multicolor Autopilot campaign accent." }, "id": { "type": "string", "description": "Content ID" }, "title": { "type": "string", "description": "Content title" }, "type": { "type": "string", "description": "Content type: blog_post, linkedin_post, facebook_post, instagram_post, twitter_post, ad_copy, email_template, tiktok_idea, newsletter, whitepaper" }, "status": { "type": "string", "description": "Content status: ideated, queued, generating, draft, scheduled, published, archived" }, "funnelStage": { "type": "string", "description": "Funnel stage: N/A, tofu, mofu, bofu" }, "topicSummary": { "type": "string", "description": "Topic summary" }, "hookOptions": { "type": "array", "items": { "type": "string" }, "description": "Hook options" }, "selectedHook": { "type": "string", "description": "Selected hook" }, "variants": { "type": "object", "description": "Content variants" }, "publishDate": { "type": "string", "description": "Publish date" }, "created": { "type": "number", "description": "Creation timestamp" } }, "description": "The content object" } }, "description": "Content operation success response" } } } } }, "summary": "Publish content to a connected account.", "description": "The request configures the destination and schedule, not the article body.\nBlog post bodies must remain Markdown in `variants.default`; the publisher\nconverts them to destination HTML automatically.\n\nCreate or save the Markdown body first. This endpoint accepts publishing\nconfiguration only, such as `publishAccount`, `collectionId`, and\n`scheduleDateTime`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "publishAccount": { "type": "object", "description": "Publishing account configuration: {integrationId: string, platform?: string (linkedin, twitter, etc.)}" }, "imageId": { "type": "string", "description": "Image ID to use for publishing" }, "publishAsDraft": { "type": "boolean", "description": "Whether to publish as draft (default: false)" }, "scheduleDateTime": { "type": "string", "description": "ISO 8601 datetime for scheduled publishing" }, "collectionId": { "type": "string", "description": "Collection to publish into, instead of an integration. Any website showing the collection picks the post up on its next build." } }, "required": [ "companyId" ], "description": "Request body for publishing content. This endpoint selects a destination and schedule; it does not accept the article body. For blog_post records, keep variants.default as Markdown source. The publisher renders it to destination HTML automatically." } } }, "description": "Publish configuration" } } }, "/api/v0/content/{contentId}/schedule": { "put": { "tags": [ "Content" ], "operationId": "content_updateScheduledPublishDate", "parameters": [ { "name": "contentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Content with updated schedule", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Operation success status" }, "content": { "type": "object", "properties": { "campaignIsAutopilot": { "type": "boolean", "description": "Uses the shared multicolor Autopilot campaign accent." }, "id": { "type": "string", "description": "Content ID" }, "title": { "type": "string", "description": "Content title" }, "type": { "type": "string", "description": "Content type: blog_post, linkedin_post, facebook_post, instagram_post, twitter_post, ad_copy, email_template, tiktok_idea, newsletter, whitepaper" }, "status": { "type": "string", "description": "Content status: ideated, queued, generating, draft, scheduled, published, archived" }, "funnelStage": { "type": "string", "description": "Funnel stage: N/A, tofu, mofu, bofu" }, "topicSummary": { "type": "string", "description": "Topic summary" }, "hookOptions": { "type": "array", "items": { "type": "string" }, "description": "Hook options" }, "selectedHook": { "type": "string", "description": "Selected hook" }, "variants": { "type": "object", "description": "Content variants" }, "publishDate": { "type": "string", "description": "Publish date" }, "created": { "type": "number", "description": "Creation timestamp" } }, "description": "The content object" } }, "description": "Content operation success response" } } } } }, "summary": "Update the scheduled publish date and metadata for already-scheduled content.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "scheduleDateTime": { "type": "string", "description": "ISO 8601 datetime for scheduled publishing" }, "imageId": { "type": "string", "description": "Image ID to use when publishing" }, "publishAccount": { "type": "object", "description": "Account to publish to: {integrationId: string, platform?: string}" }, "publishAsDraft": { "type": "boolean", "description": "Whether to publish as draft" } }, "required": [ "companyId", "scheduleDateTime" ], "description": "Request body for updating scheduled publish date" } } }, "description": "Schedule update data" } } }, "/api/v0/content/bulk-schedule": { "post": { "tags": [ "Content" ], "operationId": "content_bulkScheduleContent", "parameters": [], "responses": { "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Scheduled content items", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Operation success" }, "msg": { "type": "string", "description": "Success message" }, "scheduled": { "type": "integer", "description": "Number of items scheduled" }, "contents": { "type": "array", "items": { "type": "object", "properties": { "campaignIsAutopilot": { "type": "boolean", "description": "Uses the shared multicolor Autopilot campaign accent." }, "id": { "type": "string", "description": "Content ID" }, "title": { "type": "string", "description": "Content title" }, "type": { "type": "string", "description": "Content type: blog_post, linkedin_post, facebook_post, instagram_post, twitter_post, ad_copy, email_template, tiktok_idea, newsletter, whitepaper" }, "status": { "type": "string", "description": "Content status: ideated, queued, generating, draft, scheduled, published, archived" }, "funnelStage": { "type": "string", "description": "Funnel stage: N/A, tofu, mofu, bofu" }, "topicSummary": { "type": "string", "description": "Topic summary" }, "hookOptions": { "type": "array", "items": { "type": "string" }, "description": "Hook options" }, "selectedHook": { "type": "string", "description": "Selected hook" }, "variants": { "type": "object", "description": "Content variants" }, "publishDate": { "type": "string", "description": "Publish date" }, "created": { "type": "number", "description": "Creation timestamp" } }, "description": "Content object" }, "description": "Scheduled content items" } }, "description": "Bulk schedule result" } } } } }, "summary": "Bulk schedule multiple content items with the same publish account.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "contentIds": { "type": "array", "items": { "type": "string" }, "description": "List of content IDs to schedule" }, "publishAccount": { "type": "object", "description": "Publishing account configuration: {integrationId: string, platform?: string (linkedin, twitter, etc.)}" } }, "required": [ "companyId", "contentIds", "publishAccount" ], "description": "Request body for bulk scheduling content" } } }, "description": "Bulk schedule data" } } }, "/api/v0/content/{contentId}/images": { "get": { "tags": [ "Content" ], "operationId": "content_getContentImages", "parameters": [ { "name": "contentId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID" }, "description": "Company ID" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Page number (default: 1)" }, "description": "Page number (default: 1)" }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "description": "Items per page (default: 50)" }, "description": "Items per page (default: 50)" } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Content not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Content images", "content": { "application/json": { "schema": { "type": "object", "properties": { "images": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Content image ID" }, "imageId": { "type": "string", "description": "Image ID" }, "url": { "type": "string", "description": "Image URL" }, "prompt": { "type": "string", "description": "Image prompt" }, "provider": { "type": "string", "description": "Image provider" } }, "description": "Content image object" }, "description": "List of images" } }, "description": "Content images response" } } } } }, "summary": "Get all images associated with a specific content." } }, "/api/v0/content/{contentId}/canvas": { "post": { "tags": [ "Content" ], "operationId": "content_generateContentCanvas", "parameters": [ { "name": "contentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Content or brand kit not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Usage limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Canvas generation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Generated canvas images", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether canvas generation completed" }, "generated": { "type": "integer", "description": "Number of canvas images attached to the content" } }, "description": "Generated canvas image count" } } } } }, "summary": "Generate and attach agent-designed canvases using a selected brand kit.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "brandKitId": { "type": "string", "description": "Canvas-enabled brand kit ID" } }, "required": [ "companyId", "brandKitId" ], "description": "Brand kit selection for canvas generation" } } }, "description": "Canvas-enabled brand kit to use" } } }, "/api/v0/content/campaigns": { "get": { "tags": [ "Content" ], "operationId": "content_getContentCampaigns", "parameters": [ { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID" }, "description": "Company ID" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Page number" }, "description": "Page number" }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "description": "Items per page" }, "description": "Items per page" } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "List of campaigns", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Campaign ID" }, "name": { "type": "string", "description": "Campaign name" }, "plan": { "type": "string", "description": "Campaign plan/description" }, "tone": { "type": "string", "description": "Content tone" }, "model": { "type": "string", "description": "AI model" }, "color": { "type": "string", "description": "Campaign color" }, "webResearch": { "type": "boolean", "description": "Web research enabled" }, "knowledgeBase": { "type": "boolean", "description": "Knowledge base enabled" }, "idealCustomerProfileId": { "type": "string", "description": "ICP profile ID" }, "contentStrategyId": { "type": "string", "description": "Content strategy ID" }, "brandVoiceId": { "type": "string", "description": "Brand voice ID" }, "brandImageId": { "type": "string", "description": "Brand image ID" }, "isIdeationMode": { "type": "boolean", "description": "Ideation mode enabled" }, "numberOfPosts": { "type": "integer", "description": "Number of posts" }, "status": { "type": "string", "description": "Worker state: healthy, running, cancelling, cancelled or error. Autopilot pause state is frequency=manual." }, "errorMessage": { "type": "string" }, "publishDaysOfWeek": { "type": "array", "items": { "type": "integer" }, "description": "UTC weekdays, Sunday=0 through Saturday=6." }, "targetKeywords": { "type": "array", "items": { "type": "string" }, "description": "Seed keywords; non-null (including []) identifies SEO Autopilot." }, "frequency": { "type": "string", "description": "Publishing frequency" }, "channels": { "type": "object", "properties": { "blog_post": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether this channel is enabled for the campaign", "default": false }, "subSettings": { "type": "object", "properties": { "generateImages": { "type": "boolean", "description": "Generate images for this content type; disable for text only", "default": true }, "autoPublish": { "type": "boolean", "description": "Enable auto-publishing to this channel" }, "publishAsDraft": { "type": "boolean", "description": "Publish as draft instead of live" }, "websiteUrl": { "type": "string", "description": "Website researched and written for by Auto SEO; defaults to the company website" }, "wordpressIntegration": { "type": "string", "description": "WordPress/Blog integration ID for blog_post" }, "linkedinIntegration": { "type": "string", "description": "LinkedIn integration ID for linkedin_post" }, "facebookIntegration": { "type": "string", "description": "Facebook integration ID for facebook_post" }, "instagramIntegration": { "type": "string", "description": "Instagram integration ID for instagram_post" } }, "description": "Channel-specific settings (auto-publish, integrations, etc.)" } }, "description": "Blog post channel configuration" }, "facebook_post": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether this channel is enabled for the campaign", "default": false }, "subSettings": { "type": "object", "properties": { "generateImages": { "type": "boolean", "description": "Generate images for this content type; disable for text only", "default": true }, "autoPublish": { "type": "boolean", "description": "Enable auto-publishing to this channel" }, "publishAsDraft": { "type": "boolean", "description": "Publish as draft instead of live" }, "websiteUrl": { "type": "string", "description": "Website researched and written for by Auto SEO; defaults to the company website" }, "wordpressIntegration": { "type": "string", "description": "WordPress/Blog integration ID for blog_post" }, "linkedinIntegration": { "type": "string", "description": "LinkedIn integration ID for linkedin_post" }, "facebookIntegration": { "type": "string", "description": "Facebook integration ID for facebook_post" }, "instagramIntegration": { "type": "string", "description": "Instagram integration ID for instagram_post" } }, "description": "Channel-specific settings (auto-publish, integrations, etc.)" } }, "description": "Facebook post channel configuration" }, "linkedin_post": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether this channel is enabled for the campaign", "default": false }, "subSettings": { "type": "object", "properties": { "generateImages": { "type": "boolean", "description": "Generate images for this content type; disable for text only", "default": true }, "autoPublish": { "type": "boolean", "description": "Enable auto-publishing to this channel" }, "publishAsDraft": { "type": "boolean", "description": "Publish as draft instead of live" }, "websiteUrl": { "type": "string", "description": "Website researched and written for by Auto SEO; defaults to the company website" }, "wordpressIntegration": { "type": "string", "description": "WordPress/Blog integration ID for blog_post" }, "linkedinIntegration": { "type": "string", "description": "LinkedIn integration ID for linkedin_post" }, "facebookIntegration": { "type": "string", "description": "Facebook integration ID for facebook_post" }, "instagramIntegration": { "type": "string", "description": "Instagram integration ID for instagram_post" } }, "description": "Channel-specific settings (auto-publish, integrations, etc.)" } }, "description": "LinkedIn post channel configuration" }, "instagram_post": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether this channel is enabled for the campaign", "default": false }, "subSettings": { "type": "object", "properties": { "generateImages": { "type": "boolean", "description": "Generate images for this content type; disable for text only", "default": true }, "autoPublish": { "type": "boolean", "description": "Enable auto-publishing to this channel" }, "publishAsDraft": { "type": "boolean", "description": "Publish as draft instead of live" }, "websiteUrl": { "type": "string", "description": "Website researched and written for by Auto SEO; defaults to the company website" }, "wordpressIntegration": { "type": "string", "description": "WordPress/Blog integration ID for blog_post" }, "linkedinIntegration": { "type": "string", "description": "LinkedIn integration ID for linkedin_post" }, "facebookIntegration": { "type": "string", "description": "Facebook integration ID for facebook_post" }, "instagramIntegration": { "type": "string", "description": "Instagram integration ID for instagram_post" } }, "description": "Channel-specific settings (auto-publish, integrations, etc.)" } }, "description": "Instagram post channel configuration" }, "x_post": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether this channel is enabled for the campaign", "default": false }, "subSettings": { "type": "object", "properties": { "generateImages": { "type": "boolean", "description": "Generate images for this content type; disable for text only", "default": true }, "autoPublish": { "type": "boolean", "description": "Enable auto-publishing to this channel" }, "publishAsDraft": { "type": "boolean", "description": "Publish as draft instead of live" }, "websiteUrl": { "type": "string", "description": "Website researched and written for by Auto SEO; defaults to the company website" }, "wordpressIntegration": { "type": "string", "description": "WordPress/Blog integration ID for blog_post" }, "linkedinIntegration": { "type": "string", "description": "LinkedIn integration ID for linkedin_post" }, "facebookIntegration": { "type": "string", "description": "Facebook integration ID for facebook_post" }, "instagramIntegration": { "type": "string", "description": "Instagram integration ID for instagram_post" } }, "description": "Channel-specific settings (auto-publish, integrations, etc.)" } }, "description": "X (Twitter) post channel configuration" }, "youtube_video": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether this channel is enabled for the campaign", "default": false }, "subSettings": { "type": "object", "properties": { "generateImages": { "type": "boolean", "description": "Generate images for this content type; disable for text only", "default": true }, "autoPublish": { "type": "boolean", "description": "Enable auto-publishing to this channel" }, "publishAsDraft": { "type": "boolean", "description": "Publish as draft instead of live" }, "websiteUrl": { "type": "string", "description": "Website researched and written for by Auto SEO; defaults to the company website" }, "wordpressIntegration": { "type": "string", "description": "WordPress/Blog integration ID for blog_post" }, "linkedinIntegration": { "type": "string", "description": "LinkedIn integration ID for linkedin_post" }, "facebookIntegration": { "type": "string", "description": "Facebook integration ID for facebook_post" }, "instagramIntegration": { "type": "string", "description": "Instagram integration ID for instagram_post" } }, "description": "Channel-specific settings (auto-publish, integrations, etc.)" } }, "description": "YouTube video channel configuration" }, "tiktok_video": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether this channel is enabled for the campaign", "default": false }, "subSettings": { "type": "object", "properties": { "generateImages": { "type": "boolean", "description": "Generate images for this content type; disable for text only", "default": true }, "autoPublish": { "type": "boolean", "description": "Enable auto-publishing to this channel" }, "publishAsDraft": { "type": "boolean", "description": "Publish as draft instead of live" }, "websiteUrl": { "type": "string", "description": "Website researched and written for by Auto SEO; defaults to the company website" }, "wordpressIntegration": { "type": "string", "description": "WordPress/Blog integration ID for blog_post" }, "linkedinIntegration": { "type": "string", "description": "LinkedIn integration ID for linkedin_post" }, "facebookIntegration": { "type": "string", "description": "Facebook integration ID for facebook_post" }, "instagramIntegration": { "type": "string", "description": "Instagram integration ID for instagram_post" } }, "description": "Channel-specific settings (auto-publish, integrations, etc.)" } }, "description": "TikTok video channel configuration" }, "email_newsletter": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether this channel is enabled for the campaign", "default": false }, "subSettings": { "type": "object", "properties": { "generateImages": { "type": "boolean", "description": "Generate images for this content type; disable for text only", "default": true }, "autoPublish": { "type": "boolean", "description": "Enable auto-publishing to this channel" }, "publishAsDraft": { "type": "boolean", "description": "Publish as draft instead of live" }, "websiteUrl": { "type": "string", "description": "Website researched and written for by Auto SEO; defaults to the company website" }, "wordpressIntegration": { "type": "string", "description": "WordPress/Blog integration ID for blog_post" }, "linkedinIntegration": { "type": "string", "description": "LinkedIn integration ID for linkedin_post" }, "facebookIntegration": { "type": "string", "description": "Facebook integration ID for facebook_post" }, "instagramIntegration": { "type": "string", "description": "Instagram integration ID for instagram_post" } }, "description": "Channel-specific settings (auto-publish, integrations, etc.)" } }, "description": "Email newsletter channel configuration" }, "podcast_episode": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether this channel is enabled for the campaign", "default": false }, "subSettings": { "type": "object", "properties": { "generateImages": { "type": "boolean", "description": "Generate images for this content type; disable for text only", "default": true }, "autoPublish": { "type": "boolean", "description": "Enable auto-publishing to this channel" }, "publishAsDraft": { "type": "boolean", "description": "Publish as draft instead of live" }, "websiteUrl": { "type": "string", "description": "Website researched and written for by Auto SEO; defaults to the company website" }, "wordpressIntegration": { "type": "string", "description": "WordPress/Blog integration ID for blog_post" }, "linkedinIntegration": { "type": "string", "description": "LinkedIn integration ID for linkedin_post" }, "facebookIntegration": { "type": "string", "description": "Facebook integration ID for facebook_post" }, "instagramIntegration": { "type": "string", "description": "Instagram integration ID for instagram_post" } }, "description": "Channel-specific settings (auto-publish, integrations, etc.)" } }, "description": "Podcast episode channel configuration" }, "website_copy": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether this channel is enabled for the campaign", "default": false }, "subSettings": { "type": "object", "properties": { "generateImages": { "type": "boolean", "description": "Generate images for this content type; disable for text only", "default": true }, "autoPublish": { "type": "boolean", "description": "Enable auto-publishing to this channel" }, "publishAsDraft": { "type": "boolean", "description": "Publish as draft instead of live" }, "websiteUrl": { "type": "string", "description": "Website researched and written for by Auto SEO; defaults to the company website" }, "wordpressIntegration": { "type": "string", "description": "WordPress/Blog integration ID for blog_post" }, "linkedinIntegration": { "type": "string", "description": "LinkedIn integration ID for linkedin_post" }, "facebookIntegration": { "type": "string", "description": "Facebook integration ID for facebook_post" }, "instagramIntegration": { "type": "string", "description": "Instagram integration ID for instagram_post" } }, "description": "Channel-specific settings (auto-publish, integrations, etc.)" } }, "description": "Website copy channel configuration" }, "marketing_email": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether this channel is enabled for the campaign", "default": false }, "subSettings": { "type": "object", "properties": { "generateImages": { "type": "boolean", "description": "Generate images for this content type; disable for text only", "default": true }, "autoPublish": { "type": "boolean", "description": "Enable auto-publishing to this channel" }, "publishAsDraft": { "type": "boolean", "description": "Publish as draft instead of live" }, "websiteUrl": { "type": "string", "description": "Website researched and written for by Auto SEO; defaults to the company website" }, "wordpressIntegration": { "type": "string", "description": "WordPress/Blog integration ID for blog_post" }, "linkedinIntegration": { "type": "string", "description": "LinkedIn integration ID for linkedin_post" }, "facebookIntegration": { "type": "string", "description": "Facebook integration ID for facebook_post" }, "instagramIntegration": { "type": "string", "description": "Instagram integration ID for instagram_post" } }, "description": "Channel-specific settings (auto-publish, integrations, etc.)" } }, "description": "Marketing email channel configuration" }, "ad_copy": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether this channel is enabled for the campaign", "default": false }, "subSettings": { "type": "object", "properties": { "generateImages": { "type": "boolean", "description": "Generate images for this content type; disable for text only", "default": true }, "autoPublish": { "type": "boolean", "description": "Enable auto-publishing to this channel" }, "publishAsDraft": { "type": "boolean", "description": "Publish as draft instead of live" }, "websiteUrl": { "type": "string", "description": "Website researched and written for by Auto SEO; defaults to the company website" }, "wordpressIntegration": { "type": "string", "description": "WordPress/Blog integration ID for blog_post" }, "linkedinIntegration": { "type": "string", "description": "LinkedIn integration ID for linkedin_post" }, "facebookIntegration": { "type": "string", "description": "Facebook integration ID for facebook_post" }, "instagramIntegration": { "type": "string", "description": "Instagram integration ID for instagram_post" } }, "description": "Channel-specific settings (auto-publish, integrations, etc.)" } }, "description": "Ad copy channel configuration" }, "press_release": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether this channel is enabled for the campaign", "default": false }, "subSettings": { "type": "object", "properties": { "generateImages": { "type": "boolean", "description": "Generate images for this content type; disable for text only", "default": true }, "autoPublish": { "type": "boolean", "description": "Enable auto-publishing to this channel" }, "publishAsDraft": { "type": "boolean", "description": "Publish as draft instead of live" }, "websiteUrl": { "type": "string", "description": "Website researched and written for by Auto SEO; defaults to the company website" }, "wordpressIntegration": { "type": "string", "description": "WordPress/Blog integration ID for blog_post" }, "linkedinIntegration": { "type": "string", "description": "LinkedIn integration ID for linkedin_post" }, "facebookIntegration": { "type": "string", "description": "Facebook integration ID for facebook_post" }, "instagramIntegration": { "type": "string", "description": "Instagram integration ID for instagram_post" } }, "description": "Channel-specific settings (auto-publish, integrations, etc.)" } }, "description": "Press release channel configuration" } }, "description": "Content channel configurations. Object with content type keys (blog_post, linkedin_post, etc.)" }, "content_count": { "type": "integer", "description": "Number of content items in campaign" }, "created_date": { "type": "string", "format": "date-time", "description": "Creation timestamp" } }, "description": "Campaign object" }, "description": "List of campaigns" }, "total": { "type": "integer", "description": "Total count" }, "page": { "type": "integer", "description": "Current page number" }, "pages": { "type": "integer", "description": "Total number of pages" }, "has_next": { "type": "boolean", "description": "Whether there is a next page" } }, "description": "List of campaigns" } } } } }, "summary": "List all content campaigns." }, "post": { "tags": [ "Content" ], "operationId": "content_saveContentCampaign", "parameters": [], "responses": { "400": { "description": "Invalid campaign settings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access or plan restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Campaign or integration not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting creation request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string" }, "campaignId": { "type": "string" }, "name": { "type": "string" }, "campaign": { "type": "object", "properties": { "id": { "type": "string", "description": "Campaign ID" }, "name": { "type": "string", "description": "Campaign name" }, "plan": { "type": "string", "description": "Campaign plan/description" }, "tone": { "type": "string", "description": "Content tone" }, "model": { "type": "string", "description": "AI model" }, "color": { "type": "string", "description": "Campaign color" }, "webResearch": { "type": "boolean", "description": "Web research enabled" }, "knowledgeBase": { "type": "boolean", "description": "Knowledge base enabled" }, "idealCustomerProfileId": { "type": "string", "description": "ICP profile ID" }, "contentStrategyId": { "type": "string", "description": "Content strategy ID" }, "brandVoiceId": { "type": "string", "description": "Brand voice ID" }, "brandImageId": { "type": "string", "description": "Brand image ID" }, "isIdeationMode": { "type": "boolean", "description": "Ideation mode enabled" }, "numberOfPosts": { "type": "integer", "description": "Number of posts" }, "status": { "type": "string", "description": "Worker state: healthy, running, cancelling, cancelled or error. Autopilot pause state is frequency=manual." }, "errorMessage": { "type": "string" }, "publishDaysOfWeek": { "type": "array", "items": { "type": "integer" }, "description": "UTC weekdays, Sunday=0 through Saturday=6." }, "targetKeywords": { "type": "array", "items": { "type": "string" }, "description": "Seed keywords; non-null (including []) identifies SEO Autopilot." }, "frequency": { "type": "string", "description": "Publishing frequency" }, "channels": { "type": "object", "properties": { "blog_post": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether this channel is enabled for the campaign", "default": false }, "subSettings": { "type": "object", "properties": { "generateImages": { "type": "boolean", "description": "Generate images for this content type; disable for text only", "default": true }, "autoPublish": { "type": "boolean", "description": "Enable auto-publishing to this channel" }, "publishAsDraft": { "type": "boolean", "description": "Publish as draft instead of live" }, "websiteUrl": { "type": "string", "description": "Website researched and written for by Auto SEO; defaults to the company website" }, "wordpressIntegration": { "type": "string", "description": "WordPress/Blog integration ID for blog_post" }, "linkedinIntegration": { "type": "string", "description": "LinkedIn integration ID for linkedin_post" }, "facebookIntegration": { "type": "string", "description": "Facebook integration ID for facebook_post" }, "instagramIntegration": { "type": "string", "description": "Instagram integration ID for instagram_post" } }, "description": "Channel-specific settings (auto-publish, integrations, etc.)" } }, "description": "Blog post channel configuration" }, "facebook_post": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether this channel is enabled for the campaign", "default": false }, "subSettings": { "type": "object", "properties": { "generateImages": { "type": "boolean", "description": "Generate images for this content type; disable for text only", "default": true }, "autoPublish": { "type": "boolean", "description": "Enable auto-publishing to this channel" }, "publishAsDraft": { "type": "boolean", "description": "Publish as draft instead of live" }, "websiteUrl": { "type": "string", "description": "Website researched and written for by Auto SEO; defaults to the company website" }, "wordpressIntegration": { "type": "string", "description": "WordPress/Blog integration ID for blog_post" }, "linkedinIntegration": { "type": "string", "description": "LinkedIn integration ID for linkedin_post" }, "facebookIntegration": { "type": "string", "description": "Facebook integration ID for facebook_post" }, "instagramIntegration": { "type": "string", "description": "Instagram integration ID for instagram_post" } }, "description": "Channel-specific settings (auto-publish, integrations, etc.)" } }, "description": "Facebook post channel configuration" }, "linkedin_post": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether this channel is enabled for the campaign", "default": false }, "subSettings": { "type": "object", "properties": { "generateImages": { "type": "boolean", "description": "Generate images for this content type; disable for text only", "default": true }, "autoPublish": { "type": "boolean", "description": "Enable auto-publishing to this channel" }, "publishAsDraft": { "type": "boolean", "description": "Publish as draft instead of live" }, "websiteUrl": { "type": "string", "description": "Website researched and written for by Auto SEO; defaults to the company website" }, "wordpressIntegration": { "type": "string", "description": "WordPress/Blog integration ID for blog_post" }, "linkedinIntegration": { "type": "string", "description": "LinkedIn integration ID for linkedin_post" }, "facebookIntegration": { "type": "string", "description": "Facebook integration ID for facebook_post" }, "instagramIntegration": { "type": "string", "description": "Instagram integration ID for instagram_post" } }, "description": "Channel-specific settings (auto-publish, integrations, etc.)" } }, "description": "LinkedIn post channel configuration" }, "instagram_post": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether this channel is enabled for the campaign", "default": false }, "subSettings": { "type": "object", "properties": { "generateImages": { "type": "boolean", "description": "Generate images for this content type; disable for text only", "default": true }, "autoPublish": { "type": "boolean", "description": "Enable auto-publishing to this channel" }, "publishAsDraft": { "type": "boolean", "description": "Publish as draft instead of live" }, "websiteUrl": { "type": "string", "description": "Website researched and written for by Auto SEO; defaults to the company website" }, "wordpressIntegration": { "type": "string", "description": "WordPress/Blog integration ID for blog_post" }, "linkedinIntegration": { "type": "string", "description": "LinkedIn integration ID for linkedin_post" }, "facebookIntegration": { "type": "string", "description": "Facebook integration ID for facebook_post" }, "instagramIntegration": { "type": "string", "description": "Instagram integration ID for instagram_post" } }, "description": "Channel-specific settings (auto-publish, integrations, etc.)" } }, "description": "Instagram post channel configuration" }, "x_post": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether this channel is enabled for the campaign", "default": false }, "subSettings": { "type": "object", "properties": { "generateImages": { "type": "boolean", "description": "Generate images for this content type; disable for text only", "default": true }, "autoPublish": { "type": "boolean", "description": "Enable auto-publishing to this channel" }, "publishAsDraft": { "type": "boolean", "description": "Publish as draft instead of live" }, "websiteUrl": { "type": "string", "description": "Website researched and written for by Auto SEO; defaults to the company website" }, "wordpressIntegration": { "type": "string", "description": "WordPress/Blog integration ID for blog_post" }, "linkedinIntegration": { "type": "string", "description": "LinkedIn integration ID for linkedin_post" }, "facebookIntegration": { "type": "string", "description": "Facebook integration ID for facebook_post" }, "instagramIntegration": { "type": "string", "description": "Instagram integration ID for instagram_post" } }, "description": "Channel-specific settings (auto-publish, integrations, etc.)" } }, "description": "X (Twitter) post channel configuration" }, "youtube_video": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether this channel is enabled for the campaign", "default": false }, "subSettings": { "type": "object", "properties": { "generateImages": { "type": "boolean", "description": "Generate images for this content type; disable for text only", "default": true }, "autoPublish": { "type": "boolean", "description": "Enable auto-publishing to this channel" }, "publishAsDraft": { "type": "boolean", "description": "Publish as draft instead of live" }, "websiteUrl": { "type": "string", "description": "Website researched and written for by Auto SEO; defaults to the company website" }, "wordpressIntegration": { "type": "string", "description": "WordPress/Blog integration ID for blog_post" }, "linkedinIntegration": { "type": "string", "description": "LinkedIn integration ID for linkedin_post" }, "facebookIntegration": { "type": "string", "description": "Facebook integration ID for facebook_post" }, "instagramIntegration": { "type": "string", "description": "Instagram integration ID for instagram_post" } }, "description": "Channel-specific settings (auto-publish, integrations, etc.)" } }, "description": "YouTube video channel configuration" }, "tiktok_video": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether this channel is enabled for the campaign", "default": false }, "subSettings": { "type": "object", "properties": { "generateImages": { "type": "boolean", "description": "Generate images for this content type; disable for text only", "default": true }, "autoPublish": { "type": "boolean", "description": "Enable auto-publishing to this channel" }, "publishAsDraft": { "type": "boolean", "description": "Publish as draft instead of live" }, "websiteUrl": { "type": "string", "description": "Website researched and written for by Auto SEO; defaults to the company website" }, "wordpressIntegration": { "type": "string", "description": "WordPress/Blog integration ID for blog_post" }, "linkedinIntegration": { "type": "string", "description": "LinkedIn integration ID for linkedin_post" }, "facebookIntegration": { "type": "string", "description": "Facebook integration ID for facebook_post" }, "instagramIntegration": { "type": "string", "description": "Instagram integration ID for instagram_post" } }, "description": "Channel-specific settings (auto-publish, integrations, etc.)" } }, "description": "TikTok video channel configuration" }, "email_newsletter": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether this channel is enabled for the campaign", "default": false }, "subSettings": { "type": "object", "properties": { "generateImages": { "type": "boolean", "description": "Generate images for this content type; disable for text only", "default": true }, "autoPublish": { "type": "boolean", "description": "Enable auto-publishing to this channel" }, "publishAsDraft": { "type": "boolean", "description": "Publish as draft instead of live" }, "websiteUrl": { "type": "string", "description": "Website researched and written for by Auto SEO; defaults to the company website" }, "wordpressIntegration": { "type": "string", "description": "WordPress/Blog integration ID for blog_post" }, "linkedinIntegration": { "type": "string", "description": "LinkedIn integration ID for linkedin_post" }, "facebookIntegration": { "type": "string", "description": "Facebook integration ID for facebook_post" }, "instagramIntegration": { "type": "string", "description": "Instagram integration ID for instagram_post" } }, "description": "Channel-specific settings (auto-publish, integrations, etc.)" } }, "description": "Email newsletter channel configuration" }, "podcast_episode": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether this channel is enabled for the campaign", "default": false }, "subSettings": { "type": "object", "properties": { "generateImages": { "type": "boolean", "description": "Generate images for this content type; disable for text only", "default": true }, "autoPublish": { "type": "boolean", "description": "Enable auto-publishing to this channel" }, "publishAsDraft": { "type": "boolean", "description": "Publish as draft instead of live" }, "websiteUrl": { "type": "string", "description": "Website researched and written for by Auto SEO; defaults to the company website" }, "wordpressIntegration": { "type": "string", "description": "WordPress/Blog integration ID for blog_post" }, "linkedinIntegration": { "type": "string", "description": "LinkedIn integration ID for linkedin_post" }, "facebookIntegration": { "type": "string", "description": "Facebook integration ID for facebook_post" }, "instagramIntegration": { "type": "string", "description": "Instagram integration ID for instagram_post" } }, "description": "Channel-specific settings (auto-publish, integrations, etc.)" } }, "description": "Podcast episode channel configuration" }, "website_copy": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether this channel is enabled for the campaign", "default": false }, "subSettings": { "type": "object", "properties": { "generateImages": { "type": "boolean", "description": "Generate images for this content type; disable for text only", "default": true }, "autoPublish": { "type": "boolean", "description": "Enable auto-publishing to this channel" }, "publishAsDraft": { "type": "boolean", "description": "Publish as draft instead of live" }, "websiteUrl": { "type": "string", "description": "Website researched and written for by Auto SEO; defaults to the company website" }, "wordpressIntegration": { "type": "string", "description": "WordPress/Blog integration ID for blog_post" }, "linkedinIntegration": { "type": "string", "description": "LinkedIn integration ID for linkedin_post" }, "facebookIntegration": { "type": "string", "description": "Facebook integration ID for facebook_post" }, "instagramIntegration": { "type": "string", "description": "Instagram integration ID for instagram_post" } }, "description": "Channel-specific settings (auto-publish, integrations, etc.)" } }, "description": "Website copy channel configuration" }, "marketing_email": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether this channel is enabled for the campaign", "default": false }, "subSettings": { "type": "object", "properties": { "generateImages": { "type": "boolean", "description": "Generate images for this content type; disable for text only", "default": true }, "autoPublish": { "type": "boolean", "description": "Enable auto-publishing to this channel" }, "publishAsDraft": { "type": "boolean", "description": "Publish as draft instead of live" }, "websiteUrl": { "type": "string", "description": "Website researched and written for by Auto SEO; defaults to the company website" }, "wordpressIntegration": { "type": "string", "description": "WordPress/Blog integration ID for blog_post" }, "linkedinIntegration": { "type": "string", "description": "LinkedIn integration ID for linkedin_post" }, "facebookIntegration": { "type": "string", "description": "Facebook integration ID for facebook_post" }, "instagramIntegration": { "type": "string", "description": "Instagram integration ID for instagram_post" } }, "description": "Channel-specific settings (auto-publish, integrations, etc.)" } }, "description": "Marketing email channel configuration" }, "ad_copy": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether this channel is enabled for the campaign", "default": false }, "subSettings": { "type": "object", "properties": { "generateImages": { "type": "boolean", "description": "Generate images for this content type; disable for text only", "default": true }, "autoPublish": { "type": "boolean", "description": "Enable auto-publishing to this channel" }, "publishAsDraft": { "type": "boolean", "description": "Publish as draft instead of live" }, "websiteUrl": { "type": "string", "description": "Website researched and written for by Auto SEO; defaults to the company website" }, "wordpressIntegration": { "type": "string", "description": "WordPress/Blog integration ID for blog_post" }, "linkedinIntegration": { "type": "string", "description": "LinkedIn integration ID for linkedin_post" }, "facebookIntegration": { "type": "string", "description": "Facebook integration ID for facebook_post" }, "instagramIntegration": { "type": "string", "description": "Instagram integration ID for instagram_post" } }, "description": "Channel-specific settings (auto-publish, integrations, etc.)" } }, "description": "Ad copy channel configuration" }, "press_release": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether this channel is enabled for the campaign", "default": false }, "subSettings": { "type": "object", "properties": { "generateImages": { "type": "boolean", "description": "Generate images for this content type; disable for text only", "default": true }, "autoPublish": { "type": "boolean", "description": "Enable auto-publishing to this channel" }, "publishAsDraft": { "type": "boolean", "description": "Publish as draft instead of live" }, "websiteUrl": { "type": "string", "description": "Website researched and written for by Auto SEO; defaults to the company website" }, "wordpressIntegration": { "type": "string", "description": "WordPress/Blog integration ID for blog_post" }, "linkedinIntegration": { "type": "string", "description": "LinkedIn integration ID for linkedin_post" }, "facebookIntegration": { "type": "string", "description": "Facebook integration ID for facebook_post" }, "instagramIntegration": { "type": "string", "description": "Instagram integration ID for instagram_post" } }, "description": "Channel-specific settings (auto-publish, integrations, etc.)" } }, "description": "Press release channel configuration" } }, "description": "Content channel configurations. Object with content type keys (blog_post, linkedin_post, etc.)" }, "content_count": { "type": "integer", "description": "Number of content items in campaign" }, "created_date": { "type": "string", "format": "date-time", "description": "Creation timestamp" } }, "description": "Campaign object" }, "employee": { "type": "object", "description": "The company SEO employee assigned on Autopilot launch (id, name, title, picture)." } } } } } } }, "summary": "Create or update a standard or SEO Autopilot content campaign.", "description": "Send campaign.id to update; omit it to create. A non-null targetKeywords (including [])\nselects Autopilot. Configure its blog through channels.blog_post.subSettings:\nwordpressIntegration, publishAsDraft (default true), autoPublish (true), generateImages.\nAutopilot creation prepares unapproved proposals asynchronously. Updates preserve the\nexisting content and do not start another plan. frequency=manual pauses automatic runs;\ndaily resumes selected UTC weekdays (Sunday=0). Existing planned dates are unchanged.\nUse top-level requestId for idempotent Autopilot creation retries. Read campaign records\nthrough the existing campaign list. Review and generate articles in the Content Engine.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "requestId": { "type": "string", "description": "Optional idempotency key for Autopilot creation only. Reuse on retry; use campaign.id for updates." }, "campaign": { "type": "object", "properties": { "id": { "type": "string", "description": "Campaign ID (optional for create, required for update)" }, "name": { "type": "string", "description": "Required for standard creation; defaults to SEO Autopilot for Autopilot. Optional on update." }, "plan": { "type": "string", "description": "Required for standard creation; Autopilot supplies a default. Optional on update." }, "tone": { "type": "string", "description": "Content tone (e.g., professional, casual, friendly)" }, "model": { "type": "string", "description": "AI model to use for content generation" }, "color": { "type": "string", "description": "Campaign color for UI (e.g., #FF5733)" }, "webResearch": { "type": "boolean", "description": "Enable web research for content generation" }, "knowledgeBase": { "type": "boolean", "description": "Use knowledge base for content generation" }, "knowledgeBaseScope": { "type": "string", "description": "Knowledge base path scope (optional)" }, "idealCustomerProfileId": { "type": "string", "description": "ICP profile ID to target" }, "contentStrategyId": { "type": "string", "description": "Content strategy ID to follow" }, "brandVoiceId": { "type": "string", "description": "Brand voice ID to use" }, "brandImageId": { "type": "string", "description": "Brand image ID for visuals" }, "isIdeationMode": { "type": "boolean", "description": "Whether campaign is for content ideation (default: false)" }, "numberOfPosts": { "type": "integer", "description": "Number of posts to generate in ideation mode" }, "startPublishDate": { "type": "string", "format": "date-time", "description": "Start date for publishing content calendar items" }, "publishDaysOfWeek": { "type": "array", "items": { "type": "integer" }, "description": "UTC weekdays (Sunday=0 through Saturday=6). Daily campaigns run only on these days; planned posts use these days for all campaign types. Omit for all days." }, "targetKeywords": { "type": "array", "items": { "type": "string" }, "description": "Autopilot seed keywords; null marks a standard campaign. Use this same campaign endpoint for Autopilot creation and updates; a new Autopilot campaign prepares its content ideas." }, "status": { "type": "string", "description": "Campaign health status. One of: healthy, running, cancelling, cancelled, error. Defaults to \"healthy\" on create.", "enum": [ "healthy", "running", "cancelling", "cancelled", "error" ] }, "errorMessage": { "type": "string", "description": "Error message if status is error" }, "frequency": { "type": "string", "description": "How often the campaign auto-runs. One of: manual, daily, weekly, monthly. \"manual\" means it only runs on demand (via the trigger endpoint) and is the standard-campaign default. Autopilot defaults to daily and supports only daily/manual; daily/weekly/monthly are picked up by the scheduled campaign jobs.", "enum": [ "manual", "daily", "weekly", "monthly" ] }, "start_date": { "type": "string", "format": "date-time", "description": "Campaign start date" }, "end_date": { "type": "string", "format": "date-time", "description": "Campaign end date" }, "channels": { "type": "object", "properties": { "blog_post": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether this channel is enabled for the campaign", "default": false }, "subSettings": { "type": "object", "properties": { "generateImages": { "type": "boolean", "description": "Generate images for this content type; disable for text only", "default": true }, "autoPublish": { "type": "boolean", "description": "Enable auto-publishing to this channel" }, "publishAsDraft": { "type": "boolean", "description": "Publish as draft instead of live" }, "websiteUrl": { "type": "string", "description": "Website researched and written for by Auto SEO; defaults to the company website" }, "wordpressIntegration": { "type": "string", "description": "WordPress/Blog integration ID for blog_post" }, "linkedinIntegration": { "type": "string", "description": "LinkedIn integration ID for linkedin_post" }, "facebookIntegration": { "type": "string", "description": "Facebook integration ID for facebook_post" }, "instagramIntegration": { "type": "string", "description": "Instagram integration ID for instagram_post" } }, "description": "Channel-specific settings (auto-publish, integrations, etc.)" } }, "description": "Blog post channel configuration" }, "facebook_post": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether this channel is enabled for the campaign", "default": false }, "subSettings": { "type": "object", "properties": { "generateImages": { "type": "boolean", "description": "Generate images for this content type; disable for text only", "default": true }, "autoPublish": { "type": "boolean", "description": "Enable auto-publishing to this channel" }, "publishAsDraft": { "type": "boolean", "description": "Publish as draft instead of live" }, "websiteUrl": { "type": "string", "description": "Website researched and written for by Auto SEO; defaults to the company website" }, "wordpressIntegration": { "type": "string", "description": "WordPress/Blog integration ID for blog_post" }, "linkedinIntegration": { "type": "string", "description": "LinkedIn integration ID for linkedin_post" }, "facebookIntegration": { "type": "string", "description": "Facebook integration ID for facebook_post" }, "instagramIntegration": { "type": "string", "description": "Instagram integration ID for instagram_post" } }, "description": "Channel-specific settings (auto-publish, integrations, etc.)" } }, "description": "Facebook post channel configuration" }, "linkedin_post": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether this channel is enabled for the campaign", "default": false }, "subSettings": { "type": "object", "properties": { "generateImages": { "type": "boolean", "description": "Generate images for this content type; disable for text only", "default": true }, "autoPublish": { "type": "boolean", "description": "Enable auto-publishing to this channel" }, "publishAsDraft": { "type": "boolean", "description": "Publish as draft instead of live" }, "websiteUrl": { "type": "string", "description": "Website researched and written for by Auto SEO; defaults to the company website" }, "wordpressIntegration": { "type": "string", "description": "WordPress/Blog integration ID for blog_post" }, "linkedinIntegration": { "type": "string", "description": "LinkedIn integration ID for linkedin_post" }, "facebookIntegration": { "type": "string", "description": "Facebook integration ID for facebook_post" }, "instagramIntegration": { "type": "string", "description": "Instagram integration ID for instagram_post" } }, "description": "Channel-specific settings (auto-publish, integrations, etc.)" } }, "description": "LinkedIn post channel configuration" }, "instagram_post": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether this channel is enabled for the campaign", "default": false }, "subSettings": { "type": "object", "properties": { "generateImages": { "type": "boolean", "description": "Generate images for this content type; disable for text only", "default": true }, "autoPublish": { "type": "boolean", "description": "Enable auto-publishing to this channel" }, "publishAsDraft": { "type": "boolean", "description": "Publish as draft instead of live" }, "websiteUrl": { "type": "string", "description": "Website researched and written for by Auto SEO; defaults to the company website" }, "wordpressIntegration": { "type": "string", "description": "WordPress/Blog integration ID for blog_post" }, "linkedinIntegration": { "type": "string", "description": "LinkedIn integration ID for linkedin_post" }, "facebookIntegration": { "type": "string", "description": "Facebook integration ID for facebook_post" }, "instagramIntegration": { "type": "string", "description": "Instagram integration ID for instagram_post" } }, "description": "Channel-specific settings (auto-publish, integrations, etc.)" } }, "description": "Instagram post channel configuration" }, "x_post": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether this channel is enabled for the campaign", "default": false }, "subSettings": { "type": "object", "properties": { "generateImages": { "type": "boolean", "description": "Generate images for this content type; disable for text only", "default": true }, "autoPublish": { "type": "boolean", "description": "Enable auto-publishing to this channel" }, "publishAsDraft": { "type": "boolean", "description": "Publish as draft instead of live" }, "websiteUrl": { "type": "string", "description": "Website researched and written for by Auto SEO; defaults to the company website" }, "wordpressIntegration": { "type": "string", "description": "WordPress/Blog integration ID for blog_post" }, "linkedinIntegration": { "type": "string", "description": "LinkedIn integration ID for linkedin_post" }, "facebookIntegration": { "type": "string", "description": "Facebook integration ID for facebook_post" }, "instagramIntegration": { "type": "string", "description": "Instagram integration ID for instagram_post" } }, "description": "Channel-specific settings (auto-publish, integrations, etc.)" } }, "description": "X (Twitter) post channel configuration" }, "youtube_video": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether this channel is enabled for the campaign", "default": false }, "subSettings": { "type": "object", "properties": { "generateImages": { "type": "boolean", "description": "Generate images for this content type; disable for text only", "default": true }, "autoPublish": { "type": "boolean", "description": "Enable auto-publishing to this channel" }, "publishAsDraft": { "type": "boolean", "description": "Publish as draft instead of live" }, "websiteUrl": { "type": "string", "description": "Website researched and written for by Auto SEO; defaults to the company website" }, "wordpressIntegration": { "type": "string", "description": "WordPress/Blog integration ID for blog_post" }, "linkedinIntegration": { "type": "string", "description": "LinkedIn integration ID for linkedin_post" }, "facebookIntegration": { "type": "string", "description": "Facebook integration ID for facebook_post" }, "instagramIntegration": { "type": "string", "description": "Instagram integration ID for instagram_post" } }, "description": "Channel-specific settings (auto-publish, integrations, etc.)" } }, "description": "YouTube video channel configuration" }, "tiktok_video": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether this channel is enabled for the campaign", "default": false }, "subSettings": { "type": "object", "properties": { "generateImages": { "type": "boolean", "description": "Generate images for this content type; disable for text only", "default": true }, "autoPublish": { "type": "boolean", "description": "Enable auto-publishing to this channel" }, "publishAsDraft": { "type": "boolean", "description": "Publish as draft instead of live" }, "websiteUrl": { "type": "string", "description": "Website researched and written for by Auto SEO; defaults to the company website" }, "wordpressIntegration": { "type": "string", "description": "WordPress/Blog integration ID for blog_post" }, "linkedinIntegration": { "type": "string", "description": "LinkedIn integration ID for linkedin_post" }, "facebookIntegration": { "type": "string", "description": "Facebook integration ID for facebook_post" }, "instagramIntegration": { "type": "string", "description": "Instagram integration ID for instagram_post" } }, "description": "Channel-specific settings (auto-publish, integrations, etc.)" } }, "description": "TikTok video channel configuration" }, "email_newsletter": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether this channel is enabled for the campaign", "default": false }, "subSettings": { "type": "object", "properties": { "generateImages": { "type": "boolean", "description": "Generate images for this content type; disable for text only", "default": true }, "autoPublish": { "type": "boolean", "description": "Enable auto-publishing to this channel" }, "publishAsDraft": { "type": "boolean", "description": "Publish as draft instead of live" }, "websiteUrl": { "type": "string", "description": "Website researched and written for by Auto SEO; defaults to the company website" }, "wordpressIntegration": { "type": "string", "description": "WordPress/Blog integration ID for blog_post" }, "linkedinIntegration": { "type": "string", "description": "LinkedIn integration ID for linkedin_post" }, "facebookIntegration": { "type": "string", "description": "Facebook integration ID for facebook_post" }, "instagramIntegration": { "type": "string", "description": "Instagram integration ID for instagram_post" } }, "description": "Channel-specific settings (auto-publish, integrations, etc.)" } }, "description": "Email newsletter channel configuration" }, "podcast_episode": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether this channel is enabled for the campaign", "default": false }, "subSettings": { "type": "object", "properties": { "generateImages": { "type": "boolean", "description": "Generate images for this content type; disable for text only", "default": true }, "autoPublish": { "type": "boolean", "description": "Enable auto-publishing to this channel" }, "publishAsDraft": { "type": "boolean", "description": "Publish as draft instead of live" }, "websiteUrl": { "type": "string", "description": "Website researched and written for by Auto SEO; defaults to the company website" }, "wordpressIntegration": { "type": "string", "description": "WordPress/Blog integration ID for blog_post" }, "linkedinIntegration": { "type": "string", "description": "LinkedIn integration ID for linkedin_post" }, "facebookIntegration": { "type": "string", "description": "Facebook integration ID for facebook_post" }, "instagramIntegration": { "type": "string", "description": "Instagram integration ID for instagram_post" } }, "description": "Channel-specific settings (auto-publish, integrations, etc.)" } }, "description": "Podcast episode channel configuration" }, "website_copy": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether this channel is enabled for the campaign", "default": false }, "subSettings": { "type": "object", "properties": { "generateImages": { "type": "boolean", "description": "Generate images for this content type; disable for text only", "default": true }, "autoPublish": { "type": "boolean", "description": "Enable auto-publishing to this channel" }, "publishAsDraft": { "type": "boolean", "description": "Publish as draft instead of live" }, "websiteUrl": { "type": "string", "description": "Website researched and written for by Auto SEO; defaults to the company website" }, "wordpressIntegration": { "type": "string", "description": "WordPress/Blog integration ID for blog_post" }, "linkedinIntegration": { "type": "string", "description": "LinkedIn integration ID for linkedin_post" }, "facebookIntegration": { "type": "string", "description": "Facebook integration ID for facebook_post" }, "instagramIntegration": { "type": "string", "description": "Instagram integration ID for instagram_post" } }, "description": "Channel-specific settings (auto-publish, integrations, etc.)" } }, "description": "Website copy channel configuration" }, "marketing_email": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether this channel is enabled for the campaign", "default": false }, "subSettings": { "type": "object", "properties": { "generateImages": { "type": "boolean", "description": "Generate images for this content type; disable for text only", "default": true }, "autoPublish": { "type": "boolean", "description": "Enable auto-publishing to this channel" }, "publishAsDraft": { "type": "boolean", "description": "Publish as draft instead of live" }, "websiteUrl": { "type": "string", "description": "Website researched and written for by Auto SEO; defaults to the company website" }, "wordpressIntegration": { "type": "string", "description": "WordPress/Blog integration ID for blog_post" }, "linkedinIntegration": { "type": "string", "description": "LinkedIn integration ID for linkedin_post" }, "facebookIntegration": { "type": "string", "description": "Facebook integration ID for facebook_post" }, "instagramIntegration": { "type": "string", "description": "Instagram integration ID for instagram_post" } }, "description": "Channel-specific settings (auto-publish, integrations, etc.)" } }, "description": "Marketing email channel configuration" }, "ad_copy": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether this channel is enabled for the campaign", "default": false }, "subSettings": { "type": "object", "properties": { "generateImages": { "type": "boolean", "description": "Generate images for this content type; disable for text only", "default": true }, "autoPublish": { "type": "boolean", "description": "Enable auto-publishing to this channel" }, "publishAsDraft": { "type": "boolean", "description": "Publish as draft instead of live" }, "websiteUrl": { "type": "string", "description": "Website researched and written for by Auto SEO; defaults to the company website" }, "wordpressIntegration": { "type": "string", "description": "WordPress/Blog integration ID for blog_post" }, "linkedinIntegration": { "type": "string", "description": "LinkedIn integration ID for linkedin_post" }, "facebookIntegration": { "type": "string", "description": "Facebook integration ID for facebook_post" }, "instagramIntegration": { "type": "string", "description": "Instagram integration ID for instagram_post" } }, "description": "Channel-specific settings (auto-publish, integrations, etc.)" } }, "description": "Ad copy channel configuration" }, "press_release": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether this channel is enabled for the campaign", "default": false }, "subSettings": { "type": "object", "properties": { "generateImages": { "type": "boolean", "description": "Generate images for this content type; disable for text only", "default": true }, "autoPublish": { "type": "boolean", "description": "Enable auto-publishing to this channel" }, "publishAsDraft": { "type": "boolean", "description": "Publish as draft instead of live" }, "websiteUrl": { "type": "string", "description": "Website researched and written for by Auto SEO; defaults to the company website" }, "wordpressIntegration": { "type": "string", "description": "WordPress/Blog integration ID for blog_post" }, "linkedinIntegration": { "type": "string", "description": "LinkedIn integration ID for linkedin_post" }, "facebookIntegration": { "type": "string", "description": "Facebook integration ID for facebook_post" }, "instagramIntegration": { "type": "string", "description": "Instagram integration ID for instagram_post" } }, "description": "Channel-specific settings (auto-publish, integrations, etc.)" } }, "description": "Press release channel configuration" } }, "description": "Content channel configurations. Must be an object (not null) with content type keys (blog_post, linkedin_post, etc.) and ChannelConfigSchema values. Example: {\"blog_post\": {\"enabled\": true, \"subSettings\": {\"autoPublish\": true}}}" } }, "description": "Campaign record. Omit id to create; send id and changed fields to update. Non-null targetKeywords enables Autopilot." } }, "required": [ "companyId", "campaign" ], "description": "Request body for saving a campaign" } } }, "description": "Create or update the canonical campaign record, including SEO Autopilot settings." } } }, "/api/v0/content/campaigns/{contentCampaignId}": { "delete": { "tags": [ "Content" ], "operationId": "content_deleteContentCapaign", "parameters": [ { "name": "contentCampaignId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID" }, "description": "Company ID" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Page number (default: 1)" }, "description": "Page number (default: 1)" }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "description": "Items per page (default: 50)" }, "description": "Items per page (default: 50)" } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Campaign not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "description": "Success message" } }, "description": "Success response" } } } } }, "summary": "Delete a content campaign." } }, "/api/v0/content/campaigns/{contentCampaignId}/trigger": { "post": { "tags": [ "Content" ], "operationId": "content_triggerContentCampaign", "parameters": [ { "name": "contentCampaignId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Campaign not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "description": "Success message" } }, "description": "Success response" } } } } }, "summary": "Trigger a content campaign to generate content.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" } }, "required": [ "companyId" ], "description": "Request body for triggering a campaign" } } }, "description": "Trigger data" } } }, "/api/v0/content/generate-from-idea": { "post": { "tags": [ "Content" ], "operationId": "content_generateContentFromIdea", "parameters": [], "responses": { "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Generated content", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Operation success status" }, "content": { "type": "object", "properties": { "campaignIsAutopilot": { "type": "boolean", "description": "Uses the shared multicolor Autopilot campaign accent." }, "id": { "type": "string", "description": "Content ID" }, "title": { "type": "string", "description": "Content title" }, "type": { "type": "string", "description": "Content type: blog_post, linkedin_post, facebook_post, instagram_post, twitter_post, ad_copy, email_template, tiktok_idea, newsletter, whitepaper" }, "status": { "type": "string", "description": "Content status: ideated, queued, generating, draft, scheduled, published, archived" }, "funnelStage": { "type": "string", "description": "Funnel stage: N/A, tofu, mofu, bofu" }, "topicSummary": { "type": "string", "description": "Topic summary" }, "hookOptions": { "type": "array", "items": { "type": "string" }, "description": "Hook options" }, "selectedHook": { "type": "string", "description": "Selected hook" }, "variants": { "type": "object", "description": "Content variants" }, "publishDate": { "type": "string", "description": "Publish date" }, "created": { "type": "number", "description": "Creation timestamp" } }, "description": "The content object" } }, "description": "Content operation success response" } } } } }, "summary": "Generate content from a content idea.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "idea": { "type": "string", "description": "The content idea" }, "contentType": { "type": "string", "description": "Type of content to generate: blog_post, linkedin_post, facebook_post, instagram_post, twitter_post, ad_copy, email_template, tiktok_idea, newsletter, whitepaper" }, "funnelStage": { "type": "string", "description": "Funnel stage: N/A, tofu (top of funnel), mofu (middle of funnel), bofu (bottom of funnel)" }, "brandVoiceId": { "type": "string", "description": "Brand voice ID to use" }, "icpId": { "type": "string", "description": "ICP profile ID to target" }, "generateImages": { "type": "boolean", "description": "Generate images with the content; disable for text only", "default": true }, "brandImageId": { "type": "string", "description": "Brand image ID to use" }, "publishDate": { "type": "string", "description": "Planned publish date" } }, "required": [ "companyId", "idea", "contentType" ], "description": "Request body for generating content from an idea" } } }, "description": "Content idea data" } } }, "/api/v0/content/statistics": { "get": { "tags": [ "Content" ], "operationId": "content_getContentStatistics", "parameters": [ { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID" }, "description": "Company ID" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Page number (default: 1)" }, "description": "Page number (default: 1)" }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "description": "Items per page (default: 50)" }, "description": "Items per page (default: 50)" } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Content statistics", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "integer", "description": "Total content count" }, "byStatus": { "type": "object", "description": "Count by status" }, "byType": { "type": "object", "description": "Count by type" } }, "description": "Content statistics" } } } } }, "summary": "Get overall statistics for content engine." } }, "/api/v0/content/export": { "post": { "tags": [ "Content" ], "operationId": "content_exportContentIdeas", "parameters": [], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Export content ideas to CSV format.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "filters": { "type": "object", "description": "Filter criteria for export" }, "contentIds": { "type": "array", "items": { "type": "string" }, "description": "Specific content IDs to export" } }, "required": [ "companyId" ], "description": "Request body for exporting content" } } }, "description": "Export configuration" } } }, "/api/v0/content/import": { "post": { "tags": [ "Content" ], "operationId": "content_importContentIdeas", "parameters": [], "responses": { "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Import results", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Import success status" }, "imported": { "type": "integer", "description": "Total items imported" }, "updated": { "type": "integer", "description": "Items updated" }, "created": { "type": "integer", "description": "Items created" }, "failed": { "type": "integer", "description": "Items failed" }, "failedItems": { "type": "array", "items": { "type": "object" }, "description": "Details of failed items" } }, "description": "Content import result" } } } } }, "summary": "Import content ideas from CSV data.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "csvData": { "type": "string", "description": "CSV data to import" }, "campaignId": { "type": "string", "description": "Campaign ID to assign imported content to" }, "generateFullContent": { "type": "boolean", "description": "Whether to generate full content from ideas (default: false)" } }, "required": [ "companyId", "csvData" ], "description": "Request body for importing content" } } }, "description": "Import data" } } }, "/api/v0/content/{contentId}/pdf": { "get": { "tags": [ "Content" ], "operationId": "content_downloadContentAsPdf", "parameters": [ { "name": "contentId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID" }, "description": "Company ID" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Page number (default: 1)" }, "description": "Page number (default: 1)" }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "description": "Items per page (default: 50)" }, "description": "Items per page (default: 50)" } ], "responses": { "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Content not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Download content as PDF." } }, "/api/v0/content/profiles": { "get": { "tags": [ "Content" ], "operationId": "content_listProfiles", "parameters": [ { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID" }, "description": "Company ID" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Page number" }, "description": "Page number" }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "description": "Items per page" }, "description": "Items per page" } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "List of ICP profiles", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Profile ID" }, "name": { "type": "string", "description": "Profile name" }, "description": { "type": "string", "description": "Profile description" }, "industry": { "type": "string", "description": "Target industry" }, "companySize": { "type": "string", "description": "Target company size" }, "jobTitles": { "type": "array", "items": { "type": "string" }, "description": "Target job titles" }, "painPoints": { "type": "array", "items": { "type": "string" }, "description": "Pain points" }, "created": { "type": "number", "description": "Creation timestamp" } }, "description": "ICP profile object" }, "description": "List of profiles" }, "total": { "type": "integer", "description": "Total count" } }, "description": "List of ICP profiles" } } } } }, "summary": "List all ICP profiles for a company." }, "post": { "tags": [ "Content" ], "operationId": "content_saveProfile", "parameters": [], "responses": { "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Created profile ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Created/updated resource ID" }, "msg": { "type": "string", "description": "Success message" } }, "description": "Success response with ID" } } } } }, "summary": "Create or update an ICP profile.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "profile": { "type": "object", "description": "ICP profile data object with fields: id (optional for create), name (required), companySize, industry, budget, location, description, businessProfile (object with industries/size/geography/characteristics), strategicContext (object with growth stage/priorities/values), challenges (object with pain points/needs), buyingProcess (object with decision makers/evaluation criteria/objections), personas (array of detailed personas), goToMarket (object with marketing channels/messaging/content strategies)" } }, "required": [ "companyId", "profile" ], "description": "Request body for saving an ICP profile" } } }, "description": "ICP profile data" } } }, "/api/v0/content/profiles/{profileId}": { "get": { "tags": [ "Content" ], "operationId": "content_getProfile", "parameters": [ { "name": "profileId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Profile not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "ICP profile details", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Profile ID" }, "name": { "type": "string", "description": "Profile name" }, "description": { "type": "string", "description": "Profile description" }, "industry": { "type": "string", "description": "Target industry" }, "companySize": { "type": "string", "description": "Target company size" }, "jobTitles": { "type": "array", "items": { "type": "string" }, "description": "Target job titles" }, "painPoints": { "type": "array", "items": { "type": "string" }, "description": "Pain points" }, "created": { "type": "number", "description": "Creation timestamp" } }, "description": "ICP profile object" } } } } }, "summary": "Get a specific ICP profile by ID." }, "delete": { "tags": [ "Content" ], "operationId": "content_deleteProfile", "parameters": [ { "name": "profileId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Profile not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "description": "Success message" } }, "description": "Success response" } } } } }, "summary": "Delete an ICP profile." } }, "/api/v0/content/profiles/generate": { "post": { "tags": [ "Content" ], "operationId": "content_generateProfile", "parameters": [], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Generated ICP profile", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Profile ID" }, "name": { "type": "string", "description": "Profile name" }, "description": { "type": "string", "description": "Profile description" }, "industry": { "type": "string", "description": "Target industry" }, "companySize": { "type": "string", "description": "Target company size" }, "jobTitles": { "type": "array", "items": { "type": "string" }, "description": "Target job titles" }, "painPoints": { "type": "array", "items": { "type": "string" }, "description": "Pain points" }, "created": { "type": "number", "description": "Creation timestamp" } }, "description": "ICP profile object" } } } } }, "summary": "Start ICP generation in the background. Returns immediately.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "data": { "type": "object", "description": "Input data for profile generation: {companyName?: string, product?: string, industry?: string, targetMarket?: string, existingCustomers?: string}" } }, "required": [ "companyId" ], "description": "Request body for generating an ICP profile" } } }, "description": "Generation input data" } } }, "/api/v0/content/brand-voices": { "get": { "tags": [ "Content" ], "operationId": "content_listVoices", "parameters": [ { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID" }, "description": "Company ID" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Page number" }, "description": "Page number" }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "description": "Items per page" }, "description": "Items per page" } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "List of brand voices", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Brand voice ID" }, "name": { "type": "string", "description": "Voice name" }, "description": { "type": "string", "description": "Voice description" }, "tone": { "type": "string", "description": "Tone of voice" }, "style": { "type": "string", "description": "Writing style" }, "vocabulary": { "type": "array", "items": { "type": "string" }, "description": "Preferred vocabulary" }, "created": { "type": "number", "description": "Creation timestamp" } }, "description": "Brand voice object" }, "description": "List of brand voices" }, "total": { "type": "integer", "description": "Total count" } }, "description": "List of brand voices" } } } } }, "summary": "List all brand voices for a company." }, "post": { "tags": [ "Content" ], "operationId": "content_saveVoice", "parameters": [], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Created brand voice ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Created/updated resource ID" }, "msg": { "type": "string", "description": "Success message" } }, "description": "Success response with ID" } } } } }, "summary": "Create or update a brand voice.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "voice": { "type": "object", "description": "Brand voice data object with fields: id (optional for create), name (required), industry, audience, description, brandPersonality (object with traits/tone/character), communicationStyle (object with formality/complexity/style), languageGuidelines (object with vocabulary/phrases/terminology), contentStructure (object with format preferences), visualElements (object with imagery/colors/typography), distinctiveFeatures (object with taglines/motifs), personalBackground (object with bio/career journey), achievements (array of accomplishments), failures (array of lessons learned), editingInstructions" } }, "required": [ "companyId", "voice" ], "description": "Request body for saving a brand voice" } } }, "description": "Brand voice data" } } }, "/api/v0/content/brand-voices/{voiceId}": { "get": { "tags": [ "Content" ], "operationId": "content_getVoice", "parameters": [ { "name": "voiceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Brand voice not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Brand voice details", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Brand voice ID" }, "name": { "type": "string", "description": "Voice name" }, "description": { "type": "string", "description": "Voice description" }, "tone": { "type": "string", "description": "Tone of voice" }, "style": { "type": "string", "description": "Writing style" }, "vocabulary": { "type": "array", "items": { "type": "string" }, "description": "Preferred vocabulary" }, "created": { "type": "number", "description": "Creation timestamp" } }, "description": "Brand voice object" } } } } }, "summary": "Get a specific brand voice by ID." }, "delete": { "tags": [ "Content" ], "operationId": "content_deleteVoice", "parameters": [ { "name": "voiceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Brand voice not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "description": "Success message" } }, "description": "Success response" } } } } }, "summary": "Delete a brand voice." } }, "/api/v0/content/brand-voices/generate": { "post": { "tags": [ "Content" ], "operationId": "content_generateVoice", "parameters": [], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Generated brand voice", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Brand voice ID" }, "name": { "type": "string", "description": "Voice name" }, "description": { "type": "string", "description": "Voice description" }, "tone": { "type": "string", "description": "Tone of voice" }, "style": { "type": "string", "description": "Writing style" }, "vocabulary": { "type": "array", "items": { "type": "string" }, "description": "Preferred vocabulary" }, "created": { "type": "number", "description": "Creation timestamp" } }, "description": "Brand voice object" } } } } }, "summary": "Generate a brand voice using AI based on input data.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "data": { "type": "object", "description": "Input data for voice generation: {companyName?: string, industry?: string, targetAudience?: string, existingContent?: string, brandUrls?: string[]}" } }, "required": [ "companyId" ], "description": "Request body for generating a brand voice" } } }, "description": "Generation input data" } } }, "/api/v0/content/brand-voices/generate-from-linkedin": { "post": { "tags": [ "Content" ], "operationId": "content_generateVoiceFromLinkedin", "parameters": [], "responses": { "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Profile not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "LinkedIn scraping failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Generated brand voice from LinkedIn", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Operation success" }, "data": { "type": "object", "description": "Generated voice data" }, "profile_name": { "type": "string", "description": "Profile name extracted" }, "profile_type": { "type": "string", "description": "Profile type (person/company)" }, "credits_used": { "type": "integer", "description": "Credits consumed" } }, "description": "LinkedIn brand voice generation response" } } } } }, "summary": "Generate a brand voice from a LinkedIn profile (person or company).", "description": "Either linkedin_url or link_id must be provided. The profile_type will be\nauto-detected from the URL if not specified.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "linkedin_url": { "type": "string", "description": "LinkedIn profile URL" }, "link_id": { "type": "string", "description": "LinkedIn profile ID" }, "profile_type": { "type": "string", "description": "Profile type (person or company)" }, "premium": { "type": "boolean", "description": "Use premium/residential proxy (default: false)" }, "voice_name": { "type": "string", "description": "Custom voice name" }, "brand_links": { "type": "array", "items": { "type": "string" }, "description": "Additional brand links to analyze" } }, "required": [ "companyId" ], "description": "Request body for generating brand voice from LinkedIn" } } }, "description": "LinkedIn profile data" } } }, "/api/v0/content/canvases": { "get": { "tags": [ "Content" ], "operationId": "content_listCanvasDesigns", "parameters": [ { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID" }, "description": "Company ID" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Page number" }, "description": "Page number" }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "description": "Items per page" }, "description": "Items per page" } ], "responses": { "400": { "description": "Missing companyId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Paginated list of canvas designs", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Canvas ID" }, "companyId": { "type": "string", "description": "Company ID" }, "name": { "type": "string", "description": "Canvas name" }, "width": { "type": "integer", "description": "Canvas width in pixels" }, "height": { "type": "integer", "description": "Canvas height in pixels" }, "format": { "type": "string", "description": "Named canvas format id, when the size came from one" }, "htmlContent": { "type": "string", "description": "The standalone HTML document for the canvas" }, "animated": { "type": "boolean", "description": "Whether the canvas is animated (exports a looping MP4 instead of a PNG)" }, "videoDuration": { "type": "number", "description": "Loop length in seconds for animated canvases" }, "imageId": { "type": "string", "description": "Images table id of the last render" }, "imageUrl": { "type": "string", "description": "Public PNG URL of the last render" }, "videoId": { "type": "string", "description": "Videos table id of the last recording (animated canvases)" }, "videoUrl": { "type": "string", "description": "Public MP4 URL of the last recording (animated canvases)" } }, "description": "Canvas design" }, "description": "Canvas designs" }, "total": { "type": "integer", "description": "Total count" }, "page": { "type": "integer", "description": "Current page" }, "pages": { "type": "integer", "description": "Total pages" } }, "description": "Paginated list of canvas designs" } } } } }, "summary": "List canvas designs for a company (paginated)." }, "post": { "tags": [ "Content" ], "operationId": "content_createCanvasDesign", "parameters": [], "responses": { "400": { "description": "Missing required fields or invalid dimensions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Created canvas design", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Canvas ID" }, "companyId": { "type": "string", "description": "Company ID" }, "name": { "type": "string", "description": "Canvas name" }, "width": { "type": "integer", "description": "Canvas width in pixels" }, "height": { "type": "integer", "description": "Canvas height in pixels" }, "format": { "type": "string", "description": "Named canvas format id, when the size came from one" }, "htmlContent": { "type": "string", "description": "The standalone HTML document for the canvas" }, "animated": { "type": "boolean", "description": "Whether the canvas is animated (exports a looping MP4 instead of a PNG)" }, "videoDuration": { "type": "number", "description": "Loop length in seconds for animated canvases" }, "imageId": { "type": "string", "description": "Images table id of the last render" }, "imageUrl": { "type": "string", "description": "Public PNG URL of the last render" }, "videoId": { "type": "string", "description": "Videos table id of the last recording (animated canvases)" }, "videoUrl": { "type": "string", "description": "Public MP4 URL of the last recording (animated canvases)" } }, "description": "Canvas design" } } } } }, "summary": "Create a new canvas design.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "name": { "type": "string", "description": "Canvas name" }, "width": { "type": "integer", "description": "Canvas width in pixels" }, "height": { "type": "integer", "description": "Canvas height in pixels" }, "format": { "type": "string", "description": "Named canvas format id the size came from (square, portrait, story, landscape)" }, "animated": { "type": "boolean", "description": "Design with motion and export a looping MP4 instead of a still PNG. Default false" } }, "required": [ "companyId", "name", "width", "height" ], "description": "Request body for creating a canvas design" } } }, "description": "Canvas to create" } } }, "/api/v0/content/canvases/{canvas_id}": { "get": { "tags": [ "Content" ], "operationId": "content_getCanvasDesign", "parameters": [ { "name": "canvas_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Missing companyId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Canvas design", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Canvas ID" }, "companyId": { "type": "string", "description": "Company ID" }, "name": { "type": "string", "description": "Canvas name" }, "width": { "type": "integer", "description": "Canvas width in pixels" }, "height": { "type": "integer", "description": "Canvas height in pixels" }, "format": { "type": "string", "description": "Named canvas format id, when the size came from one" }, "htmlContent": { "type": "string", "description": "The standalone HTML document for the canvas" }, "animated": { "type": "boolean", "description": "Whether the canvas is animated (exports a looping MP4 instead of a PNG)" }, "videoDuration": { "type": "number", "description": "Loop length in seconds for animated canvases" }, "imageId": { "type": "string", "description": "Images table id of the last render" }, "imageUrl": { "type": "string", "description": "Public PNG URL of the last render" }, "videoId": { "type": "string", "description": "Videos table id of the last recording (animated canvases)" }, "videoUrl": { "type": "string", "description": "Public MP4 URL of the last recording (animated canvases)" } }, "description": "Canvas design" } } } } }, "summary": "Get a canvas design (includes the current HTML for the preview)." }, "patch": { "tags": [ "Content" ], "operationId": "content_updateCanvasDesign", "parameters": [ { "name": "canvas_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Updated canvas design", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Canvas ID" }, "companyId": { "type": "string", "description": "Company ID" }, "name": { "type": "string", "description": "Canvas name" }, "width": { "type": "integer", "description": "Canvas width in pixels" }, "height": { "type": "integer", "description": "Canvas height in pixels" }, "format": { "type": "string", "description": "Named canvas format id, when the size came from one" }, "htmlContent": { "type": "string", "description": "The standalone HTML document for the canvas" }, "animated": { "type": "boolean", "description": "Whether the canvas is animated (exports a looping MP4 instead of a PNG)" }, "videoDuration": { "type": "number", "description": "Loop length in seconds for animated canvases" }, "imageId": { "type": "string", "description": "Images table id of the last render" }, "imageUrl": { "type": "string", "description": "Public PNG URL of the last render" }, "videoId": { "type": "string", "description": "Videos table id of the last recording (animated canvases)" }, "videoUrl": { "type": "string", "description": "Public MP4 URL of the last recording (animated canvases)" } }, "description": "Canvas design" } } } } }, "summary": "Update a canvas design's name, size, or animation settings.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "name": { "type": "string", "description": "New name" }, "width": { "type": "integer", "description": "New width in pixels" }, "height": { "type": "integer", "description": "New height in pixels" }, "format": { "type": "string", "description": "Named canvas format id the size came from" }, "animated": { "type": "boolean", "description": "Whether the canvas is animated (exports a looping MP4 instead of a PNG)" }, "videoDuration": { "type": "number", "description": "Loop length in seconds for animated canvases (clamped to the allowed range)" } }, "required": [ "companyId" ], "description": "Request body for updating a canvas design" } } }, "description": "Fields to update" } }, "delete": { "tags": [ "Content" ], "operationId": "content_deleteCanvasDesign", "parameters": [ { "name": "canvas_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Missing companyId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "description": "Success message" } }, "description": "Success response" } } } } }, "summary": "Delete a canvas design." } }, "/api/v0/content/canvases/{canvas_id}/render": { "post": { "tags": [ "Content" ], "operationId": "content_renderCanvasDesign", "parameters": [ { "name": "canvas_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Canvas has no design yet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials or out of credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The canvas could not be rendered \u2014 not charged", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Canvas with its rendered PNG url", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Canvas ID" }, "companyId": { "type": "string", "description": "Company ID" }, "name": { "type": "string", "description": "Canvas name" }, "width": { "type": "integer", "description": "Canvas width in pixels" }, "height": { "type": "integer", "description": "Canvas height in pixels" }, "format": { "type": "string", "description": "Named canvas format id, when the size came from one" }, "htmlContent": { "type": "string", "description": "The standalone HTML document for the canvas" }, "animated": { "type": "boolean", "description": "Whether the canvas is animated (exports a looping MP4 instead of a PNG)" }, "videoDuration": { "type": "number", "description": "Loop length in seconds for animated canvases" }, "imageId": { "type": "string", "description": "Images table id of the last render" }, "imageUrl": { "type": "string", "description": "Public PNG URL of the last render" }, "videoId": { "type": "string", "description": "Videos table id of the last recording (animated canvases)" }, "videoUrl": { "type": "string", "description": "Public MP4 URL of the last recording (animated canvases)" } }, "description": "Canvas design" } } } } }, "summary": "Render the canvas's saved HTML to a permanent public PNG (charged at DATA_CREDIT_COST_CANVAS)." } }, "/api/v0/content/canvases/{canvas_id}/render-video": { "post": { "tags": [ "Content" ], "operationId": "content_renderCanvasDesignVideo", "parameters": [ { "name": "canvas_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Canvas has no design yet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials or out of credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "202": { "description": "The queued (or already running) export job", "content": { "application/json": { "schema": { "type": "object", "properties": { "videoId": { "type": "string", "description": "Video id of the export" }, "status": { "type": "string", "description": "generating, completed or failed" }, "videoUrl": { "type": "string", "description": "Public MP4 URL once completed" }, "error": { "type": "string", "description": "Reason the export failed" } }, "description": "Canvas MP4 export job" } } } } }, "summary": "Start recording the canvas's saved HTML to a permanent public MP4 in the background.", "description": "Returns 202 with the export job; poll GET .../render-video until its status\nis completed (videoUrl) or failed (error). Charged at\nDATA_CREDIT_COST_CANVAS_VIDEO only when the recording succeeds. A second\nrequest while an export is running returns that job instead of a new one." } }, "/api/v0/content/canvases/{canvasId}/render-video": { "get": { "tags": [ "Content" ], "operationId": "content_getCanvasDesignVideoJob", "parameters": [ { "name": "canvasId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "The latest export job for the canvas (all fields null when none)", "content": { "application/json": { "schema": { "type": "object", "properties": { "videoId": { "type": "string", "description": "Video id of the export" }, "status": { "type": "string", "description": "generating, completed or failed" }, "videoUrl": { "type": "string", "description": "Public MP4 URL once completed" }, "error": { "type": "string", "description": "Reason the export failed" } }, "description": "Canvas MP4 export job" } } } } }, "summary": "Status of the canvas's latest MP4 export: generating, completed (videoUrl) or failed (error)." } }, "/api/v0/content/canvases/{canvasId}/html": { "put": { "tags": [ "Content" ], "operationId": "content_saveCanvasDesignHtml", "parameters": [ { "name": "canvasId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid timeline clips", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The canvas changed since it was loaded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Updated canvas design", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Canvas ID" }, "companyId": { "type": "string", "description": "Company ID" }, "name": { "type": "string", "description": "Canvas name" }, "width": { "type": "integer", "description": "Canvas width in pixels" }, "height": { "type": "integer", "description": "Canvas height in pixels" }, "format": { "type": "string", "description": "Named canvas format id, when the size came from one" }, "htmlContent": { "type": "string", "description": "The standalone HTML document for the canvas" }, "animated": { "type": "boolean", "description": "Whether the canvas is animated (exports a looping MP4 instead of a PNG)" }, "videoDuration": { "type": "number", "description": "Loop length in seconds for animated canvases" }, "imageId": { "type": "string", "description": "Images table id of the last render" }, "imageUrl": { "type": "string", "description": "Public PNG URL of the last render" }, "videoId": { "type": "string", "description": "Videos table id of the last recording (animated canvases)" }, "videoUrl": { "type": "string", "description": "Public MP4 URL of the last recording (animated canvases)" } }, "description": "Canvas design" } } } } }, "summary": "Save timeline edits to the canvas HTML, refusing to overwrite a newer version.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "htmlContent": { "type": "string", "description": "The complete canvas HTML document" }, "baseHtmlSha256": { "type": "string", "description": "SHA-256 of the HTML the edit was made on; a mismatch returns 409" } }, "required": [ "companyId", "htmlContent" ], "description": "Request body for saving edited canvas HTML" } } }, "description": "The edited canvas HTML" } } }, "/api/v0/content/canvases/{canvasId}/media": { "get": { "tags": [ "Content" ], "operationId": "content_listCanvasDesignMedia", "parameters": [ { "name": "canvasId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID" }, "description": "Company ID" }, { "name": "kind", "in": "query", "required": true, "schema": { "type": "string", "description": "video or audio" }, "description": "video or audio" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Page number (1-indexed)" }, "description": "Page number (1-indexed)" }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "description": "Items per page" }, "description": "Items per page" } ], "responses": { "400": { "description": "Invalid kind", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Paginated media usable on the timeline", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "description": "video or audio" }, "id": { "type": "string", "description": "Video or audio id" }, "url": { "type": "string", "description": "Permanent public URL to use as the clip src" }, "name": { "type": "string", "description": "File name" }, "duration": { "type": "number", "description": "Length in seconds" }, "status": { "type": "string", "description": "processing, ready or failed" }, "public": { "type": "boolean", "description": "False for a private video; placing it makes a public copy" }, "fileSize": { "type": "integer", "description": "Size in bytes, when known" }, "error": { "type": "string", "description": "Why processing failed" } }, "description": "An uploaded video or audio clip" } }, "total": { "type": "integer" }, "page": { "type": "integer" } }, "description": "Paginated timeline media" } } } } }, "summary": "List videos or audio for the canvas timeline's media bin (videos include the user's uploads still processing)." }, "post": { "tags": [ "Content" ], "operationId": "content_uploadCanvasDesignMedia", "parameters": [ { "name": "canvasId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Unsupported or unreadable file", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "File too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Audio: the stored clip (200). Video: a processing item (202) to poll", "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "description": "video or audio" }, "id": { "type": "string", "description": "Video or audio id" }, "url": { "type": "string", "description": "Permanent public URL to use as the clip src" }, "name": { "type": "string", "description": "File name" }, "duration": { "type": "number", "description": "Length in seconds" }, "status": { "type": "string", "description": "processing, ready or failed" }, "public": { "type": "boolean", "description": "False for a private video; placing it makes a public copy" }, "fileSize": { "type": "integer", "description": "Size in bytes, when known" }, "error": { "type": "string", "description": "Why processing failed" } }, "description": "An uploaded video or audio clip" } } } } }, "summary": "Upload a video or audio file for the canvas timeline. Videos are processed in the background." } }, "/api/v0/content/canvases/{canvasId}/media/{videoId}": { "get": { "tags": [ "Content" ], "operationId": "content_getCanvasDesignMedia", "parameters": [ { "name": "canvasId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "videoId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Missing companyId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "The video item with its processing status", "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "description": "video or audio" }, "id": { "type": "string", "description": "Video or audio id" }, "url": { "type": "string", "description": "Permanent public URL to use as the clip src" }, "name": { "type": "string", "description": "File name" }, "duration": { "type": "number", "description": "Length in seconds" }, "status": { "type": "string", "description": "processing, ready or failed" }, "public": { "type": "boolean", "description": "False for a private video; placing it makes a public copy" }, "fileSize": { "type": "integer", "description": "Size in bytes, when known" }, "error": { "type": "string", "description": "Why processing failed" } }, "description": "An uploaded video or audio clip" } } } } }, "summary": "Poll one timeline video (an upload's processing status)." } }, "/api/v0/content/canvases/{canvasId}/media/{videoId}/use": { "post": { "tags": [ "Content" ], "operationId": "content_useCanvasDesignMedia", "parameters": [ { "name": "canvasId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "videoId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Video not ready or unusable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "A public video to place on the timeline", "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "description": "video or audio" }, "id": { "type": "string", "description": "Video or audio id" }, "url": { "type": "string", "description": "Permanent public URL to use as the clip src" }, "name": { "type": "string", "description": "File name" }, "duration": { "type": "number", "description": "Length in seconds" }, "status": { "type": "string", "description": "processing, ready or failed" }, "public": { "type": "boolean", "description": "False for a private video; placing it makes a public copy" }, "fileSize": { "type": "integer", "description": "Size in bytes, when known" }, "error": { "type": "string", "description": "Why processing failed" } }, "description": "An uploaded video or audio clip" } } } } }, "summary": "Get a public video for the timeline: the video itself, or a public copy of a private one." } }, "/api/v0/content/canvases/{canvas_id}/chat": { "post": { "tags": [ "Content" ], "operationId": "content_canvasDesignChat", "parameters": [ { "name": "canvas_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Missing required fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Chat endpoint for the AI canvas builder.", "description": "Shares the app builder's agent loop and typed SSE protocol (text /\ntool_call / tool_result / files_changed / done / error). The thread is the\nsource of truth: history is loaded from the canvas's stored threads, the\nuser message is persisted immediately, and the assistant message (with its\ntool-call log) is persisted when the stream ends.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "message": { "type": "string", "description": "User message" }, "threadId": { "type": "string", "description": "Thread to continue (defaults to the active thread)" }, "clientMessageId": { "type": "string", "description": "Client-generated id for the user message" }, "attachments": { "type": "array", "items": { "type": "object" }, "description": "Image attachments (design references)" } }, "required": [ "companyId" ], "description": "Chat message for the canvas builder agent" } } }, "description": "Chat message" } } }, "/api/v0/content/canvases/{canvas_id}/threads": { "get": { "tags": [ "Content" ], "operationId": "content_listCanvasDesignThreads", "parameters": [ { "name": "canvas_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "List chat threads for a canvas ({threads, activeThreadId})." }, "post": { "tags": [ "Content" ], "operationId": "content_createCanvasDesignThread", "parameters": [ { "name": "canvas_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Missing required fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Create a new chat thread (becomes the active thread).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "title": { "type": "string", "description": "Thread title" } }, "required": [ "companyId" ], "description": "Request body for creating a chat thread" } } }, "description": "Thread to create" } } }, "/api/v0/content/canvases/{canvas_id}/threads/{thread_id}": { "get": { "tags": [ "Content" ], "operationId": "content_getCanvasDesignThread", "parameters": [ { "name": "thread_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "canvas_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Get one thread's messages." }, "patch": { "tags": [ "Content" ], "operationId": "content_updateCanvasDesignThread", "parameters": [ { "name": "thread_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "canvas_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Missing required fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Rename a thread (`title`) or make it active (`active: true`).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "title": { "type": "string", "description": "New thread title" }, "active": { "type": "boolean", "description": "Set true to make this the active thread" } }, "required": [ "companyId" ], "description": "Rename or activate a chat thread" } } }, "description": "Rename or activate a thread" } }, "delete": { "tags": [ "Content" ], "operationId": "content_deleteCanvasDesignThread", "parameters": [ { "name": "thread_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "canvas_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Delete a thread; returns the refreshed thread view." } }, "/api/v0/content/canvases/{canvas_id}/threads/{thread_id}/stop": { "post": { "tags": [ "Content" ], "operationId": "content_stopCanvasDesignThreadRun", "parameters": [ { "name": "thread_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "canvas_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Missing required fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Ask the thread's in-flight agent run to wrap up (same signal a new", "description": "message sends; the partial reply is already saved)." } }, "/api/v0/content/canvases/{canvas_id}/upload": { "post": { "tags": [ "Content" ], "operationId": "content_canvasDesignChatUpload", "parameters": [ { "name": "canvas_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid file", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Upload an image to attach as a design reference in the AI chat." } }, "/api/v0/content/strategies": { "get": { "tags": [ "Content" ], "operationId": "content_listContentStrategies", "parameters": [ { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID" }, "description": "Company ID" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Page number" }, "description": "Page number" }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "description": "Items per page" }, "description": "Items per page" } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "List of content strategies", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Strategy ID" }, "name": { "type": "string", "description": "Strategy name" }, "description": { "type": "string", "description": "Strategy description" }, "goals": { "type": "array", "items": { "type": "string" }, "description": "Strategy goals" }, "contentTypes": { "type": "array", "items": { "type": "string" }, "description": "Content types to create" }, "publishingFrequency": { "type": "string", "description": "Publishing frequency" }, "created": { "type": "number", "description": "Creation timestamp" } }, "description": "Content strategy object" }, "description": "List of strategies" }, "total": { "type": "integer", "description": "Total count" } }, "description": "List of strategies" } } } } }, "summary": "List all content strategies for a company." } }, "/api/v0/content/strategy/{strategyId}": { "get": { "tags": [ "Content" ], "operationId": "content_getSpecificContentStrategy", "parameters": [ { "name": "strategyId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Strategy not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Content strategy details", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Strategy ID" }, "name": { "type": "string", "description": "Strategy name" }, "description": { "type": "string", "description": "Strategy description" }, "goals": { "type": "array", "items": { "type": "string" }, "description": "Strategy goals" }, "contentTypes": { "type": "array", "items": { "type": "string" }, "description": "Content types to create" }, "publishingFrequency": { "type": "string", "description": "Publishing frequency" }, "created": { "type": "number", "description": "Creation timestamp" } }, "description": "Content strategy object" } } } } }, "summary": "Get a specific content strategy by ID." }, "delete": { "tags": [ "Content" ], "operationId": "content_deleteContentStrategy", "parameters": [ { "name": "strategyId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Strategy not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "description": "Success message" } }, "description": "Success response" } } } } }, "summary": "Delete a content strategy." } }, "/api/v0/content/strategy": { "get": { "tags": [ "Content" ], "operationId": "content_getContentStrategy", "parameters": [ { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID" }, "description": "Company ID" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Page number" }, "description": "Page number" }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "description": "Items per page" }, "description": "Items per page" } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Content strategy", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Strategy ID" }, "name": { "type": "string", "description": "Strategy name" }, "description": { "type": "string", "description": "Strategy description" }, "goals": { "type": "array", "items": { "type": "string" }, "description": "Strategy goals" }, "contentTypes": { "type": "array", "items": { "type": "string" }, "description": "Content types to create" }, "publishingFrequency": { "type": "string", "description": "Publishing frequency" }, "created": { "type": "number", "description": "Creation timestamp" } }, "description": "Content strategy object" } } } } }, "summary": "Get the default content strategy for a company." }, "post": { "tags": [ "Content" ], "operationId": "content_saveContentStrategy", "parameters": [], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Saved strategy", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Strategy ID" }, "name": { "type": "string", "description": "Strategy name" }, "description": { "type": "string", "description": "Strategy description" }, "goals": { "type": "array", "items": { "type": "string" }, "description": "Strategy goals" }, "contentTypes": { "type": "array", "items": { "type": "string" }, "description": "Content types to create" }, "publishingFrequency": { "type": "string", "description": "Publishing frequency" }, "created": { "type": "number", "description": "Creation timestamp" } }, "description": "Content strategy object" } } } } }, "summary": "Create or update a content strategy.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "strategy": { "type": "object", "description": "Content strategy data object with fields: id (optional for create), name (required), salesNarrative, targetAudience, pillars (array of content pillar objects with name, description, topics)" } }, "required": [ "companyId", "strategy" ], "description": "Request body for saving a strategy" } } }, "description": "Strategy data" } } }, "/api/v0/content/strategy/generate": { "post": { "tags": [ "Content" ], "operationId": "content_generateContentStrategyWithAi", "parameters": [], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Generated strategy", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Strategy ID" }, "name": { "type": "string", "description": "Strategy name" }, "description": { "type": "string", "description": "Strategy description" }, "goals": { "type": "array", "items": { "type": "string" }, "description": "Strategy goals" }, "contentTypes": { "type": "array", "items": { "type": "string" }, "description": "Content types to create" }, "publishingFrequency": { "type": "string", "description": "Publishing frequency" }, "created": { "type": "number", "description": "Creation timestamp" } }, "description": "Content strategy object" } } } } }, "summary": "Generate a content strategy using AI based on input data.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "data": { "type": "object", "description": "Input data for strategy generation: {companyName?: string, industry?: string, targetAudience?: string, goals?: string, brandVoiceId?: string, icpProfileId?: string}" } }, "required": [ "companyId" ], "description": "Request body for generating a strategy" } } }, "description": "Generation input data" } } }, "/api/v0/content/prompts": { "get": { "tags": [ "Content" ], "operationId": "content_listPrompts", "parameters": [ { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID" }, "description": "Company ID" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Page number" }, "description": "Page number" }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "description": "Items per page" }, "description": "Items per page" } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "List of prompts", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Prompt ID" }, "name": { "type": "string", "description": "Prompt name" }, "description": { "type": "string", "description": "Prompt description" }, "content": { "type": "string", "description": "Prompt content" }, "category": { "type": "string", "description": "Prompt category" }, "isPublic": { "type": "boolean", "description": "Whether prompt is public" }, "isShared": { "type": "boolean", "description": "Whether prompt is shared in company" }, "created": { "type": "number", "description": "Creation timestamp" } }, "description": "Prompt object" }, "description": "List of prompts" }, "total": { "type": "integer", "description": "Total count" } }, "description": "List of prompts" } } } } }, "summary": "List prompts visible to the user (own private + shared in company)." }, "post": { "tags": [ "Content" ], "operationId": "content_savePrompt", "parameters": [], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Created prompt ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Created/updated resource ID" }, "msg": { "type": "string", "description": "Success message" } }, "description": "Success response with ID" } } } } }, "summary": "Create or update a prompt.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "prompt": { "type": "object", "description": "Prompt data object with fields: id (optional for create), name (required), content (required, the prompt text), description, visibility (private, shared, public - default: private)" } }, "required": [ "companyId", "prompt" ], "description": "Request body for saving a prompt" } } }, "description": "Prompt data" } } }, "/api/v0/content/prompts/public": { "get": { "tags": [ "Content" ], "operationId": "content_listPublicPrompts", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Page number" }, "description": "Page number" }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "description": "Items per page" }, "description": "Items per page" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "description": "Search query" }, "description": "Search query" } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "List of public prompts", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Prompt ID" }, "name": { "type": "string", "description": "Prompt name" }, "description": { "type": "string", "description": "Prompt description" }, "content": { "type": "string", "description": "Prompt content" }, "category": { "type": "string", "description": "Prompt category" }, "isPublic": { "type": "boolean", "description": "Whether prompt is public" }, "isShared": { "type": "boolean", "description": "Whether prompt is shared in company" }, "created": { "type": "number", "description": "Creation timestamp" } }, "description": "Prompt object" }, "description": "List of prompts" }, "total": { "type": "integer", "description": "Total count" } }, "description": "List of prompts" } } } } }, "summary": "List all public prompts from any company." } }, "/api/v0/content/prompts/{promptId}": { "get": { "tags": [ "Content" ], "operationId": "content_getPrompt", "parameters": [ { "name": "promptId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Prompt not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Prompt details", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Prompt ID" }, "name": { "type": "string", "description": "Prompt name" }, "description": { "type": "string", "description": "Prompt description" }, "content": { "type": "string", "description": "Prompt content" }, "category": { "type": "string", "description": "Prompt category" }, "isPublic": { "type": "boolean", "description": "Whether prompt is public" }, "isShared": { "type": "boolean", "description": "Whether prompt is shared in company" }, "created": { "type": "number", "description": "Creation timestamp" } }, "description": "Prompt object" } } } } }, "summary": "Get a specific prompt by ID." }, "delete": { "tags": [ "Content" ], "operationId": "content_deletePrompt", "parameters": [ { "name": "promptId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Prompt not found or no permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "description": "Success message" } }, "description": "Success response" } } } } }, "summary": "Delete a prompt." } }, "/api/v0/content/prompts/{promptId}/clone": { "post": { "tags": [ "Content" ], "operationId": "content_clonePublicPrompt", "parameters": [ { "name": "promptId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Prompt not found or not public", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Cloned prompt ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Created/updated resource ID" }, "msg": { "type": "string", "description": "Success message" } }, "description": "Success response with ID" } } } } }, "summary": "Clone a public prompt to the user's company.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" } }, "required": [ "companyId" ], "description": "Request body for cloning a prompt" } } }, "description": "Clone request" } } }, "/api/v0/content/generate": { "post": { "tags": [ "Content" ], "operationId": "content_generateContent", "parameters": [], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Generated content", "content": { "application/json": { "schema": { "type": "object", "properties": { "subject": { "type": "string", "description": "Generated subject line (for emails)" }, "content": { "type": "string", "description": "Generated content" } }, "description": "AI content generation response" } } } } }, "summary": "Generate content using AI based on context and user instructions.", "description": "Supports email, sms, linkedin_message, and voice_message content types.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "instructions": { "type": "string", "description": "Instructions for content generation" }, "contentType": { "type": "string", "description": "Type of content: email, sms, linkedin_message, voice_message" }, "existingContent": { "type": "string", "description": "Existing content to improve/expand" }, "subject": { "type": "string", "description": "Subject line for emails" }, "context": { "type": "object", "description": "Additional context (sequenceName, sequenceGoal, etc.)" } }, "required": [ "companyId" ], "description": "Request body for AI content generation" } } }, "description": "Content generation request" } } }, "/api/v0/content/spintax": { "post": { "tags": [ "Content" ], "operationId": "content_generateSpintax", "parameters": [], "responses": { "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Generated spintax", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "description": "Content with spintax variations" }, "subject": { "type": "string", "description": "Subject with spintax variations (if provided)" }, "explanation": { "type": "string", "description": "Explanation of changes made" } }, "description": "Spintax generation response" } } } } }, "summary": "Convert text content to spintax format using AI.", "description": "Spintax allows for variation in messages using {{RANDOM | option1 | option2}} syntax.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "content": { "type": "string", "description": "Text content to convert to spintax" }, "subject": { "type": "string", "description": "Email subject to convert to spintax" }, "aggressive": { "type": "boolean", "description": "Add more variations (default: false)" } }, "required": [ "companyId" ], "description": "Request body for spintax generation" } } }, "description": "Spintax generation request" } } }, "/api/v0/content/ai-snippet": { "post": { "tags": [ "Content" ], "operationId": "content_generateAiSnippet", "parameters": [], "responses": { "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Generated snippet", "content": { "application/json": { "schema": { "type": "object", "properties": { "snippet": { "type": "string", "description": "Generated short text snippet" } }, "description": "AI snippet generation response" } } } } }, "summary": "Generate a short AI snippet based on a prompt with variable placeholders.", "description": "This endpoint is used at send time to generate small, personalized text snippets.\nThe AI has guardrails to keep responses short (1-2 sentences max).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "prompt": { "type": "string", "description": "Prompt with variables already replaced" }, "memberData": { "type": "object", "description": "Member data for additional context" } }, "required": [ "companyId", "prompt" ], "description": "Request body for AI snippet generation" } } }, "description": "AI snippet generation request" } } }, "/api/v0/content/spam-check": { "post": { "tags": [ "Content" ], "operationId": "content_checkSpam", "parameters": [], "responses": { "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Spam analysis results", "content": { "application/json": { "schema": { "type": "object", "properties": { "overallScore": { "type": "integer", "description": "Overall deliverability score (0-100)" }, "verdict": { "type": "string", "description": "Verdict (excellent, good, average, poor, spam)" }, "metrics": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Metric name" }, "score": { "type": "integer", "description": "Score from 0-10" }, "description": { "type": "string", "description": "Metric description" }, "issues": { "type": "array", "items": { "type": "string" }, "description": "Issues found" }, "suggestions": { "type": "array", "items": { "type": "string" }, "description": "Improvement suggestions" } }, "description": "Spam analysis metric" }, "description": "Detailed metrics" }, "spamWordsFound": { "type": "array", "items": { "type": "string" }, "description": "Spam trigger words found" }, "summary": { "type": "string", "description": "Analysis summary" }, "improvedSubject": { "type": "string", "description": "Improved subject line (if score < 70)" }, "improvedContent": { "type": "string", "description": "Improved content (if score < 70)" } }, "description": "Spam analysis response" } } } } }, "summary": "Analyze email content for spam triggers and deliverability issues.", "description": "Based on email deliverability best practices and spam filter guidelines,\nthis endpoint analyzes email subject and content for potential issues.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "subject": { "type": "string", "description": "Email subject line" }, "content": { "type": "string", "description": "Email body content (HTML or plain text)" } }, "required": [ "companyId", "content" ], "description": "Request body for spam analysis" } } }, "description": "Spam check request" } } }, "/api/v0/content/humanize": { "post": { "tags": [ "Content" ], "operationId": "content_humanizeText", "parameters": [], "responses": { "400": { "description": "Missing/invalid text or usage quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials or no company access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Humanized text with a summary of what changed", "content": { "application/json": { "schema": { "type": "object", "properties": { "humanizedText": { "type": "string", "description": "The rewritten text (or the original, unchanged, if the rewrite failed)" }, "rewritten": { "type": "boolean", "description": "True if the text was rewritten; false if the rewrite failed and the original was returned" }, "initialIssues": { "type": "integer", "description": "Number of AI-tell issues the automated checks found before rewriting" }, "remainingIssues": { "type": "integer", "description": "Number of issues left after rewriting" }, "invisibleRemoved": { "type": "integer", "description": "Count of invisible/homoglyph characters stripped from the input" } }, "description": "Humanized text and a summary of what changed" } } } } }, "summary": "Humanize AI-generated text so it reads naturally human-written.", "description": "Strips invisible/homoglyph characters, then runs the text through the\ncontent engine's AI-tell checks (AI-typical phrases, uniform sentence\nlength, em dashes, readability) and rewrites it against the returned\nguidance, preserving meaning, facts, formatting, and approximate length.\nOptional instructions (e.g. \"keep it casual\") take precedence over the\ndefault rules. Billed against the content-engine model quota.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "text": { "type": "string", "description": "The text to humanize, verbatim. Markdown is preserved. Up to 60000 characters." }, "instructions": { "type": "string", "description": "Optional style or special editing instructions passed verbatim to the editor (e.g. \"keep it casual\"). They take precedence over the default humanization rules." } }, "required": [ "companyId", "text" ], "description": "Request body for humanizing text" } } }, "description": "Text to humanize" } } }, "/api/v0/content/seo-autopilot/suggest-keywords": { "get": { "tags": [ "Content" ], "operationId": "content_suggestSeoAutopilotKeywords", "parameters": [], "responses": { "400": { "description": "companyId is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Suggest target keywords for a company's website.", "description": "Research-backed topics ranked by buyer relevance and attainability.\nInteractive clients use the asynchronous research endpoints below." } }, "/api/v0/content/seo-autopilot/integrations": { "get": { "tags": [ "Content" ], "operationId": "content_seoAutopilotIntegrations", "parameters": [ { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "name": { "type": "string" }, "instanceName": { "type": "string" } } } }, "total": { "type": "integer" } } } } } } }, "summary": "Page through visible CMS connections, including legacy category mappings." } }, "/api/v0/brand-kits": { "get": { "tags": [ "Brand Kit" ], "operationId": "brand_kit_listBrandKits", "parameters": [ { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID" }, "description": "Company ID" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Page number" }, "description": "Page number" }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "description": "Items per page" }, "description": "Items per page" } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "List of brand kits, or one resolved kit", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Brand kit ID" }, "name": { "type": "string", "description": "Brand kit name" }, "url": { "type": "string", "description": "Image URL" }, "stylePrompt": { "type": "string", "description": "Style prompt" }, "created": { "type": "number", "description": "Creation timestamp" } }, "description": "Brand kit object" }, "description": "List of brand kits" }, "total": { "type": "integer", "description": "Total count" } }, "description": "List of brand kits" } } } } }, "summary": "List a company's brand kits.", "description": "Default: a paginated list. With `?listAll=true`, returns the full list\n(default first). With `?landingPageId=` or `?brandKitId=`, resolves the\nsingle kit a landing page / website should use (page-specific \u2192 company\ndefault), for the landing-page / website renderers." }, "post": { "tags": [ "Brand Kit" ], "operationId": "brand_kit_saveBrandKit", "parameters": [], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Created brand kit ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Created/updated resource ID" }, "msg": { "type": "string", "description": "Success message" } }, "description": "Success response with ID" } } } } }, "summary": "Create or update a brand kit.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "brandKit": { "type": "object", "description": "Brand kit data object with fields: id (optional for create), name (required), description, images (array of {url, key, width, height, fileSize, mimeType, type}), imageModels (array of preferred AI image generation models), imageStylePrompt (canvas style prompt: brand colors, typography, layout, mood), imageCreationMode (how content images are produced: ai_image, canvas, or template for locked canvas templates filled from the content \u2014 see GET /api/v0/canvas/templates), canvasTemplates (template mode: array of template ids content images may use; null = all), canvasTools (array of imagery tools the canvas agent or the Photo Headline template may use: ai_images, stock_images; empty = typography only), templates (array of {id, url, name, description, width, height} for PNG overlay templates), and the landing-page/website assets: webArtifacts ({favicon, logo, images}), globalStyles (CSS), headScripts, brandGuidelines, landingPageId, isDefault" } }, "required": [ "companyId", "brandKit" ], "description": "Request body for saving a brand kit" } } }, "description": "Brand kit data" } }, "put": { "tags": [ "Brand Kit" ], "operationId": "brand_kit_saveBrandKitAssets", "parameters": [], "responses": { "400": { "description": "Missing required fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Updated brand kit", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Brand kit ID" }, "name": { "type": "string", "description": "Brand kit name" }, "favicon": { "type": "object", "description": "Favicon data" }, "logo": { "type": "object", "description": "Logo data" }, "images": { "type": "array", "items": { "type": "object" }, "description": "Custom images" }, "globalStyles": { "type": "string", "description": "Global CSS" }, "headScripts": { "type": "string", "description": "Head scripts" }, "brandGuidelines": { "type": "string", "description": "Brand guidelines" }, "colorPalette": { "type": "object", "description": "Brand colors by role as #RRGGBB" }, "isDefault": { "type": "boolean", "description": "Whether default kit" } }, "description": "Brand kit object" } } } } }, "summary": "Save a brand kit's landing-page / website assets (favicon, logo, images,", "description": "CSS, head scripts, guidelines), with automatic S3 upload for images.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "brandKitId": { "type": "string", "description": "Specific brand kit to update" }, "webArtifacts": { "type": "object", "description": "Brand kit asset data (favicon, logo, images)" }, "globalStyles": { "type": "string", "description": "Global CSS" }, "headScripts": { "type": "string", "description": "Scripts to inject into head" }, "brandGuidelines": { "type": "string", "description": "Brand guidelines" }, "colorPalette": { "type": "object", "description": "Brand colors by role (primary, secondary, accent, background, surface, text) as #RRGGBB" }, "name": { "type": "string", "description": "Name for this brand kit" }, "landingPageId": { "type": "string", "description": "Link to a landing page" }, "isDefault": { "type": "boolean", "description": "Whether this is the default kit" } }, "required": [ "companyId" ], "description": "Request body for saving a brand kit" } } }, "description": "Brand kit landing-page assets" } } }, "/api/v0/brand-kits/color-palettes": { "get": { "tags": [ "Brand Kit" ], "operationId": "brand_kit_listColorPalettes", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Page number (1-indexed)" }, "description": "Page number (1-indexed)" }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "description": "Items per page (max 100)" }, "description": "Items per page (max 100)" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "description": "Palette name, tag (e.g. pastel) or hex code" }, "description": "Palette name, tag (e.g. pastel) or hex code" } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "A page of the color palette library", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object" }, "description": "Palettes: {id, name, colors, roles, tags}" }, "total": { "type": "integer", "description": "Total matching palettes" } }, "description": "Color palettes: original swatches plus the brand kit roles each one fills" } } } } }, "summary": "List the color palette library offered in the brand kit color picker." } }, "/api/v0/brand-kits/{brandKitId}": { "get": { "tags": [ "Brand Kit" ], "operationId": "brand_kit_getBrandKit", "parameters": [ { "name": "brandKitId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID." }, "description": "Company ID." } ], "responses": { "400": { "description": "Invalid brand kit ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Brand kit not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Brand kit details", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Brand kit ID" }, "name": { "type": "string", "description": "Brand kit name" }, "url": { "type": "string", "description": "Image URL" }, "stylePrompt": { "type": "string", "description": "Style prompt" }, "created": { "type": "number", "description": "Creation timestamp" } }, "description": "Brand kit object" } } } } }, "summary": "Get a specific brand kit by ID." }, "delete": { "tags": [ "Brand Kit" ], "operationId": "brand_kit_deleteBrandKit", "parameters": [ { "name": "brandKitId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Brand kit not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "description": "Success message" } }, "description": "Success response" } } } } }, "summary": "Delete a brand kit." } }, "/api/v0/brand-kits/create": { "post": { "tags": [ "Brand Kit" ], "operationId": "brand_kit_createBrandKit", "parameters": [], "responses": { "400": { "description": "Missing companyId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Created brand kit", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Brand kit ID" }, "name": { "type": "string", "description": "Brand kit name" }, "favicon": { "type": "object", "description": "Favicon data" }, "logo": { "type": "object", "description": "Logo data" }, "images": { "type": "array", "items": { "type": "object" }, "description": "Custom images" }, "globalStyles": { "type": "string", "description": "Global CSS" }, "headScripts": { "type": "string", "description": "Head scripts" }, "brandGuidelines": { "type": "string", "description": "Brand guidelines" }, "colorPalette": { "type": "object", "description": "Brand colors by role as #RRGGBB" }, "isDefault": { "type": "boolean", "description": "Whether default kit" } }, "description": "Brand kit object" } } } } }, "summary": "Create a new (empty) brand kit for landing pages / websites.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "name": { "type": "string", "description": "Name for this brand kit" }, "landingPageId": { "type": "string", "description": "Link to a landing page" }, "isDefault": { "type": "boolean", "description": "Whether this is the default kit" } }, "required": [ "companyId" ], "description": "Request body for creating a brand kit" } } }, "description": "Brand kit details" } } }, "/api/v0/brand-kits/test": { "post": { "tags": [ "Brand Kit" ], "operationId": "brand_kit_testBrandKit", "parameters": [], "responses": { "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials or no company access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Content not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Usage limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Generated test images", "content": { "application/json": { "schema": { "type": "object", "properties": { "images": { "type": "array", "items": { "type": "object" }, "description": "Generated test images: {url, width, height, prompt}" } }, "description": "Generated test images" } } } } }, "summary": "Generate test images from a brand kit configuration", "description": "Runs the content-engine image pipeline (AI image or canvas agent, per the\nsupplied configuration) against sample text or an existing content piece\nand returns the generated image URLs without attaching them to any\ncontent. Charges the same credits as normal generation.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "brandKit": { "type": "object", "description": "Brand kit configuration to test \u2014 same shape as the save payload brandKit object; does not need to be saved first" }, "contentId": { "type": "string", "description": "Existing content ID to test with (its title, body, and type are used; overrides title/text/contentType)" }, "title": { "type": "string", "description": "Sample content title" }, "text": { "type": "string", "description": "Sample content body text" }, "contentType": { "type": "string", "description": "Content type used for image sizing (default blog_post)" } }, "required": [ "companyId", "brandKit" ], "description": "Request body for testing a brand kit configuration" } } }, "description": "Brand kit test request" } } }, "/api/v0/brand-kits/build": { "post": { "tags": [ "Brand Kit" ], "operationId": "brand_kit_buildBrandKitRoute", "parameters": [], "responses": { "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Company not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Usage limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Draft brand kit created; poll it for buildStatus", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Created/updated resource ID" }, "msg": { "type": "string", "description": "Success message" } }, "description": "Success response with ID" } } } } }, "summary": "Build a full brand kit (name, description, style, logos) from a website or an uploaded image.", "description": "An agent screenshots and reads the source itself to assemble the whole brand\nkit. The work runs in the background: this creates a draft brand kit row\nwith buildStatus 'building' and returns its id. Poll GET\n/brand-kits/<id> \u2014 buildStatus flips to 'ready' (fields filled) or\n'failed' (buildError set). Provide exactly one of websiteUrl / imageDataUri.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "websiteUrl": { "type": "string", "description": "Website URL to build the brand from (defaults to the company website when neither websiteUrl nor imageDataUri is given)" }, "imageDataUri": { "type": "string", "description": "An uploaded image as a data: URI, to build the brand from instead of a website. Provide exactly one of websiteUrl or imageDataUri." } }, "required": [ "companyId" ], "description": "Request body for building a full brand kit (name, description, style, logos) from a website or an uploaded image" } } }, "description": "Build a full brand kit from a website or an uploaded image" } } }, "/api/v0/brand-kits/upload": { "post": { "tags": [ "Brand Kit" ], "operationId": "brand_kit_uploadBrandKitImage", "parameters": [], "responses": { "400": { "description": "Missing required fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Uploaded image metadata with URL", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "S3 URL of uploaded image" }, "type": { "type": "string", "description": "Image type" }, "fileName": { "type": "string", "description": "File name" } }, "description": "Uploaded brand kit image metadata" } } } } }, "summary": "Upload a single brand kit image (favicon/logo/custom) via multipart form data." } }, "/api/v0/voices": { "get": { "tags": [ "Voices" ], "operationId": "voices_listVoices", "parameters": [ { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID." }, "description": "Company ID." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Page number (default: 1)" }, "description": "Page number (default: 1)" }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "description": "Items per page (default: 100)" }, "description": "Items per page (default: 100)" }, { "name": "includePublic", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Include public voices (default: false)" }, "description": "Include public voices (default: false)" } ], "responses": { "400": { "description": "companyId required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "List of voices", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Voice ID" }, "voiceId": { "type": "string", "description": "External voice ID (e.g., ElevenLabs voice ID)" }, "name": { "type": "string", "description": "Voice name" }, "description": { "type": "string", "description": "Voice description" }, "category": { "type": "string", "description": "Voice category (e.g., cloned, premade)" }, "language": { "type": "string", "description": "Voice language" }, "isPublic": { "type": "boolean", "description": "Whether voice is public" }, "created": { "type": "number", "description": "Creation timestamp" } }, "description": "Voice object" }, "description": "List of voices" }, "total": { "type": "integer", "description": "Total count" }, "page": { "type": "integer", "description": "Current page" }, "pageSize": { "type": "integer", "description": "Items per page" } }, "description": "List of voices" } } } } }, "summary": "List all voices available to the user (company-specific by default)", "description": "Query params:\n- companyId: Company ID (optional if includePublic=true)\n- page: Page number (default: 1)\n- pageSize: Page size (default: 100)\n- includePublic: Whether to include public voices (default: False)" }, "post": { "tags": [ "Voices" ], "operationId": "voices_createVoice", "parameters": [], "responses": { "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not available or access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Voice created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Created voice ID" }, "voice_id": { "type": "string", "description": "ElevenLabs voice ID" }, "message": { "type": "string", "description": "Success message" } }, "description": "Voice creation response" } } } } }, "summary": "Create a custom voice using ElevenLabs Voice Cloning (IVC) API", "description": "Request body (multipart/form-data):\n- companyId: Company ID (required)\n- name: Voice name (required)\n- description: Voice description (optional)\n- files: Audio files for voice cloning (required, one or more)\n- remove_background_noise: Whether to remove background noise (optional, default: true)\n\nElevenLabs API Reference:\nhttps://elevenlabs.io/docs/api-reference/voices/ivc/create" } }, "/api/v0/voices/{voice_id}": { "get": { "tags": [ "Voices" ], "operationId": "voices_getVoice", "parameters": [ { "name": "voice_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID" }, "description": "Company ID" } ], "responses": { "400": { "description": "companyId required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Voice not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Voice details", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Voice ID" }, "voiceId": { "type": "string", "description": "External voice ID (e.g., ElevenLabs voice ID)" }, "name": { "type": "string", "description": "Voice name" }, "description": { "type": "string", "description": "Voice description" }, "category": { "type": "string", "description": "Voice category (e.g., cloned, premade)" }, "language": { "type": "string", "description": "Voice language" }, "isPublic": { "type": "boolean", "description": "Whether voice is public" }, "created": { "type": "number", "description": "Creation timestamp" } }, "description": "Voice object" } } } } }, "summary": "Get a specific voice by ID" }, "put": { "tags": [ "Voices" ], "operationId": "voices_updateVoice", "parameters": [ { "name": "voice_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "companyId required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not available or access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Voice updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message" } }, "description": "Success response" } } } } }, "summary": "Update a custom voice", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "name": { "type": "string", "description": "Voice name" }, "description": { "type": "string", "description": "Voice description" } }, "required": [ "companyId" ], "description": "Request body for updating a voice" } } }, "description": "Voice update data" } }, "delete": { "tags": [ "Voices" ], "operationId": "voices_deleteVoice", "parameters": [ { "name": "voice_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID" }, "description": "Company ID" } ], "responses": { "400": { "description": "companyId required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Voice not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Voice deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message" } }, "description": "Success response" } } } } }, "summary": "Delete a custom voice (soft delete)" } }, "/api/v0/voices/{voice_id}/test": { "post": { "tags": [ "Voices" ], "operationId": "voices_testVoice", "parameters": [ { "name": "voice_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Voice not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Test a voice by generating audio from text", "description": "Request body:\n- companyId: Company ID (required)\n- text: Text to convert to speech (required)\n- ttsModel: ElevenLabs model to synthesize with (optional)\n\nReturns audio/mpeg binary data.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "text": { "type": "string", "description": "Text to convert to speech" }, "ttsModel": { "type": "string", "description": "ElevenLabs TTS model (default: eleven_flash_v2_5)" } }, "required": [ "companyId", "text" ], "description": "Request body for testing a voice" } } }, "description": "Voice test parameters" } } }, "/api/v0/voices/elevenlabs/library": { "get": { "tags": [ "Voices" ], "operationId": "voices_getElevenlabsLibrary", "parameters": [ { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID" }, "description": "Company ID" } ], "responses": { "400": { "description": "companyId required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not available or access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "ElevenLabs voice library", "content": { "application/json": { "schema": { "type": "object", "properties": { "voices": { "type": "array", "items": { "type": "object", "properties": { "voice_id": { "type": "string", "description": "ElevenLabs voice ID" }, "name": { "type": "string", "description": "Voice name" }, "description": { "type": "string", "description": "Voice description" }, "category": { "type": "string", "description": "Voice category" }, "labels": { "type": "object", "description": "Voice labels/tags" }, "preview_url": { "type": "string", "description": "Preview audio URL" } }, "description": "ElevenLabs voice object" }, "description": "List of ElevenLabs voices" }, "total": { "type": "integer", "description": "Total count" } }, "description": "ElevenLabs voice library" } } } } }, "summary": "Fetch the full ElevenLabs voice library", "description": "This endpoint fetches voices from ElevenLabs API and caches them" } }, "/api/v0/leads/enrich": { "post": { "tags": [ "Leads" ], "operationId": "leads_enrichContact", "parameters": [], "responses": { "400": { "description": "No person identifier provided or companyId missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials or no company access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient data credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Enrichment unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Matching enrichment records ({results: [], count: 0} on no match \u2014 not an error)", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object" }, "description": "Matching person/company enrichment records." }, "count": { "type": "integer", "description": "Number of matches (0 = no match, not an error)" } }, "description": "Matching person/company enrichment records" } } } } }, "summary": "Enrich a known person: emails, job title, employer and company data", "description": "Requires a person identifier: firstName/lastName, email, phone, or\nlinkedinUrl. Add company or companyDomain to disambiguate a name. A\ncompany on its own is rejected with 400 \u2014 to find people at a company, use\nleads_searchPeopleDatabase with the companyDomain or company filter.\nPhone numbers are not returned; use leads_enrichPhone. A no-match returns\n{results: [], count: 0}, not an error, and is free. Costs 1 data credit per\nreturned contact.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID for access and any applicable data-credit charges" }, "firstName": { "type": "string", "description": "First name" }, "lastName": { "type": "string", "description": "Last name" }, "email": { "type": "string", "description": "Email address" }, "emailDomain": { "type": "string", "description": "Email domain (e.g., company.com)" }, "phone": { "type": "string", "description": "Phone number" }, "company": { "type": "string", "description": "Company name" }, "companyDomain": { "type": "string", "description": "Company domain name" }, "linkedinUrl": { "type": "string", "description": "LinkedIn profile URL" }, "personalCity": { "type": "string", "description": "Personal city" }, "personalState": { "type": "string", "description": "Personal state/province" } }, "required": [ "companyId" ], "description": "Identifiers for the person to enrich. Include at least one of firstName/lastName, email, phone or linkedinUrl; company fields only narrow a name match." } } } } } }, "/api/v0/leads/enrich-phone": { "post": { "tags": [ "Leads" ], "operationId": "leads_enrichPhone", "parameters": [], "responses": { "400": { "description": "No person identifier provided or companyId missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials or no company access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient data credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Phone enrichment unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Phone numbers and contact identifiers only. No match returns empty results and is free.", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object" }, "description": "Matching person/company enrichment records." }, "count": { "type": "integer", "description": "Number of matches (0 = no match, not an error)" } }, "description": "Matching person/company enrichment records" } } } } }, "summary": "Find a known person's phone numbers.", "description": "Accepts the same identifiers as leads_enrichContact and likewise requires a\nperson identifier (firstName/lastName, email, phone, or linkedinUrl); a\nlinkedinUrl gives the best match rate. Returns phone numbers and profile\nidentifiers only. Costs 2 data credits per returned phone record; no match\nis free.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID for access and any applicable data-credit charges" }, "firstName": { "type": "string", "description": "First name" }, "lastName": { "type": "string", "description": "Last name" }, "email": { "type": "string", "description": "Email address" }, "emailDomain": { "type": "string", "description": "Email domain (e.g., company.com)" }, "phone": { "type": "string", "description": "Phone number" }, "company": { "type": "string", "description": "Company name" }, "companyDomain": { "type": "string", "description": "Company domain name" }, "linkedinUrl": { "type": "string", "description": "LinkedIn profile URL" }, "personalCity": { "type": "string", "description": "Personal city" }, "personalState": { "type": "string", "description": "Personal state/province" } }, "required": [ "companyId" ], "description": "Phone-only enrichment using any supported contact identifiers" } } } } } }, "/api/v0/leads/field-options": { "get": { "tags": [ "Leads" ], "operationId": "leads_listFieldOptions", "parameters": [ { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID for access and any applicable data-credit charges" }, "description": "Company ID for access and any applicable data-credit charges" }, { "name": "describe", "in": "query", "required": false, "schema": { "type": "boolean", "description": "true = filter schema map (all fields + types). Compact unless field/group is set. Recommended first call." }, "description": "true = filter schema map (all fields + types). Compact unless field/group is set. Recommended first call." }, { "name": "group", "in": "query", "required": false, "schema": { "type": "string", "description": "With describe: scope to one group (location/person/company/funding) and inline its enum options." }, "description": "With describe: scope to one group (location/person/company/funding) and inline its enum options." }, { "name": "field", "in": "query", "required": false, "schema": { "type": "string", "description": "One field. With describe: inline that field's options. Without describe: that enumerated field's values (omit for all)." }, "description": "One field. With describe: inline that field's options. Without describe: that enumerated field's values (omit for all)." } ], "responses": { "400": { "description": "Unknown field or group", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Filter schema map (with describe) or enum option values", "content": { "application/json": { "schema": { "type": "object", "properties": { "fields": { "type": "object", "description": "Field name -> schema entry (with describe) or field name -> option values (without)." } }, "description": "Field name -> schema entry (with describe) or field name -> option values (without)" } } } } }, "summary": "Describe the people-search filters and list valid enum values", "description": "Call this before building filters for leads_searchPeopleDatabase,\nleads_importPeopleDatabaseResults or leads_exportPeopleDatabaseResults.\ndescribe=true returns the schema map \u2014 every filter field, its type\n(enum/text/number/boolean), its group (person/company/funding/location)\nand whether it can be a positive criterion. Enum option lists are inlined\nonly when scoped with field= or group=, so call describe=true first, then\nfetch options per group. Enum filters reject any value not in these lists.\nFree \u2014 no data credits charged." } }, "/api/v0/leads/people-search": { "post": { "tags": [ "Leads" ], "operationId": "leads_searchPeopleDatabase", "parameters": [], "responses": { "400": { "description": "Invalid filters, pagination or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No company access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Data-credit window capacity or at least 1 lead data credit required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Search or AI search unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Paginated people database matches", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object" }, "description": "Matching people: name, title, company, location, linkedinUrl and other profile fields, as text. No emails or phones. Pass items back unchanged as rows to import or export them." }, "total": { "type": "integer", "description": "Total people matching the filters" }, "page": { "type": "integer" }, "pageSize": { "type": "integer" }, "creditCost": { "type": "integer", "description": "Always zero; people search is free. Importing costs one data credit per record and enriches emails." }, "nextCursor": { "type": "string", "description": "Continuation cursor; null means the end of the results" }, "filters": { "type": "object", "description": "The normalized filters that were searched. For an AI search, these are the filters it chose; send them with nextCursor for later pages." } } } } } } }, "summary": "Search the professional people database by filters or a plain-language description.", "description": "Send either `query` (AI search, below) or `filters`. For filters, get\nfield names and enum values from leads_listFieldOptions first; at least\none positive filter is required (exclusions alone are rejected).\nReturns basic profiles (name, title, company, location, linkedinUrl) plus\nthe total match count \u2014 no emails or phones. To page, send the same\nfilters, companyId and pageSize with page+1 and the previous nextCursor;\nnextCursor null means the last page. Free: searching requires at least 1\ndata credit or remaining data-credit window capacity but never spends it.\nTo get contact details, import the results into a smart list or export\nthem.\n\nAI search: send `query` (a description such as \"engineers in New York at\nsoftware companies with more than 500 employees\") instead of filters \u2014 no\nleads_listFieldOptions call needed. AI picks the filters (using AI\ncredits), the search runs, and the response's `filters` shows what was\nsearched \u2014 page on with those filters and nextCursor.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID for access and any applicable data-credit charges" }, "filters": { "type": "object", "description": "Person and company filters keyed by the camelCase field names from leads_listFieldOptions, e.g. {\"title\": [\"Head of Marketing\"], \"seniority\": [\"Director\"], \"companyDomain\": [\"acme.com\"], \"employeeRange\": [\"51-200\"], \"country\": [\"US\"]}. Text and enum filters take a list of values (any value matches); different filters must all match. Enum values must come from leads_listFieldOptions; countries are two-letter codes. Number filters take a single number. At least one positive (non-exclude) filter is required. Send filters or query, not both." }, "query": { "type": "string", "description": "AI search: a plain-language description of the people to find, e.g. \"engineers in New York at software companies with more than 500 employees\". Turned into filters by AI (uses AI credits), then searched. Page 1 only; the response returns the filters used, so request later pages with those filters and nextCursor." }, "page": { "type": "integer", "description": "1-based page number. Page 1 needs no cursor; later pages need the previous response's nextCursor.", "default": 1 }, "pageSize": { "type": "integer", "description": "Results per page: 5, 10, 25, 50. Default: 25.", "default": 25 }, "cursor": { "type": "string", "description": "nextCursor from the previous response. Required for page > 1; keep filters, companyId and pageSize unchanged." } }, "required": [ "companyId" ] } } } } } }, "/api/v0/leads/people-search/lists/{listId}/import": { "post": { "tags": [ "Leads" ], "operationId": "leads_importPeopleDatabaseResults", "parameters": [ { "name": "listId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid rows, filters, count or importId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No company access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient data credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Destination list not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "importId reused with different options", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "202": { "description": "Queued import; poll lists_getTaskStatus with taskId", "content": { "application/json": { "schema": { "type": "object", "properties": { "taskId": { "type": "string", "description": "Background task id. Poll lists_getTaskStatus with it until status is completed, failed or cancelled." }, "listId": { "type": "string", "description": "The destination smart list (null for an export)." }, "status": { "type": "string", "description": "Always \"background\" \u2014 the job runs asynchronously." }, "message": { "type": "string", "description": "Human-readable status message" } }, "description": "The queued background people job" } } } } }, "summary": "Import people-search results into an existing smart list.", "description": "Send either rows (1\u201350 results from leads_searchPeopleDatabase, passed\nback unchanged) or filters plus count (or importAll=true) to import a\nfiltered search of up to 50,000 people. Runs in the background and returns\na taskId: poll lists_getTaskStatus until status is completed, failed or\ncancelled. A pending task with taskMetadata.waitReason is waiting for data\ncredits or the provider and resumes on its own. People already in the list\nwith the same LinkedIn URL or email are updated, not duplicated.\nincludeEmail (default true) costs 1 data credit per imported person;\nincludePhone (default false) costs 2 per phone found. Pass a fresh UUID as\nimportId and reuse it on retries so a retry returns the same task.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "includeEmail": { "type": "boolean", "description": "Enrich email for 1 data credit per person.", "default": true }, "includePhone": { "type": "boolean", "description": "Enrich mobile/direct phone for 2 data credits per returned number.", "default": false }, "companyId": { "type": "string", "description": "Company ID for access and any applicable data-credit charges" }, "rows": { "type": "array", "items": { "type": "object" }, "description": "Select 1\u201350 search results. Each needs linkedinUrl or email. Profile values must be text of at most 5000 characters (250000 for structured fields and long descriptions). Structured fields such as workHistory and educationHistory contain JSON in their own columns. Supported fields: workHistory, educationHistory, skills, certifications, locationDetails, companyLocationDetails, companyNaicsCodes, companyNaicsTitles, companyLinkedinIndustries, allEmails, nickname, salutation, profileUpdatedAt, companyEmployeeCount, externalId, displayName, firstName, lastName, email, businessEmail, personalEmail, phoneNumber, linkedinUrl, headline, location, positionTitle, positionLocation, seniority, department, companyName, companyWebsite, companyLinkedinUrl, companyEmployeeRange, companyIndustry, companyAnnualRevenue, businessEmailRiskScore, businessEmailValidatedAt, numOfConnections, about, photoUrl, companyDescription, companyFoundedOn, companyNumberOfFollowers, companyEmployeesOnLinkedin, companyLocation, summary, positionDescription, companyHeadquarters, companyCountry, companyType, companyKeywords, companyLogoUrl." }, "filters": { "type": "object", "description": "Search filters, same shape as leads_searchPeopleDatabase. Required when rows are omitted." }, "count": { "type": "integer", "description": "With filters: how many people to process, from 1 to 50000, starting at the first result. Required unless importAll is true." }, "importAll": { "type": "boolean", "description": "With filters: process every match, capped at 50000." }, "audienceName": { "type": "string", "description": "Optional label for the job." }, "importId": { "type": "string", "description": "Optional UUID identifying this job. Reuse it to retrieve the same job when retrying an unchanged request." } }, "required": [ "companyId" ] } } } } } }, "/api/v0/leads/people-search/export": { "post": { "tags": [ "Leads" ], "operationId": "leads_exportPeopleDatabaseResults", "parameters": [], "responses": { "400": { "description": "Invalid rows, filters, count or importId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No company access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient data credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "importId reused with different options", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "202": { "description": "Queued export; poll lists_getTaskStatus for result.downloadUrl", "content": { "application/json": { "schema": { "type": "object", "properties": { "taskId": { "type": "string", "description": "Background task id. Poll lists_getTaskStatus with it until status is completed, failed or cancelled." }, "listId": { "type": "string", "description": "The destination smart list (null for an export)." }, "status": { "type": "string", "description": "Always \"background\" \u2014 the job runs asynchronously." }, "message": { "type": "string", "description": "Human-readable status message" } }, "description": "The queued background people job" } } } } }, "summary": "Export people-search results to a CSV file.", "description": "Takes the same rows or filters/count, includeEmail/includePhone and\nimportId options as leads_importPeopleDatabaseResults, at the same data\ncredit cost, but writes a CSV instead of a smart list. Returns a taskId:\npoll lists_getTaskStatus until status is completed, then read\nresult.downloadUrl (valid for 24 hours). The link is also emailed to the\ncaller.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "includeEmail": { "type": "boolean", "description": "Enrich email for 1 data credit per person.", "default": true }, "includePhone": { "type": "boolean", "description": "Enrich mobile/direct phone for 2 data credits per returned number.", "default": false }, "companyId": { "type": "string", "description": "Company ID for access and any applicable data-credit charges" }, "rows": { "type": "array", "items": { "type": "object" }, "description": "Selected results, up to 50. Omit to export a filtered search." }, "filters": { "type": "object", "description": "Search filters; required when rows are omitted." }, "count": { "type": "integer", "description": "Maximum people to export, from 1 to 50000." }, "importAll": { "type": "boolean", "description": "Export matching results, capped at 50000." }, "audienceName": { "type": "string", "description": "Optional label for the job." }, "importId": { "type": "string", "description": "Optional UUID identifying this job. Reuse it to retrieve the same job when retrying an unchanged request." } }, "required": [ "companyId" ] } } } } } }, "/api/v0/leads/lists/{listId}/rows/{rowId}/found-leads": { "get": { "tags": [ "Leads" ], "operationId": "leads_getStagedLeads", "parameters": [ { "name": "listId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "rowId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID for access and any applicable data-credit charges" }, "description": "Company ID for access and any applicable data-credit charges" }, { "name": "headerId", "in": "query", "required": true, "schema": { "type": "string", "description": "The \"Find Leads at Company\" action column id (from the list's headers)." }, "description": "The \"Find Leads at Company\" action column id (from the list's headers)." } ], "responses": { "400": { "description": "companyId or headerId missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No company access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "List or row not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "The company searched and the leads found for this row", "content": { "application/json": { "schema": { "type": "object", "properties": { "company": { "type": "string", "description": "The company domain or name that was searched" }, "leads": { "type": "array", "items": { "type": "object" }, "description": "People found at the company. Empty when nothing is waiting for review." } } } } } } }, "summary": "Read the leads a \"Find Leads at Company\" action found for one row.", "description": "headerId is the find-leads action's column id. The action keeps every match\non that row's cell for review \u2014 when the action is set to neither enrich the\nrow nor add leads to a list, review is the only way they are used. Returns\n{company, leads}; leads is empty when nothing is waiting. Pass chosen leads\nto leads_applyStagedLeads unchanged." } }, "/api/v0/leads/lists/{listId}/rows/{rowId}/found-leads/apply": { "post": { "tags": [ "Leads" ], "operationId": "leads_applyStagedLeads", "parameters": [ { "name": "listId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "rowId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "companyId/headerId missing or no leads selected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No company access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "List, row or target list not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "How many leads enriched the row and were added as rows", "content": { "application/json": { "schema": { "type": "object", "properties": { "enriched": { "type": "integer", "description": "1 when enrichLead was written over the row" }, "appended": { "type": "integer", "description": "Rows added from appendLeads" } } } } } } }, "summary": "Apply leads found by \"Find Leads at Company\" for one row.", "description": "enrichLead (one lead from leads_getStagedLeads) is written over the source\nrow; appendLeads are added as new rows to targetListId (default: this\nlist), creating missing columns. Send at least one of them. Clears the\nfound leads from the cell. Records 1 data credit of usage per lead used;\nthe lookup itself was already charged when the action ran.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID for access and any applicable data-credit charges" }, "headerId": { "type": "string", "description": "The \"Find Leads at Company\" action column id." }, "enrichLead": { "type": "object", "description": "One lead from leads_getStagedLeads to write over this row." }, "appendLeads": { "type": "array", "items": { "type": "object" }, "description": "Leads from leads_getStagedLeads to add as new rows." }, "targetListId": { "type": "string", "description": "Smart list for appendLeads. Defaults to this list." } }, "required": [ "companyId", "headerId" ] } } } } } }, "/api/v0/web/search": { "get": { "tags": [ "Web" ], "operationId": "web_searchWeb", "parameters": [ { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID whose data credits are billed for the call" }, "description": "Company ID whose data credits are billed for the call" }, { "name": "query", "in": "query", "required": true, "schema": { "type": "string", "description": "Search query, as you would type it into a search engine" }, "description": "Search query, as you would type it into a search engine" }, { "name": "maxResults", "in": "query", "required": false, "schema": { "type": "integer", "description": "Maximum results to return, 1-100 (default 10)" }, "description": "Maximum results to return, 1-100 (default 10)" } ], "responses": { "400": { "description": "Missing/invalid parameters or companyId missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials, no company access, or out of credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream web data request failed \u2014 not charged", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Matching results, best first", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "description": "Result title" }, "url": { "type": "string", "description": "Result URL \u2014 pass to the scrape endpoint to read the page in full" }, "description": { "type": "string", "description": "Result snippet (empty for news results)" }, "date": { "type": "string", "description": "Result date, or 'N/A'" }, "source": { "type": "string", "description": "Publisher name (news results only)" }, "thumbnail": { "type": "string", "description": "Thumbnail image URL (news results only)" } }, "description": "Search result" }, "description": "Matching results, best first" }, "count": { "type": "integer", "description": "Number of results returned" } }, "description": "Search results" } } } } }, "summary": "Search the web", "description": "Returns titles, URLs, snippets, and dates for the best-matching pages.\nPass a result URL to the scrape endpoint to read the page in full.\nCosts 1 data credit per call." } }, "/api/v0/web/news": { "get": { "tags": [ "Web" ], "operationId": "web_searchNews", "parameters": [ { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID whose data credits are billed for the call" }, "description": "Company ID whose data credits are billed for the call" }, { "name": "query", "in": "query", "required": true, "schema": { "type": "string", "description": "News search query" }, "description": "News search query" }, { "name": "freshness", "in": "query", "required": false, "schema": { "type": "string", "description": "Recency window: pd = past day, pw = past week, pm = past month, py = past year. Omit for the default ranking." }, "description": "Recency window: pd = past day, pw = past week, pm = past month, py = past year. Omit for the default ranking." }, { "name": "maxResults", "in": "query", "required": false, "schema": { "type": "integer", "description": "Maximum results to return, 1-100 (default 10)" }, "description": "Maximum results to return, 1-100 (default 10)" } ], "responses": { "400": { "description": "Missing/invalid parameters or companyId missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials, no company access, or out of credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream web data request failed \u2014 not charged", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Matching news results inside the freshness window, newest first", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "description": "Result title" }, "url": { "type": "string", "description": "Result URL \u2014 pass to the scrape endpoint to read the page in full" }, "description": { "type": "string", "description": "Result snippet (empty for news results)" }, "date": { "type": "string", "description": "Result date, or 'N/A'" }, "source": { "type": "string", "description": "Publisher name (news results only)" }, "thumbnail": { "type": "string", "description": "Thumbnail image URL (news results only)" } }, "description": "Search result" }, "description": "Matching results, best first" }, "count": { "type": "integer", "description": "Number of results returned" } }, "description": "Search results" } } } } }, "summary": "Search recent news", "description": "Returns titles, URLs, publishers, and dates for matching news coverage.\nNarrow the window with freshness (pd = past day, pw = past week, pm =\npast month, py = past year). Costs 1 data credit per call." } }, "/api/v0/web/scrape": { "get": { "tags": [ "Web" ], "operationId": "web_scrapePage", "parameters": [ { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID whose data credits are billed for the call" }, "description": "Company ID whose data credits are billed for the call" }, { "name": "url", "in": "query", "required": true, "schema": { "type": "string", "description": "Full http(s) URL of the page to read. JavaScript-rendered pages and hard-to-scrape sites (including LinkedIn) are handled automatically." }, "description": "Full http(s) URL of the page to read. JavaScript-rendered pages and hard-to-scrape sites (including LinkedIn) are handled automatically." }, { "name": "responseType", "in": "query", "required": false, "schema": { "type": "string", "description": "'markdown' (default, recommended for reading) or 'html' for the raw page source" }, "description": "'markdown' (default, recommended for reading) or 'html' for the raw page source" } ], "responses": { "400": { "description": "Missing/invalid parameters or companyId missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials, no company access, or out of credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The page could not be read \u2014 not charged", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Page content as markdown or raw HTML", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "The URL that was read" }, "responseType": { "type": "string", "description": "'markdown' or 'html'" }, "content": { "type": "string", "description": "Page content as markdown (links preserved as absolute URLs) or raw HTML" } }, "description": "Page content" } } } } }, "summary": "Read a web page", "description": "Fetches the page and returns it as clean markdown (default) or raw HTML\nvia responseType. JavaScript-rendered pages and hard-to-scrape sites,\nincluding LinkedIn, are handled automatically. Costs 1 data credit per\ncall." } }, "/api/v0/web/jobs": { "get": { "tags": [ "Web" ], "operationId": "web_searchJobs", "parameters": [ { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID whose data credits are billed for the call" }, "description": "Company ID whose data credits are billed for the call" }, { "name": "query", "in": "query", "required": true, "schema": { "type": "string", "description": "Job search query, e.g. 'software engineer in New York'" }, "description": "Job search query, e.g. 'software engineer in New York'" }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string", "description": "Two-letter country code (default 'us')" }, "description": "Two-letter country code (default 'us')" }, { "name": "language", "in": "query", "required": false, "schema": { "type": "string", "description": "Results language (default 'en_us')" }, "description": "Results language (default 'en_us')" }, { "name": "nextPageToken", "in": "query", "required": false, "schema": { "type": "string", "description": "Pagination token from a previous response" }, "description": "Pagination token from a previous response" }, { "name": "chips", "in": "query", "required": false, "schema": { "type": "string", "description": "Filter chips string from a previous response (e.g. date_posted:today)" }, "description": "Filter chips string from a previous response (e.g. date_posted:today)" }, { "name": "lrad", "in": "query", "required": false, "schema": { "type": "string", "description": "Search radius in kilometers" }, "description": "Search radius in kilometers" }, { "name": "ltype", "in": "query", "required": false, "schema": { "type": "string", "description": "Set to '1' to only return work-from-home jobs" }, "description": "Set to '1' to only return work-from-home jobs" }, { "name": "uds", "in": "query", "required": false, "schema": { "type": "string", "description": "Advanced filter string from a previous response" }, "description": "Advanced filter string from a previous response" } ], "responses": { "400": { "description": "Missing/invalid parameters or companyId missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials, no company access, or out of credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream web data request failed \u2014 not charged", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Job listings payload (jobs_results) with pagination", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "description": "Job listings payload. jobs_results holds the listings (title, company_name, location, description, extensions); scroll further pages with the returned pagination token. The response body is the raw payload object." } } } } }, "summary": "Search job listings", "description": "Returns job listings (title, company, location, description) for a query\nlike 'software engineer in New York'. Paginate with nextPageToken from a\nprevious response. Costs 1 data credit per call." } }, "/api/v0/web/maps/search": { "get": { "tags": [ "Web" ], "operationId": "web_searchPlaces", "parameters": [ { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID whose data credits are billed for the call" }, "description": "Company ID whose data credits are billed for the call" }, { "name": "query", "in": "query", "required": true, "schema": { "type": "string", "description": "What to find, e.g. 'coffee shops in Austin'" }, "description": "What to find, e.g. 'coffee shops in Austin'" }, { "name": "ll", "in": "query", "required": false, "schema": { "type": "string", "description": "GPS origin as @latitude,longitude,zoom, e.g. '@40.7455096,-74.0083012,15.1z'" }, "description": "GPS origin as @latitude,longitude,zoom, e.g. '@40.7455096,-74.0083012,15.1z'" }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string", "description": "Two-letter country code (default 'us')" }, "description": "Two-letter country code (default 'us')" }, { "name": "language", "in": "query", "required": false, "schema": { "type": "string", "description": "Results language (default 'en')" }, "description": "Results language (default 'en')" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Pagination offset: 0, 20, 40, ..." }, "description": "Pagination offset: 0, 20, 40, ..." }, { "name": "placeId", "in": "query", "required": false, "schema": { "type": "string", "description": "Look up one specific place by its place ID instead of searching" }, "description": "Look up one specific place by its place ID instead of searching" }, { "name": "data", "in": "query", "required": false, "schema": { "type": "string", "description": "Advanced filter parameter from a maps URL" }, "description": "Advanced filter parameter from a maps URL" }, { "name": "searchType", "in": "query", "required": false, "schema": { "type": "string", "description": "'search' (default) for a listing search or 'place' for a single-place lookup" }, "description": "'search' (default) for a listing search or 'place' for a single-place lookup" } ], "responses": { "400": { "description": "Missing/invalid parameters or companyId missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials, no company access, or out of credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream web data request failed \u2014 not charged", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Business listings payload (search_results) \u2014 each result carries the place_id/data_id for the place, reviews, and photos endpoints", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "description": "Business listings payload. search_results holds the listings (title, address, rating, reviews, phone, type, gps_coordinates) \u2014 each includes the place_id and data_id needed by the place, reviews, and photos endpoints. Paginate with the page parameter (0, 20, 40, ...)." } } } } }, "summary": "Search local businesses and places", "description": "Finds businesses matching a query like 'coffee shops in Austin', with\naddress, rating, phone, and coordinates. Each result includes the\nplace_id and data_id used by the place-details, reviews, and photos\nendpoints. Paginate with page (0, 20, 40, ...). Costs 1 data credit per\ncall." } }, "/api/v0/web/maps/place": { "get": { "tags": [ "Web" ], "operationId": "web_getPlace", "parameters": [ { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID whose data credits are billed for the call" }, "description": "Company ID whose data credits are billed for the call" }, { "name": "placeId", "in": "query", "required": false, "schema": { "type": "string", "description": "Place ID from a places search result (provide this or dataId)" }, "description": "Place ID from a places search result (provide this or dataId)" }, { "name": "dataId", "in": "query", "required": false, "schema": { "type": "string", "description": "Data ID from a places search result (provide this or placeId)" }, "description": "Data ID from a places search result (provide this or placeId)" }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string", "description": "Two-letter country code (default 'us')" }, "description": "Two-letter country code (default 'us')" } ], "responses": { "400": { "description": "placeId/dataId missing or companyId missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials, no company access, or out of credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream web data request failed \u2014 not charged", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Full place details payload", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "description": "Full place details payload: name, address, phone, website, hours, rating, review counts, popular times, and GPS coordinates." } } } } }, "summary": "Get full details for a place", "description": "Returns name, address, phone, website, hours, rating, and coordinates\nfor one place. Provide placeId or dataId from a places search result.\nCosts 1 data credit per call." } }, "/api/v0/web/maps/reviews": { "get": { "tags": [ "Web" ], "operationId": "web_getPlaceReviews", "parameters": [ { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID whose data credits are billed for the call" }, "description": "Company ID whose data credits are billed for the call" }, { "name": "dataId", "in": "query", "required": true, "schema": { "type": "string", "description": "Data ID of the place, from a places search result" }, "description": "Data ID of the place, from a places search result" }, { "name": "language", "in": "query", "required": false, "schema": { "type": "string", "description": "Results language (default 'en')" }, "description": "Results language (default 'en')" }, { "name": "sortBy", "in": "query", "required": false, "schema": { "type": "string", "description": "Sort order: 'qualityScore' (default), 'newestFirst', 'ratingHigh', or 'ratingLow'" }, "description": "Sort order: 'qualityScore' (default), 'newestFirst', 'ratingHigh', or 'ratingLow'" }, { "name": "topicId", "in": "query", "required": false, "schema": { "type": "string", "description": "Filter reviews by a topic ID from a previous response" }, "description": "Filter reviews by a topic ID from a previous response" }, { "name": "nextPageToken", "in": "query", "required": false, "schema": { "type": "string", "description": "Pagination token from a previous response" }, "description": "Pagination token from a previous response" }, { "name": "maxResults", "in": "query", "required": false, "schema": { "type": "integer", "description": "Reviews per page, 1-20 (default 10)" }, "description": "Reviews per page, 1-20 (default 10)" } ], "responses": { "400": { "description": "dataId missing/invalid parameters or companyId missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials, no company access, or out of credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream web data request failed \u2014 not charged", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Reviews payload with topics and pagination token", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "description": "Reviews payload: location summary, review topics, the reviews list (rating, snippet, date, reviewer), and a pagination token for the next page." } } } } }, "summary": "Get reviews for a place", "description": "Returns reviews (rating, text, date, reviewer) for a place identified by\nthe dataId from a places search result. Sort with sortBy and paginate\nwith nextPageToken. Costs 1 data credit per call." } }, "/api/v0/web/maps/photos": { "get": { "tags": [ "Web" ], "operationId": "web_getPlacePhotos", "parameters": [ { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID whose data credits are billed for the call" }, "description": "Company ID whose data credits are billed for the call" }, { "name": "dataId", "in": "query", "required": true, "schema": { "type": "string", "description": "Data ID of the place, from a places search result" }, "description": "Data ID of the place, from a places search result" }, { "name": "language", "in": "query", "required": false, "schema": { "type": "string", "description": "Results language (default 'en')" }, "description": "Results language (default 'en')" }, { "name": "categoryId", "in": "query", "required": false, "schema": { "type": "string", "description": "Filter by a photo category ID from a previous response" }, "description": "Filter by a photo category ID from a previous response" }, { "name": "nextPageToken", "in": "query", "required": false, "schema": { "type": "string", "description": "Pagination token from a previous response" }, "description": "Pagination token from a previous response" } ], "responses": { "400": { "description": "dataId missing or companyId missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials, no company access, or out of credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream web data request failed \u2014 not charged", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Photos payload with categories and pagination token", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "description": "Photos payload: photo categories, the photos list (thumbnail and full-size image URLs), and a pagination token for the next page." } } } } }, "summary": "Get photos for a place", "description": "Returns photo thumbnails and full-size image URLs for a place identified\nby the dataId from a places search result. Filter by categoryId and\npaginate with nextPageToken. Costs 1 data credit per call." } }, "/api/v0/web/trends/autocomplete": { "get": { "tags": [ "Web" ], "operationId": "web_autocompleteTrends", "parameters": [ { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID whose data credits are billed for the call" }, "description": "Company ID whose data credits are billed for the call" }, { "name": "query", "in": "query", "required": true, "schema": { "type": "string", "description": "Phrase to map to trending topics, e.g. 'jaguar'" }, "description": "Phrase to map to trending topics, e.g. 'jaguar'" }, { "name": "language", "in": "query", "required": false, "schema": { "type": "string", "description": "Results language (default 'en')" }, "description": "Results language (default 'en')" } ], "responses": { "400": { "description": "Missing/invalid parameters or companyId missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials, no company access, or out of credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream web data request failed \u2014 not charged", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Topic suggestions payload", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "description": "Topic suggestions payload: each suggestion maps the phrase to a disambiguated topic (title, type, topic id)." } } } } }, "summary": "Map a phrase to trending search topics", "description": "Disambiguates a phrase into the trending topics it could refer to (e.g.\n'jaguar' the animal vs the car brand), each with a topic title and type.\nCosts 1 data credit per call." } }, "/api/v0/web/screenshot": { "post": { "tags": [ "Web" ], "operationId": "web_screenshotPage", "parameters": [], "responses": { "400": { "description": "Missing/invalid url or companyId missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials, no company access, or out of credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The page could not be captured \u2014 not charged", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Saved screenshot with its public image URL", "content": { "application/json": { "schema": { "type": "object", "properties": { "imageId": { "type": "string", "description": "Saved image ID \u2014 the screenshot also appears in the Images library" }, "url": { "type": "string", "description": "Public URL of the PNG" }, "sourceUrl": { "type": "string", "description": "The page that was captured" }, "fullPage": { "type": "boolean", "description": "Whether the full scrollable page was captured" } }, "description": "Captured screenshot, saved to the image library" } } } } }, "summary": "Capture a screenshot of a web page", "description": "Renders the page, captures it as a PNG (full scrollable page by default,\nviewport only with fullPage=false), saves it to the image library, and\nreturns a public image URL. Costs 1 data credit per call.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID whose data credits are billed for the call" }, "url": { "type": "string", "description": "Full http(s) URL of the page to capture" }, "fullPage": { "type": "boolean", "description": "Capture the entire scrollable page (default true) or just the visible viewport (false)" } }, "required": [ "companyId", "url" ], "description": "Screenshot capture parameters" } } } } } }, "/api/v0/web/view": { "post": { "tags": [ "Web" ], "operationId": "web_viewPage", "parameters": [], "responses": { "400": { "description": "Missing/invalid url/imageUrl or query, or companyId missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials, no company access, or out of credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The page or image could not be viewed \u2014 not charged", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "The vision model's text answer about the page or image", "content": { "application/json": { "schema": { "type": "object", "properties": { "answer": { "type": "string", "description": "The vision model's plain-text answer to the query, based only on what is visible" }, "sourceUrl": { "type": "string", "description": "The page or image that was viewed" } }, "description": "Vision answer about the page or image" } } } } }, "summary": "View a web page or an image and answer a question about it.", "description": "Pass a page `url` (screenshotted in a real browser) OR a direct `imageUrl`\n(viewed as-is), plus a `query`. A vision model answers in text based only on\nwhat it can see. Costs 1 data credit per successful call. This is the same\nunified capability the AI-employee `take_website_screenshot` / `view_image`\ntools use (app/utils/visual_qa.py).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID whose data credits are billed for the call" }, "url": { "type": "string", "description": "Full http(s) URL of a web PAGE to screenshot and view. Provide exactly one of url or imageUrl." }, "imageUrl": { "type": "string", "description": "Full http(s) URL (or data: URI) of a direct IMAGE file to view. Provide exactly one of url or imageUrl." }, "query": { "type": "string", "description": "What to answer about what is seen, e.g. \"Describe the visual design and layout\" or \"What text is in this graphic?\"" }, "fullPage": { "type": "boolean", "description": "For a page url: view the entire scrollable page (default true) or just the visible viewport (false). Ignored for imageUrl." } }, "required": [ "companyId", "query" ], "description": "Visual question-answering parameters" } } } } } }, "/api/v0/linkedin/accounts": { "get": { "tags": [ "Linkedin" ], "operationId": "linkedin_listAccounts", "parameters": [ { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company used for access and billing." }, "description": "Company used for access and billing." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Page number, starting at 1.", "default": 1 }, "description": "Page number, starting at 1." }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "description": "Accounts per page, 1\u2013100.", "default": 20 }, "description": "Accounts per page, 1\u2013100." } ], "responses": { "400": { "description": "Invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials or company access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "integrationId": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" } } } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "pageSize": { "type": "integer" } } } } } } }, "summary": "List connected LinkedIn accounts", "description": "Paginated accessible accounts. Connect accounts through Integrations first.\nBuilder end-user accounts are excluded." } }, "/api/v0/linkedin/counts": { "get": { "tags": [ "Linkedin" ], "operationId": "linkedin_getCounts", "parameters": [ { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company used for access and billing." }, "description": "Company used for access and billing." }, { "name": "integrationId", "in": "query", "required": false, "schema": { "type": "string", "description": "Optional connected account ID. Omit to use your default personal-assistant browser profile.", "default": null }, "description": "Optional connected account ID. Omit to use your default personal-assistant browser profile." } ], "responses": { "400": { "description": "Invalid parameters or inaccessible account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials or company access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "date": { "type": "string", "description": "Date for the daily counter bucket." }, "actions": { "type": "object", "description": "By action type: count, limit, remaining. Includes reserved attempts with uncertain outcomes; shares sequence account counters." } } } } } } }, "summary": "Get daily LinkedIn action counts", "description": "Counts and remaining per-action limits shared with sequences and chat.\nCounts include reserved attempts with uncertain outcomes." } }, "/api/v0/linkedin/visit": { "post": { "tags": [ "Linkedin" ], "operationId": "linkedin_visitProfile", "parameters": [], "responses": { "202": { "description": "Action queued; poll the task endpoint", "content": { "application/json": { "schema": { "type": "object", "properties": { "taskId": { "type": "string" }, "status": { "type": "string", "description": "queued, running, completed, or failed. Do not submit a duplicate action while polling." }, "result": { "type": "object", "description": "Action result and quota; a failed action may still have occurred. Check LinkedIn before retrying." }, "error": { "type": "string" }, "updatedAt": { "type": "string" } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials or company access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Account inaccessible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Account needs reconnecting", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Action could not be queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Visit a LinkedIn profile", "description": "Returns a task ID. Poll GET /api/v0/linkedin/tasks/{taskId} with companyId. Never resubmit while polling. Uses an optional connected account or the default user browser profile and shared daily counters. Each browser task costs 5 credits, including failed attempts. LinkedIn actions have no additional action fee.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company used for access and billing." }, "integrationId": { "type": "string", "description": "Optional connected account ID. Omit to use your default personal-assistant browser profile.", "default": null }, "profileUrl": { "type": "string", "description": "Exact https://www.linkedin.com/in/... profile URL." } }, "required": [ "companyId", "profileUrl" ] } } } } } }, "/api/v0/linkedin/connect": { "post": { "tags": [ "Linkedin" ], "operationId": "linkedin_connectProfile", "parameters": [], "responses": { "202": { "description": "Action queued; poll the task endpoint", "content": { "application/json": { "schema": { "type": "object", "properties": { "taskId": { "type": "string" }, "status": { "type": "string", "description": "queued, running, completed, or failed. Do not submit a duplicate action while polling." }, "result": { "type": "object", "description": "Action result and quota; a failed action may still have occurred. Check LinkedIn before retrying." }, "error": { "type": "string" }, "updatedAt": { "type": "string" } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials or company access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Account inaccessible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Account needs reconnecting", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Action could not be queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Send a LinkedIn connection request", "description": "Returns a task ID. Poll GET /api/v0/linkedin/tasks/{taskId} with companyId. Never resubmit while polling. Uses an optional connected account or the default user browser profile and shared daily counters. Each browser task costs 5 credits, including failed attempts. LinkedIn actions have no additional action fee.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company used for access and billing." }, "integrationId": { "type": "string", "description": "Optional connected account ID. Omit to use your default personal-assistant browser profile.", "default": null }, "profileUrl": { "type": "string", "description": "Exact https://www.linkedin.com/in/... profile URL." }, "note": { "type": "string", "description": "Optional connection note. Maximum 300 characters.", "default": "" } }, "required": [ "companyId", "profileUrl" ] } } } } } }, "/api/v0/linkedin/message": { "post": { "tags": [ "Linkedin" ], "operationId": "linkedin_sendMessage", "parameters": [], "responses": { "202": { "description": "Action queued; poll the task endpoint", "content": { "application/json": { "schema": { "type": "object", "properties": { "taskId": { "type": "string" }, "status": { "type": "string", "description": "queued, running, completed, or failed. Do not submit a duplicate action while polling." }, "result": { "type": "object", "description": "Action result and quota; a failed action may still have occurred. Check LinkedIn before retrying." }, "error": { "type": "string" }, "updatedAt": { "type": "string" } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials or company access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Account inaccessible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Account needs reconnecting", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Action could not be queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Send a LinkedIn message", "description": "Returns a task ID. Poll GET /api/v0/linkedin/tasks/{taskId} with companyId. Never resubmit while polling. Uses an optional connected account or the default user browser profile and shared daily counters. Each browser task costs 5 credits, including failed attempts. LinkedIn actions have no additional action fee.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company used for access and billing." }, "integrationId": { "type": "string", "description": "Optional connected account ID. Omit to use your default personal-assistant browser profile.", "default": null }, "profileUrl": { "type": "string", "description": "Exact https://www.linkedin.com/in/... profile URL." }, "message": { "type": "string", "description": "Message text; cannot be blank. Maximum 200 characters." } }, "required": [ "companyId", "profileUrl", "message" ] } } } } } }, "/api/v0/linkedin/like": { "post": { "tags": [ "Linkedin" ], "operationId": "linkedin_likePost", "parameters": [], "responses": { "202": { "description": "Action queued; poll the task endpoint", "content": { "application/json": { "schema": { "type": "object", "properties": { "taskId": { "type": "string" }, "status": { "type": "string", "description": "queued, running, completed, or failed. Do not submit a duplicate action while polling." }, "result": { "type": "object", "description": "Action result and quota; a failed action may still have occurred. Check LinkedIn before retrying." }, "error": { "type": "string" }, "updatedAt": { "type": "string" } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials or company access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Account inaccessible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Account needs reconnecting", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Action could not be queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Like a LinkedIn post", "description": "Returns a task ID. Poll GET /api/v0/linkedin/tasks/{taskId} with companyId. Never resubmit while polling. Uses an optional connected account or the default user browser profile and shared daily counters. Each browser task costs 5 credits, including failed attempts. LinkedIn actions have no additional action fee.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company used for access and billing." }, "integrationId": { "type": "string", "description": "Optional connected account ID. Omit to use your default personal-assistant browser profile.", "default": null }, "postUrl": { "type": "string", "description": "Exact LinkedIn /posts/... or /feed/update/urn:li:activity:... URL." } }, "required": [ "companyId", "postUrl" ] } } } } } }, "/api/v0/linkedin/comment": { "post": { "tags": [ "Linkedin" ], "operationId": "linkedin_commentPost", "parameters": [], "responses": { "202": { "description": "Action queued; poll the task endpoint", "content": { "application/json": { "schema": { "type": "object", "properties": { "taskId": { "type": "string" }, "status": { "type": "string", "description": "queued, running, completed, or failed. Do not submit a duplicate action while polling." }, "result": { "type": "object", "description": "Action result and quota; a failed action may still have occurred. Check LinkedIn before retrying." }, "error": { "type": "string" }, "updatedAt": { "type": "string" } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials or company access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Account inaccessible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Account needs reconnecting", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Action could not be queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Comment on a LinkedIn post", "description": "Returns a task ID. Poll GET /api/v0/linkedin/tasks/{taskId} with companyId. Never resubmit while polling. Uses an optional connected account or the default user browser profile and shared daily counters. Each browser task costs 5 credits, including failed attempts. LinkedIn actions have no additional action fee.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company used for access and billing." }, "integrationId": { "type": "string", "description": "Optional connected account ID. Omit to use your default personal-assistant browser profile.", "default": null }, "postUrl": { "type": "string", "description": "Exact LinkedIn /posts/... or /feed/update/urn:li:activity:... URL." }, "comment": { "type": "string", "description": "Comment text; cannot be blank. Maximum 1250 characters." } }, "required": [ "companyId", "postUrl", "comment" ] } } } } } }, "/api/v0/linkedin/tasks/{taskId}": { "get": { "tags": [ "Linkedin" ], "operationId": "linkedin_getTask", "parameters": [ { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company used for access and billing." }, "description": "Company used for access and billing." } ], "responses": { "400": { "description": "Malformed taskId or missing companyId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials or company access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Task not found or expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "taskId": { "type": "string" }, "status": { "type": "string", "description": "queued, running, completed, or failed. Do not submit a duplicate action while polling." }, "result": { "type": "object", "description": "Action result and quota; a failed action may still have occurred. Check LinkedIn before retrying." }, "error": { "type": "string" }, "updatedAt": { "type": "string" } } } } } } }, "summary": "Check a LinkedIn action task", "description": "Only the initiating user in the same company can read the task. Tasks expire\nafter 24 hours. A failed or uncertain action may still have occurred: check\nLinkedIn before retrying. Poll this endpoint; do not repeat the action POST." } }, "/api/v0/canvas": { "post": { "tags": [ "Canvas" ], "operationId": "canvas_createCanvas", "parameters": [], "responses": { "400": { "description": "Invalid html/format/dimensions or companyId missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials, no company access, or out of credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The canvas could not be rendered \u2014 not charged", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "The rendered canvas with its public image (or video) URL", "content": { "application/json": { "schema": { "type": "object", "properties": { "imageId": { "type": "string", "description": "ID of the saved image (still canvases only)" }, "videoId": { "type": "string", "description": "ID of the saved video (animated canvases only)" }, "url": { "type": "string", "description": "Permanent public URL of the rendered PNG, or of the recorded MP4 when animated" }, "width": { "type": "integer", "description": "Rendered width in px" }, "height": { "type": "integer", "description": "Rendered height in px" }, "duration": { "type": "number", "description": "Video length in seconds (animated canvases only)" } }, "description": "Rendered canvas" } } } } }, "summary": "Render a canvas art image or animation from HTML", "description": "Renders a self-contained HTML canvas at exact pixel dimensions and returns a permanent public URL \u2014 for social posts, story graphics, quote cards, and link preview art. Costs 0.1 credits per call.\n\nPass animated=true to record the canvas as a looping MP4 instead of a still PNG (animate with infinite CSS keyframes); that returns videoId and an MP4 url, and costs 3 credits.\n\nAuthor the HTML to these design guidelines:\n\n## What You Are Making\nA canvas is a piece of visual art, not a document. Museum-quality, magazine-quality \u2014\nnever cartoony, never clip-art, never a slide. Before writing any HTML, decide a design\ndirection in one sentence (e.g. \"Swiss formalism: one monumental word, hard grid,\nred/black/paper\" or \"quiet editorial: thin serif, vast negative space, one photograph\").\nEvery choice then serves that direction.\n\n## Brand Style (check first)\n- Before choosing a direction, check whether the company has a brand kit saved in\n the content engine (GET /brand-kits \u2014 brand_kit_listBrandKits on the platform\n API/MCP). Do this BEFORE the first render, not after.\n- If a brand kit exists, its `imageStylePrompt` is the company's established visual\n style (palette, mood, typography feel, photographic treatment); its `images` list\n holds brand assets (logos, product shots, approved photography) with public URLs;\n and its `webArtifacts` holds the primary `favicon` and `logo` (each with a public\n `url`). Treat these as the source of truth: derive the palette and type choices\n from the style prompt, and embed brand assets by their exact URL instead of stock\n or AI-generated stand-ins when a suitable one exists. Never alter, recolor, or\n distort a logo.\n- If no brand kit exists, or the session already supplies brand context in its\n instructions, skip the lookup and design from the brief.\n\n## Canvas Setup (exact rules)\n- Output one complete standalone HTML document. No external CSS/JS files; inline a\n `<style>` block. Plain CSS preferred, but these shared platform libraries may be loaded\n from their CDNs:\n - Tailwind CSS: `<script src=\"https://cdn.tailwindcss.com\"></script>` \u2014 utility classes; no build step\n - Lucide Icons: `<script src=\"https://unpkg.com/lucide@1.33.0/dist/umd/lucide.min.js\"></script>` \u2014 place `<i data-lucide=\"arrow-right\"></i>`, then call `lucide.createIcons();` after the last icon\n - Google Fonts: `<link href=\"https://fonts.googleapis.com/css2?family=...&display=swap\" rel=\"stylesheet\">` \u2014 pick faces that match the brand\n- Size the canvas EXACTLY to the chosen format:\n `html,body{margin:0;padding:0}` and `body{width:<W>px;height:<H>px;overflow:hidden;position:relative}`\n- Named formats include: square 1080x1080 (feed), portrait 1080x1350 (feed, default), story\n 1080x1920 (Stories/Reels), landscape 1200x630 (link previews), slide 1920x1080 (16:9\n presentation slide background \u2014 decorative art only, no text; editable text is layered on\n later), plus profile covers (linkedin_banner, twitter_header, facebook_cover),\n youtube_thumb, email_header, print pages (a4_portrait, a4_landscape, letter_portrait) and\n business_card. When none fits, an exact custom width/height (200-2160px each) can be\n supplied instead \u2014 size the body to whatever exact dimensions the session gives you.\n- A canvas is rendered one of two ways, and you are told which one this session wants:\n - STILL (default): the canvas is photographed the instant it loads. Design it static \u2014\n no animations or transitions, since only the first frame is ever seen.\n - ANIMATED: the canvas is recorded to a short MP4. Follow the animation rules below.\n\n## Image sharpness\n- Use the stock result's fullUrl, never a thumbnail or preview URL. Choose photos\n with enough native pixels for the area they cover, including any cover crop.\n Avoid enlarging small photos or cropping so tightly that the subject becomes blurry.\n- Keep text, logos, icons, and geometric details as HTML/CSS or SVG where possible;\n never flatten them into a low-resolution bitmap. Avoid blur filters on these layers.\n- For a HTML <canvas>, size its backing bitmap to its CSS dimensions multiplied by\n window.devicePixelRatio and scale the drawing context accordingly. CSS size alone\n stretches the default bitmap and produces blurry artwork.\n- Generated photo prompts should specify crisp subject detail and sharp focus where\n the design needs it. Keep typography in the HTML layer rather than inside the photo.\n\n## Typography (the heart of the canvas)\n- Google Fonts only, loaded via `<link href=\"https://fonts.googleapis.com/css2?family=...&display=swap\" rel=\"stylesheet\">`.\n- Choose from this curated library \u2014 at most TWO fonts per canvas:\n - Monumental display: Boldonse, Big Shoulders, Erica One, Archivo Black, Bebas Neue\n - Elegant serif: Gloock, Italiana, Young Serif, Instrument Serif, Playfair Display, Libre Baskerville\n - Modern sans: Bricolage Grotesque, Outfit, Work Sans, Instrument Sans, Space Grotesk\n - Editorial body serif: Lora, Crimson Pro, IBM Plex Serif\n - Technical mono: JetBrains Mono, IBM Plex Mono, DM Mono, Tektur, Jura\n - Retro pixel: Silkscreen, Pixelify Sans\n - Handwritten: Nothing You Could Do, Smooch Sans; thin deco: Poiret One\n- Text is minimal and visual-first: usually one dominant word or short phrase plus tiny\n supporting labels. Rarely more than a dozen words on the whole canvas.\n- Make the hero text HUGE \u2014 roughly 10-25% of the canvas height. Uppercase display type\n wants letter-spacing (0.02-0.15em); tiny labels want wide tracking (0.2-0.4em).\n- Line-height on stacked display lines: some display fonts draw far taller than their\n em box and collide when stacked (Boldonse needs line-height ~1.3). Use 1.2-1.3 for\n multi-line display type and only go tighter for fonts you know sit inside their box.\n- Contrast in scale is the composition: one enormous element, a few whisper-small ones.\n Nothing in between.\n\n## Icons (Lucide)\n- When the design calls for an icon \u2014 a directional arrow, a play glyph, a small\n functional mark next to a label \u2014 use Lucide, never emoji and never clip-art.\n- Load it once, at the END of the body, then render the icons:\n `<script src=\"https://unpkg.com/lucide@1.33.0/dist/umd/lucide.min.js\"></script>` followed by `<script>lucide.createIcons();</script>`\n- Place an icon with `<i data-lucide=\"arrow-right\"></i>`. Size and color it through CSS on\n the element \u2014 Lucide SVGs inherit `currentColor` and take `width`/`height`:\n `i[data-lucide]{width:64px;height:64px;stroke-width:1.5}` (the stroke weight matters as\n much as the size \u2014 hairline strokes read as refined, thick ones as cartoonish).\n- Use real Lucide names (arrow-right, arrow-up-right, sparkles, zap, check, star, play,\n quote, trending-up, circle-dot). A misspelled name renders nothing at all.\n- Icons are accents, not the subject: one or two per canvas, small against the hero type.\n An icon never substitutes for a real design idea.\n\n## Animation (ANIMATED canvases only)\nOnly when the session asks for an animated canvas. A still canvas must have no animation\nat all \u2014 it is photographed on the first frame.\n- Animate with CSS `@keyframes` on the elements themselves. The recording seeks the page's\n animation timeline frame by frame, so what is recorded is exactly your CSS timeline.\n- Every animation MUST be `infinite` and MUST tile seamlessly: the state at the end of one\n iteration has to match the state at the start, or the loop visibly jumps. The cleanest\n way is a single cycle that returns home (`0%` and `100%` identical).\n- Give the whole piece ONE shared cycle length \u2014 set every animation to the same\n `animation-duration` (or an exact divisor of it, e.g. 2s inside an 8s piece) so the\n composition repeats as a whole rather than drifting out of phase.\n- Stagger with `animation-delay` (negative delays start an element mid-cycle), never by\n giving elements unrelated durations.\n- Animate `transform` and `opacity` above all \u2014 they are what animates smoothly. Also fine:\n `filter`, `clip-path`, gradient positions, `stroke-dashoffset` on SVG.\n- Keep it restrained and slow: a drifting gradient, a slow parallax push, type that breathes,\n a single element sliding through. Elegant motion is subtle \u2014 nothing bouncing, spinning\n fast, or flashing. The canvas must still look composed in any single frozen frame.\n\n### What the recorder can and cannot capture\nThe recording pauses the browser's animation timeline and steps through it \u2014 it does NOT\nwatch the page play in real time. Only animations the browser itself drives are captured:\n- CAPTURED: CSS `@keyframes`, CSS transitions, SVG SMIL, and the Web Animations API\n (`element.animate(...)`) \u2014 everything that appears in `document.getAnimations()`.\n HTML `<video>` frames are also seeked in step with the animation timeline.\n- NOT CAPTURED (records as a frozen video, with no error): anything driven by JavaScript\n frame by frame \u2014 `requestAnimationFrame`, `setInterval`/`setTimeout` loops, canvas 2D/WebGL\n draw loops, and scroll-triggered libraries. Animated GIFs are not seeked reliably.\n- This is the ONE rule that differs from the landing page builder, whose pages play live in\n a real browser and can use anything. Do not carry those habits over.\n\n### Stock video for animated canvases \u2014 search_stock_videos\nSearch Pexels stock videos for animated canvases. Returns direct videoUrl MP4 URLs, preview images, dimensions, duration and creator attribution. Use the exact videoUrl in <video autoplay loop muted playsinline> with object-fit:cover, sized to the canvas; layer readable text above it. Set animated=true when calling create_canvas, or set_animated(True) in the canvas builder. Video frames are seeked with the animation timeline in exports; use separate audio tracks for sound. Still PNGs have no motion. Paginate with page/pageSize; this tool is available whenever canvas tools are enabled.\n\n### Audio for animated canvases\nDefault to free stock music for music, soundtracks, reels and stories: use search_stock_music then import_stock_music. Use paid create_music ONLY when the user explicitly requests custom AI-generated music. Never automatically fall back to paid generation when stock search/import fails; try different keywords or tracks and report if none are suitable.\nSearch Openverse for free CC0/public-domain stock music and loops by mood, genre or instruments. Returns candidates with stockAudioId, previewUrl, duration in seconds, creator and source/license links. Choose a track and call import_stock_music to get a permanent canvas audio URL. Do not embed previewUrl in a canvas. Search consumes no audio credits.\nImport a selected search_stock_music result by stockAudioId. Rechecks its indexed license and matching license link on the original source page, saves an MP3 with source/license metadata, and returns a permanent public audioUrl plus measured duration in seconds. Use audioUrl in <audio src=\"URL\" loop data-volume=\"0.2\"></audio> in an animated canvas. No audio generation credits are charged. Sources that cannot be verified are rejected; choose another track. Imports are bounded by the configured file-size and duration limits (default 40 MiB and the first ten minutes).\n\n- For narration or dialogue, call `create_speech`. Audio tools return permanent public\n audio URLs and measured durations. Never invent audio URLs. If speech generation\n is unavailable, explain that limitation.\n- Include tracks directly in the HTML: `<audio src=\"RETURNED_URL\" loop\n data-volume=\"0.2\"></audio>` for quiet background music; `<audio src=\"RETURNED_URL\"\n data-start=\"2\" data-volume=\"1\"></audio>` for narration starting 2 seconds in.\n- Up to 8 tracks are mixed into the exported MP4. data-start is seconds (default 0);\n data-volume is 0..1 (default 1). `loop` repeats music; omit it for speech. `muted`\n excludes a track. Only platform public generated or imported audio URLs are accepted.\n- For dialogue, generate each speaker's line separately with the desired voice ID,\n then use data-start and the returned durations to place the lines in sequence.\n Lower the music volume under dialogue. Do not repeat or cut off spoken lines.\n- Set video duration long enough for all lines, within the tool's duration limit;\n shorten the script if needed. With audio the requested duration is preserved,\n without rounding to whole animation cycles. Tracks are trimmed/padded to that length.\n- Audio is mixed during export; browser autoplay, Web Audio and JavaScript playback\n are not recorded. HTML preview autoplay may be blocked; use the exported MP4 to\n review the finished soundtrack. Still PNGs have no audio.\n\n### Animation libraries\nCSS keyframes are the default and are always enough for a canvas \u2014 reach for a library only\nwhen the motion genuinely needs orchestration (staggered sequences, timelines).\n- The ONLY animation library available here is Anime.js, and ONLY through its WAAPI entry\n point, which puts animations on the browser timeline:\n - Anime.js (advanced animation): `<script src=\"https://cdn.jsdelivr.net/npm/animejs/dist/bundles/anime.umd.min.js\"></script>` \u2014 staggered reveals, timelines, kinetic type. `anime.waapi.animate(...)` puts the animation on the browser timeline; `anime.animate(...)` / `anime.Timeline` drive it from JS frame by frame\n Call it as `anime.waapi.animate('.el', { translateX: 300, duration: 2000, loop: true })`.\n Its classic `anime.animate(...)` / `anime.Timeline` API is JS-driven and records as a\n FROZEN video \u2014 if you use Anime.js at all, every animation must go through\n `anime.waapi.animate`.\n- AOS (used by the landing page builder) is scroll-triggered and USELESS here: a canvas is a\n fixed viewport with nothing to scroll, so its animations never fire. Never load it.\n- Whatever you use, the seamless-loop and shared-cycle rules above still apply.\n\n### Canvas Motion Kit \u2014 preferred for multi-scene videos\nFor a sequenced video with named scene transitions, use the built-in Canvas Motion Kit instead\nof writing timing/animation JavaScript. It is loaded automatically in both preview and MP4\nexport, creates recorder-safe Web Animations API timelines, and keeps the agent's HTML compact.\n- Set `<html data-canvas-duration=\"5\">` to the exact loop duration. Use one full-bleed\n `<section data-canvas-scene data-start=\"0\" data-duration=\"2.7\"\n data-transition-in=\"fade\" data-transition-out=\"wipe-left\">` per scene. Scenes may overlap\n briefly for transitions; position them absolutely at `inset:0`.\n- Supported scene transitions: `fade`, `slide-left`, `slide-right`, `slide-up`, `slide-down`,\n `scale`, `blur`, `wipe-left`, `wipe-right`.\n- Add `data-canvas-motion=\"fade-up\"` (or `fade-down`, `reveal`, `pop`, `focus`, `float`) to\n scene children. Optional `data-delay`, `data-stagger`, and `data-motion-duration` are seconds.\n The kit handles the keyframes and timing; never add a second JS animation loop.\n- Use it only for animated canvases. For an elegant single looping composition, ordinary CSS\n keyframes remain simpler and preferred.\n\n### Timeline clips \u2014 the video editor\nThe canvas editor shows a timeline built from tagged elements in this HTML. The user drags and\ntrims clips there, which rewrites their attributes in the HTML. Read the current HTML before\nediting and keep every `data-clip-id` and timing attribute you do not mean to change.\n- Footage: `<video data-clip-id=\"intro\" data-start=\"0\" data-in=\"2\" data-out=\"10\" src=\"URL\"\n muted playsinline></video>` plays source seconds data-in..data-out from timeline second\n data-start. Tagged clips always render full-bleed BENEATH all graphics (object-fit: cover);\n a later clip covers an earlier one where they overlap, and gaps are black. Do not style or\n position them. `src` must be a platform video URL or a search_stock_videos videoUrl.\n `data-volume` (0..1, default 1) sets the clip's own sound.\n- Sound: `<audio data-clip-id=\"vo1\" data-track=\"voiceover\" data-start=\"1\" data-volume=\"1\"\n src=\"URL\"></audio>`; `data-track` is `voiceover` or `music`; optional `data-in`/`data-out`\n trim the source. The audio rules above still apply.\n- Graphics: Motion Kit scenes with a `data-clip-id` are the timeline's graphics clips\n (`data-start`/`data-duration`).\n- With video clips the page background is transparent so the footage shows through \u2014 put\n backgrounds inside scenes, never on html/body.\n- Set `<html data-canvas-duration>` to the full timeline length (at most 60s with\n video clips; the shorter animation limit applies without them).\n- An untagged `<video>` stays a free-form looping background inside the page.\n\n## Color & Background\n- A limited, intentional palette: 2-3 colors total. Pick them for the design direction,\n not decoration. High text/background contrast is non-negotiable.\n- Backgrounds: a flat color, a subtle gradient, or a photo. For photos use\n `background:url(...) center/cover` and ALWAYS add a scrim over photo areas behind text\n (e.g. `background:rgba(0,0,0,.35)` or a directional gradient) so type stays legible.\n The scrim serves the text, not the whole canvas: keep it light (\u2264 ~0.5 opacity) or\n directional so the photo stays clearly visible \u2014 a photo buried under a near-opaque\n overlay reads as a plain dark field and wastes the imagery.\n- Photo URLs must be public http(s) images. Two ways to get one:\n - Stock photography: search the stock image library (Unsplash/Pexels via the stock\n image search \u2014 images_searchStockImages on the platform API/MCP) and use a\n result's fullUrl.\n - AI-generated imagery: generate an image with the platform's AI image models\n (images_createImage on the platform API/MCP \u2014 describe the scene, pick a model,\n and use the returned public URL). Best for imagery no stock photo can match;\n request it WITHOUT text, since the canvas type layer supplies all text.\n\n## Composition (non-negotiable craft rules)\n- Keep a safe margin of at least 5% of the canvas on every side. NOTHING touches or\n overflows the canvas edge, and elements never overlap illegibly.\n- Compose deliberately: strong asymmetry or a strict grid both work; accidental\n centering of everything does not. Let negative space breathe \u2014 empty space is a\n design element, not waste.\n- Repetition rewards attention: thin rules, small registration marks, an index number,\n a tiny caption line \u2014 sparse, clinical details make the piece feel designed.\n- The finished canvas should look like it took a top-of-field designer hours of\n painstaking refinement: aligned edges, consistent spacing rhythm, optically balanced.\n Double-check every element is inside the canvas and nothing collides before finishing.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID whose credits are billed for the call" }, "html": { "type": "string", "description": "Complete standalone HTML document for the canvas. Must be fully self-contained (inline <style>; Google Fonts links, the Tailwind CDN script, and the Lucide icons CDN script are allowed) with html,body{margin:0} and the body sized to EXACTLY the canvas dimensions with overflow:hidden. Static \u2014 no animations \u2014 unless animated is true, in which case animate with infinite, seamlessly looping CSS keyframes. Follow the design guidelines in the Canvas tag description." }, "format": { "type": "string", "description": "Named canvas format: 'square' (1080x1080 feed), 'portrait' (1080x1350 feed, default), 'story' (1080x1920 Stories/Reels), 'landscape' (1200x630 link preview), 'slide' (1920x1080 slide background), 'wide' (1920x1080), 'tall' (1080x1620), 'pin' (1000x1500), 'linkedin_banner' (1584x396), 'twitter_header' (1500x500), 'facebook_cover' (1640x924), 'youtube_thumb' (1280x720), 'email_header' (1200x400), 'a4_portrait' (1240x1754), 'a4_landscape' (1754x1240), 'letter_portrait' (1275x1650), 'business_card' (1050x600). Ignored when width/height are given." }, "width": { "type": "integer", "description": "Custom canvas width in px (200-2160); requires height. Overrides format." }, "height": { "type": "integer", "description": "Custom canvas height in px (200-2160); requires width. Overrides format." }, "animated": { "type": "boolean", "description": "Record the canvas as a looping MP4 video instead of a still PNG. The response returns videoId and an MP4 url instead of imageId. Costs 3 credits instead of 0.1. Default false." }, "duration": { "type": "number", "description": "Video length in seconds when animated is true (1-15, out-of-range values are clamped; default 5). Match it to the CSS animation cycle so the loop tiles cleanly. Ignored for stills." } }, "required": [ "companyId", "html" ], "description": "Canvas to render" } } } } } }, "/api/v0/canvas/templates": { "get": { "tags": [ "Canvas" ], "operationId": "canvas_listCanvasTemplates", "parameters": [], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Every locked canvas template with its slots", "content": { "application/json": { "schema": { "type": "object", "properties": { "templates": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Template ID (templateId)" }, "name": { "type": "string" }, "description": { "type": "string" }, "bestFor": { "type": "array", "items": { "type": "string" }, "description": "Content this template fits" }, "usesPhoto": { "type": "boolean", "description": "Whether the template has a photo media zone" }, "slots": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Slot key used in the slots object" }, "label": { "type": "string", "description": "Human-readable slot name" }, "maxWords": { "type": "integer", "description": "Word limit; longer text is cut at a word boundary" }, "required": { "type": "boolean", "description": "Whether the template needs this slot" }, "description": { "type": "string", "description": "What belongs in the slot" } } } } } } } } } } } } }, "summary": "List locked canvas templates", "description": "Locked templates have fixed slot geometry for every format, auto-fitting\ntext, safe margins and contrast-checked brand colors. Pick the template\nwhose bestFor matches the content, then fill its slots via\nPOST /api/v0/canvas/templates/render; no HTML authoring is needed." } }, "/api/v0/canvas/templates/preview": { "post": { "tags": [ "Canvas" ], "operationId": "canvas_previewCanvasTemplate", "parameters": [], "responses": { "400": { "description": "Unknown template, bad size or brand kit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Canvas HTML with sample content", "content": { "application/json": { "schema": { "type": "object", "properties": { "html": { "type": "string", "description": "Complete canvas HTML filled with sample content" }, "width": { "type": "integer" }, "height": { "type": "integer" } } } } } } }, "summary": "Preview a canvas template", "description": "Returns the template's HTML filled with sample content in a brand kit's\ncolors and logo. Free \u2014 nothing is rendered or saved.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company that owns brandKitId" }, "templateId": { "type": "string", "description": "Template ID from GET /api/v0/canvas/templates" }, "format": { "type": "string", "description": "Named canvas format (same values as POST /api/v0/canvas, e.g. 'square', 'portrait', 'story', 'landscape'); default 'portrait'. Ignored when width/height are given." }, "width": { "type": "integer", "description": "Custom width in px; requires height" }, "height": { "type": "integer", "description": "Custom height in px; requires width" }, "brandKitId": { "type": "string", "description": "Brand kit whose colors and logo to preview with; defaults to the company's default brand kit" }, "colorPalette": { "type": "object", "description": "Unsaved palette {primary, secondary, accent, background, surface, text} as #RRGGBB; overrides the brand kit palette" } }, "required": [ "templateId" ], "description": "Template to preview" } } } } } }, "/api/v0/canvas/templates/render": { "post": { "tags": [ "Canvas" ], "operationId": "canvas_renderCanvasTemplate", "parameters": [], "responses": { "400": { "description": "Unknown template, missing required slot, bad size or brand kit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials, no company access, or out of credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The canvas could not be rendered \u2014 not charged", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "The rendered canvas with its public image URL", "content": { "application/json": { "schema": { "type": "object", "properties": { "imageId": { "type": "string", "description": "ID of the saved image (still canvases only)" }, "videoId": { "type": "string", "description": "ID of the saved video (animated canvases only)" }, "url": { "type": "string", "description": "Permanent public URL of the rendered PNG, or of the recorded MP4 when animated" }, "width": { "type": "integer", "description": "Rendered width in px" }, "height": { "type": "integer", "description": "Rendered height in px" }, "duration": { "type": "number", "description": "Video length in seconds (animated canvases only)" } }, "description": "Rendered canvas" } } } } }, "summary": "Render a locked canvas template to a PNG.", "description": "Renders a locked canvas template filled with your slot text and returns a permanent public PNG URL. The layout, type sizing, margins and contrast are fixed by the template, so the result always fits its format. Costs 0.1 credits per call. List templates and their slots with GET /api/v0/canvas/templates.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID whose credits are billed for the call" }, "templateId": { "type": "string", "description": "Template ID from GET /api/v0/canvas/templates" }, "slots": { "type": "object", "description": "Slot text keyed by slot name, e.g. {\"headline\": \"...\", \"supporting\": \"...\"}. Required slots must be present; text over a slot's word limit is cut." }, "format": { "type": "string", "description": "Named canvas format (same values as POST /api/v0/canvas, e.g. 'square', 'portrait', 'story', 'landscape'); default 'portrait'. Ignored when width/height are given." }, "width": { "type": "integer", "description": "Custom width in px (200-2160); requires height" }, "height": { "type": "integer", "description": "Custom height in px (200-2160); requires width" }, "brandKitId": { "type": "string", "description": "Brand kit whose color palette and logo style the template; defaults to the company's default brand kit" }, "photoUrl": { "type": "string", "description": "Public https image URL for the template's photo zone (e.g. a stock search fullUrl); every template uses one, and without it the zone shows a brand pattern" } }, "required": [ "companyId", "templateId", "slots" ], "description": "Template and slot text to render" } } } } } }, "/api/v0/stock-videos/search": { "get": { "tags": [ "Canvas" ], "operationId": "canvas_searchStockVideos", "parameters": [ { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "query", "in": "query", "required": true, "schema": { "type": "string", "description": "Desired subject, mood or style" }, "description": "Desired subject, mood or style" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "description": "Results per page, 1\u201320", "default": 6 }, "description": "Results per page, 1\u201320" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object" } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "pageSize": { "type": "integer" }, "hasMore": { "type": "boolean" }, "provider": { "type": "string" }, "nextStep": { "type": "string" } } } } } } }, "summary": "Search stock videos.", "description": "Search Pexels stock videos for animated canvases. Returns direct videoUrl MP4 URLs, preview images, dimensions, duration and creator attribution. Use the exact videoUrl in <video autoplay loop muted playsinline> with object-fit:cover, sized to the canvas; layer readable text above it. Set animated=true when calling create_canvas, or set_animated(True) in the canvas builder. Video frames are seeked with the animation timeline in exports; use separate audio tracks for sound. Still PNGs have no motion. Paginate with page/pageSize; this tool is available whenever canvas tools are enabled." } }, "/api/v0/stock-music/search": { "get": { "tags": [ "Canvas" ], "operationId": "canvas_searchStockMusic", "parameters": [ { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "query", "in": "query", "required": true, "schema": { "type": "string", "description": "Desired subject, mood or style" }, "description": "Desired subject, mood or style" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "description": "Results per page, 1\u201320", "default": 6 }, "description": "Results per page, 1\u201320" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object" } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "pageSize": { "type": "integer" }, "hasMore": { "type": "boolean" }, "provider": { "type": "string" }, "nextStep": { "type": "string" } } } } } } }, "summary": "Search free stock music.", "description": "Default to free stock music for music, soundtracks, reels and stories: use search_stock_music then import_stock_music. Use paid create_music ONLY when the user explicitly requests custom AI-generated music. Never automatically fall back to paid generation when stock search/import fails; try different keywords or tracks and report if none are suitable.\nSearch Openverse for free CC0/public-domain stock music and loops by mood, genre or instruments. Returns candidates with stockAudioId, previewUrl, duration in seconds, creator and source/license links. Choose a track and call import_stock_music to get a permanent canvas audio URL. Do not embed previewUrl in a canvas. Search consumes no audio credits." } }, "/api/v0/stock-music/import": { "post": { "tags": [ "Canvas" ], "operationId": "canvas_importStockMusic", "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "audioId": { "type": "string", "description": "Created audio ID" }, "audioUrl": { "type": "string", "description": "Permanent public audio URL" }, "duration": { "type": "number", "description": "Measured audio duration in seconds" }, "model": { "type": "string", "description": "Model used for generation" }, "creditsCharged": { "type": "number", "description": "Credits charged for this generation" }, "format": { "type": "string", "description": "Audio format" }, "msg": { "type": "string", "description": "Success message" } }, "description": "Audio creation response" } } } } }, "summary": "Import licensed stock music into the audio library.", "description": "Import a selected search_stock_music result by stockAudioId. Rechecks its indexed license and matching license link on the original source page, saves an MP3 with source/license metadata, and returns a permanent public audioUrl plus measured duration in seconds. Use audioUrl in <audio src=\"URL\" loop data-volume=\"0.2\"></audio> in an animated canvas. No audio generation credits are charged. Sources that cannot be verified are rejected; choose another track. Imports are bounded by the configured file-size and duration limits (default 40 MiB and the first ten minutes).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string" }, "stockAudioId": { "type": "string", "description": "ID returned by stock music search" } }, "required": [ "companyId", "stockAudioId" ] } } } } } }, "/api/v0/audio/music": { "post": { "tags": [ "Canvas" ], "operationId": "canvas_createMusic", "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "audioId": { "type": "string", "description": "Created audio ID" }, "audioUrl": { "type": "string", "description": "Permanent public audio URL" }, "duration": { "type": "number", "description": "Measured audio duration in seconds" }, "model": { "type": "string", "description": "Model used for generation" }, "creditsCharged": { "type": "number", "description": "Credits charged for this generation" }, "format": { "type": "string", "description": "Audio format" }, "msg": { "type": "string", "description": "Success message" } }, "description": "Audio creation response" } } } } }, "summary": "Generate custom music.", "description": "Default to free stock music for music, soundtracks, reels and stories: use search_stock_music then import_stock_music. Use paid create_music ONLY when the user explicitly requests custom AI-generated music. Never automatically fall back to paid generation when stock search/import fails; try different keywords or tracks and report if none are suitable.\nCreate music with ElevenLabs and return a permanent public audio URL and duration in seconds. Describe genre, mood, instruments, tempo and any desired lyrics. Instrumental defaults to true for background music underneath narration. Embed the URL in animated canvas HTML as <audio src=\"URL\" loop data-volume=\"0.2\"></audio> to include it in the exported MP4. Generation consumes audio credits.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string" }, "prompt": { "type": "string" }, "duration": { "type": "number", "description": "Duration in seconds, 3\u201360", "default": 10 }, "instrumental": { "type": "boolean", "default": true } }, "required": [ "companyId", "prompt" ] } } } } } }, "/api/v0/support/tickets": { "post": { "tags": [ "Support" ], "operationId": "support_createSupportTicket", "parameters": [], "responses": { "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "201": { "description": "The created ticket", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Ticket ID" }, "companyId": { "type": "string", "description": "Associated company ID (may be null for general tickets)" }, "userId": { "type": "string", "description": "User ID of the ticket creator" }, "whitelabelId": { "type": "string", "description": "Whitelabel instance ID if submitted from a whitelabel domain" }, "subject": { "type": "string", "description": "Ticket subject" }, "description": { "type": "string", "description": "Ticket description" }, "severity": { "type": "string", "description": "Severity (low, medium, high, critical)" }, "status": { "type": "string", "description": "Status (open, in_progress, resolved, closed)" }, "ticketType": { "type": "string", "description": "Ticket type (bug, feature_request, question, other)" }, "attachments": { "type": "array", "items": { "type": "string" }, "description": "Attachment objects with type info" }, "response": { "type": "string", "description": "Final support response when resolved" }, "resolvedAt": { "type": "string", "description": "ISO timestamp when the ticket was resolved" }, "resolvedBy": { "type": "string", "description": "User ID of the resolver" }, "createdAt": { "type": "string", "description": "ISO timestamp when the ticket was created" }, "updatedAt": { "type": "string", "description": "ISO timestamp when the ticket was last updated" } }, "description": "Support ticket object" } } } } }, "summary": "Create a new support ticket.", "description": "Submit a bug report, feature request, question, or other support issue.\nThe ticket is scoped to the authenticated user and company.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "subject": { "type": "string", "description": "Short summary of the issue or request" }, "description": { "type": "string", "description": "Detailed description of the issue or request" }, "ticketType": { "type": "string", "description": "Ticket type (one of: bug, feature_request, question, other). Default: question" }, "severity": { "type": "string", "description": "Severity (one of: low, medium, high, critical). Default: medium" }, "attachments": { "type": "array", "items": { "type": "string" }, "description": "Attachment references (platform image IDs, document IDs, or {type, id, name} objects)" } }, "required": [ "subject", "description" ], "description": "Request body for creating a support ticket" } } }, "description": "Ticket details" } }, "get": { "tags": [ "Support" ], "operationId": "support_listSupportTickets", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "description": "Filter by status. Accepts a single value or comma-separated list (values: open, in_progress, resolved, closed)" }, "description": "Filter by status. Accepts a single value or comma-separated list (values: open, in_progress, resolved, closed)" }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "description": "Filter by ticket type (bug, feature_request, question, other)" }, "description": "Filter by ticket type (bug, feature_request, question, other)" }, { "name": "severity", "in": "query", "required": false, "schema": { "type": "string", "description": "Filter by severity (low, medium, high, critical)" }, "description": "Filter by severity (low, medium, high, critical)" }, { "name": "query", "in": "query", "required": false, "schema": { "type": "string", "description": "Case-insensitive text search across ticket subject and description" }, "description": "Case-insensitive text search across ticket subject and description" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Page number (default: 1)", "default": 1 }, "description": "Page number (default: 1)" }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Items per page (default: 20, max: 100)", "default": 20 }, "description": "Items per page (default: 20, max: 100)" } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Paginated list of support tickets", "content": { "application/json": { "schema": { "type": "object", "properties": { "tickets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Ticket ID" }, "companyId": { "type": "string", "description": "Associated company ID (may be null for general tickets)" }, "userId": { "type": "string", "description": "User ID of the ticket creator" }, "whitelabelId": { "type": "string", "description": "Whitelabel instance ID if submitted from a whitelabel domain" }, "subject": { "type": "string", "description": "Ticket subject" }, "description": { "type": "string", "description": "Ticket description" }, "severity": { "type": "string", "description": "Severity (low, medium, high, critical)" }, "status": { "type": "string", "description": "Status (open, in_progress, resolved, closed)" }, "ticketType": { "type": "string", "description": "Ticket type (bug, feature_request, question, other)" }, "attachments": { "type": "array", "items": { "type": "string" }, "description": "Attachment objects with type info" }, "response": { "type": "string", "description": "Final support response when resolved" }, "resolvedAt": { "type": "string", "description": "ISO timestamp when the ticket was resolved" }, "resolvedBy": { "type": "string", "description": "User ID of the resolver" }, "createdAt": { "type": "string", "description": "ISO timestamp when the ticket was created" }, "updatedAt": { "type": "string", "description": "ISO timestamp when the ticket was last updated" } }, "description": "Support ticket object" } }, "pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total_count": { "type": "integer" }, "total_pages": { "type": "integer" }, "has_next": { "type": "boolean" }, "has_prev": { "type": "boolean" } }, "description": "Pagination metadata" } }, "description": "Paginated list of support tickets" } } } } }, "summary": "List support tickets accessible to the authenticated user.", "description": "Regular users only see their own tickets. Supports filtering by status,\nticket type, severity, free-text query, and pagination." } }, "/api/v0/support/tickets/{ticketId}": { "get": { "tags": [ "Support" ], "operationId": "support_getSupportTicket", "parameters": [ { "name": "ticketId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Ticket not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "The requested support ticket", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Ticket ID" }, "companyId": { "type": "string", "description": "Associated company ID (may be null for general tickets)" }, "userId": { "type": "string", "description": "User ID of the ticket creator" }, "whitelabelId": { "type": "string", "description": "Whitelabel instance ID if submitted from a whitelabel domain" }, "subject": { "type": "string", "description": "Ticket subject" }, "description": { "type": "string", "description": "Ticket description" }, "severity": { "type": "string", "description": "Severity (low, medium, high, critical)" }, "status": { "type": "string", "description": "Status (open, in_progress, resolved, closed)" }, "ticketType": { "type": "string", "description": "Ticket type (bug, feature_request, question, other)" }, "attachments": { "type": "array", "items": { "type": "string" }, "description": "Attachment objects with type info" }, "response": { "type": "string", "description": "Final support response when resolved" }, "resolvedAt": { "type": "string", "description": "ISO timestamp when the ticket was resolved" }, "resolvedBy": { "type": "string", "description": "User ID of the resolver" }, "createdAt": { "type": "string", "description": "ISO timestamp when the ticket was created" }, "updatedAt": { "type": "string", "description": "ISO timestamp when the ticket was last updated" } }, "description": "Support ticket object" } } } } }, "summary": "Get a single support ticket by ID." }, "put": { "tags": [ "Support" ], "operationId": "support_updateSupportTicket", "parameters": [ { "name": "ticketId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Ticket not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "The updated support ticket", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Ticket ID" }, "companyId": { "type": "string", "description": "Associated company ID (may be null for general tickets)" }, "userId": { "type": "string", "description": "User ID of the ticket creator" }, "whitelabelId": { "type": "string", "description": "Whitelabel instance ID if submitted from a whitelabel domain" }, "subject": { "type": "string", "description": "Ticket subject" }, "description": { "type": "string", "description": "Ticket description" }, "severity": { "type": "string", "description": "Severity (low, medium, high, critical)" }, "status": { "type": "string", "description": "Status (open, in_progress, resolved, closed)" }, "ticketType": { "type": "string", "description": "Ticket type (bug, feature_request, question, other)" }, "attachments": { "type": "array", "items": { "type": "string" }, "description": "Attachment objects with type info" }, "response": { "type": "string", "description": "Final support response when resolved" }, "resolvedAt": { "type": "string", "description": "ISO timestamp when the ticket was resolved" }, "resolvedBy": { "type": "string", "description": "User ID of the resolver" }, "createdAt": { "type": "string", "description": "ISO timestamp when the ticket was created" }, "updatedAt": { "type": "string", "description": "ISO timestamp when the ticket was last updated" } }, "description": "Support ticket object" } } } } }, "summary": "Update fields on an existing support ticket.", "description": "Include only the fields you want to change. Status and response fields\nmay be restricted to support/admin users.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "subject": { "type": "string", "description": "Short summary of the issue or request" }, "description": { "type": "string", "description": "Detailed description of the issue or request" }, "ticketType": { "type": "string", "description": "Ticket type (one of: bug, feature_request, question, other)" }, "severity": { "type": "string", "description": "Severity (one of: low, medium, high, critical)" }, "status": { "type": "string", "description": "Status (one of: open, in_progress, resolved, closed). Updating status may require support privileges." }, "attachments": { "type": "array", "items": { "type": "string" }, "description": "Replacement list of attachments" }, "response": { "type": "string", "description": "Support response text (support/admin only)" } }, "description": "Request body for updating a support ticket (only include fields to change)" } } }, "description": "Fields to update" } } }, "/api/v0/support/tickets/{ticketId}/messages": { "get": { "tags": [ "Support" ], "operationId": "support_listSupportTicketMessages", "parameters": [ { "name": "ticketId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Messages on the support ticket", "content": { "application/json": { "schema": { "type": "object", "properties": { "messages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Message ID" }, "ticketId": { "type": "string", "description": "Ticket ID this message belongs to" }, "userId": { "type": "string", "description": "User ID of the sender" }, "message": { "type": "string", "description": "Message body" }, "isFromSupport": { "type": "boolean", "description": "Whether the message was sent by a support agent" }, "attachments": { "type": "array", "items": { "type": "string" }, "description": "Attachment objects" }, "createdAt": { "type": "string", "description": "ISO timestamp when the message was created" }, "updatedAt": { "type": "string", "description": "ISO timestamp when the message was last updated" } }, "description": "Support ticket message object" } } }, "description": "List of messages for a support ticket" } } } } }, "summary": "List all messages on a support ticket, ordered oldest to newest." }, "post": { "tags": [ "Support" ], "operationId": "support_createSupportTicketMessage", "parameters": [ { "name": "ticketId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Ticket not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "201": { "description": "The created message", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Message ID" }, "ticketId": { "type": "string", "description": "Ticket ID this message belongs to" }, "userId": { "type": "string", "description": "User ID of the sender" }, "message": { "type": "string", "description": "Message body" }, "isFromSupport": { "type": "boolean", "description": "Whether the message was sent by a support agent" }, "attachments": { "type": "array", "items": { "type": "string" }, "description": "Attachment objects" }, "createdAt": { "type": "string", "description": "ISO timestamp when the message was created" }, "updatedAt": { "type": "string", "description": "ISO timestamp when the message was last updated" } }, "description": "Support ticket message object" } } } } }, "summary": "Post a new message (reply) to an existing support ticket.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Message body" }, "attachments": { "type": "array", "items": { "type": "string" }, "description": "Platform image IDs or support document IDs to attach to the message" } }, "required": [ "message" ], "description": "Request body for adding a new message to a ticket" } } }, "description": "Message to add to the ticket" } } }, "/api/v0/tags": { "get": { "tags": [ "Tags" ], "operationId": "tags_getTags", "parameters": [ { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID" }, "description": "Company ID" } ], "responses": { "400": { "description": "Missing companyId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "List of tags for the company", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Tag ID" }, "companyId": { "type": "string", "description": "Company ID" }, "name": { "type": "string", "description": "Tag name" }, "color": { "type": "string", "description": "Tag color (hex code)" }, "description": { "type": "string", "description": "Tag description" }, "created": { "type": "number", "description": "Creation timestamp" }, "updated": { "type": "number", "description": "Last update timestamp" } }, "description": "Tag object" }, "description": "List of tags" } }, "description": "List of tags" } } } } }, "summary": "Get all tags for a company." }, "post": { "tags": [ "Tags" ], "operationId": "tags_createTag", "parameters": [], "responses": { "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Created tag", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Tag ID" }, "companyId": { "type": "string", "description": "Company ID" }, "name": { "type": "string", "description": "Tag name" }, "color": { "type": "string", "description": "Tag color (hex code)" }, "description": { "type": "string", "description": "Tag description" }, "created": { "type": "number", "description": "Creation timestamp" }, "updated": { "type": "number", "description": "Last update timestamp" } }, "description": "Tag object" } } } } }, "summary": "Create a new tag.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "name": { "type": "string", "description": "Tag name" }, "color": { "type": "string", "description": "Tag color (hex code)" }, "description": { "type": "string", "description": "Tag description" } }, "required": [ "companyId", "name" ], "description": "Request body for creating a tag" } } }, "description": "Tag creation data" } } }, "/api/v0/tags/{tag_id}": { "put": { "tags": [ "Tags" ], "operationId": "tags_updateTag", "parameters": [ { "name": "tag_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Updated tag", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Tag ID" }, "companyId": { "type": "string", "description": "Company ID" }, "name": { "type": "string", "description": "Tag name" }, "color": { "type": "string", "description": "Tag color (hex code)" }, "description": { "type": "string", "description": "Tag description" }, "created": { "type": "number", "description": "Creation timestamp" }, "updated": { "type": "number", "description": "Last update timestamp" } }, "description": "Tag object" } } } } }, "summary": "Update a tag.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Tag name" }, "color": { "type": "string", "description": "Tag color (hex code)" }, "description": { "type": "string", "description": "Tag description" } }, "description": "Request body for updating a tag" } } }, "description": "Tag update data" } }, "delete": { "tags": [ "Tags" ], "operationId": "tags_deleteTag", "parameters": [ { "name": "tag_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Tag not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Tag deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message" } }, "description": "Success response" } } } } }, "summary": "Delete a tag." } }, "/api/v0/departments": { "get": { "tags": [ "Departments" ], "operationId": "departments_getDepartments", "parameters": [ { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID" }, "description": "Company ID" } ], "responses": { "400": { "description": "Missing companyId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "List of departments for the company", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Department ID" }, "companyId": { "type": "string", "description": "Company ID" }, "name": { "type": "string", "description": "Department name" }, "description": { "type": "string", "description": "Department description" }, "color": { "type": "string", "description": "Department color (hex code)" }, "created": { "type": "number", "description": "Creation timestamp" }, "updated": { "type": "number", "description": "Last update timestamp" } }, "description": "Department object" }, "description": "List of departments" } }, "description": "List of departments" } } } } }, "summary": "Get all departments for a company." }, "post": { "tags": [ "Departments" ], "operationId": "departments_createDepartment", "parameters": [], "responses": { "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Created department", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Department ID" }, "companyId": { "type": "string", "description": "Company ID" }, "name": { "type": "string", "description": "Department name" }, "description": { "type": "string", "description": "Department description" }, "color": { "type": "string", "description": "Department color (hex code)" }, "created": { "type": "number", "description": "Creation timestamp" }, "updated": { "type": "number", "description": "Last update timestamp" } }, "description": "Department object" } } } } }, "summary": "Create a new department.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "name": { "type": "string", "description": "Department name" }, "description": { "type": "string", "description": "Department description" }, "color": { "type": "string", "description": "Department color (hex code)" } }, "required": [ "companyId", "name" ], "description": "Request body for creating a department" } } }, "description": "Department creation data" } } }, "/api/v0/departments/{department_id}": { "put": { "tags": [ "Departments" ], "operationId": "departments_updateDepartment", "parameters": [ { "name": "department_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Updated department", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Department ID" }, "companyId": { "type": "string", "description": "Company ID" }, "name": { "type": "string", "description": "Department name" }, "description": { "type": "string", "description": "Department description" }, "color": { "type": "string", "description": "Department color (hex code)" }, "created": { "type": "number", "description": "Creation timestamp" }, "updated": { "type": "number", "description": "Last update timestamp" } }, "description": "Department object" } } } } }, "summary": "Update a department.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "name": { "type": "string", "description": "Department name" }, "description": { "type": "string", "description": "Department description" }, "color": { "type": "string", "description": "Department color (hex code)" } }, "required": [ "companyId" ], "description": "Request body for updating a department" } } }, "description": "Department update data" } }, "delete": { "tags": [ "Departments" ], "operationId": "departments_deleteDepartment", "parameters": [ { "name": "department_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID" }, "description": "Company ID" } ], "responses": { "400": { "description": "Missing companyId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Department deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message" } }, "description": "Success response" } } } } }, "summary": "Delete a department." } }, "/api/v0/employees/{employee_id}/departments": { "get": { "tags": [ "Departments" ], "operationId": "departments_getEmployeeDepartments", "parameters": [ { "name": "employee_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID" }, "description": "Company ID" } ], "responses": { "400": { "description": "Missing companyId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "List of departments assigned to the employee", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Department ID" }, "companyId": { "type": "string", "description": "Company ID" }, "name": { "type": "string", "description": "Department name" }, "description": { "type": "string", "description": "Department description" }, "color": { "type": "string", "description": "Department color (hex code)" }, "created": { "type": "number", "description": "Creation timestamp" }, "updated": { "type": "number", "description": "Last update timestamp" } }, "description": "Department object" }, "description": "List of departments" } }, "description": "List of departments" } } } } }, "summary": "Get departments assigned to an employee." }, "put": { "tags": [ "Departments" ], "operationId": "departments_assignEmployeeDepartments", "parameters": [ { "name": "employee_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Missing companyId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Employee departments updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message" } }, "description": "Success response" } } } } }, "summary": "Assign departments to an employee.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "departmentIds": { "type": "array", "items": { "type": "string" }, "description": "List of department IDs to assign" } }, "required": [ "companyId", "departmentIds" ], "description": "Request body for assigning departments" } } }, "description": "Department assignment data" } } }, "/api/v0/company-users/{company_user_id}/departments": { "get": { "tags": [ "Departments" ], "operationId": "departments_getUserDepartments", "parameters": [ { "name": "company_user_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID" }, "description": "Company ID" } ], "responses": { "400": { "description": "Missing companyId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "List of departments assigned to the user", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Department ID" }, "companyId": { "type": "string", "description": "Company ID" }, "name": { "type": "string", "description": "Department name" }, "description": { "type": "string", "description": "Department description" }, "color": { "type": "string", "description": "Department color (hex code)" }, "created": { "type": "number", "description": "Creation timestamp" }, "updated": { "type": "number", "description": "Last update timestamp" } }, "description": "Department object" }, "description": "List of departments" } }, "description": "List of departments" } } } } }, "summary": "Get departments assigned to a company user." }, "put": { "tags": [ "Departments" ], "operationId": "departments_assignUserDepartments", "parameters": [ { "name": "company_user_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Missing companyId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "User departments updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message" } }, "description": "Success response" } } } } }, "summary": "Assign departments to a company user (member).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "departmentIds": { "type": "array", "items": { "type": "string" }, "description": "List of department IDs to assign" } }, "required": [ "companyId", "departmentIds" ], "description": "Request body for assigning departments" } } }, "description": "Department assignment data" } } }, "/api/v0/documentation/categories": { "get": { "tags": [ "Documentation" ], "operationId": "documentation_listDocumentationCategories", "parameters": [], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Top-level documentation categories", "content": { "application/json": { "schema": { "type": "object", "properties": { "parentId": { "type": "string", "description": "Parent the listing is scoped to (null for top-level)" }, "pages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Page ID" }, "parentId": { "type": "string", "description": "Parent page ID (null for top-level)" }, "whitelabelId": { "type": "string", "description": "Whitelabel instance ID" }, "title": { "type": "string", "description": "Page title" }, "slug": { "type": "string", "description": "Page slug" }, "icon": { "type": "string", "description": "Optional icon name" }, "sortOrder": { "type": "integer", "description": "Sort order within its parent" }, "childCount": { "type": "integer", "description": "Number of direct child pages (0 if it is a leaf page)" } }, "description": "Documentation page summary (no content body)" } } }, "description": "List of documentation page summaries. Fetch full content via GET /api/v0/documentation/{id}." } } } } }, "summary": "List top-level documentation categories (pages with no parent).", "description": "Use this first to see what areas of documentation exist, then call\nGET /api/v0/documentation?parentId={id} to drill into one." } }, "/api/v0/documentation": { "get": { "tags": [ "Documentation" ], "operationId": "documentation_listDocumentationPages", "parameters": [ { "name": "parentId", "in": "query", "required": false, "schema": { "type": "string", "description": "Parent page ID to list children of. Omit to list top-level categories." }, "description": "Parent page ID to list children of. Omit to list top-level categories." } ], "responses": { "400": { "description": "Invalid parentId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "List of documentation page summaries", "content": { "application/json": { "schema": { "type": "object", "properties": { "parentId": { "type": "string", "description": "Parent the listing is scoped to (null for top-level)" }, "pages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Page ID" }, "parentId": { "type": "string", "description": "Parent page ID (null for top-level)" }, "whitelabelId": { "type": "string", "description": "Whitelabel instance ID" }, "title": { "type": "string", "description": "Page title" }, "slug": { "type": "string", "description": "Page slug" }, "icon": { "type": "string", "description": "Optional icon name" }, "sortOrder": { "type": "integer", "description": "Sort order within its parent" }, "childCount": { "type": "integer", "description": "Number of direct child pages (0 if it is a leaf page)" } }, "description": "Documentation page summary (no content body)" } } }, "description": "List of documentation page summaries. Fetch full content via GET /api/v0/documentation/{id}." } } } } }, "summary": "List documentation pages.", "description": "Omit ``parentId`` to list top-level categories, or pass a parent page ID\nto list its direct children. Responses exclude the full page content so\npayloads stay small \u2014 fetch a specific page with\nGET /api/v0/documentation/{id} when you need the body." } }, "/api/v0/documentation/{pageId}": { "get": { "tags": [ "Documentation" ], "operationId": "documentation_getDocumentationPage", "parameters": [ { "name": "pageId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid page ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Page not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "The requested documentation page", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Page ID (UUID)" }, "whitelabelId": { "type": "string", "description": "Whitelabel instance ID (null for global pages)" }, "parentId": { "type": "string", "description": "Parent page ID for hierarchy (null for top-level pages)" }, "title": { "type": "string", "description": "Page title" }, "slug": { "type": "string", "description": "URL-friendly identifier" }, "content": { "type": "string", "description": "Markdown content of the page" }, "sortOrder": { "type": "integer", "description": "Sort order within the parent" }, "icon": { "type": "string", "description": "Optional icon name" }, "isPublished": { "type": "boolean", "description": "Whether the page is published" }, "createdAt": { "type": "string", "description": "ISO timestamp when the page was created" }, "updatedAt": { "type": "string", "description": "ISO timestamp when the page was last updated" } }, "description": "Documentation page object" } } } } }, "summary": "Get a documentation page by ID." } }, "/api/v0/documentation/search": { "get": { "tags": [ "Documentation" ], "operationId": "documentation_searchDocumentation", "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "description": "Keywords to search the documentation for" }, "description": "Keywords to search the documentation for" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "description": "Maximum number of results (default: 5, max: 50)", "default": 5 }, "description": "Maximum number of results (default: 5, max: 50)" }, { "name": "snippetChars", "in": "query", "required": false, "schema": { "type": "integer", "description": "Approximate length of each matching snippet (default: 300)", "default": 300 }, "description": "Approximate length of each matching snippet (default: 300)" }, { "name": "maxSnippets", "in": "query", "required": false, "schema": { "type": "integer", "description": "Maximum snippets returned per page (default: 3)", "default": 3 }, "description": "Maximum snippets returned per page (default: 3)" } ], "responses": { "400": { "description": "Missing or invalid query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Keyword search results", "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "description": "Original query" }, "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Page ID" }, "title": { "type": "string", "description": "Page title" }, "slug": { "type": "string", "description": "Page slug" }, "score": { "type": "integer", "description": "Match score (higher = more matched tokens; title matches weighted 3x)" }, "snippets": { "type": "array", "items": { "type": "string" }, "description": "Excerpts of content around the keyword matches" }, "parentId": { "type": "string", "description": "Parent page ID" }, "whitelabelId": { "type": "string", "description": "Whitelabel instance ID if scoped" } }, "description": "Documentation search result (a page plus match snippets)" } } }, "description": "Keyword search results. Fetch a full page with GET /api/v0/documentation/{id}." } } } } }, "summary": "Keyword search over documentation pages.", "description": "Matches are ranked by how many query tokens appear in the title (weighted)\nand content, and each result includes short snippets around the matches\nso the caller can decide whether to fetch the full page via\nGET /api/v0/documentation/{id}." } }, "/api/v0/documentation/requests": { "post": { "tags": [ "Documentation" ], "operationId": "documentation_submitDocumentationRequest", "parameters": [], "responses": { "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "201": { "description": "Documentation request accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "ticketId": { "type": "string", "description": "Support ticket ID created to track this request" }, "status": { "type": "string", "description": "Ticket status (typically \"open\")" }, "topic": { "type": "string", "description": "The requested topic" }, "createdAt": { "type": "string", "description": "ISO timestamp when the request was created" } }, "description": "Documentation request submission confirmation" } } } } }, "summary": "Submit a request for new or improved documentation.", "description": "Creates a support ticket of type \"feature_request\" tagged as a\ndocumentation request so the docs team can triage it alongside\nother feedback.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "topic": { "type": "string", "description": "Short topic / title for the documentation being requested" }, "details": { "type": "string", "description": "Detailed description of what should be documented, what is missing, and any context that would help." }, "relatedSlug": { "type": "string", "description": "Optional slug of an existing documentation page that is related or incomplete" } }, "required": [ "topic", "details" ], "description": "Request body for submitting a documentation request" } } }, "description": "Details of the documentation request" } } }, "/api/v0/crm/integrations": { "get": { "tags": [ "Integrations" ], "operationId": "crm_getCrmIntegrations", "parameters": [], "responses": { "400": { "description": "companyId is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Enabled CRM integrations", "content": { "application/json": { "schema": { "type": "object", "properties": { "integrations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "CRM integration ID \u2014 the value to put in a sequence crmIntegrationId." }, "type": { "type": "string", "description": "CRM type (hubspot, gohighlevel, salesforce)." }, "name": { "type": "string", "description": "Display name." }, "instanceName": { "type": "string", "description": "Account/instance name." }, "status": { "type": "string", "description": "Connection status." }, "lastSync": { "type": "string", "description": "Last sync timestamp." }, "created_date": { "type": "string", "description": "Creation timestamp." } }, "description": "CRM integration summary item" }, "description": "Enabled CRM integrations." } }, "description": "List of enabled CRM integrations for a company" } } } } }, "summary": "List enabled CRM integrations, to discover a valid crmIntegrationId.", "description": "Use the returned id when setting a sequence's crmIntegrationId (with\ncrmSyncEnabled=true). Pass companyId as a query parameter." } }, "/api/v0/design-styles": { "get": { "tags": [ "Websites" ], "operationId": "design_styles_listDesignStyles", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Page number, 1-indexed (default 1)" }, "description": "Page number, 1-indexed (default 1)" }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "description": "Styles per page, 1-100 (default 24)" }, "description": "Styles per page, 1-100 (default 24)" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "description": "Match on name, description or category (e.g. \"minimal\", \"bold\", \"luxury\")" }, "description": "Match on name, description or category (e.g. \"minimal\", \"bold\", \"luxury\")" }, { "name": "category", "in": "query", "required": false, "schema": { "type": "string", "description": "Only styles in this category (one of the categories this list returns)" }, "description": "Only styles in this category (one of the categories this list returns)" }, { "name": "medium", "in": "query", "required": false, "schema": { "type": "string", "description": "Only styles with an example for this medium: website, blog, social, story or email. Use \"website\" when picking a style for a new website." }, "description": "Only styles with an example for this medium: website, blog, social, story or email. Use \"website\" when picking a style for a new website." } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "A page of the design style library", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "string" }, "description": "Styles in library order: {id, slug, name, category, description, mediums}. mediums maps each medium to {width, height, imageUrl}, a preview image of the style. Pass id as designStyleId when creating a website." }, "total": { "type": "integer" }, "categories": { "type": "array", "items": { "type": "string" }, "description": "Every category, for the category filter" } } } } } } }, "summary": "List design styles for a new website", "description": "The design style library: preset looks (layout, typography, color and\nmood) the website builder designs a new site in. Pick one whose name,\ncategory and description fit the site \u2014 filter with medium=website and\nsearch \u2014 and pass its id as designStyleId when creating the website. The\nbuilder agent follows the style on the site's first build. A brand kit\n(brandKitId) wins over a design style when both are given." } }, "/api/v0/landing-pages": { "get": { "tags": [ "Landing Pages" ], "operationId": "landing_pages_getLandingPages", "parameters": [ { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID" }, "description": "Company ID" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Page number" }, "description": "Page number" }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "description": "Items per page" }, "description": "Items per page" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "description": "Filter by status (draft, published, archived)" }, "description": "Filter by status (draft, published, archived)" } ], "responses": { "400": { "description": "Missing companyId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Paginated list of landing pages", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Landing page ID" }, "name": { "type": "string", "description": "Landing page name" }, "description": { "type": "string", "description": "Description" }, "status": { "type": "string", "description": "Status: draft, published, archived" }, "publicSlug": { "type": "string", "description": "Public URL slug" }, "publicUrl": { "type": "string", "description": "Full public URL" }, "isPublished": { "type": "boolean", "description": "Whether page is published" }, "htmlContent": { "type": "string", "description": "HTML content" }, "seoMetadata": { "type": "object", "description": "SEO metadata" }, "projectId": { "type": "string", "description": "Associated project ID" }, "listId": { "type": "string", "description": "Attached smart list ID" }, "designStyleId": { "type": "string", "description": "Seed design style library preset ID" }, "domainId": { "type": "string", "description": "Custom domain ID" }, "created": { "type": "number", "description": "Creation timestamp" }, "updated": { "type": "number", "description": "Last update timestamp" } }, "description": "Landing page object" }, "description": "Landing pages" }, "total": { "type": "integer", "description": "Total count" }, "page": { "type": "integer", "description": "Current page" }, "pageSize": { "type": "integer", "description": "Items per page" } }, "description": "List of landing pages" } } } } }, "summary": "Get paginated list of landing pages." }, "post": { "tags": [ "Landing Pages" ], "operationId": "landing_pages_createLandingPage", "parameters": [], "responses": { "400": { "description": "Missing required fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Created landing page", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Landing page ID" }, "name": { "type": "string", "description": "Landing page name" }, "description": { "type": "string", "description": "Description" }, "status": { "type": "string", "description": "Status: draft, published, archived" }, "publicSlug": { "type": "string", "description": "Public URL slug" }, "publicUrl": { "type": "string", "description": "Full public URL" }, "isPublished": { "type": "boolean", "description": "Whether page is published" }, "htmlContent": { "type": "string", "description": "HTML content" }, "seoMetadata": { "type": "object", "description": "SEO metadata" }, "projectId": { "type": "string", "description": "Associated project ID" }, "listId": { "type": "string", "description": "Attached smart list ID" }, "designStyleId": { "type": "string", "description": "Seed design style library preset ID" }, "domainId": { "type": "string", "description": "Custom domain ID" }, "created": { "type": "number", "description": "Creation timestamp" }, "updated": { "type": "number", "description": "Last update timestamp" } }, "description": "Landing page object" } } } } }, "summary": "Create a new landing page.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "name": { "type": "string", "description": "Landing page name" }, "description": { "type": "string", "description": "Optional description" }, "initialPrompt": { "type": "string", "description": "Initial prompt for AI" }, "brandKitId": { "type": "string", "description": "ID of existing brand kit to link" }, "artifactsId": { "type": "string", "description": "Legacy alias for brandKitId" }, "listId": { "type": "string", "description": "ID of smart list to attach for form capture" }, "designStyleId": { "type": "string", "description": "ID of a design style library preset that seeds the first build" } }, "required": [ "companyId", "name" ], "description": "Request body for creating a landing page" } } }, "description": "Landing page details" } } }, "/api/v0/landing-pages/{page_id}": { "get": { "tags": [ "Landing Pages" ], "operationId": "landing_pages_getLandingPage", "parameters": [ { "name": "page_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID" }, "description": "Company ID" } ], "responses": { "400": { "description": "Missing companyId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Landing page with HTML content", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Landing page ID" }, "name": { "type": "string", "description": "Landing page name" }, "description": { "type": "string", "description": "Description" }, "status": { "type": "string", "description": "Status: draft, published, archived" }, "publicSlug": { "type": "string", "description": "Public URL slug" }, "publicUrl": { "type": "string", "description": "Full public URL" }, "isPublished": { "type": "boolean", "description": "Whether page is published" }, "htmlContent": { "type": "string", "description": "HTML content" }, "seoMetadata": { "type": "object", "description": "SEO metadata" }, "projectId": { "type": "string", "description": "Associated project ID" }, "listId": { "type": "string", "description": "Attached smart list ID" }, "designStyleId": { "type": "string", "description": "Seed design style library preset ID" }, "domainId": { "type": "string", "description": "Custom domain ID" }, "created": { "type": "number", "description": "Creation timestamp" }, "updated": { "type": "number", "description": "Last update timestamp" } }, "description": "Landing page object" } } } } }, "summary": "Get a landing page by ID with HTML content." }, "patch": { "tags": [ "Landing Pages" ], "operationId": "landing_pages_updateLandingPage", "parameters": [ { "name": "page_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Missing companyId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Updated landing page", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Landing page ID" }, "name": { "type": "string", "description": "Landing page name" }, "description": { "type": "string", "description": "Description" }, "status": { "type": "string", "description": "Status: draft, published, archived" }, "publicSlug": { "type": "string", "description": "Public URL slug" }, "publicUrl": { "type": "string", "description": "Full public URL" }, "isPublished": { "type": "boolean", "description": "Whether page is published" }, "htmlContent": { "type": "string", "description": "HTML content" }, "seoMetadata": { "type": "object", "description": "SEO metadata" }, "projectId": { "type": "string", "description": "Associated project ID" }, "listId": { "type": "string", "description": "Attached smart list ID" }, "designStyleId": { "type": "string", "description": "Seed design style library preset ID" }, "domainId": { "type": "string", "description": "Custom domain ID" }, "created": { "type": "number", "description": "Creation timestamp" }, "updated": { "type": "number", "description": "Last update timestamp" } }, "description": "Landing page object" } } } } }, "summary": "Update landing page metadata.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "name": { "type": "string", "description": "New name" }, "description": { "type": "string", "description": "New description" }, "seoMetadata": { "type": "object", "description": "SEO metadata" }, "status": { "type": "string", "description": "New status: draft, published, archived" }, "listId": { "type": "string", "description": "Smart list ID for form capture" }, "domainId": { "type": "string", "description": "Domain ID for custom domain publishing" } }, "required": [ "companyId" ], "description": "Request body for updating a landing page" } } }, "description": "Landing page updates" } }, "delete": { "tags": [ "Landing Pages" ], "operationId": "landing_pages_deleteLandingPage", "parameters": [ { "name": "page_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID" }, "description": "Company ID" } ], "responses": { "400": { "description": "Missing companyId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Success status", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Success status" } }, "description": "Success response" } } } } }, "summary": "Delete a landing page." } }, "/api/v0/landing-pages/{page_id}/content": { "put": { "tags": [ "Landing Pages" ], "operationId": "landing_pages_updateLandingPageContent", "parameters": [ { "name": "page_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Missing required fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Updated landing page", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Landing page ID" }, "name": { "type": "string", "description": "Landing page name" }, "description": { "type": "string", "description": "Description" }, "status": { "type": "string", "description": "Status: draft, published, archived" }, "publicSlug": { "type": "string", "description": "Public URL slug" }, "publicUrl": { "type": "string", "description": "Full public URL" }, "isPublished": { "type": "boolean", "description": "Whether page is published" }, "htmlContent": { "type": "string", "description": "HTML content" }, "seoMetadata": { "type": "object", "description": "SEO metadata" }, "projectId": { "type": "string", "description": "Associated project ID" }, "listId": { "type": "string", "description": "Attached smart list ID" }, "designStyleId": { "type": "string", "description": "Seed design style library preset ID" }, "domainId": { "type": "string", "description": "Custom domain ID" }, "created": { "type": "number", "description": "Creation timestamp" }, "updated": { "type": "number", "description": "Last update timestamp" } }, "description": "Landing page object" } } } } }, "summary": "Update the HTML content of a landing page.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "htmlContent": { "type": "string", "description": "HTML content" } }, "required": [ "companyId", "htmlContent" ], "description": "Request body for updating landing page HTML content" } } }, "description": "HTML content" } } }, "/api/v0/landing-pages/{page_id}/publish": { "post": { "tags": [ "Landing Pages" ], "operationId": "landing_pages_publishLandingPage", "parameters": [ { "name": "page_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Missing companyId or invalid content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Published landing page with public URL", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Landing page ID" }, "name": { "type": "string", "description": "Landing page name" }, "description": { "type": "string", "description": "Description" }, "status": { "type": "string", "description": "Status: draft, published, archived" }, "publicSlug": { "type": "string", "description": "Public URL slug" }, "publicUrl": { "type": "string", "description": "Full public URL" }, "isPublished": { "type": "boolean", "description": "Whether page is published" }, "htmlContent": { "type": "string", "description": "HTML content" }, "seoMetadata": { "type": "object", "description": "SEO metadata" }, "projectId": { "type": "string", "description": "Associated project ID" }, "listId": { "type": "string", "description": "Attached smart list ID" }, "designStyleId": { "type": "string", "description": "Seed design style library preset ID" }, "domainId": { "type": "string", "description": "Custom domain ID" }, "created": { "type": "number", "description": "Creation timestamp" }, "updated": { "type": "number", "description": "Last update timestamp" } }, "description": "Landing page object" } } } } }, "summary": "Publish a landing page to make it publicly accessible.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" } }, "required": [ "companyId" ], "description": "Request body for publishing a landing page" } } }, "description": "Company ID" } } }, "/api/v0/landing-pages/{page_id}/unpublish": { "post": { "tags": [ "Landing Pages" ], "operationId": "landing_pages_unpublishLandingPage", "parameters": [ { "name": "page_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Missing companyId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Unpublished landing page", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Landing page ID" }, "name": { "type": "string", "description": "Landing page name" }, "description": { "type": "string", "description": "Description" }, "status": { "type": "string", "description": "Status: draft, published, archived" }, "publicSlug": { "type": "string", "description": "Public URL slug" }, "publicUrl": { "type": "string", "description": "Full public URL" }, "isPublished": { "type": "boolean", "description": "Whether page is published" }, "htmlContent": { "type": "string", "description": "HTML content" }, "seoMetadata": { "type": "object", "description": "SEO metadata" }, "projectId": { "type": "string", "description": "Associated project ID" }, "listId": { "type": "string", "description": "Attached smart list ID" }, "designStyleId": { "type": "string", "description": "Seed design style library preset ID" }, "domainId": { "type": "string", "description": "Custom domain ID" }, "created": { "type": "number", "description": "Creation timestamp" }, "updated": { "type": "number", "description": "Last update timestamp" } }, "description": "Landing page object" } } } } }, "summary": "Unpublish a landing page to remove public access.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" } }, "required": [ "companyId" ], "description": "Request body for publishing a landing page" } } }, "description": "Company ID" } } }, "/api/v0/landing-pages/{page_id}/preview": { "get": { "tags": [ "Landing Pages" ], "operationId": "landing_pages_getLandingPagePreview", "parameters": [ { "name": "page_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID" }, "description": "Company ID" } ], "responses": { "400": { "description": "Missing companyId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Landing page preview HTML", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "description": "HTML content" }, "renderedContent": { "type": "string", "description": "HTML content with brand kit head content (favicon, head scripts) as served publicly" }, "publicSlug": { "type": "string", "description": "Public slug" }, "isPublished": { "type": "boolean", "description": "Whether published" } }, "description": "Landing page preview" } } } } }, "summary": "Get the current preview HTML content from the landing page's project." } }, "/api/v0/landing-pages/{page_id}/chat-history": { "put": { "tags": [ "Landing Pages" ], "operationId": "landing_pages_saveChatHistory", "parameters": [ { "name": "page_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Missing required fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Success status", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Success status" } }, "description": "Success response" } } } } }, "summary": "Save chat history for a landing page.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "chatHistory": { "type": "array", "items": { "type": "object" }, "description": "Chat messages" } }, "required": [ "companyId", "chatHistory" ], "description": "Request body for saving chat history" } } }, "description": "Chat history to save" } } }, "/api/v0/landing-pages/{page_id}/chat": { "post": { "tags": [ "Landing Pages" ], "operationId": "landing_pages_landingPageChat", "parameters": [ { "name": "page_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Missing required fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Chat endpoint for the AI website builder.", "description": "Shares the app builder's agent loop and typed SSE protocol (text /\ntool_call / tool_result / files_changed / done / error). The thread is the\nsource of truth: history is loaded from the landing page's stored threads,\nthe user message is persisted immediately, and the assistant message\n(with its tool-call log) is persisted when the stream ends \u2014 the client\nnever bulk-saves history.\n\nLegacy clients (no `clientMessageId`, inline `messages` history) still get\nthe old raw-text stream so an older frontend keeps working.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "message": { "type": "string", "description": "User message" }, "messages": { "type": "array", "items": { "type": "object" }, "description": "Previous chat messages (legacy clients only \u2014 thread history is stored server-side)" }, "threadId": { "type": "string", "description": "Chat thread to append to (defaults to the active thread)" }, "clientMessageId": { "type": "string", "description": "Client-generated id for the user message (dedupe)" }, "attachments": { "type": "array", "items": { "type": "object" }, "description": "Uploaded image attachments (design references)" } }, "required": [ "companyId", "message" ], "description": "Request body for AI chat" } } }, "description": "Chat message" } } }, "/api/v0/landing-pages/{page_id}/threads": { "get": { "tags": [ "Landing Pages" ], "operationId": "landing_pages_listLandingPageThreads", "parameters": [ { "name": "page_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "List chat threads for a landing page ({threads, activeThreadId})." }, "post": { "tags": [ "Landing Pages" ], "operationId": "landing_pages_createLandingPageThread", "parameters": [ { "name": "page_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Missing required fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Create a new chat thread (becomes the active thread).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "title": { "type": "string", "description": "Optional thread title" } }, "required": [ "companyId" ], "description": "Request body for creating a chat thread" } } }, "description": "Thread to create" } } }, "/api/v0/landing-pages/{page_id}/threads/{thread_id}": { "get": { "tags": [ "Landing Pages" ], "operationId": "landing_pages_getLandingPageThread", "parameters": [ { "name": "thread_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Get one thread's messages." }, "patch": { "tags": [ "Landing Pages" ], "operationId": "landing_pages_updateLandingPageThread", "parameters": [ { "name": "thread_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Missing required fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Rename a thread (`title`) or make it active (`active: true`).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "title": { "type": "string", "description": "New thread title" }, "active": { "type": "boolean", "description": "Set true to make this the active thread" } }, "required": [ "companyId" ], "description": "Request body for updating a chat thread" } } }, "description": "Rename or activate a thread" } }, "delete": { "tags": [ "Landing Pages" ], "operationId": "landing_pages_deleteLandingPageThread", "parameters": [ { "name": "thread_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Delete a thread; returns the refreshed thread view." } }, "/api/v0/landing-pages/{page_id}/threads/{thread_id}/stop": { "post": { "tags": [ "Landing Pages" ], "operationId": "landing_pages_stopLandingPageThreadRun", "parameters": [ { "name": "thread_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Missing required fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Ask the thread's in-flight agent run to wrap up (same signal a new", "description": "message sends; the partial reply is already saved)." } }, "/api/v0/landing-pages/{page_id}/upload": { "post": { "tags": [ "Landing Pages" ], "operationId": "landing_pages_landingPageChatUpload", "parameters": [ { "name": "page_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid file", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Upload an image to attach as a design reference in the AI chat." } }, "/api/v0/scheduled-tasks": { "get": { "tags": [ "Scheduled Tasks" ], "operationId": "scheduled_tasks_listScheduledTasks", "parameters": [ { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string", "description": "Company ID. Optional when the API key is a company key; required for personal access keys unless X-Company-ID is set." }, "description": "Company ID. Optional when the API key is a company key; required for personal access keys unless X-Company-ID is set." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Page number, 1-indexed (default: 1)" }, "description": "Page number, 1-indexed (default: 1)" }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "description": "Tasks per page (default: 20)" }, "description": "Tasks per page (default: 20)" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "description": "Filter by status: active, paused, or completed", "enum": [ "active", "paused", "completed" ] }, "description": "Filter by status: active, paused, or completed" }, { "name": "includeCompleted", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Include completed one-time tasks (default: false)" }, "description": "Include completed one-time tasks (default: false)" } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Paged list of scheduled tasks", "content": { "application/json": { "schema": { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "userId": { "type": "string", "description": "User who owns the task" }, "employeeId": { "type": "string" }, "name": { "type": "string" }, "prompt": { "type": "string" }, "scheduleType": { "type": "string", "description": "one_time, recurring, or heartbeat" }, "scheduledAt": { "type": "string", "description": "One-time tasks: ISO 8601 run time" }, "recurringConfig": { "type": "object", "description": "Recurring or heartbeat schedule details" }, "contextSettings": { "type": "object", "description": "Tool and context settings for runs" }, "timezone": { "type": "string" }, "nextRunAt": { "type": "string", "description": "ISO 8601 time of the next run, null when none" }, "lastRunAt": { "type": "string", "description": "ISO 8601 time of the last run, null when never run" }, "status": { "type": "string", "description": "active, paused, or completed" }, "runCount": { "type": "integer" }, "dailyCreditLimit": { "type": "number" }, "templateId": { "type": "string" }, "templateVersion": { "type": "integer" }, "createdDate": { "type": "string" }, "updatedDate": { "type": "string" } }, "description": "Scheduled task" } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "pageSize": { "type": "integer" }, "totalPages": { "type": "integer" } }, "description": "Paged list of scheduled tasks" } } } } }, "summary": "List scheduled tasks for a company." }, "post": { "tags": [ "Scheduled Tasks" ], "operationId": "scheduled_tasks_createScheduledTask", "parameters": [], "responses": { "400": { "description": "Missing or invalid fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "201": { "description": "The created task", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "userId": { "type": "string", "description": "User who owns the task" }, "employeeId": { "type": "string" }, "name": { "type": "string" }, "prompt": { "type": "string" }, "scheduleType": { "type": "string", "description": "one_time, recurring, or heartbeat" }, "scheduledAt": { "type": "string", "description": "One-time tasks: ISO 8601 run time" }, "recurringConfig": { "type": "object", "description": "Recurring or heartbeat schedule details" }, "contextSettings": { "type": "object", "description": "Tool and context settings for runs" }, "timezone": { "type": "string" }, "nextRunAt": { "type": "string", "description": "ISO 8601 time of the next run, null when none" }, "lastRunAt": { "type": "string", "description": "ISO 8601 time of the last run, null when never run" }, "status": { "type": "string", "description": "active, paused, or completed" }, "runCount": { "type": "integer" }, "dailyCreditLimit": { "type": "number" }, "templateId": { "type": "string" }, "templateVersion": { "type": "integer" }, "createdDate": { "type": "string" }, "updatedDate": { "type": "string" } }, "description": "Scheduled task" } } } } }, "summary": "Create a scheduled task for an AI employee.", "description": "scheduleType is one_time (needs scheduledAt), recurring (needs\nrecurringConfig.frequency and time) or heartbeat (needs\nrecurringConfig.interval, optionally activeHoursStart/activeHoursEnd and\ndaysOfWeek). The task runs with the employee's chat settings unless\ncontextSettings is given.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID. Optional when the API key is a company key." }, "employeeId": { "type": "string", "description": "ID of the AI employee that runs the task" }, "name": { "type": "string", "description": "Short descriptive name" }, "prompt": { "type": "string", "description": "The instruction the employee executes on every run. Be specific." }, "scheduleType": { "type": "string", "description": "one_time (default), recurring, or heartbeat", "enum": [ "one_time", "recurring", "heartbeat" ] }, "scheduledAt": { "type": "string", "description": "One-time tasks: ISO 8601 datetime to run at" }, "recurringConfig": { "type": "object", "properties": { "frequency": { "type": "string", "description": "Recurring tasks: daily, weekly, or monthly", "enum": [ "daily", "weekly", "monthly" ] }, "time": { "type": "string", "description": "Recurring tasks: time of day to run, HH:MM in the task timezone" }, "daysOfWeek": { "type": "array", "items": { "type": "integer" }, "description": "Weekly recurring and heartbeat tasks: days the task may run, 0=Sunday .. 6=Saturday. Heartbeat tasks run every day when omitted." }, "dayOfMonth": { "type": "integer", "description": "Monthly recurring tasks: day of the month (1-31)" }, "interval": { "type": "string", "description": "Heartbeat tasks: how often to run. One of 5m, 15m, 30m, 1h, 2h, 4h, 8h, 12h, 24h", "enum": [ "5m", "15m", "30m", "1h", "2h", "4h", "8h", "12h", "24h" ] }, "activeHoursStart": { "type": "string", "description": "Heartbeat tasks: start of the daily active window, HH:MM. Omit for 24/7." }, "activeHoursEnd": { "type": "string", "description": "Heartbeat tasks: end of the daily active window, HH:MM. Omit for 24/7." } }, "description": "Schedule details for recurring and heartbeat tasks" }, "timezone": { "type": "string", "description": "IANA timezone the schedule is expressed in (default: UTC)" }, "contextSettings": { "type": "object", "properties": { "platformTools": { "type": "boolean", "description": "Enable company-scoped platform tools" }, "scheduledTemplateSetup": { "type": "object", "description": "Scheduled template resource and integration selections (no credentials)" }, "model": { "type": "string", "description": "AI model to use (e.g., gpt-5-nano, claude-sonnet-5)" }, "temperature": { "type": "number", "description": "Temperature for model variation (0.0-1.0). Default: 0.7" }, "reasoningEffort": { "type": "string", "description": "Reasoning effort for models that support reasoning tokens. Valid values: \"none\", \"minimal\", \"low\", \"medium\", \"high\", \"xhigh\". Empty string means use model default.", "enum": [ "", "none", "minimal", "low", "medium", "high", "xhigh" ] }, "strategy": { "type": "string", "description": "Response strategy. Valid values: \"one-shot\", \"chain\", \"function-chain\", \"langchain\". Default: \"function-chain\"", "enum": [ "one-shot", "chain", "function-chain", "langchain" ] }, "memoryScope": { "type": "string", "description": "Memory scope for context retrieval. Valid values: \"chat\", \"company\", \"global\". Default: \"chat\"", "enum": [ "chat", "company", "global" ] }, "shortTermMemories": { "type": "boolean", "description": "Include short-term memories in context. Default: true" }, "longTermMemories": { "type": "boolean", "description": "Include long-term memories in context. Default: false" }, "documents": { "type": "boolean", "description": "Enable document retrieval from knowledge base. Default: true" }, "documentScope": { "type": "string", "description": "Document scope for retrieval. Valid values: \"root\", \"folder\", \"file\", \"tags\". Default: \"root\"", "enum": [ "root", "folder", "file", "tags" ] }, "documentStrategy": { "type": "string", "description": "Document retrieval strategy. Default: \"similarity-ranking\"" }, "documentPath": { "type": "string", "description": "Document path for scoping retrieval. Default: \"/\"" }, "requestDocuments": { "type": "array", "items": { "type": "object" }, "description": "Specific documents to include in context. Array of {id: string, name?: string, path?: string} objects" }, "searchEngine": { "type": "boolean", "description": "Enable web search via search engine. Default: false" }, "websites": { "type": "boolean", "description": "Enable website content retrieval. Default: false" }, "websitesJs": { "type": "boolean", "description": "Enable JavaScript-rendered website reading. Default: false" }, "news": { "type": "boolean", "description": "Enable online news search. Default: false" }, "company": { "type": "boolean", "description": "Include company context. Default: true" }, "employee": { "type": "boolean", "description": "Include employee context. Default: true" }, "responseInstructions": { "type": "boolean", "description": "Include response instructions in context. Default: true" }, "image": { "type": "string", "description": "Image URL for vision models" }, "lists": { "type": "boolean", "description": "Enable access to lists feature. Default: false" }, "browserTask": { "type": "object", "description": "Browser task configuration: {integrationId: string, task: string, useVision?: boolean} for web automation" }, "documentCreation": { "type": "boolean", "description": "Enable document creation tool. Default: false" }, "inboxId": { "type": "string", "description": "ID of an inbox the employee works from. When set, the employee gets inbox tools (list with a live provider pull, read, send, reply, forward, mark handled) and uses this inbox for email by default. Empty: no inbox" }, "sleepTool": { "type": "boolean", "description": "Enable the sleep tool, which pauses briefly mid-run. Default: true" }, "canvasTool": { "type": "boolean", "description": "Enable the create_canvas tool, which renders an HTML canvas into a shareable image. Default: true" }, "mcpServers": { "type": "array", "items": { "type": "string" }, "description": "Array of MCP server IDs to enable" }, "composioTools": { "type": "array", "items": { "type": "string" }, "description": "Array of Composio integration IDs to enable as tools" }, "toolRouter": { "type": "boolean", "description": "Enable Composio tool router for dynamic tool discovery across 1000+ apps. Default: false" }, "audienceTools": { "type": "boolean", "description": "Enable the lead tools: enrich, leads, lead_field_options, import_leads. Default: false" }, "voiceId": { "type": "string", "description": "ElevenLabs voice ID to override employee default for TTS" } }, "description": "Tool and context settings for the run. Defaults to the employee's own chat settings when omitted." }, "templateId": { "type": "string", "description": "Template this task was created from, if any" }, "templateVersion": { "type": "integer", "description": "Version of that template" }, "dailyCreditLimit": { "type": "number", "description": "Daily credit budget for this task; null uses the platform default" } }, "required": [ "employeeId", "name", "prompt" ], "description": "Request body for creating a scheduled task" } } }, "description": "Scheduled task to create" } } }, "/api/v0/scheduled-task-templates": { "get": { "tags": [ "Scheduled Tasks" ], "operationId": "scheduled_tasks_listScheduledTaskTemplates", "parameters": [ { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "description": "Matches the template title, description or category" }, "description": "Matches the template title, description or category" }, { "name": "category", "in": "query", "required": false, "schema": { "type": "string", "description": "Only templates in this category" }, "description": "Only templates in this category" } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Available task templates", "content": { "application/json": { "schema": { "type": "object", "properties": { "templates": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "version": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string" }, "title": { "type": "string" }, "icon": { "type": "string" }, "category": { "type": "string", "description": "Gallery category, e.g. Sales or Finance" }, "personaTitle": { "type": "string", "description": "employee_personas title of the AI employee that runs this task" }, "persona": { "type": "object", "description": "The resolved persona record (name, title, picture) when seeded" }, "setup": { "type": "object" }, "prefill": { "type": "object" }, "task": { "type": "object", "description": "Prefilled task fields (name, prompt, schedule, settings)" } }, "description": "Predefined task template that prefills a new task" } }, "categories": { "type": "array", "items": { "type": "string" }, "description": "Every template category, for the gallery filter" } }, "description": "Available task templates" } } } } }, "summary": "List predefined task templates that prefill a new scheduled task.", "description": "Optional search and category filters narrow the gallery. Each template's\npersona (the AI employee that runs the task) is resolved from the\nemployee_personas table so the gallery can show the actual person under\nthe template title." } }, "/api/v0/scheduled-task-templates/{template_id}/employee": { "post": { "tags": [ "Scheduled Tasks" ], "operationId": "scheduled_tasks_ensureTemplateEmployee", "parameters": [ { "name": "template_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Unknown template or persona not seeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Admin access required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "The template persona as a company employee", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "picture": { "type": "string" } }, "description": "The template's persona as a company employee" } } } } }, "summary": "Ensure a template's persona exists as an employee on the company.", "description": "Called when the user picks a template, so the create-task form opens with\nthe right AI employee already assigned. Reuses an existing company\nemployee with the persona's title; otherwise adds the persona to the\ncompany carrying its name, photo, prompt and tags.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID. Optional when the API key is a company key." } }, "description": "Company scoping" } } }, "description": "Company scoping" } } }, "/api/v0/scheduled-tasks/summary": { "get": { "tags": [ "Scheduled Tasks" ], "operationId": "scheduled_tasks_scheduledTasksSummary", "parameters": [ { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string", "description": "Company ID. Optional when the API key is a company key; required for personal access keys unless X-Company-ID is set." }, "description": "Company ID. Optional when the API key is a company key; required for personal access keys unless X-Company-ID is set." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Page number, 1-indexed (default: 1)" }, "description": "Page number, 1-indexed (default: 1)" }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "description": "Tasks per page (default: 25)" }, "description": "Tasks per page (default: 25)" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "description": "Filter tasks by name" }, "description": "Filter tasks by name" }, { "name": "includeCompleted", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Include completed one-time tasks (default: false)" }, "description": "Include completed one-time tasks (default: false)" } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Summary stats and a page of tasks", "content": { "application/json": { "schema": { "type": "object", "properties": { "stats": { "type": "object", "description": "Headline counts and averages across the company" }, "tasks": { "type": "array", "items": { "type": "object" }, "description": "Tasks with run counts, average score and recent score trend" }, "total": { "type": "integer" }, "page": { "type": "integer" }, "pageSize": { "type": "integer" }, "totalPages": { "type": "integer" } }, "description": "Company-wide headline stats plus a page of tasks with run counts, average scores and score trends" } } } } }, "summary": "Company-wide scheduled task stats plus a page of tasks with run quality.", "description": "Headline stats across the company, then a page of tasks with their run\ncounts, average quality scores and score trends.\n\nOpen to any company member: the in-chat Scheduled dialog renders the same\npanel, and members could already list and manage their scheduled tasks\nbefore this endpoint existed. The Scheduled *page* is super-user gated in\nthe UI, but that gate is about surfacing a new nav destination, not about\nprotecting this data." } }, "/api/v0/scheduled-tasks/{task_id}": { "get": { "tags": [ "Scheduled Tasks" ], "operationId": "scheduled_tasks_getScheduledTask", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string", "description": "Company ID. Optional when the API key is a company key; required for personal access keys unless X-Company-ID is set." }, "description": "Company ID. Optional when the API key is a company key; required for personal access keys unless X-Company-ID is set." } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Task not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Scheduled task daily quota reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "The scheduled task", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "userId": { "type": "string", "description": "User who owns the task" }, "employeeId": { "type": "string" }, "name": { "type": "string" }, "prompt": { "type": "string" }, "scheduleType": { "type": "string", "description": "one_time, recurring, or heartbeat" }, "scheduledAt": { "type": "string", "description": "One-time tasks: ISO 8601 run time" }, "recurringConfig": { "type": "object", "description": "Recurring or heartbeat schedule details" }, "contextSettings": { "type": "object", "description": "Tool and context settings for runs" }, "timezone": { "type": "string" }, "nextRunAt": { "type": "string", "description": "ISO 8601 time of the next run, null when none" }, "lastRunAt": { "type": "string", "description": "ISO 8601 time of the last run, null when never run" }, "status": { "type": "string", "description": "active, paused, or completed" }, "runCount": { "type": "integer" }, "dailyCreditLimit": { "type": "number" }, "templateId": { "type": "string" }, "templateVersion": { "type": "integer" }, "createdDate": { "type": "string" }, "updatedDate": { "type": "string" } }, "description": "Scheduled task" } } } } }, "summary": "Get a single scheduled task." }, "put": { "tags": [ "Scheduled Tasks" ], "operationId": "scheduled_tasks_updateScheduledTask", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Task not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "This task is training. Try again when training finishes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "The updated task", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "userId": { "type": "string", "description": "User who owns the task" }, "employeeId": { "type": "string" }, "name": { "type": "string" }, "prompt": { "type": "string" }, "scheduleType": { "type": "string", "description": "one_time, recurring, or heartbeat" }, "scheduledAt": { "type": "string", "description": "One-time tasks: ISO 8601 run time" }, "recurringConfig": { "type": "object", "description": "Recurring or heartbeat schedule details" }, "contextSettings": { "type": "object", "description": "Tool and context settings for runs" }, "timezone": { "type": "string" }, "nextRunAt": { "type": "string", "description": "ISO 8601 time of the next run, null when none" }, "lastRunAt": { "type": "string", "description": "ISO 8601 time of the last run, null when never run" }, "status": { "type": "string", "description": "active, paused, or completed" }, "runCount": { "type": "integer" }, "dailyCreditLimit": { "type": "number" }, "templateId": { "type": "string" }, "templateVersion": { "type": "integer" }, "createdDate": { "type": "string" }, "updatedDate": { "type": "string" } }, "description": "Scheduled task" } } } } }, "summary": "Update a scheduled task. Only the supplied fields change.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID. Optional when the API key is a company key." }, "name": { "type": "string", "description": "Short descriptive name" }, "prompt": { "type": "string", "description": "The instruction the employee executes on every run" }, "scheduleType": { "type": "string", "description": "one_time, recurring, or heartbeat", "enum": [ "one_time", "recurring", "heartbeat" ] }, "scheduledAt": { "type": "string", "description": "One-time tasks: ISO 8601 datetime to run at" }, "recurringConfig": { "type": "object", "properties": { "frequency": { "type": "string", "description": "Recurring tasks: daily, weekly, or monthly", "enum": [ "daily", "weekly", "monthly" ] }, "time": { "type": "string", "description": "Recurring tasks: time of day to run, HH:MM in the task timezone" }, "daysOfWeek": { "type": "array", "items": { "type": "integer" }, "description": "Weekly recurring and heartbeat tasks: days the task may run, 0=Sunday .. 6=Saturday. Heartbeat tasks run every day when omitted." }, "dayOfMonth": { "type": "integer", "description": "Monthly recurring tasks: day of the month (1-31)" }, "interval": { "type": "string", "description": "Heartbeat tasks: how often to run. One of 5m, 15m, 30m, 1h, 2h, 4h, 8h, 12h, 24h", "enum": [ "5m", "15m", "30m", "1h", "2h", "4h", "8h", "12h", "24h" ] }, "activeHoursStart": { "type": "string", "description": "Heartbeat tasks: start of the daily active window, HH:MM. Omit for 24/7." }, "activeHoursEnd": { "type": "string", "description": "Heartbeat tasks: end of the daily active window, HH:MM. Omit for 24/7." } }, "description": "Schedule details for recurring and heartbeat tasks" }, "timezone": { "type": "string", "description": "IANA timezone the schedule is expressed in" }, "contextSettings": { "type": "object", "properties": { "platformTools": { "type": "boolean", "description": "Enable company-scoped platform tools" }, "scheduledTemplateSetup": { "type": "object", "description": "Scheduled template resource and integration selections (no credentials)" }, "model": { "type": "string", "description": "AI model to use (e.g., gpt-5-nano, claude-sonnet-5)" }, "temperature": { "type": "number", "description": "Temperature for model variation (0.0-1.0). Default: 0.7" }, "reasoningEffort": { "type": "string", "description": "Reasoning effort for models that support reasoning tokens. Valid values: \"none\", \"minimal\", \"low\", \"medium\", \"high\", \"xhigh\". Empty string means use model default.", "enum": [ "", "none", "minimal", "low", "medium", "high", "xhigh" ] }, "strategy": { "type": "string", "description": "Response strategy. Valid values: \"one-shot\", \"chain\", \"function-chain\", \"langchain\". Default: \"function-chain\"", "enum": [ "one-shot", "chain", "function-chain", "langchain" ] }, "memoryScope": { "type": "string", "description": "Memory scope for context retrieval. Valid values: \"chat\", \"company\", \"global\". Default: \"chat\"", "enum": [ "chat", "company", "global" ] }, "shortTermMemories": { "type": "boolean", "description": "Include short-term memories in context. Default: true" }, "longTermMemories": { "type": "boolean", "description": "Include long-term memories in context. Default: false" }, "documents": { "type": "boolean", "description": "Enable document retrieval from knowledge base. Default: true" }, "documentScope": { "type": "string", "description": "Document scope for retrieval. Valid values: \"root\", \"folder\", \"file\", \"tags\". Default: \"root\"", "enum": [ "root", "folder", "file", "tags" ] }, "documentStrategy": { "type": "string", "description": "Document retrieval strategy. Default: \"similarity-ranking\"" }, "documentPath": { "type": "string", "description": "Document path for scoping retrieval. Default: \"/\"" }, "requestDocuments": { "type": "array", "items": { "type": "object" }, "description": "Specific documents to include in context. Array of {id: string, name?: string, path?: string} objects" }, "searchEngine": { "type": "boolean", "description": "Enable web search via search engine. Default: false" }, "websites": { "type": "boolean", "description": "Enable website content retrieval. Default: false" }, "websitesJs": { "type": "boolean", "description": "Enable JavaScript-rendered website reading. Default: false" }, "news": { "type": "boolean", "description": "Enable online news search. Default: false" }, "company": { "type": "boolean", "description": "Include company context. Default: true" }, "employee": { "type": "boolean", "description": "Include employee context. Default: true" }, "responseInstructions": { "type": "boolean", "description": "Include response instructions in context. Default: true" }, "image": { "type": "string", "description": "Image URL for vision models" }, "lists": { "type": "boolean", "description": "Enable access to lists feature. Default: false" }, "browserTask": { "type": "object", "description": "Browser task configuration: {integrationId: string, task: string, useVision?: boolean} for web automation" }, "documentCreation": { "type": "boolean", "description": "Enable document creation tool. Default: false" }, "inboxId": { "type": "string", "description": "ID of an inbox the employee works from. When set, the employee gets inbox tools (list with a live provider pull, read, send, reply, forward, mark handled) and uses this inbox for email by default. Empty: no inbox" }, "sleepTool": { "type": "boolean", "description": "Enable the sleep tool, which pauses briefly mid-run. Default: true" }, "canvasTool": { "type": "boolean", "description": "Enable the create_canvas tool, which renders an HTML canvas into a shareable image. Default: true" }, "mcpServers": { "type": "array", "items": { "type": "string" }, "description": "Array of MCP server IDs to enable" }, "composioTools": { "type": "array", "items": { "type": "string" }, "description": "Array of Composio integration IDs to enable as tools" }, "toolRouter": { "type": "boolean", "description": "Enable Composio tool router for dynamic tool discovery across 1000+ apps. Default: false" }, "audienceTools": { "type": "boolean", "description": "Enable the lead tools: enrich, leads, lead_field_options, import_leads. Default: false" }, "voiceId": { "type": "string", "description": "ElevenLabs voice ID to override employee default for TTS" } }, "description": "Tool and context settings for the run" }, "status": { "type": "string", "description": "active or paused", "enum": [ "active", "paused", "completed" ] }, "dailyCreditLimit": { "type": "number", "description": "Daily credit budget for this task; null uses the platform default" } }, "description": "Request body for updating a scheduled task. Only supplied fields change." } } }, "description": "Fields to change" } }, "delete": { "tags": [ "Scheduled Tasks" ], "operationId": "scheduled_tasks_deleteScheduledTask", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string", "description": "Company ID. Optional when the API key is a company key; required for personal access keys unless X-Company-ID is set." }, "description": "Company ID. Optional when the API key is a company key; required for personal access keys unless X-Company-ID is set." } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Task not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Scheduled task daily quota reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Task deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "description": "Simple message response" } } } } }, "summary": "Delete a scheduled task." } }, "/api/v0/scheduled-tasks/{task_id}/upgrade-template": { "post": { "tags": [ "Scheduled Tasks" ], "operationId": "scheduled_tasks_upgradeScheduledTaskTemplate", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Task not found or not from a known template", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "This task is training. Try again when training finishes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "The upgraded task", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "userId": { "type": "string", "description": "User who owns the task" }, "employeeId": { "type": "string" }, "name": { "type": "string" }, "prompt": { "type": "string" }, "scheduleType": { "type": "string", "description": "one_time, recurring, or heartbeat" }, "scheduledAt": { "type": "string", "description": "One-time tasks: ISO 8601 run time" }, "recurringConfig": { "type": "object", "description": "Recurring or heartbeat schedule details" }, "contextSettings": { "type": "object", "description": "Tool and context settings for runs" }, "timezone": { "type": "string" }, "nextRunAt": { "type": "string", "description": "ISO 8601 time of the next run, null when none" }, "lastRunAt": { "type": "string", "description": "ISO 8601 time of the last run, null when never run" }, "status": { "type": "string", "description": "active, paused, or completed" }, "runCount": { "type": "integer" }, "dailyCreditLimit": { "type": "number" }, "templateId": { "type": "string" }, "templateVersion": { "type": "integer" }, "createdDate": { "type": "string" }, "updatedDate": { "type": "string" } }, "description": "Scheduled task" } } } } }, "summary": "Re-apply the task's source template at its latest version.", "description": "Overwrites the prompt and tool settings with the template's latest, keeping\nthe task's schedule, employee and name.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID. Optional when the API key is a company key." } }, "description": "Company scoping" } } }, "description": "Company scoping" } } }, "/api/v0/scheduled-tasks/{task_id}/pause": { "post": { "tags": [ "Scheduled Tasks" ], "operationId": "scheduled_tasks_pauseScheduledTask", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Task not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Scheduled task daily quota reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "The paused task", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "userId": { "type": "string", "description": "User who owns the task" }, "employeeId": { "type": "string" }, "name": { "type": "string" }, "prompt": { "type": "string" }, "scheduleType": { "type": "string", "description": "one_time, recurring, or heartbeat" }, "scheduledAt": { "type": "string", "description": "One-time tasks: ISO 8601 run time" }, "recurringConfig": { "type": "object", "description": "Recurring or heartbeat schedule details" }, "contextSettings": { "type": "object", "description": "Tool and context settings for runs" }, "timezone": { "type": "string" }, "nextRunAt": { "type": "string", "description": "ISO 8601 time of the next run, null when none" }, "lastRunAt": { "type": "string", "description": "ISO 8601 time of the last run, null when never run" }, "status": { "type": "string", "description": "active, paused, or completed" }, "runCount": { "type": "integer" }, "dailyCreditLimit": { "type": "number" }, "templateId": { "type": "string" }, "templateVersion": { "type": "integer" }, "createdDate": { "type": "string" }, "updatedDate": { "type": "string" } }, "description": "Scheduled task" } } } } }, "summary": "Pause a scheduled task so no runs fire until it is resumed.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID. Optional when the API key is a company key." } }, "description": "Company scoping" } } }, "description": "Company scoping" } } }, "/api/v0/scheduled-tasks/{task_id}/resume": { "post": { "tags": [ "Scheduled Tasks" ], "operationId": "scheduled_tasks_resumeScheduledTask", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Task not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Scheduled task daily quota reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "The resumed task", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "userId": { "type": "string", "description": "User who owns the task" }, "employeeId": { "type": "string" }, "name": { "type": "string" }, "prompt": { "type": "string" }, "scheduleType": { "type": "string", "description": "one_time, recurring, or heartbeat" }, "scheduledAt": { "type": "string", "description": "One-time tasks: ISO 8601 run time" }, "recurringConfig": { "type": "object", "description": "Recurring or heartbeat schedule details" }, "contextSettings": { "type": "object", "description": "Tool and context settings for runs" }, "timezone": { "type": "string" }, "nextRunAt": { "type": "string", "description": "ISO 8601 time of the next run, null when none" }, "lastRunAt": { "type": "string", "description": "ISO 8601 time of the last run, null when never run" }, "status": { "type": "string", "description": "active, paused, or completed" }, "runCount": { "type": "integer" }, "dailyCreditLimit": { "type": "number" }, "templateId": { "type": "string" }, "templateVersion": { "type": "integer" }, "createdDate": { "type": "string" }, "updatedDate": { "type": "string" } }, "description": "Scheduled task" } } } } }, "summary": "Resume a paused scheduled task (recomputes its next run).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID. Optional when the API key is a company key." } }, "description": "Company scoping" } } }, "description": "Company scoping" } } }, "/api/v0/scheduled-tasks/{task_id}/reset": { "post": { "tags": [ "Scheduled Tasks" ], "operationId": "scheduled_tasks_resetScheduledTask", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Task not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Scheduled task daily quota reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "This task is training. Try again when training finishes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "The reset task", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "userId": { "type": "string", "description": "User who owns the task" }, "employeeId": { "type": "string" }, "name": { "type": "string" }, "prompt": { "type": "string" }, "scheduleType": { "type": "string", "description": "one_time, recurring, or heartbeat" }, "scheduledAt": { "type": "string", "description": "One-time tasks: ISO 8601 run time" }, "recurringConfig": { "type": "object", "description": "Recurring or heartbeat schedule details" }, "contextSettings": { "type": "object", "description": "Tool and context settings for runs" }, "timezone": { "type": "string" }, "nextRunAt": { "type": "string", "description": "ISO 8601 time of the next run, null when none" }, "lastRunAt": { "type": "string", "description": "ISO 8601 time of the last run, null when never run" }, "status": { "type": "string", "description": "active, paused, or completed" }, "runCount": { "type": "integer" }, "dailyCreditLimit": { "type": "number" }, "templateId": { "type": "string" }, "templateVersion": { "type": "integer" }, "createdDate": { "type": "string" }, "updatedDate": { "type": "string" } }, "description": "Scheduled task" } } } } }, "summary": "Reset a task's history.", "description": "Soft-deletes its executions, trainings and daily logs/notes and zeroes\nits run counters. The task's settings are untouched.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID. Optional when the API key is a company key." } }, "description": "Company scoping" } } }, "description": "Company scoping" } } }, "/api/v0/scheduled-tasks/{task_id}/duplicate": { "post": { "tags": [ "Scheduled Tasks" ], "operationId": "scheduled_tasks_duplicateScheduledTask", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Task not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Scheduled task daily quota reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "201": { "description": "The new (paused) copy", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "userId": { "type": "string", "description": "User who owns the task" }, "employeeId": { "type": "string" }, "name": { "type": "string" }, "prompt": { "type": "string" }, "scheduleType": { "type": "string", "description": "one_time, recurring, or heartbeat" }, "scheduledAt": { "type": "string", "description": "One-time tasks: ISO 8601 run time" }, "recurringConfig": { "type": "object", "description": "Recurring or heartbeat schedule details" }, "contextSettings": { "type": "object", "description": "Tool and context settings for runs" }, "timezone": { "type": "string" }, "nextRunAt": { "type": "string", "description": "ISO 8601 time of the next run, null when none" }, "lastRunAt": { "type": "string", "description": "ISO 8601 time of the last run, null when never run" }, "status": { "type": "string", "description": "active, paused, or completed" }, "runCount": { "type": "integer" }, "dailyCreditLimit": { "type": "number" }, "templateId": { "type": "string" }, "templateVersion": { "type": "integer" }, "createdDate": { "type": "string" }, "updatedDate": { "type": "string" } }, "description": "Scheduled task" } } } } }, "summary": "Duplicate a task's settings into a new task (no history).", "description": "The copy starts paused so it can be renamed and reviewed before it begins\nrunning.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID. Optional when the API key is a company key." } }, "description": "Company scoping" } } }, "description": "Company scoping" } } }, "/api/v0/scheduled-tasks/{task_id}/run": { "post": { "tags": [ "Scheduled Tasks" ], "operationId": "scheduled_tasks_runScheduledTaskNow", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Task not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Scheduled task daily quota reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "This task is training. Try again when training finishes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "202": { "description": "Run started in the background", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "executionId": { "type": "string", "description": "Id of the run, which is also its chat id" } }, "description": "A manual run that was started in the background" } } } } }, "summary": "Run a scheduled task immediately.", "description": "Runs the same executor the scheduler uses (so it records an execution with\nblocks/response the same way), in the background. A manual run executes even\nif the task is paused and does NOT alter the task's normal schedule. The\nresponse's executionId is the run's execution (and chat) id; poll the\nexecutions endpoint for the result.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID. Optional when the API key is a company key." } }, "description": "Company scoping" } } }, "description": "Company scoping" } } }, "/api/v0/scheduled-tasks/{task_id}/train": { "post": { "tags": [ "Scheduled Tasks" ], "operationId": "scheduled_tasks_trainScheduledTask", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "This task is not trained", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Task not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Task is already training", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "202": { "description": "Training started; poll the GET endpoint", "content": { "application/json": { "schema": { "type": "object", "properties": { "training": { "type": "object", "properties": { "id": { "type": "string" }, "scheduledTaskId": { "type": "string" }, "status": { "type": "string", "description": "running, completed, or failed" }, "suggestion": { "type": "object", "description": "rounds (phase, ready, report, runbook, chatId, credits, toolCalls, durationMs, error), summary, improvedPrompt, passed, applied" }, "errorMessage": { "type": "string" }, "createdDate": { "type": "string" }, "completedDate": { "type": "string" } }, "description": "The task's employee rehearses it without sending or changing anything, writes exact steps (a runbook) and dry-runs them; a ready runbook replaces the task prompt" } }, "description": "Latest training for a task; training is null when it has never trained" } } } } }, "summary": "Train the task again on its current prompt.", "description": "Its employee rehearses the task without sending or changing anything,\nwrites exact steps and dry-runs them; if the steps are ready they replace\nthe task prompt. Pass notes to fine-tune it (\"stop it posting twice\", \"keep\nthe tone\"): every round builds them into the steps. Runs due before training\nfinishes are held. Training takes several minutes, so this returns 202 and\nthe client polls GET /scheduled-tasks/<task_id>/train.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID. Optional when the API key is a company key." }, "notes": { "type": "string", "description": "Changes for training to build into the task steps, e.g. \"stop it posting twice\"" } }, "description": "Request body for training a scheduled task" } } }, "description": "Company scoping and optional changes to train in" } }, "get": { "tags": [ "Scheduled Tasks" ], "operationId": "scheduled_tasks_getScheduledTaskTraining", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string", "description": "Company ID. Optional when the API key is a company key; required for personal access keys unless X-Company-ID is set." }, "description": "Company ID. Optional when the API key is a company key; required for personal access keys unless X-Company-ID is set." } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Latest training, or null", "content": { "application/json": { "schema": { "type": "object", "properties": { "training": { "type": "object", "properties": { "id": { "type": "string" }, "scheduledTaskId": { "type": "string" }, "status": { "type": "string", "description": "running, completed, or failed" }, "suggestion": { "type": "object", "description": "rounds (phase, ready, report, runbook, chatId, credits, toolCalls, durationMs, error), summary, improvedPrompt, passed, applied" }, "errorMessage": { "type": "string" }, "createdDate": { "type": "string" }, "completedDate": { "type": "string" } }, "description": "The task's employee rehearses it without sending or changing anything, writes exact steps (a runbook) and dry-runs them; a ready runbook replaces the task prompt" } }, "description": "Latest training for a task; training is null when it has never trained" } } } } }, "summary": "Latest training for a task: its status, each round, and the outcome." } }, "/api/v0/scheduled-tasks/{task_id}/executions": { "get": { "tags": [ "Scheduled Tasks" ], "operationId": "scheduled_tasks_listTaskExecutions", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string", "description": "Company ID. Optional when the API key is a company key; required for personal access keys unless X-Company-ID is set." }, "description": "Company ID. Optional when the API key is a company key; required for personal access keys unless X-Company-ID is set." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Page number, 1-indexed (default: 1)" }, "description": "Page number, 1-indexed (default: 1)" }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "description": "Items per page" }, "description": "Items per page" } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Paged execution history, newest first", "content": { "application/json": { "schema": { "type": "object", "properties": { "executions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "scheduledTaskId": { "type": "string" }, "companyId": { "type": "string" }, "userId": { "type": "string" }, "employeeId": { "type": "string" }, "status": { "type": "string", "description": "pending, running, completed, or failed" }, "scheduledTime": { "type": "string" }, "startedAt": { "type": "string" }, "completedAt": { "type": "string" }, "durationMs": { "type": "integer" }, "promptSent": { "type": "string" }, "response": { "type": "string", "description": "The employee's final response" }, "toolCalls": { "type": "array", "items": { "type": "object" } }, "blocks": { "type": "array", "items": { "type": "object" } }, "errorMessage": { "type": "string" }, "tokensUsed": { "type": "integer" }, "creditsUsed": { "type": "number", "description": "Credits charged by this run" }, "score": { "type": "integer", "description": "0-100 quality grade of the run, null until graded" }, "scoreReason": { "type": "string" }, "scoredAt": { "type": "string" }, "createdDate": { "type": "string" } }, "description": "One run of a scheduled task" } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "pageSize": { "type": "integer" }, "totalPages": { "type": "integer" } }, "description": "Paged execution history" } } } } }, "summary": "List execution history for a specific task." } }, "/api/v0/scheduled-tasks/{task_id}/daily-logs": { "get": { "tags": [ "Scheduled Tasks" ], "operationId": "scheduled_tasks_listTaskDailyLogs", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string", "description": "Company ID. Optional when the API key is a company key; required for personal access keys unless X-Company-ID is set." }, "description": "Company ID. Optional when the API key is a company key; required for personal access keys unless X-Company-ID is set." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Page number, 1-indexed (default: 1)" }, "description": "Page number, 1-indexed (default: 1)" }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "description": "Items per page" }, "description": "Items per page" } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Paged daily logs, newest first", "content": { "application/json": { "schema": { "type": "object", "properties": { "logs": { "type": "array", "items": { "type": "object" }, "description": "One entry per day the task ran: date and the notes it recorded" }, "total": { "type": "integer" }, "page": { "type": "integer" }, "pageSize": { "type": "integer" }, "totalPages": { "type": "integer" } }, "description": "Paged heartbeat daily logs, newest first" } } } } }, "summary": "List the daily logs (heartbeat status timeline) for a scheduled task." } }, "/api/v0/scheduled-task-executions": { "get": { "tags": [ "Scheduled Tasks" ], "operationId": "scheduled_tasks_listAllExecutions", "parameters": [ { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string", "description": "Company ID. Optional when the API key is a company key; required for personal access keys unless X-Company-ID is set." }, "description": "Company ID. Optional when the API key is a company key; required for personal access keys unless X-Company-ID is set." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Page number, 1-indexed (default: 1)" }, "description": "Page number, 1-indexed (default: 1)" }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "description": "Items per page" }, "description": "Items per page" } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Paged execution history across all tasks", "content": { "application/json": { "schema": { "type": "object", "properties": { "executions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "scheduledTaskId": { "type": "string" }, "companyId": { "type": "string" }, "userId": { "type": "string" }, "employeeId": { "type": "string" }, "status": { "type": "string", "description": "pending, running, completed, or failed" }, "scheduledTime": { "type": "string" }, "startedAt": { "type": "string" }, "completedAt": { "type": "string" }, "durationMs": { "type": "integer" }, "promptSent": { "type": "string" }, "response": { "type": "string", "description": "The employee's final response" }, "toolCalls": { "type": "array", "items": { "type": "object" } }, "blocks": { "type": "array", "items": { "type": "object" } }, "errorMessage": { "type": "string" }, "tokensUsed": { "type": "integer" }, "creditsUsed": { "type": "number", "description": "Credits charged by this run" }, "score": { "type": "integer", "description": "0-100 quality grade of the run, null until graded" }, "scoreReason": { "type": "string" }, "scoredAt": { "type": "string" }, "createdDate": { "type": "string" } }, "description": "One run of a scheduled task" } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "pageSize": { "type": "integer" }, "totalPages": { "type": "integer" } }, "description": "Paged execution history" } } } } }, "summary": "List execution history across every scheduled task in a company." } }, "/api/v0/scheduled-task-templates/{template_id}/setup": { "get": { "tags": [ "Scheduled Tasks" ], "operationId": "scheduled_tasks_getTemplateSetup", "parameters": [ { "name": "template_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string", "description": "Company ID. Optional when the API key is a company key; required for personal access keys unless X-Company-ID is set." }, "description": "Company ID. Optional when the API key is a company key; required for personal access keys unless X-Company-ID is set." } ], "responses": { "200": { "description": "Successful response" } }, "summary": "List visible connections for a template's required integration choices." } }, "/api/v0/monitors": { "post": { "tags": [ "Monitors" ], "operationId": "monitoring_createMonitor", "parameters": [], "responses": { "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "201": { "description": "The created monitor", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether creation succeeded" }, "monitor": { "type": "object", "properties": { "id": { "type": "string", "description": "Monitor ID (UUID)" }, "companyId": { "type": "string", "description": "Company ID" }, "name": { "type": "string", "description": "Display name" }, "keywords": { "type": "array", "items": { "type": "string" }, "description": "Keywords being tracked" }, "platforms": { "type": "array", "items": { "type": "string" }, "description": "Platforms being monitored" }, "filters": { "type": "object", "description": "Platform-specific filters" }, "aiFilterEnabled": { "type": "boolean", "description": "Whether AI relevance filtering is enabled" }, "notifyEmail": { "type": "boolean", "description": "Whether email notifications are enabled" }, "notifyInApp": { "type": "boolean", "description": "Whether in-app notifications are enabled" }, "notifyUserIds": { "type": "array", "items": { "type": "string" }, "description": "User IDs receiving notifications" }, "syncToListId": { "type": "string", "description": "Smart list ID for syncing" }, "status": { "type": "string", "description": "Monitor status: active, paused" }, "lastRunAt": { "type": "string", "description": "ISO timestamp of last monitor run" }, "totalMentionsFound": { "type": "integer", "description": "Total mentions discovered by this monitor" }, "created_date": { "type": "string", "description": "ISO timestamp of creation" }, "updated_date": { "type": "string", "description": "ISO timestamp of last update" } }, "description": "The created monitor" } }, "description": "Monitor creation response" } } } } }, "summary": "Create a new keyword monitor.", "description": "Creates a monitor to track specified keywords across social media platforms\nlike Reddit, Hacker News, LinkedIn, X (Twitter), and Quora. When matching\nposts are found, you'll receive notifications and can generate AI-powered\nreply suggestions.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Display name for the monitor" }, "keywords": { "type": "array", "items": { "type": "string" }, "description": "List of keywords to track across platforms" }, "platforms": { "type": "array", "items": { "type": "string" }, "description": "Platforms to monitor: reddit, hackernews, linkedin, x, quora, chatgpt, google_ai" }, "filters": { "type": "object", "description": "Platform-specific filters: subreddits, hnTags, chatgptPrompt, aiFilterInstructions, and negativeKeywords (list of terms that exclude a post when matched as whole words)" }, "aiFilterEnabled": { "type": "boolean", "description": "Use AI to filter relevance (default: true)" }, "notifyEmail": { "type": "boolean", "description": "Send email notifications for new mentions (default: true)" }, "notifyInApp": { "type": "boolean", "description": "Send in-app notifications (default: true)" }, "notifyUserIds": { "type": "array", "items": { "type": "string" }, "description": "List of user IDs to receive notifications" }, "syncToListId": { "type": "string", "description": "Smart list ID to sync mentions to automatically" } }, "required": [ "name", "keywords", "platforms" ], "description": "Request body for creating a new keyword monitor" } } }, "description": "Monitor configuration" } }, "get": { "tags": [ "Monitors" ], "operationId": "monitoring_listMonitors", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "description": "Filter by status: active, paused" }, "description": "Filter by status: active, paused" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "description": "Maximum results (default: 50, max: 100)", "default": 50 }, "description": "Maximum results (default: 50, max: 100)" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "description": "Number of results to skip", "default": 0 }, "description": "Number of results to skip" } ], "responses": { "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "List of monitors", "content": { "application/json": { "schema": { "type": "object", "properties": { "monitors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Monitor ID (UUID)" }, "companyId": { "type": "string", "description": "Company ID" }, "name": { "type": "string", "description": "Display name" }, "keywords": { "type": "array", "items": { "type": "string" }, "description": "Keywords being tracked" }, "platforms": { "type": "array", "items": { "type": "string" }, "description": "Platforms being monitored" }, "filters": { "type": "object", "description": "Platform-specific filters" }, "aiFilterEnabled": { "type": "boolean", "description": "Whether AI relevance filtering is enabled" }, "notifyEmail": { "type": "boolean", "description": "Whether email notifications are enabled" }, "notifyInApp": { "type": "boolean", "description": "Whether in-app notifications are enabled" }, "notifyUserIds": { "type": "array", "items": { "type": "string" }, "description": "User IDs receiving notifications" }, "syncToListId": { "type": "string", "description": "Smart list ID for syncing" }, "status": { "type": "string", "description": "Monitor status: active, paused" }, "lastRunAt": { "type": "string", "description": "ISO timestamp of last monitor run" }, "totalMentionsFound": { "type": "integer", "description": "Total mentions discovered by this monitor" }, "created_date": { "type": "string", "description": "ISO timestamp of creation" }, "updated_date": { "type": "string", "description": "ISO timestamp of last update" } }, "description": "Keyword monitor object" }, "description": "List of monitors" }, "count": { "type": "integer", "description": "Number of monitors returned" } }, "description": "List of keyword monitors" } } } } }, "summary": "List all keyword monitors.", "description": "Returns all keyword monitors for the current company. Monitors can be\nfiltered by status (active or paused) and support pagination." } }, "/api/v0/monitors/{monitor_id}": { "get": { "tags": [ "Monitors" ], "operationId": "monitoring_getMonitor", "parameters": [ { "name": "monitor_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Monitor not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Monitor details", "content": { "application/json": { "schema": { "type": "object", "properties": { "monitor": { "type": "object", "properties": { "id": { "type": "string", "description": "Monitor ID (UUID)" }, "companyId": { "type": "string", "description": "Company ID" }, "name": { "type": "string", "description": "Display name" }, "keywords": { "type": "array", "items": { "type": "string" }, "description": "Keywords being tracked" }, "platforms": { "type": "array", "items": { "type": "string" }, "description": "Platforms being monitored" }, "filters": { "type": "object", "description": "Platform-specific filters" }, "aiFilterEnabled": { "type": "boolean", "description": "Whether AI relevance filtering is enabled" }, "notifyEmail": { "type": "boolean", "description": "Whether email notifications are enabled" }, "notifyInApp": { "type": "boolean", "description": "Whether in-app notifications are enabled" }, "notifyUserIds": { "type": "array", "items": { "type": "string" }, "description": "User IDs receiving notifications" }, "syncToListId": { "type": "string", "description": "Smart list ID for syncing" }, "status": { "type": "string", "description": "Monitor status: active, paused" }, "lastRunAt": { "type": "string", "description": "ISO timestamp of last monitor run" }, "totalMentionsFound": { "type": "integer", "description": "Total mentions discovered by this monitor" }, "created_date": { "type": "string", "description": "ISO timestamp of creation" }, "updated_date": { "type": "string", "description": "ISO timestamp of last update" } }, "description": "The monitor object" } }, "description": "Single monitor response" } } } } }, "summary": "Get a specific monitor by ID.", "description": "Returns the full configuration for a keyword monitor including its\nkeywords, platforms, notification settings, and run statistics." }, "put": { "tags": [ "Monitors" ], "operationId": "monitoring_updateMonitor", "parameters": [ { "name": "monitor_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Monitor not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "The updated monitor", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether update succeeded" }, "monitor": { "type": "object", "properties": { "id": { "type": "string", "description": "Monitor ID (UUID)" }, "companyId": { "type": "string", "description": "Company ID" }, "name": { "type": "string", "description": "Display name" }, "keywords": { "type": "array", "items": { "type": "string" }, "description": "Keywords being tracked" }, "platforms": { "type": "array", "items": { "type": "string" }, "description": "Platforms being monitored" }, "filters": { "type": "object", "description": "Platform-specific filters" }, "aiFilterEnabled": { "type": "boolean", "description": "Whether AI relevance filtering is enabled" }, "notifyEmail": { "type": "boolean", "description": "Whether email notifications are enabled" }, "notifyInApp": { "type": "boolean", "description": "Whether in-app notifications are enabled" }, "notifyUserIds": { "type": "array", "items": { "type": "string" }, "description": "User IDs receiving notifications" }, "syncToListId": { "type": "string", "description": "Smart list ID for syncing" }, "status": { "type": "string", "description": "Monitor status: active, paused" }, "lastRunAt": { "type": "string", "description": "ISO timestamp of last monitor run" }, "totalMentionsFound": { "type": "integer", "description": "Total mentions discovered by this monitor" }, "created_date": { "type": "string", "description": "ISO timestamp of creation" }, "updated_date": { "type": "string", "description": "ISO timestamp of last update" } }, "description": "The updated monitor" } }, "description": "Monitor update response" } } } } }, "summary": "Update a monitor's settings.", "description": "Updates the monitor configuration. Only include fields that need to be\nchanged - unspecified fields will retain their current values.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Display name for the monitor" }, "keywords": { "type": "array", "items": { "type": "string" }, "description": "List of keywords to track" }, "platforms": { "type": "array", "items": { "type": "string" }, "description": "Platforms to monitor: reddit, hackernews, linkedin, x, quora, chatgpt, google_ai" }, "filters": { "type": "object", "description": "Platform-specific filters: subreddits, hnTags, chatgptPrompt, aiFilterInstructions, and negativeKeywords (list of terms that exclude a post when matched as whole words)" }, "aiFilterEnabled": { "type": "boolean", "description": "Use AI to filter relevance" }, "notifyEmail": { "type": "boolean", "description": "Send email notifications" }, "notifyInApp": { "type": "boolean", "description": "Send in-app notifications" }, "notifyUserIds": { "type": "array", "items": { "type": "string" }, "description": "List of user IDs to receive notifications" }, "syncToListId": { "type": "string", "description": "Smart list ID to sync mentions to" }, "status": { "type": "string", "description": "Monitor status: active, paused" } }, "description": "Request body for updating a monitor (include only fields to update)" } } }, "description": "Fields to update" } }, "delete": { "tags": [ "Monitors" ], "operationId": "monitoring_deleteMonitor", "parameters": [ { "name": "monitor_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Monitor not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Deletion result", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether operation succeeded" } }, "description": "Success response" } } } } }, "summary": "Delete a monitor.", "description": "Permanently deletes the specified monitor. Associated mentions are\npreserved but will no longer receive updates." } }, "/api/v0/monitors/{monitor_id}/pause": { "post": { "tags": [ "Monitors" ], "operationId": "monitoring_pauseMonitor", "parameters": [ { "name": "monitor_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Monitor not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "The paused monitor", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether update succeeded" }, "monitor": { "type": "object", "properties": { "id": { "type": "string", "description": "Monitor ID (UUID)" }, "companyId": { "type": "string", "description": "Company ID" }, "name": { "type": "string", "description": "Display name" }, "keywords": { "type": "array", "items": { "type": "string" }, "description": "Keywords being tracked" }, "platforms": { "type": "array", "items": { "type": "string" }, "description": "Platforms being monitored" }, "filters": { "type": "object", "description": "Platform-specific filters" }, "aiFilterEnabled": { "type": "boolean", "description": "Whether AI relevance filtering is enabled" }, "notifyEmail": { "type": "boolean", "description": "Whether email notifications are enabled" }, "notifyInApp": { "type": "boolean", "description": "Whether in-app notifications are enabled" }, "notifyUserIds": { "type": "array", "items": { "type": "string" }, "description": "User IDs receiving notifications" }, "syncToListId": { "type": "string", "description": "Smart list ID for syncing" }, "status": { "type": "string", "description": "Monitor status: active, paused" }, "lastRunAt": { "type": "string", "description": "ISO timestamp of last monitor run" }, "totalMentionsFound": { "type": "integer", "description": "Total mentions discovered by this monitor" }, "created_date": { "type": "string", "description": "ISO timestamp of creation" }, "updated_date": { "type": "string", "description": "ISO timestamp of last update" } }, "description": "The updated monitor" } }, "description": "Monitor update response" } } } } }, "summary": "Pause a monitor.", "description": "Temporarily stops the monitor from checking for new mentions. The monitor\ncan be resumed later without losing any configuration." } }, "/api/v0/monitors/{monitor_id}/resume": { "post": { "tags": [ "Monitors" ], "operationId": "monitoring_resumeMonitor", "parameters": [ { "name": "monitor_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Monitor not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "The resumed monitor", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether update succeeded" }, "monitor": { "type": "object", "properties": { "id": { "type": "string", "description": "Monitor ID (UUID)" }, "companyId": { "type": "string", "description": "Company ID" }, "name": { "type": "string", "description": "Display name" }, "keywords": { "type": "array", "items": { "type": "string" }, "description": "Keywords being tracked" }, "platforms": { "type": "array", "items": { "type": "string" }, "description": "Platforms being monitored" }, "filters": { "type": "object", "description": "Platform-specific filters" }, "aiFilterEnabled": { "type": "boolean", "description": "Whether AI relevance filtering is enabled" }, "notifyEmail": { "type": "boolean", "description": "Whether email notifications are enabled" }, "notifyInApp": { "type": "boolean", "description": "Whether in-app notifications are enabled" }, "notifyUserIds": { "type": "array", "items": { "type": "string" }, "description": "User IDs receiving notifications" }, "syncToListId": { "type": "string", "description": "Smart list ID for syncing" }, "status": { "type": "string", "description": "Monitor status: active, paused" }, "lastRunAt": { "type": "string", "description": "ISO timestamp of last monitor run" }, "totalMentionsFound": { "type": "integer", "description": "Total mentions discovered by this monitor" }, "created_date": { "type": "string", "description": "ISO timestamp of creation" }, "updated_date": { "type": "string", "description": "ISO timestamp of last update" } }, "description": "The updated monitor" } }, "description": "Monitor update response" } } } } }, "summary": "Resume a paused monitor.", "description": "Reactivates a paused monitor so it will begin checking for new mentions\nagain on its regular schedule." } }, "/api/v0/monitors/{monitor_id}/run": { "post": { "tags": [ "Monitors" ], "operationId": "monitoring_triggerMonitorRun", "parameters": [ { "name": "monitor_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Monitor not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Run trigger confirmation", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether trigger succeeded" }, "message": { "type": "string", "description": "Status message" } }, "description": "Monitor run trigger response" } } } } }, "summary": "Trigger a manual run of a monitor.", "description": "Immediately triggers the monitor to check all configured platforms for\nnew mentions. The run executes asynchronously in the background." } }, "/api/v0/mentions": { "get": { "tags": [ "Monitors" ], "operationId": "monitoring_listMentions", "parameters": [ { "name": "monitorId", "in": "query", "required": false, "schema": { "type": "string", "description": "Filter by specific monitor ID" }, "description": "Filter by specific monitor ID" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "description": "Filter by status: new, seen, replied, dismissed" }, "description": "Filter by status: new, seen, replied, dismissed" }, { "name": "platform", "in": "query", "required": false, "schema": { "type": "string", "description": "Filter by platform: reddit, hackernews, linkedin, x, quora, chatgpt, google_ai" }, "description": "Filter by platform: reddit, hackernews, linkedin, x, quora, chatgpt, google_ai" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "description": "Maximum results (default: 50, max: 100)", "default": 50 }, "description": "Maximum results (default: 50, max: 100)" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "description": "Number of results to skip", "default": 0 }, "description": "Number of results to skip" } ], "responses": { "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "List of mentions", "content": { "application/json": { "schema": { "type": "object", "properties": { "mentions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Mention ID (UUID)" }, "monitorId": { "type": "string", "description": "Parent monitor ID" }, "companyId": { "type": "string", "description": "Company ID" }, "platform": { "type": "string", "description": "Source platform: reddit, hackernews, linkedin, x, quora, chatgpt, google_ai" }, "postId": { "type": "string", "description": "External post ID from the platform" }, "postUrl": { "type": "string", "description": "Direct URL to the post" }, "authorUsername": { "type": "string", "description": "Username of the post author" }, "authorUrl": { "type": "string", "description": "Profile URL of the author" }, "title": { "type": "string", "description": "Post title (if available)" }, "content": { "type": "string", "description": "Post content/body text" }, "subreddit": { "type": "string", "description": "Subreddit name (Reddit only)" }, "matchedKeywords": { "type": "array", "items": { "type": "string" }, "description": "Keywords that matched this post" }, "relevanceScore": { "type": "number", "description": "AI-computed relevance score (0-10)" }, "relevanceReason": { "type": "string", "description": "Why the AI filter gave this relevance score" }, "sentiment": { "type": "string", "description": "Detected sentiment: positive, negative, neutral" }, "metrics": { "type": "object", "properties": { "upvotes": { "type": "integer", "description": "Number of upvotes (Reddit/HN)" }, "comments": { "type": "integer", "description": "Number of comments" }, "points": { "type": "integer", "description": "Points score (Hacker News)" }, "score": { "type": "integer", "description": "Post score" } }, "description": "Engagement metrics" }, "suggestedReplies": { "type": "object", "description": "AI-generated reply suggestions by style" }, "status": { "type": "string", "description": "Mention status: new, seen, replied, dismissed" }, "syncedToList": { "type": "boolean", "description": "Whether synced to Smart List" }, "postedAt": { "type": "string", "description": "ISO timestamp when post was originally made" }, "foundAt": { "type": "string", "description": "ISO timestamp when we discovered the post" }, "created_date": { "type": "string", "description": "ISO timestamp of creation" }, "updated_date": { "type": "string", "description": "ISO timestamp of last update" } }, "description": "Mention object representing a discovered social media post" }, "description": "List of mentions" }, "count": { "type": "integer", "description": "Number of mentions returned" } }, "description": "List of mentions" } } } } }, "summary": "List mentions discovered by monitors.", "description": "Returns social media mentions found by your keyword monitors. Mentions\ncan be filtered by monitor, status (new, seen, dismissed), and platform.\nResults are sorted by discovery time, newest first." } }, "/api/v0/mentions/{mention_id}": { "get": { "tags": [ "Monitors" ], "operationId": "monitoring_getMention", "parameters": [ { "name": "mention_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Mention not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Mention details", "content": { "application/json": { "schema": { "type": "object", "properties": { "mention": { "type": "object", "properties": { "id": { "type": "string", "description": "Mention ID (UUID)" }, "monitorId": { "type": "string", "description": "Parent monitor ID" }, "companyId": { "type": "string", "description": "Company ID" }, "platform": { "type": "string", "description": "Source platform: reddit, hackernews, linkedin, x, quora, chatgpt, google_ai" }, "postId": { "type": "string", "description": "External post ID from the platform" }, "postUrl": { "type": "string", "description": "Direct URL to the post" }, "authorUsername": { "type": "string", "description": "Username of the post author" }, "authorUrl": { "type": "string", "description": "Profile URL of the author" }, "title": { "type": "string", "description": "Post title (if available)" }, "content": { "type": "string", "description": "Post content/body text" }, "subreddit": { "type": "string", "description": "Subreddit name (Reddit only)" }, "matchedKeywords": { "type": "array", "items": { "type": "string" }, "description": "Keywords that matched this post" }, "relevanceScore": { "type": "number", "description": "AI-computed relevance score (0-10)" }, "relevanceReason": { "type": "string", "description": "Why the AI filter gave this relevance score" }, "sentiment": { "type": "string", "description": "Detected sentiment: positive, negative, neutral" }, "metrics": { "type": "object", "properties": { "upvotes": { "type": "integer", "description": "Number of upvotes (Reddit/HN)" }, "comments": { "type": "integer", "description": "Number of comments" }, "points": { "type": "integer", "description": "Points score (Hacker News)" }, "score": { "type": "integer", "description": "Post score" } }, "description": "Engagement metrics" }, "suggestedReplies": { "type": "object", "description": "AI-generated reply suggestions by style" }, "status": { "type": "string", "description": "Mention status: new, seen, replied, dismissed" }, "syncedToList": { "type": "boolean", "description": "Whether synced to Smart List" }, "postedAt": { "type": "string", "description": "ISO timestamp when post was originally made" }, "foundAt": { "type": "string", "description": "ISO timestamp when we discovered the post" }, "created_date": { "type": "string", "description": "ISO timestamp of creation" }, "updated_date": { "type": "string", "description": "ISO timestamp of last update" } }, "description": "The mention object" } }, "description": "Single mention response" } } } } }, "summary": "Get a specific mention by ID.", "description": "Returns full details for a mention including the post content, author\ninformation, engagement metrics, and any generated reply suggestions.\nAutomatically marks 'new' mentions as 'seen' when retrieved." } }, "/api/v0/mentions/{mention_id}/dismiss": { "post": { "tags": [ "Monitors" ], "operationId": "monitoring_dismissMention", "parameters": [ { "name": "mention_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Mention not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "The dismissed mention", "content": { "application/json": { "schema": { "type": "object", "properties": { "mention": { "type": "object", "properties": { "id": { "type": "string", "description": "Mention ID (UUID)" }, "monitorId": { "type": "string", "description": "Parent monitor ID" }, "companyId": { "type": "string", "description": "Company ID" }, "platform": { "type": "string", "description": "Source platform: reddit, hackernews, linkedin, x, quora, chatgpt, google_ai" }, "postId": { "type": "string", "description": "External post ID from the platform" }, "postUrl": { "type": "string", "description": "Direct URL to the post" }, "authorUsername": { "type": "string", "description": "Username of the post author" }, "authorUrl": { "type": "string", "description": "Profile URL of the author" }, "title": { "type": "string", "description": "Post title (if available)" }, "content": { "type": "string", "description": "Post content/body text" }, "subreddit": { "type": "string", "description": "Subreddit name (Reddit only)" }, "matchedKeywords": { "type": "array", "items": { "type": "string" }, "description": "Keywords that matched this post" }, "relevanceScore": { "type": "number", "description": "AI-computed relevance score (0-10)" }, "relevanceReason": { "type": "string", "description": "Why the AI filter gave this relevance score" }, "sentiment": { "type": "string", "description": "Detected sentiment: positive, negative, neutral" }, "metrics": { "type": "object", "properties": { "upvotes": { "type": "integer", "description": "Number of upvotes (Reddit/HN)" }, "comments": { "type": "integer", "description": "Number of comments" }, "points": { "type": "integer", "description": "Points score (Hacker News)" }, "score": { "type": "integer", "description": "Post score" } }, "description": "Engagement metrics" }, "suggestedReplies": { "type": "object", "description": "AI-generated reply suggestions by style" }, "status": { "type": "string", "description": "Mention status: new, seen, replied, dismissed" }, "syncedToList": { "type": "boolean", "description": "Whether synced to Smart List" }, "postedAt": { "type": "string", "description": "ISO timestamp when post was originally made" }, "foundAt": { "type": "string", "description": "ISO timestamp when we discovered the post" }, "created_date": { "type": "string", "description": "ISO timestamp of creation" }, "updated_date": { "type": "string", "description": "ISO timestamp of last update" } }, "description": "The mention object" } }, "description": "Single mention response" } } } } }, "summary": "Dismiss a mention.", "description": "Marks the mention as dismissed, hiding it from the default view.\nDismissed mentions are not deleted and can still be retrieved\nby filtering for dismissed status." } }, "/api/v0/mentions/{mention_id}/generate-replies": { "post": { "tags": [ "Monitors" ], "operationId": "monitoring_generateReplies", "parameters": [ { "name": "mention_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Mention not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Generated reply suggestions", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether generation succeeded" }, "replies": { "type": "object", "description": "Generated replies by style: value-first, educational, conversational, problem-solver" } }, "description": "Generated reply suggestions response" } } } } }, "summary": "Generate AI reply suggestions for a mention.", "description": "Uses AI to generate reply suggestions in four different styles:\n- value-first: Leads with the benefits of your solution\n- educational: Informative and helpful tone\n- conversational: Friendly and engaging approach\n- problem-solver: Addresses specific pain points\n\nAll four styles are generated in a single request. Optionally provide\ncontext about your product/service to personalize the replies.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "context": { "type": "string", "description": "Additional context about your product/service to personalize replies" } }, "description": "Request body for generating AI reply suggestions" } } }, "description": "Context for reply generation" } } }, "/api/v0/mentions/stats": { "get": { "tags": [ "Monitors" ], "operationId": "monitoring_getMentionsStats", "parameters": [ { "name": "monitorId", "in": "query", "required": false, "schema": { "type": "string", "description": "Filter stats by specific monitor ID" }, "description": "Filter stats by specific monitor ID" } ], "responses": { "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Mention statistics", "content": { "application/json": { "schema": { "type": "object", "properties": { "stats": { "type": "object", "properties": { "total": { "type": "integer", "description": "Total mention count" }, "new": { "type": "integer", "description": "New (unread) mention count" }, "seen": { "type": "integer", "description": "Seen mention count" }, "dismissed": { "type": "integer", "description": "Dismissed mention count" }, "byPlatform": { "type": "object", "properties": { "reddit": { "type": "integer", "description": "Reddit mention count" }, "hackernews": { "type": "integer", "description": "Hacker News mention count" }, "linkedin": { "type": "integer", "description": "LinkedIn mention count" }, "x": { "type": "integer", "description": "X (Twitter) mention count" }, "quora": { "type": "integer", "description": "Quora mention count" }, "chatgpt": { "type": "integer", "description": "ChatGPT mention count" }, "google_ai": { "type": "integer", "description": "Google AI mention count" } }, "description": "Breakdown by platform" } }, "description": "The statistics object" } }, "description": "Mention statistics response" } } } } }, "summary": "Get aggregated mention statistics.", "description": "Returns counts of mentions broken down by status (new, seen, dismissed)\nand by platform (Reddit, Hacker News, LinkedIn, X, Quora). Optionally\nfilter to a specific monitor." } }, "/api/v0/mentions/stats/timeseries": { "get": { "tags": [ "Monitors" ], "operationId": "monitoring_getMentionsTimeseries", "parameters": [], "responses": { "200": { "description": "Successful response" } }, "summary": "Get daily mention counts over time, broken down by platform.", "description": "Returns a dense (zero-filled) series for the total and for each platform\nover the last N days (default 30), shaped for a stacked-area chart.\nOptionally filter to a specific monitor." } }, "/api/v0/research/prefill": { "get": { "tags": [ "Content Research" ], "operationId": "content_research_getResearchPrefill", "parameters": [ { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID that owns the research projects" }, "description": "Company ID that owns the research projects" } ], "responses": { "400": { "description": "Company ID required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Suggested project setup values", "content": { "application/json": { "schema": { "type": "object", "properties": { "prefill": { "type": "object", "description": "Suggested fields: name, domain, competitorDomains, seedKeywords" } }, "description": "AI-suggested setup values for a new research project" } } } } }, "summary": "Suggest setup values for a new research project.", "description": "Infers a project name, competitor domains and seed keywords from the\ncompany's own website and profile, so a project can be created without\nthe caller supplying them." } }, "/api/v0/research/projects": { "get": { "tags": [ "Content Research" ], "operationId": "content_research_listResearchProjects", "parameters": [ { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID that owns the research projects" }, "description": "Company ID that owns the research projects" } ], "responses": { "400": { "description": "Company ID required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "All research projects for the company", "content": { "application/json": { "schema": { "type": "object", "properties": { "projects": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Project ID (UUID)" }, "companyId": { "type": "string", "description": "Owning company ID" }, "createdBy": { "type": "string", "description": "UID of the user who created the project" }, "name": { "type": "string", "description": "Human-readable project name" }, "domain": { "type": "string", "description": "The domain being researched, e.g. \"yourcompany.com\"" }, "competitorDomains": { "type": "array", "items": { "type": "string" }, "description": "Competitor domains compared against this project's domain" }, "seedKeywords": { "type": "array", "items": { "type": "string" }, "description": "Seed keywords the research pipeline expands from" }, "idealCustomerProfileId": { "type": "string", "description": "ICP this project targets. Drives the relevance score and the content briefs." }, "status": { "type": "string", "description": "Project status. One of: active, archived.", "enum": [ "active", "archived" ] }, "frequency": { "type": "string", "description": "How often the project auto-runs. One of: manual, weekly, monthly. \"manual\" means it only runs when triggered.", "enum": [ "manual", "weekly", "monthly" ] }, "lastRunAt": { "type": "string", "format": "date-time", "description": "When the project last ran" }, "created_date": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updated_date": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "description": "A content research project. Each project researches one domain against one ideal customer profile, so separate ICPs or product lines should each get their own project rather than sharing one." }, "description": "Research projects owned by this company" } }, "description": "All research projects for the company" } } } } }, "summary": "List all content research projects for a company.", "description": "Each project targets one domain and one ideal customer profile. A company\ncan have many, and opportunities are scoped per project." }, "post": { "tags": [ "Content Research" ], "operationId": "content_research_createResearchProject", "parameters": [], "responses": { "400": { "description": "Domain is required, or invalid frequency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "The created project", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the operation succeeded" }, "project": { "type": "object", "properties": { "id": { "type": "string", "description": "Project ID (UUID)" }, "companyId": { "type": "string", "description": "Owning company ID" }, "createdBy": { "type": "string", "description": "UID of the user who created the project" }, "name": { "type": "string", "description": "Human-readable project name" }, "domain": { "type": "string", "description": "The domain being researched, e.g. \"yourcompany.com\"" }, "competitorDomains": { "type": "array", "items": { "type": "string" }, "description": "Competitor domains compared against this project's domain" }, "seedKeywords": { "type": "array", "items": { "type": "string" }, "description": "Seed keywords the research pipeline expands from" }, "idealCustomerProfileId": { "type": "string", "description": "ICP this project targets. Drives the relevance score and the content briefs." }, "status": { "type": "string", "description": "Project status. One of: active, archived.", "enum": [ "active", "archived" ] }, "frequency": { "type": "string", "description": "How often the project auto-runs. One of: manual, weekly, monthly. \"manual\" means it only runs when triggered.", "enum": [ "manual", "weekly", "monthly" ] }, "lastRunAt": { "type": "string", "format": "date-time", "description": "When the project last ran" }, "created_date": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updated_date": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "description": "The project" } }, "description": "A single research project" } } } } }, "summary": "Create a content research project.", "description": "Create one project per ideal customer profile or product line. Each run\nanalyses that project's domain, competitors and ICP on its own, so\nseparate audiences stay separated rather than being blended into one\nresult set.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID that will own the project" }, "domain": { "type": "string", "description": "Domain to research, e.g. \"yourcompany.com\". Required." }, "name": { "type": "string", "description": "Project name. Defaults to the domain if omitted." }, "competitorDomains": { "type": "array", "items": { "type": "string" }, "description": "Competitor domains to compare against (max 5 are used per run)" }, "seedKeywords": { "type": "array", "items": { "type": "string" }, "description": "Seed keywords to expand from. If omitted the pipeline infers them." }, "idealCustomerProfileId": { "type": "string", "description": "ICP to target. Determines the relevance score and brief angle; omit to have the pipeline infer the audience from company info." }, "frequency": { "type": "string", "description": "How often the project auto-runs. One of: manual, weekly, monthly. Defaults to \"manual\" (runs only when triggered).", "enum": [ "manual", "weekly", "monthly" ], "default": "manual" } }, "required": [ "companyId", "domain" ], "description": "Fields for a new research project. Create one project per ICP or product line - each run analyses this project's domain, competitors and ICP in isolation." } } }, "description": "Fields for the new research project" } } }, "/api/v0/research/projects/{projectId}": { "patch": { "tags": [ "Content Research" ], "operationId": "content_research_updateResearchProject", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid frequency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Project not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "The updated project", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the operation succeeded" }, "project": { "type": "object", "properties": { "id": { "type": "string", "description": "Project ID (UUID)" }, "companyId": { "type": "string", "description": "Owning company ID" }, "createdBy": { "type": "string", "description": "UID of the user who created the project" }, "name": { "type": "string", "description": "Human-readable project name" }, "domain": { "type": "string", "description": "The domain being researched, e.g. \"yourcompany.com\"" }, "competitorDomains": { "type": "array", "items": { "type": "string" }, "description": "Competitor domains compared against this project's domain" }, "seedKeywords": { "type": "array", "items": { "type": "string" }, "description": "Seed keywords the research pipeline expands from" }, "idealCustomerProfileId": { "type": "string", "description": "ICP this project targets. Drives the relevance score and the content briefs." }, "status": { "type": "string", "description": "Project status. One of: active, archived.", "enum": [ "active", "archived" ] }, "frequency": { "type": "string", "description": "How often the project auto-runs. One of: manual, weekly, monthly. \"manual\" means it only runs when triggered.", "enum": [ "manual", "weekly", "monthly" ] }, "lastRunAt": { "type": "string", "format": "date-time", "description": "When the project last ran" }, "created_date": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updated_date": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "description": "The project" } }, "description": "A single research project" } } } } }, "summary": "Update a research project's settings.", "description": "Changing the domain, competitors, seed keywords or ICP affects the next\nrun; it does not re-score opportunities already found.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID that owns the project" }, "name": { "type": "string", "description": "New project name" }, "domain": { "type": "string", "description": "New domain to research" }, "competitorDomains": { "type": "array", "items": { "type": "string" }, "description": "Replacement competitor domain list" }, "seedKeywords": { "type": "array", "items": { "type": "string" }, "description": "Replacement seed keyword list" }, "idealCustomerProfileId": { "type": "string", "description": "ICP to target" }, "status": { "type": "string", "description": "Project status. One of: active, archived.", "enum": [ "active", "archived" ] }, "frequency": { "type": "string", "description": "How often the project auto-runs. One of: manual, weekly, monthly.", "enum": [ "manual", "weekly", "monthly" ] } }, "required": [ "companyId" ], "description": "Fields to update on an existing research project. Only supplied fields change." } } }, "description": "Fields to update; only supplied fields change" } }, "delete": { "tags": [ "Content Research" ], "operationId": "content_research_deleteResearchProject", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID that owns the research projects" }, "description": "Company ID that owns the research projects" } ], "responses": { "400": { "description": "Company ID required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Project not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "The project was deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the operation succeeded" } }, "description": "Success response" } } } } }, "summary": "Delete a research project.", "description": "Soft-deletes the project. Its opportunities stop appearing in listings." } }, "/api/v0/research/projects/{projectId}/run": { "post": { "tags": [ "Content Research" ], "operationId": "content_research_runResearchProject", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Project not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Exceeded usage quota", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "The queued run, or the already-active run", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the request succeeded" }, "started": { "type": "boolean", "description": "True if a new run started; false if a run was already active and was returned instead" }, "run": { "type": "object", "properties": { "id": { "type": "string", "description": "Run ID (UUID)" }, "projectId": { "type": "string", "description": "Project this run belongs to" }, "companyId": { "type": "string", "description": "Owning company ID" }, "status": { "type": "string", "description": "Run status. One of: queued, running, completed, failed.", "enum": [ "queued", "running", "completed", "failed" ] }, "phase": { "type": "string", "description": "Current pipeline phase while running. One of: serp, aeo, keyword_metrics, domain_authority, analysis.", "enum": [ "serp", "aeo", "keyword_metrics", "domain_authority", "analysis" ] }, "stats": { "type": "object", "description": "Run statistics, including opportunitiesFound and per-phase timings" }, "error": { "type": "string", "description": "Failure reason when status is \"failed\"" }, "startedAt": { "type": "string", "format": "date-time", "description": "When the run started" }, "completedAt": { "type": "string", "format": "date-time", "description": "When the run finished" }, "created_date": { "type": "string", "format": "date-time", "description": "Creation timestamp" } }, "description": "The queued (or already-active) run" }, "creditCost": { "type": "number", "description": "Actual provider credits recorded so far. No fixed upfront fee; AI token usage is billed separately." } }, "description": "Result of a run trigger. Returns 202 when a new run started, or 200 with started=false when a run was already in progress for this project." } } } } }, "summary": "Start a research run for a project.", "description": "Runs asynchronously through the SERP, AI-answer, keyword-metrics,\ndomain-authority and analysis phases, then upserts scored opportunities.\nPoll the runs endpoint for status. Only one run per project can be active\nat a time - triggering while one is in flight returns that run with\nstarted=false rather than starting a second.\n\nCharges a flat credit cost up front, which is not refunded if the run\nlater fails.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID that owns the project" } }, "required": [ "companyId" ], "description": "Request body for starting a research run" } } }, "description": "Company scope for the run" } } }, "/api/v0/research/projects/{projectId}/runs": { "get": { "tags": [ "Content Research" ], "operationId": "content_research_listResearchRuns", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID that owns the research projects" }, "description": "Company ID that owns the research projects" } ], "responses": { "400": { "description": "Company ID required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Project not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Run history for the project, newest first", "content": { "application/json": { "schema": { "type": "object", "properties": { "runs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Run ID (UUID)" }, "projectId": { "type": "string", "description": "Project this run belongs to" }, "companyId": { "type": "string", "description": "Owning company ID" }, "status": { "type": "string", "description": "Run status. One of: queued, running, completed, failed.", "enum": [ "queued", "running", "completed", "failed" ] }, "phase": { "type": "string", "description": "Current pipeline phase while running. One of: serp, aeo, keyword_metrics, domain_authority, analysis.", "enum": [ "serp", "aeo", "keyword_metrics", "domain_authority", "analysis" ] }, "stats": { "type": "object", "description": "Run statistics, including opportunitiesFound and per-phase timings" }, "error": { "type": "string", "description": "Failure reason when status is \"failed\"" }, "startedAt": { "type": "string", "format": "date-time", "description": "When the run started" }, "completedAt": { "type": "string", "format": "date-time", "description": "When the run finished" }, "created_date": { "type": "string", "format": "date-time", "description": "Creation timestamp" } }, "description": "One execution of a research project's harvest-and-analyse pipeline" }, "description": "Runs for this project" } }, "description": "Run history for a project, newest first" } } } } }, "summary": "List run history for a research project.", "description": "Newest first. Poll this after triggering a run: the first entry carries\nthe live status and phase while the pipeline is working." } }, "/api/v0/research/opportunities": { "get": { "tags": [ "Content Research" ], "operationId": "content_research_listOpportunities", "parameters": [ { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID that owns the opportunities" }, "description": "Company ID that owns the opportunities" }, { "name": "projectId", "in": "query", "required": false, "schema": { "type": "string", "description": "Restrict to one project. Omit to return opportunities across all projects." }, "description": "Restrict to one project. Omit to return opportunities across all projects." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Page number, 1-indexed", "default": 1 }, "description": "Page number, 1-indexed" }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "description": "Results per page (max 100)", "default": 50 }, "description": "Results per page (max 100)" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "description": "Filter by status. One of: new, dismissed, generated.", "enum": [ "new", "dismissed", "generated" ] }, "description": "Filter by status. One of: new, dismissed, generated." }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "description": "Filter by opportunity type. One of: keyword_gap, question, ai_citation_gap, competitor_gap, trending.", "enum": [ "keyword_gap", "question", "ai_citation_gap", "competitor_gap", "trending" ] }, "description": "Filter by opportunity type. One of: keyword_gap, question, ai_citation_gap, competitor_gap, trending." }, { "name": "funnelStage", "in": "query", "required": false, "schema": { "type": "string", "description": "Filter by funnel stage. One of: tofu, mofu, bofu.", "enum": [ "tofu", "mofu", "bofu" ] }, "description": "Filter by funnel stage. One of: tofu, mofu, bofu." } ], "responses": { "400": { "description": "Invalid pagination parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Project not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Paginated content opportunities", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Opportunity ID (UUID)" }, "projectId": { "type": "string", "description": "Project that produced this opportunity" }, "companyId": { "type": "string", "description": "Owning company ID" }, "title": { "type": "string", "description": "Proposed content title" }, "type": { "type": "string", "description": "Opportunity type. One of: keyword_gap, question, ai_citation_gap, competitor_gap, trending.", "enum": [ "keyword_gap", "question", "ai_citation_gap", "competitor_gap", "trending" ] }, "targetKeywords": { "type": "array", "items": { "type": "object", "properties": { "keyword": { "type": "string", "description": "The keyword phrase" }, "volume": { "type": "integer", "description": "Monthly search volume" }, "cpc": { "type": "number", "description": "Cost per click in USD" }, "competition": { "type": "string", "description": "Competition level" }, "trend": { "type": "string", "description": "Volume trend direction" } }, "description": "A target keyword and its search metrics" }, "description": "Target keywords with volume, CPC and competition" }, "searchIntent": { "type": "string", "description": "Search intent. One of: informational, commercial, transactional, navigational.", "enum": [ "informational", "commercial", "transactional", "navigational" ] }, "funnelStage": { "type": "string", "description": "Funnel stage. One of: tofu, mofu, bofu.", "enum": [ "tofu", "mofu", "bofu" ] }, "opportunityScore": { "type": "integer", "description": "Overall score, 0-100" }, "scoreBreakdown": { "type": "object", "description": "Score components: demand, attainability, relevance, aeoUpside, plus a rationale" }, "brief": { "type": "object", "description": "Generation brief: angle, outline, questionsToAnswer" }, "evidence": { "type": "object", "description": "Supporting evidence: serp results, aiCitations, competitorCoverage" }, "status": { "type": "string", "description": "Opportunity status. One of: new, dismissed, generated.", "enum": [ "new", "dismissed", "generated" ] }, "contentId": { "type": "string", "description": "Content record created from this opportunity, if generated" }, "monitorId": { "type": "string", "description": "Keyword monitor tracking this opportunity, if tracked" }, "created_date": { "type": "string", "format": "date-time", "description": "Creation timestamp" } }, "description": "A scored content opportunity with its evidence and generation brief" }, "description": "Opportunities on this page" }, "total": { "type": "integer", "description": "Total matching opportunities across all pages" } }, "description": "Paginated list of content opportunities" } } } } }, "summary": "List scored content opportunities.", "description": "Pass projectId to scope results to one project's ICP; omit it to see\nopportunities across every project for the company." } }, "/api/v0/research/opportunities/{opportunityId}": { "get": { "tags": [ "Content Research" ], "operationId": "content_research_getOpportunity", "parameters": [ { "name": "opportunityId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID that owns the research projects" }, "description": "Company ID that owns the research projects" } ], "responses": { "400": { "description": "Company ID required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Opportunity not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "The opportunity with its full brief and evidence", "content": { "application/json": { "schema": { "type": "object", "properties": { "opportunity": { "type": "object", "properties": { "id": { "type": "string", "description": "Opportunity ID (UUID)" }, "projectId": { "type": "string", "description": "Project that produced this opportunity" }, "companyId": { "type": "string", "description": "Owning company ID" }, "title": { "type": "string", "description": "Proposed content title" }, "type": { "type": "string", "description": "Opportunity type. One of: keyword_gap, question, ai_citation_gap, competitor_gap, trending.", "enum": [ "keyword_gap", "question", "ai_citation_gap", "competitor_gap", "trending" ] }, "targetKeywords": { "type": "array", "items": { "type": "object", "properties": { "keyword": { "type": "string", "description": "The keyword phrase" }, "volume": { "type": "integer", "description": "Monthly search volume" }, "cpc": { "type": "number", "description": "Cost per click in USD" }, "competition": { "type": "string", "description": "Competition level" }, "trend": { "type": "string", "description": "Volume trend direction" } }, "description": "A target keyword and its search metrics" }, "description": "Target keywords with volume, CPC and competition" }, "searchIntent": { "type": "string", "description": "Search intent. One of: informational, commercial, transactional, navigational.", "enum": [ "informational", "commercial", "transactional", "navigational" ] }, "funnelStage": { "type": "string", "description": "Funnel stage. One of: tofu, mofu, bofu.", "enum": [ "tofu", "mofu", "bofu" ] }, "opportunityScore": { "type": "integer", "description": "Overall score, 0-100" }, "scoreBreakdown": { "type": "object", "description": "Score components: demand, attainability, relevance, aeoUpside, plus a rationale" }, "brief": { "type": "object", "description": "Generation brief: angle, outline, questionsToAnswer" }, "evidence": { "type": "object", "description": "Supporting evidence: serp results, aiCitations, competitorCoverage" }, "status": { "type": "string", "description": "Opportunity status. One of: new, dismissed, generated.", "enum": [ "new", "dismissed", "generated" ] }, "contentId": { "type": "string", "description": "Content record created from this opportunity, if generated" }, "monitorId": { "type": "string", "description": "Keyword monitor tracking this opportunity, if tracked" }, "created_date": { "type": "string", "format": "date-time", "description": "Creation timestamp" } }, "description": "The opportunity" } }, "description": "A single content opportunity" } } } } }, "summary": "Get a single content opportunity.", "description": "Returns the full record including the score breakdown, generation brief\nand supporting SERP and AI-citation evidence." } }, "/api/v0/research/opportunities/{opportunityId}/dismiss": { "post": { "tags": [ "Content Research" ], "operationId": "content_research_dismissOpportunity", "parameters": [ { "name": "opportunityId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Opportunity not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "The dismissed opportunity", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the operation succeeded" }, "opportunity": { "type": "object", "properties": { "id": { "type": "string", "description": "Opportunity ID (UUID)" }, "projectId": { "type": "string", "description": "Project that produced this opportunity" }, "companyId": { "type": "string", "description": "Owning company ID" }, "title": { "type": "string", "description": "Proposed content title" }, "type": { "type": "string", "description": "Opportunity type. One of: keyword_gap, question, ai_citation_gap, competitor_gap, trending.", "enum": [ "keyword_gap", "question", "ai_citation_gap", "competitor_gap", "trending" ] }, "targetKeywords": { "type": "array", "items": { "type": "object", "properties": { "keyword": { "type": "string", "description": "The keyword phrase" }, "volume": { "type": "integer", "description": "Monthly search volume" }, "cpc": { "type": "number", "description": "Cost per click in USD" }, "competition": { "type": "string", "description": "Competition level" }, "trend": { "type": "string", "description": "Volume trend direction" } }, "description": "A target keyword and its search metrics" }, "description": "Target keywords with volume, CPC and competition" }, "searchIntent": { "type": "string", "description": "Search intent. One of: informational, commercial, transactional, navigational.", "enum": [ "informational", "commercial", "transactional", "navigational" ] }, "funnelStage": { "type": "string", "description": "Funnel stage. One of: tofu, mofu, bofu.", "enum": [ "tofu", "mofu", "bofu" ] }, "opportunityScore": { "type": "integer", "description": "Overall score, 0-100" }, "scoreBreakdown": { "type": "object", "description": "Score components: demand, attainability, relevance, aeoUpside, plus a rationale" }, "brief": { "type": "object", "description": "Generation brief: angle, outline, questionsToAnswer" }, "evidence": { "type": "object", "description": "Supporting evidence: serp results, aiCitations, competitorCoverage" }, "status": { "type": "string", "description": "Opportunity status. One of: new, dismissed, generated.", "enum": [ "new", "dismissed", "generated" ] }, "contentId": { "type": "string", "description": "Content record created from this opportunity, if generated" }, "monitorId": { "type": "string", "description": "Keyword monitor tracking this opportunity, if tracked" }, "created_date": { "type": "string", "format": "date-time", "description": "Creation timestamp" } }, "description": "The updated opportunity" } }, "description": "The opportunity after its status changed" } } } } }, "summary": "Dismiss a content opportunity.", "description": "Hides it from the default listing. Re-running the project will not\nresurface it as new.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID that owns the opportunity" } }, "required": [ "companyId" ], "description": "Company scope for an opportunity action" } } }, "description": "Company scope" } } }, "/api/v0/research/opportunities/{opportunityId}/restore": { "post": { "tags": [ "Content Research" ], "operationId": "content_research_restoreOpportunity", "parameters": [ { "name": "opportunityId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Opportunity not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "The restored opportunity", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the operation succeeded" }, "opportunity": { "type": "object", "properties": { "id": { "type": "string", "description": "Opportunity ID (UUID)" }, "projectId": { "type": "string", "description": "Project that produced this opportunity" }, "companyId": { "type": "string", "description": "Owning company ID" }, "title": { "type": "string", "description": "Proposed content title" }, "type": { "type": "string", "description": "Opportunity type. One of: keyword_gap, question, ai_citation_gap, competitor_gap, trending.", "enum": [ "keyword_gap", "question", "ai_citation_gap", "competitor_gap", "trending" ] }, "targetKeywords": { "type": "array", "items": { "type": "object", "properties": { "keyword": { "type": "string", "description": "The keyword phrase" }, "volume": { "type": "integer", "description": "Monthly search volume" }, "cpc": { "type": "number", "description": "Cost per click in USD" }, "competition": { "type": "string", "description": "Competition level" }, "trend": { "type": "string", "description": "Volume trend direction" } }, "description": "A target keyword and its search metrics" }, "description": "Target keywords with volume, CPC and competition" }, "searchIntent": { "type": "string", "description": "Search intent. One of: informational, commercial, transactional, navigational.", "enum": [ "informational", "commercial", "transactional", "navigational" ] }, "funnelStage": { "type": "string", "description": "Funnel stage. One of: tofu, mofu, bofu.", "enum": [ "tofu", "mofu", "bofu" ] }, "opportunityScore": { "type": "integer", "description": "Overall score, 0-100" }, "scoreBreakdown": { "type": "object", "description": "Score components: demand, attainability, relevance, aeoUpside, plus a rationale" }, "brief": { "type": "object", "description": "Generation brief: angle, outline, questionsToAnswer" }, "evidence": { "type": "object", "description": "Supporting evidence: serp results, aiCitations, competitorCoverage" }, "status": { "type": "string", "description": "Opportunity status. One of: new, dismissed, generated.", "enum": [ "new", "dismissed", "generated" ] }, "contentId": { "type": "string", "description": "Content record created from this opportunity, if generated" }, "monitorId": { "type": "string", "description": "Keyword monitor tracking this opportunity, if tracked" }, "created_date": { "type": "string", "format": "date-time", "description": "Creation timestamp" } }, "description": "The updated opportunity" } }, "description": "The opportunity after its status changed" } } } } }, "summary": "Restore a dismissed opportunity.", "description": "Returns it to \"new\" so it appears in the default listing again.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID that owns the opportunity" } }, "required": [ "companyId" ], "description": "Company scope for an opportunity action" } } }, "description": "Company scope" } } }, "/api/v0/research/opportunities/{opportunityId}/generate": { "post": { "tags": [ "Content Research" ], "operationId": "content_research_generateFromOpportunity", "parameters": [ { "name": "opportunityId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Opportunity not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Generation started in the background", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether generation was started" }, "message": { "type": "string", "description": "Status message" } }, "description": "Acknowledgement that content generation started in the background" } } } } }, "summary": "Generate a content piece from an opportunity's brief.", "description": "Creates a record in the Content Engine and writes the piece in the\nbackground using the opportunity's title, outline, target keywords and\nAEO recommendations. Defaults to the parent project's ICP unless icpId\nis supplied. Returns immediately; the opportunity moves to \"generated\".", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID that owns the opportunity" }, "contentType": { "type": "string", "description": "Content type to generate, e.g. \"blog_post\" or \"linkedin_post\". Defaults to \"blog_post\".", "default": "blog_post" }, "brandVoiceId": { "type": "string", "description": "Brand voice to write in" }, "generateImages": { "type": "boolean", "description": "Generate images with the content; disable for text only", "default": true }, "brandImageId": { "type": "string", "description": "Brand image set for visuals" }, "publishDate": { "type": "string", "format": "date-time", "description": "Scheduled publish date for the generated piece" }, "funnelStage": { "type": "string", "description": "Override the funnel stage. One of: tofu, mofu, bofu. Defaults to the opportunity's own stage.", "enum": [ "tofu", "mofu", "bofu" ] }, "icpId": { "type": "string", "description": "ICP to write for. Defaults to the parent project's ICP." } }, "required": [ "companyId" ], "description": "Options for generating a content piece from an opportunity's brief" } } }, "description": "Generation options" } } }, "/api/v0/research/opportunities/{opportunityId}/track": { "post": { "tags": [ "Content Research" ], "operationId": "content_research_trackOpportunity", "parameters": [ { "name": "opportunityId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Already tracked, or no target keywords", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Opportunity not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "The created keyword monitor", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the monitor was created" }, "monitor": { "type": "object", "description": "The created keyword monitor" } }, "description": "The keyword monitor created for this opportunity" } } } } }, "summary": "Track an opportunity's keywords with a monitor.", "description": "Creates a daily keyword monitor across Google AI and ChatGPT for up to\nthe opportunity's first three target keywords, so citation changes are\npicked up over time. Fails if the opportunity is already tracked.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID that owns the opportunity" } }, "required": [ "companyId" ], "description": "Company scope for an opportunity action" } } }, "description": "Company scope" } } }, "/api/v0/seo/keywords/research": { "get": { "tags": [ "SEO" ], "operationId": "seo_researchKeywordsRoute", "parameters": [ { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID" }, "description": "Company ID" }, { "name": "keyword", "in": "query", "required": true, "schema": { "type": "string", "description": "Seed keyword to research. The lookup expands this into related terms automatically." }, "description": "Seed keyword to research. The lookup expands this into related terms automatically." }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string", "description": "Two-letter country code. Defaults to \"us\"." }, "description": "Two-letter country code. Defaults to \"us\"." }, { "name": "language", "in": "query", "required": false, "schema": { "type": "string", "description": "Two-letter language code. Defaults to \"en\"." }, "description": "Two-letter language code. Defaults to \"en\"." }, { "name": "includeSerp", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Also return the top organic results for the seed keyword" }, "description": "Also return the top organic results for the seed keyword" }, { "name": "refresh", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Bypass the cache and re-purchase. Costs credits - leave false unless the data is known to be stale." }, "description": "Bypass the cache and re-purchase. Costs credits - leave false unless the data is known to be stale." }, { "name": "sortBy", "in": "query", "required": false, "schema": { "type": "string", "description": "Sort field. One of: volume, cpc, competition, keyword. Defaults to volume.", "enum": [ "volume", "cpc", "competition", "keyword" ] }, "description": "Sort field. One of: volume, cpc, competition, keyword. Defaults to volume." } ], "responses": { "400": { "description": "Keyword required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Keyword demand metrics", "content": { "application/json": { "schema": { "type": "object", "properties": { "seed": { "type": "string", "description": "The keyword that was researched" }, "country": { "type": "string", "description": "Country the metrics apply to" }, "language": { "type": "string", "description": "Language the metrics apply to" }, "keywords": { "type": "array", "items": { "type": "object", "properties": { "keyword": { "type": "string", "description": "The keyword, lowercased" }, "volume": { "type": "integer", "description": "Monthly search volume, or null if unknown" }, "volumeSource": { "type": "string", "description": "Which network reported the volume: \"google\" or \"bing\". Never compare volumes across sources - Bing absolute volumes run well below Google." }, "cpc": { "type": "number", "description": "Average cost per click in USD" }, "competition": { "type": "string", "description": "Advertiser competition label" }, "competitionIndex": { "type": "integer", "description": "Advertiser competition, 0-100" }, "monthlySearches": { "type": "array", "items": { "type": "object" }, "description": "12-month volume series" }, "trend": { "type": "string", "description": "Direction of demand: rising, stable or falling" }, "momChangePct": { "type": "number", "description": "Month-over-month change, percent" }, "saved": { "type": "boolean", "description": "Whether this keyword is on the company saved list" }, "isSeed": { "type": "boolean", "description": "Whether this is the keyword that was searched for" }, "fetchedAt": { "type": "string", "format": "date-time", "description": "When these metrics were last purchased" } }, "description": "Demand metrics for a single keyword. Volume may be null: the ad networks report no volume for much of the long tail." }, "description": "The seed keyword plus related terms, with metrics" }, "serp": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "description": "Result title" }, "url": { "type": "string", "description": "Result URL" }, "description": { "type": "string", "description": "Result snippet" } }, "description": "An organic Google result" }, "description": "Top organic results, when includeSerp was set" }, "purchased": { "type": "boolean", "description": "Whether this lookup bought new data. False means it was served from cache and cost nothing." }, "fromCache": { "type": "integer", "description": "How many keywords were already cached" }, "requested": { "type": "integer", "description": "How many keywords were purchased" }, "creditCost": { "type": "number", "description": "Credits charged (actual vendor cost). Zero on a cache hit." } }, "description": "Demand metrics for the seed keyword and its related terms" } } } } }, "summary": "Research search demand for a keyword.", "description": "Expands the seed keyword into related terms and returns volume, CPC and\ncompetition for each. Answers from cache when it can; only purchases the\nterms that are missing, and reports whether anything was bought." } }, "/api/v0/seo/domain/overview": { "get": { "tags": [ "SEO" ], "operationId": "seo_domainOverviewRoute", "parameters": [ { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID" }, "description": "Company ID" }, { "name": "domain", "in": "query", "required": true, "schema": { "type": "string", "description": "Domain to look up, e.g. \"example.com\". Scheme and www are stripped automatically." }, "description": "Domain to look up, e.g. \"example.com\". Scheme and www are stripped automatically." }, { "name": "refresh", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Bypass the cache and re-purchase. Costs credits." }, "description": "Bypass the cache and re-purchase. Costs credits." } ], "responses": { "400": { "description": "Domain required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Domain authority and traffic", "content": { "application/json": { "schema": { "type": "object", "properties": { "overview": { "type": "object", "properties": { "domain": { "type": "string", "description": "The normalized domain" }, "found": { "type": "boolean", "description": "Whether any data was available for this domain" }, "domainRating": { "type": "integer", "description": "Domain rank (link authority), 0-1000" }, "backlinks": { "type": "integer", "description": "Total inbound links" }, "refDomains": { "type": "integer", "description": "Number of distinct referring domains" }, "monthlyTraffic": { "type": "integer", "description": "Estimated average monthly organic visits" }, "fetchedAt": { "type": "string", "format": "date-time", "description": "When these numbers were last purchased" }, "details": { "type": "object", "description": "Full breakdown: organic {keywords, top3, top10, top20, top50, newKeywords, upKeywords, downKeywords, lostKeywords, trafficValue}, paid {keywords, traffic}, links {domainRank, referringMainDomains, referringIps, referringPages, brokenBacklinks, brokenPages, nofollowReferringDomains, dofollowShare, spamScore, firstSeen, crawledPages, linkTypes, linkAttributes, topTlds, topCountries}, site {cms, server, ip, platformTypes, spamScore}" }, "purchased": { "type": "boolean", "description": "Whether this lookup bought new data" }, "creditCost": { "type": "number", "description": "Credits charged (actual vendor cost). Zero on a cache hit." } }, "description": "Authority, traffic and link counts for a domain" } }, "description": "Overview for the requested domain" } } } } }, "summary": "Look up authority and traffic for a domain.", "description": "Returns domain rating, estimated monthly organic traffic, total backlinks\nand referring domain count. Served from cache when available." } }, "/api/v0/seo/domain/compare": { "post": { "tags": [ "SEO" ], "operationId": "seo_compareDomainsRoute", "parameters": [], "responses": { "400": { "description": "Domains required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Overview for each domain", "content": { "application/json": { "schema": { "type": "object", "properties": { "domains": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": "string", "description": "The normalized domain" }, "found": { "type": "boolean", "description": "Whether any data was available for this domain" }, "domainRating": { "type": "integer", "description": "Domain rank (link authority), 0-1000" }, "backlinks": { "type": "integer", "description": "Total inbound links" }, "refDomains": { "type": "integer", "description": "Number of distinct referring domains" }, "monthlyTraffic": { "type": "integer", "description": "Estimated average monthly organic visits" }, "fetchedAt": { "type": "string", "format": "date-time", "description": "When these numbers were last purchased" }, "details": { "type": "object", "description": "Full breakdown: organic {keywords, top3, top10, top20, top50, newKeywords, upKeywords, downKeywords, lostKeywords, trafficValue}, paid {keywords, traffic}, links {domainRank, referringMainDomains, referringIps, referringPages, brokenBacklinks, brokenPages, nofollowReferringDomains, dofollowShare, spamScore, firstSeen, crawledPages, linkTypes, linkAttributes, topTlds, topCountries}, site {cms, server, ip, platformTypes, spamScore}" }, "purchased": { "type": "boolean", "description": "Whether this lookup bought new data" }, "creditCost": { "type": "number", "description": "Credits charged (actual vendor cost). Zero on a cache hit." } }, "description": "Authority, traffic and link counts for a domain" } } }, "description": "Overviews for each requested domain" } } } } }, "summary": "Compare authority across several domains.", "description": "Intended for putting your own domain next to its competitors. Each domain\nis billed separately when it is not already cached.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "domains": { "type": "array", "items": { "type": "string" }, "description": "Domains to compare. Duplicates are ignored." }, "refresh": { "type": "boolean", "description": "Bypass the cache and re-purchase. Costs credits per domain." } }, "required": [ "companyId", "domains" ], "description": "Compare authority across your domain and competitors" } } }, "description": "Domains to compare" } } }, "/api/v0/seo/keywords": { "get": { "tags": [ "SEO" ], "operationId": "seo_listKeywordsRoute", "parameters": [ { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID" }, "description": "Company ID" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "1-indexed page number" }, "description": "1-indexed page number" }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "description": "Rows per page, max 100" }, "description": "Rows per page, max 100" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "description": "Filter to keywords containing this text" }, "description": "Filter to keywords containing this text" }, { "name": "tag", "in": "query", "required": false, "schema": { "type": "string", "description": "Filter to keywords carrying this tag" }, "description": "Filter to keywords carrying this tag" }, { "name": "savedOnly", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Only keywords a user saved. Defaults to false (all keywords)." }, "description": "Only keywords a user saved. Defaults to false (all keywords)." }, { "name": "sortBy", "in": "query", "required": false, "schema": { "type": "string", "description": "Sort field. Defaults to volume, highest first.", "enum": [ "volume", "cpc", "competition", "keyword" ] }, "description": "Sort field. Defaults to volume, highest first." }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string", "description": "Country code. Defaults to \"us\"." }, "description": "Country code. Defaults to \"us\"." }, { "name": "language", "in": "query", "required": false, "schema": { "type": "string", "description": "Language code. Defaults to \"en\"." }, "description": "Language code. Defaults to \"en\"." } ], "responses": { "400": { "description": "Company ID required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Keywords with metrics", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Keyword ID (UUID)" }, "keyword": { "type": "string", "description": "The keyword, lowercased" }, "country": { "type": "string", "description": "Country code the metrics were pulled for" }, "language": { "type": "string", "description": "Language code the metrics were pulled for" }, "saved": { "type": "boolean", "description": "Whether a user explicitly saved this keyword" }, "savedAt": { "type": "string", "format": "date-time", "description": "When it was saved, or null" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Free-text labels for grouping" }, "notes": { "type": "string", "description": "Free-text note" }, "metrics": { "type": "object", "properties": { "keyword": { "type": "string", "description": "The keyword, lowercased" }, "volume": { "type": "integer", "description": "Monthly search volume, or null if unknown" }, "volumeSource": { "type": "string", "description": "Which network reported the volume: \"google\" or \"bing\". Never compare volumes across sources - Bing absolute volumes run well below Google." }, "cpc": { "type": "number", "description": "Average cost per click in USD" }, "competition": { "type": "string", "description": "Advertiser competition label" }, "competitionIndex": { "type": "integer", "description": "Advertiser competition, 0-100" }, "monthlySearches": { "type": "array", "items": { "type": "object" }, "description": "12-month volume series" }, "trend": { "type": "string", "description": "Direction of demand: rising, stable or falling" }, "momChangePct": { "type": "number", "description": "Month-over-month change, percent" }, "saved": { "type": "boolean", "description": "Whether this keyword is on the company saved list" }, "isSeed": { "type": "boolean", "description": "Whether this is the keyword that was searched for" }, "fetchedAt": { "type": "string", "format": "date-time", "description": "When these metrics were last purchased" } }, "description": "Cached metrics for this keyword" }, "created_date": { "type": "string", "format": "date-time", "description": "When the keyword was first harvested" } }, "description": "A keyword and its metrics. Rows are created when a research run or a manual lookup harvests the keyword, so everything the company has paid to discover is listed. `saved` records whether a user explicitly kept it." } }, "total": { "type": "integer", "description": "Total keywords matching the filters" }, "savedCount": { "type": "integer", "description": "How many of the company's keywords are saved" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "All tags currently in use" } }, "description": "One page of keywords" } } } } }, "summary": "List the company's keywords.", "description": "Returns every keyword the company has metrics for - including the ones a\nresearch run harvested - sorted by search volume. Pass savedOnly=true to\nnarrow to keywords a user explicitly kept." } }, "/api/v0/seo/keywords/saved": { "post": { "tags": [ "SEO" ], "operationId": "seo_saveKeywordsRoute", "parameters": [], "responses": { "400": { "description": "Keywords required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "How many were updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "saved": { "type": "integer", "description": "Keywords whose saved flag was set" }, "missing": { "type": "integer", "description": "Keywords with no metrics row yet, so nothing to flag" } }, "description": "How many keywords were updated" } } } } }, "summary": "Flag keywords as saved.", "description": "Sets the saved flag on keywords the company already has metrics for. Saving\nthe same set twice is a no-op rather than a duplicate.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "keywords": { "type": "array", "items": { "type": "string" }, "description": "Keywords to save. Lowercased and deduped automatically." }, "saved": { "type": "boolean", "description": "Set false to unsave instead. Defaults to true." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Labels to apply to all of these keywords" }, "notes": { "type": "string", "description": "Note to attach to all of these keywords" }, "country": { "type": "string", "description": "Country code. Defaults to \"us\"." }, "language": { "type": "string", "description": "Language code. Defaults to \"en\"." } }, "required": [ "companyId", "keywords" ], "description": "Flag keywords as saved. Operates on existing keyword rows; a keyword with no metrics yet is reported as missing rather than created blank." } } }, "description": "Keywords to save" } } }, "/api/v0/seo/keywords/{keywordId}": { "patch": { "tags": [ "SEO" ], "operationId": "seo_updateKeywordRoute", "parameters": [ { "name": "keywordId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid keyword ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "The updated keyword", "content": { "application/json": { "schema": { "type": "object", "properties": { "keyword": { "type": "object", "properties": { "id": { "type": "string", "description": "Keyword ID (UUID)" }, "keyword": { "type": "string", "description": "The keyword, lowercased" }, "country": { "type": "string", "description": "Country code the metrics were pulled for" }, "language": { "type": "string", "description": "Language code the metrics were pulled for" }, "saved": { "type": "boolean", "description": "Whether a user explicitly saved this keyword" }, "savedAt": { "type": "string", "format": "date-time", "description": "When it was saved, or null" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Free-text labels for grouping" }, "notes": { "type": "string", "description": "Free-text note" }, "metrics": { "type": "object", "properties": { "keyword": { "type": "string", "description": "The keyword, lowercased" }, "volume": { "type": "integer", "description": "Monthly search volume, or null if unknown" }, "volumeSource": { "type": "string", "description": "Which network reported the volume: \"google\" or \"bing\". Never compare volumes across sources - Bing absolute volumes run well below Google." }, "cpc": { "type": "number", "description": "Average cost per click in USD" }, "competition": { "type": "string", "description": "Advertiser competition label" }, "competitionIndex": { "type": "integer", "description": "Advertiser competition, 0-100" }, "monthlySearches": { "type": "array", "items": { "type": "object" }, "description": "12-month volume series" }, "trend": { "type": "string", "description": "Direction of demand: rising, stable or falling" }, "momChangePct": { "type": "number", "description": "Month-over-month change, percent" }, "saved": { "type": "boolean", "description": "Whether this keyword is on the company saved list" }, "isSeed": { "type": "boolean", "description": "Whether this is the keyword that was searched for" }, "fetchedAt": { "type": "string", "format": "date-time", "description": "When these metrics were last purchased" } }, "description": "Cached metrics for this keyword" }, "created_date": { "type": "string", "format": "date-time", "description": "When the keyword was first harvested" } }, "description": "A keyword and its metrics. Rows are created when a research run or a manual lookup harvests the keyword, so everything the company has paid to discover is listed. `saved` records whether a user explicitly kept it." } }, "description": "The keyword" } } } } }, "summary": "Update the tags or note on a keyword.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Replacement tag list" }, "notes": { "type": "string", "description": "Replacement note" } }, "required": [ "companyId" ], "description": "Update the tags or note on a keyword" } } }, "description": "Fields to update" } } }, "/api/v0/seo/keywords/{keywordId}/saved": { "delete": { "tags": [ "SEO" ], "operationId": "seo_unsaveKeywordRoute", "parameters": [ { "name": "keywordId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID" }, "description": "Company ID" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "1-indexed page number" }, "description": "1-indexed page number" }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "description": "Rows per page, max 100" }, "description": "Rows per page, max 100" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "description": "Filter to keywords containing this text" }, "description": "Filter to keywords containing this text" }, { "name": "tag", "in": "query", "required": false, "schema": { "type": "string", "description": "Filter to keywords carrying this tag" }, "description": "Filter to keywords carrying this tag" }, { "name": "savedOnly", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Only keywords a user saved. Defaults to false (all keywords)." }, "description": "Only keywords a user saved. Defaults to false (all keywords)." }, { "name": "sortBy", "in": "query", "required": false, "schema": { "type": "string", "description": "Sort field. Defaults to volume, highest first.", "enum": [ "volume", "cpc", "competition", "keyword" ] }, "description": "Sort field. Defaults to volume, highest first." }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string", "description": "Country code. Defaults to \"us\"." }, "description": "Country code. Defaults to \"us\"." }, { "name": "language", "in": "query", "required": false, "schema": { "type": "string", "description": "Language code. Defaults to \"en\"." }, "description": "Language code. Defaults to \"en\"." } ], "responses": { "400": { "description": "Invalid keyword ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Whether the keyword was unsaved", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the operation succeeded" } }, "description": "Success response" } } } } }, "summary": "Remove a keyword from the saved list.", "description": "Clears the saved flag only. The keyword and its metrics stay, so a later\nrun reuses them instead of re-buying the same term." } }, "/api/v0/seo/audits": { "post": { "tags": [ "SEO" ], "operationId": "seo_startAuditRoute", "parameters": [], "responses": { "400": { "description": "Domain required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "The queued audit", "content": { "application/json": { "schema": { "type": "object", "properties": { "audit": { "type": "object", "properties": { "id": { "type": "string", "description": "Audit ID (UUID)" }, "domain": { "type": "string", "description": "Domain that was crawled" }, "startUrl": { "type": "string", "description": "URL the crawl started from" }, "status": { "type": "string", "description": "queued, running, complete or failed", "enum": [ "queued", "running", "cancelling", "cancelled", "complete", "failed" ] }, "error": { "type": "string", "description": "Failure reason when status is failed" }, "maxPages": { "type": "integer", "description": "Page ceiling for this crawl" }, "pagesCrawled": { "type": "integer", "description": "Pages crawled so far" }, "healthScore": { "type": "integer", "description": "0-100, starts at 100 and drops per weighted issue" }, "issueCounts": { "type": "object", "description": "Issue totals by severity" }, "issueSummary": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Check id" }, "severity": { "type": "string", "description": "critical, warning or notice" }, "label": { "type": "string", "description": "Human-readable issue name" }, "pageCount": { "type": "integer", "description": "Pages carrying this issue" } }, "description": "Per-check rollup across the crawl" }, "description": "Per-check rollup, worst severity first" }, "linksChecked": { "type": "integer", "description": "Distinct URLs probed across the crawl" }, "brokenLinkCount": { "type": "integer", "description": "Distinct broken URLs found" }, "avgResponseMs": { "type": "integer", "description": "Mean time to first response, ms" }, "aiReadinessScore": { "type": "integer", "description": "Internal technical GEO readiness score, 0-100" }, "aiReadinessGrade": { "type": "string", "description": "Letter grade for technical GEO readiness" }, "aiReadinessChecks": { "type": "object", "description": "Evidence-backed technical GEO checks (robots.txt, llms.txt, sitemap, Schema.org, extractability, TTFB, HTTPS)" }, "aiReadinessRecommendations": { "type": "array", "items": { "type": "object" }, "description": "Prioritized technical GEO fixes" }, "aiReadinessCheckedAt": { "type": "string", "format": "date-time", "description": "When technical GEO readiness was scored" }, "aiReadinessError": { "type": "string", "description": "Why the technical GEO check failed, when it did" }, "startedAt": { "type": "string", "format": "date-time", "description": "When the crawl began" }, "completedAt": { "type": "string", "format": "date-time", "description": "When the crawl finished" }, "created_date": { "type": "string", "format": "date-time", "description": "When the audit was queued" } }, "description": "A site audit. Carries its own rolled-up totals, so listing audits never loads the per-page rows." } }, "description": "The site audit" } } } } }, "summary": "Start a site audit.", "description": "Crawls the domain from its homepage and checks each page for on-page SEO\nproblems. Returns as soon as the audit is queued - the crawl runs in the\nbackground, so poll the audit until its status is complete.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "domain": { "type": "string", "description": "Domain or URL to audit. A bare domain is crawled over https." }, "maxPages": { "type": "integer", "description": "Pages to crawl, 1-500. Defaults to 25." }, "checkAiReadiness": { "type": "boolean", "description": "Deprecated compatibility field. Technical GEO checks are included automatically for every completed audit." } }, "required": [ "companyId", "domain" ], "description": "Queue a site audit. Returns immediately with a queued audit; the crawl runs in the background, so poll the audit until status is complete." } } }, "description": "Domain to audit" } }, "get": { "tags": [ "SEO" ], "operationId": "seo_listAuditsRoute", "parameters": [ { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID" }, "description": "Company ID" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "1-indexed page number" }, "description": "1-indexed page number" }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "description": "Rows per page, max 100" }, "description": "Rows per page, max 100" }, { "name": "projectId", "in": "query", "required": false, "schema": { "type": "string", "description": "Only audits of this monitored site" }, "description": "Only audits of this monitored site" } ], "responses": { "400": { "description": "Company ID required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Site audits", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Audit ID (UUID)" }, "domain": { "type": "string", "description": "Domain that was crawled" }, "startUrl": { "type": "string", "description": "URL the crawl started from" }, "status": { "type": "string", "description": "queued, running, complete or failed", "enum": [ "queued", "running", "cancelling", "cancelled", "complete", "failed" ] }, "error": { "type": "string", "description": "Failure reason when status is failed" }, "maxPages": { "type": "integer", "description": "Page ceiling for this crawl" }, "pagesCrawled": { "type": "integer", "description": "Pages crawled so far" }, "healthScore": { "type": "integer", "description": "0-100, starts at 100 and drops per weighted issue" }, "issueCounts": { "type": "object", "description": "Issue totals by severity" }, "issueSummary": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Check id" }, "severity": { "type": "string", "description": "critical, warning or notice" }, "label": { "type": "string", "description": "Human-readable issue name" }, "pageCount": { "type": "integer", "description": "Pages carrying this issue" } }, "description": "Per-check rollup across the crawl" }, "description": "Per-check rollup, worst severity first" }, "linksChecked": { "type": "integer", "description": "Distinct URLs probed across the crawl" }, "brokenLinkCount": { "type": "integer", "description": "Distinct broken URLs found" }, "avgResponseMs": { "type": "integer", "description": "Mean time to first response, ms" }, "aiReadinessScore": { "type": "integer", "description": "Internal technical GEO readiness score, 0-100" }, "aiReadinessGrade": { "type": "string", "description": "Letter grade for technical GEO readiness" }, "aiReadinessChecks": { "type": "object", "description": "Evidence-backed technical GEO checks (robots.txt, llms.txt, sitemap, Schema.org, extractability, TTFB, HTTPS)" }, "aiReadinessRecommendations": { "type": "array", "items": { "type": "object" }, "description": "Prioritized technical GEO fixes" }, "aiReadinessCheckedAt": { "type": "string", "format": "date-time", "description": "When technical GEO readiness was scored" }, "aiReadinessError": { "type": "string", "description": "Why the technical GEO check failed, when it did" }, "startedAt": { "type": "string", "format": "date-time", "description": "When the crawl began" }, "completedAt": { "type": "string", "format": "date-time", "description": "When the crawl finished" }, "created_date": { "type": "string", "format": "date-time", "description": "When the audit was queued" } }, "description": "A site audit. Carries its own rolled-up totals, so listing audits never loads the per-page rows." } }, "total": { "type": "integer", "description": "Total audits" } }, "description": "One page of site audits" } } } } }, "summary": "List the company's site audits, newest first." } }, "/api/v0/seo/audits/{auditId}": { "get": { "tags": [ "SEO" ], "operationId": "seo_getAuditRoute", "parameters": [ { "name": "auditId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID that owns the SEO data" }, "description": "Company ID that owns the SEO data" } ], "responses": { "400": { "description": "Invalid audit ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "The audit", "content": { "application/json": { "schema": { "type": "object", "properties": { "audit": { "type": "object", "properties": { "id": { "type": "string", "description": "Audit ID (UUID)" }, "domain": { "type": "string", "description": "Domain that was crawled" }, "startUrl": { "type": "string", "description": "URL the crawl started from" }, "status": { "type": "string", "description": "queued, running, complete or failed", "enum": [ "queued", "running", "cancelling", "cancelled", "complete", "failed" ] }, "error": { "type": "string", "description": "Failure reason when status is failed" }, "maxPages": { "type": "integer", "description": "Page ceiling for this crawl" }, "pagesCrawled": { "type": "integer", "description": "Pages crawled so far" }, "healthScore": { "type": "integer", "description": "0-100, starts at 100 and drops per weighted issue" }, "issueCounts": { "type": "object", "description": "Issue totals by severity" }, "issueSummary": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Check id" }, "severity": { "type": "string", "description": "critical, warning or notice" }, "label": { "type": "string", "description": "Human-readable issue name" }, "pageCount": { "type": "integer", "description": "Pages carrying this issue" } }, "description": "Per-check rollup across the crawl" }, "description": "Per-check rollup, worst severity first" }, "linksChecked": { "type": "integer", "description": "Distinct URLs probed across the crawl" }, "brokenLinkCount": { "type": "integer", "description": "Distinct broken URLs found" }, "avgResponseMs": { "type": "integer", "description": "Mean time to first response, ms" }, "aiReadinessScore": { "type": "integer", "description": "Internal technical GEO readiness score, 0-100" }, "aiReadinessGrade": { "type": "string", "description": "Letter grade for technical GEO readiness" }, "aiReadinessChecks": { "type": "object", "description": "Evidence-backed technical GEO checks (robots.txt, llms.txt, sitemap, Schema.org, extractability, TTFB, HTTPS)" }, "aiReadinessRecommendations": { "type": "array", "items": { "type": "object" }, "description": "Prioritized technical GEO fixes" }, "aiReadinessCheckedAt": { "type": "string", "format": "date-time", "description": "When technical GEO readiness was scored" }, "aiReadinessError": { "type": "string", "description": "Why the technical GEO check failed, when it did" }, "startedAt": { "type": "string", "format": "date-time", "description": "When the crawl began" }, "completedAt": { "type": "string", "format": "date-time", "description": "When the crawl finished" }, "created_date": { "type": "string", "format": "date-time", "description": "When the audit was queued" } }, "description": "A site audit. Carries its own rolled-up totals, so listing audits never loads the per-page rows." } }, "description": "The site audit" } } } } }, "summary": "Fetch one audit, including its issue summary and progress." }, "delete": { "tags": [ "SEO" ], "operationId": "seo_deleteAuditRoute", "parameters": [ { "name": "auditId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID that owns the SEO data" }, "description": "Company ID that owns the SEO data" } ], "responses": { "400": { "description": "Invalid audit ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Whether the audit was removed", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the operation succeeded" } }, "description": "Success response" } } } } }, "summary": "Remove a site audit." } }, "/api/v0/seo/audits/{auditId}/pages": { "get": { "tags": [ "SEO" ], "operationId": "seo_listAuditPagesRoute", "parameters": [ { "name": "auditId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID" }, "description": "Company ID" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "1-indexed page number" }, "description": "1-indexed page number" }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "description": "Rows per page, max 100" }, "description": "Rows per page, max 100" }, { "name": "issueId", "in": "query", "required": false, "schema": { "type": "string", "description": "Only pages carrying this check id, e.g. title_missing" }, "description": "Only pages carrying this check id, e.g. title_missing" } ], "responses": { "400": { "description": "Invalid audit ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Crawled pages", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Page row ID (UUID)" }, "url": { "type": "string", "description": "Page URL" }, "status": { "type": "string", "description": "ok, or error when the fetch failed" }, "fetchError": { "type": "string", "description": "Fetch failure reason, when status is error" }, "statusCode": { "type": "integer", "description": "Final HTTP status code" }, "finalUrl": { "type": "string", "description": "URL after following redirects" }, "redirectHops": { "type": "integer", "description": "Redirects before the final URL" }, "redirectChain": { "type": "array", "items": { "type": "object" }, "description": "Each redirect hop as {url, status}" }, "responseMs": { "type": "integer", "description": "Time to first response, ms" }, "brokenLinks": { "type": "array", "items": { "type": "object" }, "description": "Broken links found on this page as {url, status, scope}" }, "title": { "type": "string", "description": "Title tag text" }, "titleLength": { "type": "integer", "description": "Title length in characters" }, "metaDescription": { "type": "string", "description": "Meta description text" }, "metaDescriptionLength": { "type": "integer", "description": "Description length in characters" }, "h1": { "type": "string", "description": "First H1 on the page" }, "h1Count": { "type": "integer", "description": "How many H1 tags the page has" }, "canonical": { "type": "string", "description": "Canonical URL, if declared" }, "wordCount": { "type": "integer", "description": "Words of body content, excluding nav/footer/scripts" }, "imageCount": { "type": "integer", "description": "Images on the page" }, "imagesMissingAlt": { "type": "integer", "description": "Images with no alt text" }, "internalLinkCount": { "type": "integer", "description": "Links to the same host" }, "externalLinkCount": { "type": "integer", "description": "Links off-host" }, "noindex": { "type": "boolean", "description": "Whether a robots tag blocks indexing" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable check id, e.g. title_missing" }, "severity": { "type": "string", "description": "critical, warning or notice", "enum": [ "critical", "warning", "notice" ] }, "label": { "type": "string", "description": "Human-readable issue name" }, "detail": { "type": "string", "description": "What was found, when the check has specifics" } }, "description": "A single SEO issue found on a page" }, "description": "Failing checks" } }, "description": "A crawled page with its extracted on-page signals and issues. Signals are returned alongside the issues so a fix can be made without re-opening the page." } }, "total": { "type": "integer", "description": "Total pages matching the filter" } }, "description": "One page of crawled pages" } } } } }, "summary": "List the pages an audit crawled.", "description": "Pass issueId to see only the pages carrying one particular check, which is\nhow the summary drills into \"which pages are missing a title\"." } }, "/api/v0/seo/audits/{auditId}/ai-readiness": { "post": { "tags": [ "SEO" ], "operationId": "seo_runAiReadinessRoute", "parameters": [ { "name": "auditId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid audit ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "The audit, with the check queued", "content": { "application/json": { "schema": { "type": "object", "properties": { "audit": { "type": "object", "properties": { "id": { "type": "string", "description": "Audit ID (UUID)" }, "domain": { "type": "string", "description": "Domain that was crawled" }, "startUrl": { "type": "string", "description": "URL the crawl started from" }, "status": { "type": "string", "description": "queued, running, complete or failed", "enum": [ "queued", "running", "cancelling", "cancelled", "complete", "failed" ] }, "error": { "type": "string", "description": "Failure reason when status is failed" }, "maxPages": { "type": "integer", "description": "Page ceiling for this crawl" }, "pagesCrawled": { "type": "integer", "description": "Pages crawled so far" }, "healthScore": { "type": "integer", "description": "0-100, starts at 100 and drops per weighted issue" }, "issueCounts": { "type": "object", "description": "Issue totals by severity" }, "issueSummary": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Check id" }, "severity": { "type": "string", "description": "critical, warning or notice" }, "label": { "type": "string", "description": "Human-readable issue name" }, "pageCount": { "type": "integer", "description": "Pages carrying this issue" } }, "description": "Per-check rollup across the crawl" }, "description": "Per-check rollup, worst severity first" }, "linksChecked": { "type": "integer", "description": "Distinct URLs probed across the crawl" }, "brokenLinkCount": { "type": "integer", "description": "Distinct broken URLs found" }, "avgResponseMs": { "type": "integer", "description": "Mean time to first response, ms" }, "aiReadinessScore": { "type": "integer", "description": "Internal technical GEO readiness score, 0-100" }, "aiReadinessGrade": { "type": "string", "description": "Letter grade for technical GEO readiness" }, "aiReadinessChecks": { "type": "object", "description": "Evidence-backed technical GEO checks (robots.txt, llms.txt, sitemap, Schema.org, extractability, TTFB, HTTPS)" }, "aiReadinessRecommendations": { "type": "array", "items": { "type": "object" }, "description": "Prioritized technical GEO fixes" }, "aiReadinessCheckedAt": { "type": "string", "format": "date-time", "description": "When technical GEO readiness was scored" }, "aiReadinessError": { "type": "string", "description": "Why the technical GEO check failed, when it did" }, "startedAt": { "type": "string", "format": "date-time", "description": "When the crawl began" }, "completedAt": { "type": "string", "format": "date-time", "description": "When the crawl finished" }, "created_date": { "type": "string", "format": "date-time", "description": "When the audit was queued" } }, "description": "A site audit. Carries its own rolled-up totals, so listing audits never loads the per-page rows." } }, "description": "The site audit" } } } } }, "summary": "Run (or re-run) the internal technical GEO check for an audit.", "description": "Scores AI crawler access, llms.txt, Schema.org and response speed in the\nbackground. The same check runs automatically after every site crawl.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID that owns the SEO data" } }, "required": [ "companyId" ], "description": "Company scope for the request" } } }, "description": "Company context" } } }, "/api/v0/seo/audits/{auditId}/cancel": { "post": { "tags": [ "SEO" ], "operationId": "seo_cancelAuditRoute", "parameters": [ { "name": "auditId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid audit ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Audit is not running", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "The audit, with cancellation requested", "content": { "application/json": { "schema": { "type": "object", "properties": { "audit": { "type": "object", "properties": { "id": { "type": "string", "description": "Audit ID (UUID)" }, "domain": { "type": "string", "description": "Domain that was crawled" }, "startUrl": { "type": "string", "description": "URL the crawl started from" }, "status": { "type": "string", "description": "queued, running, complete or failed", "enum": [ "queued", "running", "cancelling", "cancelled", "complete", "failed" ] }, "error": { "type": "string", "description": "Failure reason when status is failed" }, "maxPages": { "type": "integer", "description": "Page ceiling for this crawl" }, "pagesCrawled": { "type": "integer", "description": "Pages crawled so far" }, "healthScore": { "type": "integer", "description": "0-100, starts at 100 and drops per weighted issue" }, "issueCounts": { "type": "object", "description": "Issue totals by severity" }, "issueSummary": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Check id" }, "severity": { "type": "string", "description": "critical, warning or notice" }, "label": { "type": "string", "description": "Human-readable issue name" }, "pageCount": { "type": "integer", "description": "Pages carrying this issue" } }, "description": "Per-check rollup across the crawl" }, "description": "Per-check rollup, worst severity first" }, "linksChecked": { "type": "integer", "description": "Distinct URLs probed across the crawl" }, "brokenLinkCount": { "type": "integer", "description": "Distinct broken URLs found" }, "avgResponseMs": { "type": "integer", "description": "Mean time to first response, ms" }, "aiReadinessScore": { "type": "integer", "description": "Internal technical GEO readiness score, 0-100" }, "aiReadinessGrade": { "type": "string", "description": "Letter grade for technical GEO readiness" }, "aiReadinessChecks": { "type": "object", "description": "Evidence-backed technical GEO checks (robots.txt, llms.txt, sitemap, Schema.org, extractability, TTFB, HTTPS)" }, "aiReadinessRecommendations": { "type": "array", "items": { "type": "object" }, "description": "Prioritized technical GEO fixes" }, "aiReadinessCheckedAt": { "type": "string", "format": "date-time", "description": "When technical GEO readiness was scored" }, "aiReadinessError": { "type": "string", "description": "Why the technical GEO check failed, when it did" }, "startedAt": { "type": "string", "format": "date-time", "description": "When the crawl began" }, "completedAt": { "type": "string", "format": "date-time", "description": "When the crawl finished" }, "created_date": { "type": "string", "format": "date-time", "description": "When the audit was queued" } }, "description": "A site audit. Carries its own rolled-up totals, so listing audits never loads the per-page rows." } }, "description": "The site audit" } } } } }, "summary": "Stop a queued or running audit.", "description": "A queued audit stops immediately. A running one finishes its current wave\nof pages and then stops, keeping whatever it already crawled - so the\npartial result stays readable rather than being thrown away.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID that owns the SEO data" } }, "required": [ "companyId" ], "description": "Company scope for the request" } } }, "description": "Company context" } } }, "/api/v0/seo/projects": { "get": { "tags": [ "SEO" ], "operationId": "seo_listProjectsRoute", "parameters": [ { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID" }, "description": "Company ID" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "1-indexed page number" }, "description": "1-indexed page number" }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "description": "Rows per page, max 100" }, "description": "Rows per page, max 100" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "description": "Filter by domain or name" }, "description": "Filter by domain or name" } ], "responses": { "400": { "description": "Company ID required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "One page of monitored websites", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Project ID (UUID)" }, "companyId": { "type": "string", "description": "Company ID" }, "domain": { "type": "string", "description": "Monitored host, lowercased" }, "name": { "type": "string", "description": "Display name" }, "status": { "type": "string", "description": "active or paused", "enum": [ "active", "paused" ] }, "frequency": { "type": "string", "description": "manual, daily, weekly or monthly", "enum": [ "manual", "daily", "weekly", "monthly" ] }, "timezone": { "type": "string", "description": "Schedule timezone" }, "nextRunAt": { "type": "string", "format": "date-time", "description": "Next scheduled run (null when manual/paused)" }, "lastRunAt": { "type": "string", "format": "date-time", "description": "Last run" }, "runCount": { "type": "integer", "description": "Runs so far" }, "enabledModules": { "type": "object", "description": "Module key -> enabled. Keys: keyword_research, domain_overview, opportunities, backlinks, link_profile, rank_tracking, competitors, ai_visibility, site_audit, lighthouse" }, "trackedKeywords": { "type": "array", "items": { "type": "string" }, "description": "Keywords for rank tracking and keyword research" }, "competitorDomains": { "type": "array", "items": { "type": "string" }, "description": "Pinned competitor domains" }, "trackedPrompts": { "type": "array", "items": { "type": "string" }, "description": "Questions asked of AI platforms (AEO)" }, "brandNames": { "type": "array", "items": { "type": "string" }, "description": "Strings that count as a brand mention" }, "aiPlatforms": { "type": "object", "description": "AI platform key -> enabled (chatgpt, claude, gemini, perplexity)" }, "trackAiOverview": { "type": "boolean", "description": "Also check Google AI Overview" }, "backlinksMaxLinks": { "type": "integer", "description": "Backlinks pulled per run (billed per link)" }, "auditMaxPages": { "type": "integer", "description": "Pages crawled per scheduled site audit" }, "country": { "type": "string", "description": "Market country code, e.g. us" }, "language": { "type": "string", "description": "Language code, e.g. en" }, "created_date": { "type": "string", "format": "date-time" }, "updated_date": { "type": "string", "format": "date-time" } }, "description": "A monitored website. `enabledModules` maps each SEO/AEO module key to whether it runs on the schedule; any module can also be run on demand with seo_runProjectRoute." } }, "total": { "type": "integer", "description": "Total projects" } }, "description": "One page of monitored websites" } } } } }, "summary": "Paginated list of a company's monitored SEO projects." }, "post": { "tags": [ "SEO" ], "operationId": "seo_createProjectRoute", "parameters": [], "responses": { "400": { "description": "A valid domain is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "201": { "description": "The new project", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Project ID (UUID)" }, "companyId": { "type": "string", "description": "Company ID" }, "domain": { "type": "string", "description": "Monitored host, lowercased" }, "name": { "type": "string", "description": "Display name" }, "status": { "type": "string", "description": "active or paused", "enum": [ "active", "paused" ] }, "frequency": { "type": "string", "description": "manual, daily, weekly or monthly", "enum": [ "manual", "daily", "weekly", "monthly" ] }, "timezone": { "type": "string", "description": "Schedule timezone" }, "nextRunAt": { "type": "string", "format": "date-time", "description": "Next scheduled run (null when manual/paused)" }, "lastRunAt": { "type": "string", "format": "date-time", "description": "Last run" }, "runCount": { "type": "integer", "description": "Runs so far" }, "enabledModules": { "type": "object", "description": "Module key -> enabled. Keys: keyword_research, domain_overview, opportunities, backlinks, link_profile, rank_tracking, competitors, ai_visibility, site_audit, lighthouse" }, "trackedKeywords": { "type": "array", "items": { "type": "string" }, "description": "Keywords for rank tracking and keyword research" }, "competitorDomains": { "type": "array", "items": { "type": "string" }, "description": "Pinned competitor domains" }, "trackedPrompts": { "type": "array", "items": { "type": "string" }, "description": "Questions asked of AI platforms (AEO)" }, "brandNames": { "type": "array", "items": { "type": "string" }, "description": "Strings that count as a brand mention" }, "aiPlatforms": { "type": "object", "description": "AI platform key -> enabled (chatgpt, claude, gemini, perplexity)" }, "trackAiOverview": { "type": "boolean", "description": "Also check Google AI Overview" }, "backlinksMaxLinks": { "type": "integer", "description": "Backlinks pulled per run (billed per link)" }, "auditMaxPages": { "type": "integer", "description": "Pages crawled per scheduled site audit" }, "country": { "type": "string", "description": "Market country code, e.g. us" }, "language": { "type": "string", "description": "Language code, e.g. en" }, "created_date": { "type": "string", "format": "date-time" }, "updated_date": { "type": "string", "format": "date-time" } }, "description": "A monitored website. `enabledModules` maps each SEO/AEO module key to whether it runs on the schedule; any module can also be run on demand with seo_runProjectRoute." } } } } }, "summary": "Add a website to monitor and set its schedule + enabled modules.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Display name; defaults to the domain" }, "frequency": { "type": "string", "description": "manual (run-now only), daily, weekly or monthly", "enum": [ "manual", "daily", "weekly", "monthly" ] }, "enabledModules": { "type": "object", "description": "Module key -> true/false. Keys: keyword_research, domain_overview, opportunities, backlinks, link_profile, rank_tracking, competitors, ai_visibility, site_audit, lighthouse" }, "trackedKeywords": { "type": "array", "items": { "type": "string" }, "description": "Keywords to rank-track" }, "competitorDomains": { "type": "array", "items": { "type": "string" }, "description": "Competitor domains to pin" }, "trackedPrompts": { "type": "array", "items": { "type": "string" }, "description": "Questions to ask AI platforms" }, "brandNames": { "type": "array", "items": { "type": "string" }, "description": "Strings that count as a brand mention" }, "aiPlatforms": { "type": "object", "description": "AI platform key -> true/false" }, "trackAiOverview": { "type": "boolean", "description": "Also check Google AI Overview" }, "backlinksMaxLinks": { "type": "integer", "description": "Backlinks pulled per run" }, "auditMaxPages": { "type": "integer", "description": "Pages per scheduled site audit" }, "country": { "type": "string", "description": "Market country code, default us" }, "language": { "type": "string", "description": "Language code, default en" }, "timezone": { "type": "string", "description": "Schedule timezone, default UTC" }, "companyId": { "type": "string", "description": "Company ID" }, "domain": { "type": "string", "description": "Domain or URL to monitor" } }, "required": [ "companyId", "domain" ], "description": "Add a website to monitor" } } }, "description": "Website, schedule and modules" } } }, "/api/v0/seo/projects/estimate": { "post": { "tags": [ "SEO" ], "operationId": "seo_estimateProjectRunRoute", "parameters": [], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Projected credits per run", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "number", "description": "Estimated credits for one run of all enabled modules" }, "modules": { "type": "object", "description": "Estimated credits per enabled module key" }, "cacheFirst": { "type": "array", "items": { "type": "string" }, "description": "Modules that only buy missing/stale data, so usually cost less than estimated" } }, "description": "Projected credit cost of one run" } } } } }, "summary": "Estimate the credits one run of a monitored website will cost.", "description": "Priced from the vendor's list rates and the settings supplied (tracked\nkeywords, competitors, prompts, platforms, link and page caps). Actual\nruns bill exact vendor spend, so treat this as a ceiling - modules that\nread from cache first usually come in under it.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Display name; defaults to the domain" }, "frequency": { "type": "string", "description": "manual (run-now only), daily, weekly or monthly", "enum": [ "manual", "daily", "weekly", "monthly" ] }, "enabledModules": { "type": "object", "description": "Module key -> true/false. Keys: keyword_research, domain_overview, opportunities, backlinks, link_profile, rank_tracking, competitors, ai_visibility, site_audit, lighthouse" }, "trackedKeywords": { "type": "array", "items": { "type": "string" }, "description": "Keywords to rank-track" }, "competitorDomains": { "type": "array", "items": { "type": "string" }, "description": "Competitor domains to pin" }, "trackedPrompts": { "type": "array", "items": { "type": "string" }, "description": "Questions to ask AI platforms" }, "brandNames": { "type": "array", "items": { "type": "string" }, "description": "Strings that count as a brand mention" }, "aiPlatforms": { "type": "object", "description": "AI platform key -> true/false" }, "trackAiOverview": { "type": "boolean", "description": "Also check Google AI Overview" }, "backlinksMaxLinks": { "type": "integer", "description": "Backlinks pulled per run" }, "auditMaxPages": { "type": "integer", "description": "Pages per scheduled site audit" }, "country": { "type": "string", "description": "Market country code, default us" }, "language": { "type": "string", "description": "Language code, default en" }, "timezone": { "type": "string", "description": "Schedule timezone, default UTC" }, "companyId": { "type": "string", "description": "Company ID" } }, "required": [ "companyId" ], "description": "Project configuration to price" } } }, "description": "Modules and settings to price" } } }, "/api/v0/seo/projects/ensure": { "post": { "tags": [ "SEO" ], "operationId": "seo_ensureProjectRoute", "parameters": [], "responses": { "400": { "description": "A valid domain is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "The existing or new project", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Project ID (UUID)" }, "companyId": { "type": "string", "description": "Company ID" }, "domain": { "type": "string", "description": "Monitored host, lowercased" }, "name": { "type": "string", "description": "Display name" }, "status": { "type": "string", "description": "active or paused", "enum": [ "active", "paused" ] }, "frequency": { "type": "string", "description": "manual, daily, weekly or monthly", "enum": [ "manual", "daily", "weekly", "monthly" ] }, "timezone": { "type": "string", "description": "Schedule timezone" }, "nextRunAt": { "type": "string", "format": "date-time", "description": "Next scheduled run (null when manual/paused)" }, "lastRunAt": { "type": "string", "format": "date-time", "description": "Last run" }, "runCount": { "type": "integer", "description": "Runs so far" }, "enabledModules": { "type": "object", "description": "Module key -> enabled. Keys: keyword_research, domain_overview, opportunities, backlinks, link_profile, rank_tracking, competitors, ai_visibility, site_audit, lighthouse" }, "trackedKeywords": { "type": "array", "items": { "type": "string" }, "description": "Keywords for rank tracking and keyword research" }, "competitorDomains": { "type": "array", "items": { "type": "string" }, "description": "Pinned competitor domains" }, "trackedPrompts": { "type": "array", "items": { "type": "string" }, "description": "Questions asked of AI platforms (AEO)" }, "brandNames": { "type": "array", "items": { "type": "string" }, "description": "Strings that count as a brand mention" }, "aiPlatforms": { "type": "object", "description": "AI platform key -> enabled (chatgpt, claude, gemini, perplexity)" }, "trackAiOverview": { "type": "boolean", "description": "Also check Google AI Overview" }, "backlinksMaxLinks": { "type": "integer", "description": "Backlinks pulled per run (billed per link)" }, "auditMaxPages": { "type": "integer", "description": "Pages crawled per scheduled site audit" }, "country": { "type": "string", "description": "Market country code, e.g. us" }, "language": { "type": "string", "description": "Language code, e.g. en" }, "created_date": { "type": "string", "format": "date-time" }, "updated_date": { "type": "string", "format": "date-time" }, "created": { "type": "boolean", "description": "True when the project was created by this call" } }, "description": "The project, with whether it was just created" } } } } }, "summary": "Get or create the project for a domain.", "description": "Module pages call this when a site is typed freeform: the domain gets a\nblank project (manual schedule, no modules enabled) so the module can run\nagainst it, without the user first setting up monitoring.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "domain": { "type": "string", "description": "Domain or URL" } }, "required": [ "companyId", "domain" ], "description": "Get or create the project for a domain" } } }, "description": "Company and domain" } } }, "/api/v0/seo/projects/{projectId}": { "get": { "tags": [ "SEO" ], "operationId": "seo_getProjectRoute", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID that owns the SEO data" }, "description": "Company ID that owns the SEO data" } ], "responses": { "400": { "description": "Invalid project ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Project not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "The project and every module's latest result", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Project ID (UUID)" }, "companyId": { "type": "string", "description": "Company ID" }, "domain": { "type": "string", "description": "Monitored host, lowercased" }, "name": { "type": "string", "description": "Display name" }, "status": { "type": "string", "description": "active or paused", "enum": [ "active", "paused" ] }, "frequency": { "type": "string", "description": "manual, daily, weekly or monthly", "enum": [ "manual", "daily", "weekly", "monthly" ] }, "timezone": { "type": "string", "description": "Schedule timezone" }, "nextRunAt": { "type": "string", "format": "date-time", "description": "Next scheduled run (null when manual/paused)" }, "lastRunAt": { "type": "string", "format": "date-time", "description": "Last run" }, "runCount": { "type": "integer", "description": "Runs so far" }, "enabledModules": { "type": "object", "description": "Module key -> enabled. Keys: keyword_research, domain_overview, opportunities, backlinks, link_profile, rank_tracking, competitors, ai_visibility, site_audit, lighthouse" }, "trackedKeywords": { "type": "array", "items": { "type": "string" }, "description": "Keywords for rank tracking and keyword research" }, "competitorDomains": { "type": "array", "items": { "type": "string" }, "description": "Pinned competitor domains" }, "trackedPrompts": { "type": "array", "items": { "type": "string" }, "description": "Questions asked of AI platforms (AEO)" }, "brandNames": { "type": "array", "items": { "type": "string" }, "description": "Strings that count as a brand mention" }, "aiPlatforms": { "type": "object", "description": "AI platform key -> enabled (chatgpt, claude, gemini, perplexity)" }, "trackAiOverview": { "type": "boolean", "description": "Also check Google AI Overview" }, "backlinksMaxLinks": { "type": "integer", "description": "Backlinks pulled per run (billed per link)" }, "auditMaxPages": { "type": "integer", "description": "Pages crawled per scheduled site audit" }, "country": { "type": "string", "description": "Market country code, e.g. us" }, "language": { "type": "string", "description": "Language code, e.g. en" }, "created_date": { "type": "string", "format": "date-time" }, "updated_date": { "type": "string", "format": "date-time" }, "latestAudit": { "type": "object", "properties": { "id": { "type": "string", "description": "Audit ID (UUID)" }, "domain": { "type": "string", "description": "Domain that was crawled" }, "startUrl": { "type": "string", "description": "URL the crawl started from" }, "status": { "type": "string", "description": "queued, running, complete or failed", "enum": [ "queued", "running", "cancelling", "cancelled", "complete", "failed" ] }, "error": { "type": "string", "description": "Failure reason when status is failed" }, "maxPages": { "type": "integer", "description": "Page ceiling for this crawl" }, "pagesCrawled": { "type": "integer", "description": "Pages crawled so far" }, "healthScore": { "type": "integer", "description": "0-100, starts at 100 and drops per weighted issue" }, "issueCounts": { "type": "object", "description": "Issue totals by severity" }, "issueSummary": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Check id" }, "severity": { "type": "string", "description": "critical, warning or notice" }, "label": { "type": "string", "description": "Human-readable issue name" }, "pageCount": { "type": "integer", "description": "Pages carrying this issue" } }, "description": "Per-check rollup across the crawl" }, "description": "Per-check rollup, worst severity first" }, "linksChecked": { "type": "integer", "description": "Distinct URLs probed across the crawl" }, "brokenLinkCount": { "type": "integer", "description": "Distinct broken URLs found" }, "avgResponseMs": { "type": "integer", "description": "Mean time to first response, ms" }, "aiReadinessScore": { "type": "integer", "description": "Internal technical GEO readiness score, 0-100" }, "aiReadinessGrade": { "type": "string", "description": "Letter grade for technical GEO readiness" }, "aiReadinessChecks": { "type": "object", "description": "Evidence-backed technical GEO checks (robots.txt, llms.txt, sitemap, Schema.org, extractability, TTFB, HTTPS)" }, "aiReadinessRecommendations": { "type": "array", "items": { "type": "object" }, "description": "Prioritized technical GEO fixes" }, "aiReadinessCheckedAt": { "type": "string", "format": "date-time", "description": "When technical GEO readiness was scored" }, "aiReadinessError": { "type": "string", "description": "Why the technical GEO check failed, when it did" }, "startedAt": { "type": "string", "format": "date-time", "description": "When the crawl began" }, "completedAt": { "type": "string", "format": "date-time", "description": "When the crawl finished" }, "created_date": { "type": "string", "format": "date-time", "description": "When the audit was queued" } }, "description": "Latest scheduled site audit, or null" }, "backlinkHistory": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "runId": { "type": "string" }, "totalBacklinks": { "type": "integer" }, "referringDomains": { "type": "integer" }, "referringMainDomains": { "type": "integer" }, "domainRank": { "type": "integer" }, "newCount": { "type": "integer" }, "lostCount": { "type": "integer" }, "brokenCount": { "type": "integer" }, "fullPull": { "type": "boolean", "description": "Whole profile pulled (vs. delta since last run)" }, "checkedAt": { "type": "string", "format": "date-time" } }, "description": "Backlink totals on one run, with new/lost counts" }, "description": "Newest first" }, "rankHistory": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "runId": { "type": "string" }, "keyword": { "type": "string" }, "country": { "type": "string" }, "language": { "type": "string" }, "position": { "type": "integer", "description": "Null when not ranked in the checked depth" }, "url": { "type": "string", "description": "Ranking URL" }, "previousPosition": { "type": "integer" }, "checkedAt": { "type": "string", "format": "date-time" } }, "description": "One keyword's Google position on one run" }, "description": "Newest first" }, "opportunities": { "type": "object", "properties": { "id": { "type": "string" }, "runId": { "type": "string" }, "rankedKeywords": { "type": "array", "items": { "type": "object" }, "description": "[{keyword, position, volume, cpc, url}]" }, "keywordIdeas": { "type": "array", "items": { "type": "object" }, "description": "[{keyword, volume, cpc, competition}]" }, "rankedCount": { "type": "integer" }, "ideaCount": { "type": "integer" }, "checkedAt": { "type": "string", "format": "date-time" } }, "description": "Keywords the domain ranks for plus new ideas, on one run" }, "competitors": { "type": "object", "properties": { "id": { "type": "string" }, "runId": { "type": "string" }, "competitors": { "type": "array", "items": { "type": "object" }, "description": "Discovered competitor domains with overlap metrics" }, "competitorCount": { "type": "integer" }, "linkGap": { "type": "array", "items": { "type": "object" }, "description": "Domains linking to pinned competitors but not to us" }, "linkGapCount": { "type": "integer" }, "checkedAt": { "type": "string", "format": "date-time" } }, "description": "Organic competitors and backlink gap on one run" }, "linkProfile": { "type": "object", "properties": { "id": { "type": "string" }, "runId": { "type": "string" }, "anchors": { "type": "array", "items": { "type": "object" }, "description": "[{anchor, backlinks, referringDomains, nofollowPages, firstSeen}]" }, "referringDomains": { "type": "array", "items": { "type": "object" }, "description": "[{domain, rank, backlinks, firstSeen, isNew, isLost, brokenBacklinks}]" }, "backlinkHistory": { "type": "array", "items": { "type": "object" }, "description": "Monthly series [{date, backlinks, referringDomains, ...}]" }, "anchorCount": { "type": "integer" }, "referringDomainCount": { "type": "integer" }, "checkedAt": { "type": "string", "format": "date-time" } }, "description": "Anchor text, referring domains and vendor backlink history on one run" }, "lighthouse": { "type": "object", "properties": { "id": { "type": "string" }, "runId": { "type": "string" }, "url": { "type": "string", "description": "Audited URL" }, "device": { "type": "string", "description": "mobile or desktop" }, "performanceScore": { "type": "integer" }, "accessibilityScore": { "type": "integer" }, "bestPracticesScore": { "type": "integer" }, "seoScore": { "type": "integer" }, "agenticBrowsingScore": { "type": "integer", "description": "Agentic Browsing (AEO) score 0-100" }, "vitals": { "type": "object", "description": "{FCP, LCP, TBT, CLS, SI, TTI, TTFB} -> {value, rating, displayValue}" }, "failingAudits": { "type": "array", "items": { "type": "object" }, "description": "[{id, title, description, score, displayValue, category}], worst first. category is the Lighthouse category id (performance, accessibility, best-practices, seo, agentic-browsing)" }, "opportunities": { "type": "array", "items": { "type": "object" }, "description": "Performance opportunities [{id, title, description, score, displayValue, category}]" }, "passingAudits": { "type": "array", "items": { "type": "object" }, "description": "Audits that passed [{id, title, description, score, displayValue, category}]" }, "lighthouseVersion": { "type": "string" }, "error": { "type": "string", "description": "Why the scan failed, when it did" }, "checkedAt": { "type": "string", "format": "date-time" } }, "description": "One Lighthouse scan of the home page: category scores 0-100 (including agenticBrowsingScore, Lighthouse's AI-agent readiness / AEO category: llms.txt, agent accessibility tree, WebMCP), Core Web Vitals lab metrics (ms except CLS) and the audits that did not pass." }, "aiVisibility": { "type": "object", "properties": { "summary": { "type": "object", "properties": { "answers": { "type": "integer" }, "visibilityScore": { "type": "number", "description": "% of answers naming the brand" }, "citationScore": { "type": "number", "description": "% of answers citing the domain" }, "shareOfVoice": { "type": "number" }, "brandMentions": { "type": "integer" }, "domainCitations": { "type": "integer" }, "competitorMentions": { "type": "integer" } }, "description": "Aggregate AEO scores for one run" }, "topCitedDomains": { "type": "array", "items": { "type": "object" }, "description": "[{domain, answers}]" }, "answers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "runId": { "type": "string" }, "platform": { "type": "string", "description": "chatgpt, claude, gemini, perplexity or google_ai_overview" }, "model": { "type": "string" }, "prompt": { "type": "string" }, "brandMentioned": { "type": "boolean" }, "brandPosition": { "type": "integer", "description": "Character offset of the first brand mention" }, "domainCited": { "type": "boolean" }, "citationCount": { "type": "integer" }, "competitorsMentioned": { "type": "array", "items": { "type": "string" } }, "citations": { "type": "array", "items": { "type": "object" }, "description": "[{url, domain}]" }, "answerExcerpt": { "type": "string" }, "error": { "type": "string" }, "checkedAt": { "type": "string", "format": "date-time" } }, "description": "One AI platform's answer to one tracked prompt, scored" } } }, "description": "Latest AEO run" } }, "description": "The project plus the latest result of every module" } } } } }, "summary": "One project plus its latest per-module results." }, "patch": { "tags": [ "SEO" ], "operationId": "seo_updateProjectRoute", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid project ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Project not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "The updated project", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Project ID (UUID)" }, "companyId": { "type": "string", "description": "Company ID" }, "domain": { "type": "string", "description": "Monitored host, lowercased" }, "name": { "type": "string", "description": "Display name" }, "status": { "type": "string", "description": "active or paused", "enum": [ "active", "paused" ] }, "frequency": { "type": "string", "description": "manual, daily, weekly or monthly", "enum": [ "manual", "daily", "weekly", "monthly" ] }, "timezone": { "type": "string", "description": "Schedule timezone" }, "nextRunAt": { "type": "string", "format": "date-time", "description": "Next scheduled run (null when manual/paused)" }, "lastRunAt": { "type": "string", "format": "date-time", "description": "Last run" }, "runCount": { "type": "integer", "description": "Runs so far" }, "enabledModules": { "type": "object", "description": "Module key -> enabled. Keys: keyword_research, domain_overview, opportunities, backlinks, link_profile, rank_tracking, competitors, ai_visibility, site_audit, lighthouse" }, "trackedKeywords": { "type": "array", "items": { "type": "string" }, "description": "Keywords for rank tracking and keyword research" }, "competitorDomains": { "type": "array", "items": { "type": "string" }, "description": "Pinned competitor domains" }, "trackedPrompts": { "type": "array", "items": { "type": "string" }, "description": "Questions asked of AI platforms (AEO)" }, "brandNames": { "type": "array", "items": { "type": "string" }, "description": "Strings that count as a brand mention" }, "aiPlatforms": { "type": "object", "description": "AI platform key -> enabled (chatgpt, claude, gemini, perplexity)" }, "trackAiOverview": { "type": "boolean", "description": "Also check Google AI Overview" }, "backlinksMaxLinks": { "type": "integer", "description": "Backlinks pulled per run (billed per link)" }, "auditMaxPages": { "type": "integer", "description": "Pages crawled per scheduled site audit" }, "country": { "type": "string", "description": "Market country code, e.g. us" }, "language": { "type": "string", "description": "Language code, e.g. en" }, "created_date": { "type": "string", "format": "date-time" }, "updated_date": { "type": "string", "format": "date-time" } }, "description": "A monitored website. `enabledModules` maps each SEO/AEO module key to whether it runs on the schedule; any module can also be run on demand with seo_runProjectRoute." } } } } }, "summary": "Update a project's schedule, modules, tracked keywords, or caps.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Display name; defaults to the domain" }, "frequency": { "type": "string", "description": "manual (run-now only), daily, weekly or monthly", "enum": [ "manual", "daily", "weekly", "monthly" ] }, "enabledModules": { "type": "object", "description": "Module key -> true/false. Keys: keyword_research, domain_overview, opportunities, backlinks, link_profile, rank_tracking, competitors, ai_visibility, site_audit, lighthouse" }, "trackedKeywords": { "type": "array", "items": { "type": "string" }, "description": "Keywords to rank-track" }, "competitorDomains": { "type": "array", "items": { "type": "string" }, "description": "Competitor domains to pin" }, "trackedPrompts": { "type": "array", "items": { "type": "string" }, "description": "Questions to ask AI platforms" }, "brandNames": { "type": "array", "items": { "type": "string" }, "description": "Strings that count as a brand mention" }, "aiPlatforms": { "type": "object", "description": "AI platform key -> true/false" }, "trackAiOverview": { "type": "boolean", "description": "Also check Google AI Overview" }, "backlinksMaxLinks": { "type": "integer", "description": "Backlinks pulled per run" }, "auditMaxPages": { "type": "integer", "description": "Pages per scheduled site audit" }, "country": { "type": "string", "description": "Market country code, default us" }, "language": { "type": "string", "description": "Language code, default en" }, "timezone": { "type": "string", "description": "Schedule timezone, default UTC" }, "companyId": { "type": "string", "description": "Company ID" } }, "required": [ "companyId" ], "description": "Change a monitored website's schedule, modules, keywords or caps" } } }, "description": "Fields to change" } }, "delete": { "tags": [ "SEO" ], "operationId": "seo_deleteProjectRoute", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID that owns the SEO data" }, "description": "Company ID that owns the SEO data" } ], "responses": { "400": { "description": "Invalid project ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Project not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the operation succeeded" } }, "description": "Success response" } } } } }, "summary": "Remove a monitored project." } }, "/api/v0/seo/search-console/connections": { "get": { "tags": [ "SEO" ], "operationId": "seo_searchConsoleConnectionsRoute", "parameters": [], "responses": { "200": { "description": "Successful response" } }, "summary": "Google Search Console connections installed for the company.", "description": "Pass `domain` to flag which connection's site covers a project's domain." } }, "/api/v0/seo/search-console/preview": { "post": { "tags": [ "SEO" ], "operationId": "seo_searchConsolePreviewRoute", "parameters": [], "responses": { "200": { "description": "Successful response" } }, "summary": "Queries a site already ranks for in Google Search Console, tagged for", "description": "seeding a monitored website's keywords and AEO prompts: which are questions\n(prompts), branded, in striking distance, or already listed.\n\nBody: {integrationId, domain, days?, trackedKeywords?, trackedPrompts?,\nbrandNames?} -- the lists are whatever the project form currently holds.\nFree -- reads the company's Search Console connection." } }, "/api/v0/seo/projects/{projectId}/pause": { "post": { "tags": [ "SEO" ], "operationId": "seo_pauseProjectRoute", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid project ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Project not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "The paused project", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Project ID (UUID)" }, "companyId": { "type": "string", "description": "Company ID" }, "domain": { "type": "string", "description": "Monitored host, lowercased" }, "name": { "type": "string", "description": "Display name" }, "status": { "type": "string", "description": "active or paused", "enum": [ "active", "paused" ] }, "frequency": { "type": "string", "description": "manual, daily, weekly or monthly", "enum": [ "manual", "daily", "weekly", "monthly" ] }, "timezone": { "type": "string", "description": "Schedule timezone" }, "nextRunAt": { "type": "string", "format": "date-time", "description": "Next scheduled run (null when manual/paused)" }, "lastRunAt": { "type": "string", "format": "date-time", "description": "Last run" }, "runCount": { "type": "integer", "description": "Runs so far" }, "enabledModules": { "type": "object", "description": "Module key -> enabled. Keys: keyword_research, domain_overview, opportunities, backlinks, link_profile, rank_tracking, competitors, ai_visibility, site_audit, lighthouse" }, "trackedKeywords": { "type": "array", "items": { "type": "string" }, "description": "Keywords for rank tracking and keyword research" }, "competitorDomains": { "type": "array", "items": { "type": "string" }, "description": "Pinned competitor domains" }, "trackedPrompts": { "type": "array", "items": { "type": "string" }, "description": "Questions asked of AI platforms (AEO)" }, "brandNames": { "type": "array", "items": { "type": "string" }, "description": "Strings that count as a brand mention" }, "aiPlatforms": { "type": "object", "description": "AI platform key -> enabled (chatgpt, claude, gemini, perplexity)" }, "trackAiOverview": { "type": "boolean", "description": "Also check Google AI Overview" }, "backlinksMaxLinks": { "type": "integer", "description": "Backlinks pulled per run (billed per link)" }, "auditMaxPages": { "type": "integer", "description": "Pages crawled per scheduled site audit" }, "country": { "type": "string", "description": "Market country code, e.g. us" }, "language": { "type": "string", "description": "Language code, e.g. en" }, "created_date": { "type": "string", "format": "date-time" }, "updated_date": { "type": "string", "format": "date-time" } }, "description": "A monitored website. `enabledModules` maps each SEO/AEO module key to whether it runs on the schedule; any module can also be run on demand with seo_runProjectRoute." } } } } }, "summary": "Pause a project's schedule (no runs fire until resumed).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID that owns the SEO data" } }, "required": [ "companyId" ], "description": "Company scope for the request" } } }, "description": "Company context" } } }, "/api/v0/seo/projects/{projectId}/resume": { "post": { "tags": [ "SEO" ], "operationId": "seo_resumeProjectRoute", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid project ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Project not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "The resumed project", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Project ID (UUID)" }, "companyId": { "type": "string", "description": "Company ID" }, "domain": { "type": "string", "description": "Monitored host, lowercased" }, "name": { "type": "string", "description": "Display name" }, "status": { "type": "string", "description": "active or paused", "enum": [ "active", "paused" ] }, "frequency": { "type": "string", "description": "manual, daily, weekly or monthly", "enum": [ "manual", "daily", "weekly", "monthly" ] }, "timezone": { "type": "string", "description": "Schedule timezone" }, "nextRunAt": { "type": "string", "format": "date-time", "description": "Next scheduled run (null when manual/paused)" }, "lastRunAt": { "type": "string", "format": "date-time", "description": "Last run" }, "runCount": { "type": "integer", "description": "Runs so far" }, "enabledModules": { "type": "object", "description": "Module key -> enabled. Keys: keyword_research, domain_overview, opportunities, backlinks, link_profile, rank_tracking, competitors, ai_visibility, site_audit, lighthouse" }, "trackedKeywords": { "type": "array", "items": { "type": "string" }, "description": "Keywords for rank tracking and keyword research" }, "competitorDomains": { "type": "array", "items": { "type": "string" }, "description": "Pinned competitor domains" }, "trackedPrompts": { "type": "array", "items": { "type": "string" }, "description": "Questions asked of AI platforms (AEO)" }, "brandNames": { "type": "array", "items": { "type": "string" }, "description": "Strings that count as a brand mention" }, "aiPlatforms": { "type": "object", "description": "AI platform key -> enabled (chatgpt, claude, gemini, perplexity)" }, "trackAiOverview": { "type": "boolean", "description": "Also check Google AI Overview" }, "backlinksMaxLinks": { "type": "integer", "description": "Backlinks pulled per run (billed per link)" }, "auditMaxPages": { "type": "integer", "description": "Pages crawled per scheduled site audit" }, "country": { "type": "string", "description": "Market country code, e.g. us" }, "language": { "type": "string", "description": "Language code, e.g. en" }, "created_date": { "type": "string", "format": "date-time" }, "updated_date": { "type": "string", "format": "date-time" } }, "description": "A monitored website. `enabledModules` maps each SEO/AEO module key to whether it runs on the schedule; any module can also be run on demand with seo_runProjectRoute." } } } } }, "summary": "Resume a paused project (recomputes its next run).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID that owns the SEO data" } }, "required": [ "companyId" ], "description": "Company scope for the request" } } }, "description": "Company context" } } }, "/api/v0/seo/projects/{projectId}/run": { "post": { "tags": [ "SEO" ], "operationId": "seo_runProjectRoute", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid project ID or unknown modules", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Project not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Run queued", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "queued": { "type": "boolean" }, "modules": { "type": "array", "items": { "type": "string" }, "description": "Modules requested, or null for all enabled" } }, "description": "The run was queued" } } } } }, "summary": "Run a project's modules now. Does not advance the schedule.", "description": "Body may carry `modules: [...]` (SEO_MODULE_* keys) to run only those -\nenabled or not - so one report can be refreshed without re-running the\nwhole project. Without it, every enabled module runs.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "modules": { "type": "array", "items": { "type": "string", "enum": [ "keyword_research", "domain_overview", "opportunities", "backlinks", "link_profile", "rank_tracking", "competitors", "ai_visibility", "site_audit", "lighthouse" ] }, "description": "Only run these modules (enabled or not): keyword_research, domain_overview, opportunities, backlinks, link_profile, rank_tracking, competitors, ai_visibility, site_audit, lighthouse. Omit to run every enabled module." } }, "required": [ "companyId" ], "description": "Run a project's modules now. Runs in the background; read the results from the per-module routes once the run completes." } } }, "description": "Which modules to run" } } }, "/api/v0/seo/projects/{projectId}/backlinks": { "get": { "tags": [ "SEO" ], "operationId": "seo_listProjectBacklinksRoute", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID" }, "description": "Company ID" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "1-indexed page number" }, "description": "1-indexed page number" }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "description": "Rows per page, max 100" }, "description": "Rows per page, max 100" }, { "name": "includeLost", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Also return links that have dropped" }, "description": "Also return links that have dropped" } ], "responses": { "400": { "description": "Invalid project ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Project not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "One page of backlinks", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "sourceUrl": { "type": "string", "description": "Referring page" }, "sourceDomain": { "type": "string" }, "targetUrl": { "type": "string", "description": "Page on the monitored domain" }, "anchor": { "type": "string" }, "dofollow": { "type": "boolean" }, "linkType": { "type": "string" }, "domainRank": { "type": "integer", "description": "Referring page rank" }, "rankOfReferringDomain": { "type": "integer" }, "firstSeen": { "type": "string", "format": "date-time" }, "lastSeen": { "type": "string", "format": "date-time" }, "firstSeenRunAt": { "type": "string", "format": "date-time", "description": "First monitor run that saw the link" }, "lostAt": { "type": "string", "format": "date-time" }, "isLost": { "type": "boolean" } }, "description": "One backlink pointing at the monitored domain" } }, "total": { "type": "integer" } }, "description": "One page of backlinks" } } } } }, "summary": "Paginated individual backlinks for a project's domain." } }, "/api/v0/seo/projects/{projectId}/rank-history": { "get": { "tags": [ "SEO" ], "operationId": "seo_projectRankHistoryRoute", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID" }, "description": "Company ID" }, { "name": "keyword", "in": "query", "required": false, "schema": { "type": "string", "description": "Only this keyword" }, "description": "Only this keyword" } ], "responses": { "400": { "description": "Invalid project ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Project not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Rank snapshots", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "runId": { "type": "string" }, "keyword": { "type": "string" }, "country": { "type": "string" }, "language": { "type": "string" }, "position": { "type": "integer", "description": "Null when not ranked in the checked depth" }, "url": { "type": "string", "description": "Ranking URL" }, "previousPosition": { "type": "integer" }, "checkedAt": { "type": "string", "format": "date-time" } }, "description": "One keyword's Google position on one run" } } }, "description": "Rank snapshots, newest first" } } } } }, "summary": "Rank snapshots over time, optionally filtered to one keyword." } }, "/api/v0/seo/projects/{projectId}/backlink-history": { "get": { "tags": [ "SEO" ], "operationId": "seo_projectBacklinkHistoryRoute", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID that owns the SEO data" }, "description": "Company ID that owns the SEO data" } ], "responses": { "400": { "description": "Invalid project ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Project not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Backlink totals per run", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "runId": { "type": "string" }, "totalBacklinks": { "type": "integer" }, "referringDomains": { "type": "integer" }, "referringMainDomains": { "type": "integer" }, "domainRank": { "type": "integer" }, "newCount": { "type": "integer" }, "lostCount": { "type": "integer" }, "brokenCount": { "type": "integer" }, "fullPull": { "type": "boolean", "description": "Whole profile pulled (vs. delta since last run)" }, "checkedAt": { "type": "string", "format": "date-time" } }, "description": "Backlink totals on one run, with new/lost counts" } } }, "description": "Backlink totals per run, newest first" } } } } }, "summary": "Per-run backlink totals + new/lost counts over time." } }, "/api/v0/seo/projects/{projectId}/competitors": { "get": { "tags": [ "SEO" ], "operationId": "seo_projectCompetitorsRoute", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID that owns the SEO data" }, "description": "Company ID that owns the SEO data" } ], "responses": { "400": { "description": "Invalid project ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Project not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Latest competitor snapshot (empty lists when none yet)", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "runId": { "type": "string" }, "competitors": { "type": "array", "items": { "type": "object" }, "description": "Discovered competitor domains with overlap metrics" }, "competitorCount": { "type": "integer" }, "linkGap": { "type": "array", "items": { "type": "object" }, "description": "Domains linking to pinned competitors but not to us" }, "linkGapCount": { "type": "integer" }, "checkedAt": { "type": "string", "format": "date-time" } }, "description": "Organic competitors and backlink gap on one run" } } } } }, "summary": "Latest organic competitor set and backlink gap for a project." } }, "/api/v0/seo/projects/{projectId}/link-profile": { "get": { "tags": [ "SEO" ], "operationId": "seo_projectLinkProfileRoute", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID that owns the SEO data" }, "description": "Company ID that owns the SEO data" } ], "responses": { "400": { "description": "Invalid project ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Project not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Latest link profile snapshot (empty lists when none yet)", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "runId": { "type": "string" }, "anchors": { "type": "array", "items": { "type": "object" }, "description": "[{anchor, backlinks, referringDomains, nofollowPages, firstSeen}]" }, "referringDomains": { "type": "array", "items": { "type": "object" }, "description": "[{domain, rank, backlinks, firstSeen, isNew, isLost, brokenBacklinks}]" }, "backlinkHistory": { "type": "array", "items": { "type": "object" }, "description": "Monthly series [{date, backlinks, referringDomains, ...}]" }, "anchorCount": { "type": "integer" }, "referringDomainCount": { "type": "integer" }, "checkedAt": { "type": "string", "format": "date-time" } }, "description": "Anchor text, referring domains and vendor backlink history on one run" } } } } }, "summary": "Latest anchor text, referring domains, and vendor backlink history." } }, "/api/v0/seo/projects/{projectId}/lighthouse": { "get": { "tags": [ "SEO" ], "operationId": "seo_projectLighthouseRoute", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID" }, "description": "Company ID" }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "description": "History window in days: 7, 30, 90, 365. Defaults to 90.", "enum": [ 7, 30, 90, 365 ] }, "description": "History window in days: 7, 30, 90, 365. Defaults to 90." } ], "responses": { "400": { "description": "Invalid project ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Project not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Latest scan, history and recent scans", "content": { "application/json": { "schema": { "type": "object", "properties": { "latest": { "type": "object", "properties": { "id": { "type": "string" }, "runId": { "type": "string" }, "url": { "type": "string", "description": "Audited URL" }, "device": { "type": "string", "description": "mobile or desktop" }, "performanceScore": { "type": "integer" }, "accessibilityScore": { "type": "integer" }, "bestPracticesScore": { "type": "integer" }, "seoScore": { "type": "integer" }, "agenticBrowsingScore": { "type": "integer", "description": "Agentic Browsing (AEO) score 0-100" }, "vitals": { "type": "object", "description": "{FCP, LCP, TBT, CLS, SI, TTI, TTFB} -> {value, rating, displayValue}" }, "failingAudits": { "type": "array", "items": { "type": "object" }, "description": "[{id, title, description, score, displayValue, category}], worst first. category is the Lighthouse category id (performance, accessibility, best-practices, seo, agentic-browsing)" }, "opportunities": { "type": "array", "items": { "type": "object" }, "description": "Performance opportunities [{id, title, description, score, displayValue, category}]" }, "passingAudits": { "type": "array", "items": { "type": "object" }, "description": "Audits that passed [{id, title, description, score, displayValue, category}]" }, "lighthouseVersion": { "type": "string" }, "error": { "type": "string", "description": "Why the scan failed, when it did" }, "checkedAt": { "type": "string", "format": "date-time" } }, "description": "Newest successful scan, or null" }, "history": { "type": "array", "items": { "type": "object" }, "description": "Oldest -> newest [{checkedAt, performanceScore, accessibilityScore, bestPracticesScore, seoScore, agenticBrowsingScore, error}]" }, "scans": { "type": "array", "items": { "type": "object" }, "description": "Newest first [{id, checkedAt, device, ...scores, error}]; fetch one with seo_projectLighthouseSnapshotRoute" }, "days": { "type": "integer" } }, "description": "Latest successful scan, per-scan scores over the window, and recent scans" } } } } }, "summary": "Latest Lighthouse report (category scores, Core Web Vitals, failing", "description": "audits) plus per-scan scores over the last `days` for the trend chart." } }, "/api/v0/seo/projects/{projectId}/lighthouse/{snapshotId}": { "get": { "tags": [ "SEO" ], "operationId": "seo_projectLighthouseSnapshotRoute", "parameters": [ { "name": "snapshotId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID that owns the SEO data" }, "description": "Company ID that owns the SEO data" } ], "responses": { "400": { "description": "Invalid ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Scan not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "The scan in full", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "runId": { "type": "string" }, "url": { "type": "string", "description": "Audited URL" }, "device": { "type": "string", "description": "mobile or desktop" }, "performanceScore": { "type": "integer" }, "accessibilityScore": { "type": "integer" }, "bestPracticesScore": { "type": "integer" }, "seoScore": { "type": "integer" }, "agenticBrowsingScore": { "type": "integer", "description": "Agentic Browsing (AEO) score 0-100" }, "vitals": { "type": "object", "description": "{FCP, LCP, TBT, CLS, SI, TTI, TTFB} -> {value, rating, displayValue}" }, "failingAudits": { "type": "array", "items": { "type": "object" }, "description": "[{id, title, description, score, displayValue, category}], worst first. category is the Lighthouse category id (performance, accessibility, best-practices, seo, agentic-browsing)" }, "opportunities": { "type": "array", "items": { "type": "object" }, "description": "Performance opportunities [{id, title, description, score, displayValue, category}]" }, "passingAudits": { "type": "array", "items": { "type": "object" }, "description": "Audits that passed [{id, title, description, score, displayValue, category}]" }, "lighthouseVersion": { "type": "string" }, "error": { "type": "string", "description": "Why the scan failed, when it did" }, "checkedAt": { "type": "string", "format": "date-time" } }, "description": "One Lighthouse scan of the home page: category scores 0-100 (including agenticBrowsingScore, Lighthouse's AI-agent readiness / AEO category: llms.txt, agent accessibility tree, WebMCP), Core Web Vitals lab metrics (ms except CLS) and the audits that did not pass." } } } } }, "summary": "One Lighthouse scan in full, so an earlier snapshot can be inspected." } }, "/api/v0/seo/projects/{projectId}/ai-visibility": { "get": { "tags": [ "SEO" ], "operationId": "seo_projectAiVisibilityRoute", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID" }, "description": "Company ID" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "1-indexed page number" }, "description": "1-indexed page number" }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "description": "Rows per page, max 100" }, "description": "Rows per page, max 100" }, { "name": "platform", "in": "query", "required": false, "schema": { "type": "string", "description": "Only this platform" }, "description": "Only this platform" }, { "name": "prompt", "in": "query", "required": false, "schema": { "type": "string", "description": "Only this prompt" }, "description": "Only this prompt" } ], "responses": { "400": { "description": "Invalid project ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Project not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "One page of scored answers", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "runId": { "type": "string" }, "platform": { "type": "string", "description": "chatgpt, claude, gemini, perplexity or google_ai_overview" }, "model": { "type": "string" }, "prompt": { "type": "string" }, "brandMentioned": { "type": "boolean" }, "brandPosition": { "type": "integer", "description": "Character offset of the first brand mention" }, "domainCited": { "type": "boolean" }, "citationCount": { "type": "integer" }, "competitorsMentioned": { "type": "array", "items": { "type": "string" } }, "citations": { "type": "array", "items": { "type": "object" }, "description": "[{url, domain}]" }, "answerExcerpt": { "type": "string" }, "error": { "type": "string" }, "checkedAt": { "type": "string", "format": "date-time" } }, "description": "One AI platform's answer to one tracked prompt, scored" } }, "total": { "type": "integer" } }, "description": "One page of scored AI answers" } } } } }, "summary": "Paginated AEO answers, filterable by platform/prompt.", "description": "Each row is one AI platform's answer to one tracked prompt, already scored\nfor brand mention and citation." } }, "/api/v0/seo/projects/{projectId}/ai-visibility/trend": { "get": { "tags": [ "SEO" ], "operationId": "seo_projectAiVisibilityTrendRoute", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID that owns the SEO data" }, "description": "Company ID that owns the SEO data" } ], "responses": { "400": { "description": "Invalid project ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Project not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Per-run AEO summaries", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "answers": { "type": "integer" }, "visibilityScore": { "type": "number", "description": "% of answers naming the brand" }, "citationScore": { "type": "number", "description": "% of answers citing the domain" }, "shareOfVoice": { "type": "number" }, "brandMentions": { "type": "integer" }, "domainCitations": { "type": "integer" }, "competitorMentions": { "type": "integer" } }, "description": "Aggregate AEO scores for one run" } } }, "description": "Per-run AEO summary, oldest first" } } } } }, "summary": "Per-run AI visibility / citation / share-of-voice scores over time." } }, "/api/v0/seo/dataforseo": { "post": { "tags": [ "SEO" ], "operationId": "seo_dataforseoProxyRoute", "parameters": [], "responses": { "400": { "description": "Path must be a live endpoint and tasks a list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Exceeded usage quota", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Vendor request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Vendor response and credits charged", "content": { "application/json": { "schema": { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object" }, "description": "DataForSEO task results, verbatim" }, "status_code": { "type": "integer", "description": "DataForSEO top-level status code (20000 = OK)" }, "status_message": { "type": "string", "description": "DataForSEO top-level status message" }, "creditCost": { "type": "number", "description": "Credits charged for this call (actual vendor cost)" } }, "description": "The DataForSEO response body plus the credits charged" } } } } }, "summary": "Call any DataForSEO v3 live endpoint with our credentials.", "description": "Endpoint reference: https://docs.dataforseo.com/v3/ - find the endpoint\nthere, then pass its path without the /v3/ prefix (e.g.\n\"backlinks/backlinks/live\" for\nhttps://docs.dataforseo.com/v3/backlinks/backlinks/live/) and the task\narray exactly as that page documents it.\nOnly synchronous `live` endpoints are forwarded (plus on_page/instant_pages);\ntask-based, on_page and appendix endpoints are account-wide and rejected.\nBilled at what the vendor actually charged for the call, converted to\ncredits. Failed or rejected tasks cost nothing and bill nothing.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "path": { "type": "string", "description": "DataForSEO v3 endpoint path without the /v3/ prefix, e.g. \"backlinks/backlinks/live\" or \"serp/google/organic/live/advanced\". Endpoint reference: https://docs.dataforseo.com/v3/ (the docs URL for a path is https://docs.dataforseo.com/v3/<path>/)" }, "tasks": { "type": "array", "items": { "type": "object" }, "description": "Task array exactly as the endpoint's page on https://docs.dataforseo.com/v3/ documents it" } }, "required": [ "companyId", "path", "tasks" ], "description": "Forward a task array to any DataForSEO v3 live endpoint" } } }, "description": "Endpoint path and task array" } } }, "/api/v0/seo/domains-by-html-terms": { "post": { "tags": [ "SEO" ], "operationId": "seo_domainsByHtmlTermsRoute", "parameters": [], "responses": { "400": { "description": "At least one search term is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Exceeded usage quota", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Vendor request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Matching domains, total available, and credits charged", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": "string", "description": "The matching domain" }, "title": { "type": "string", "description": "Page title" }, "description": { "type": "string", "description": "Meta description" }, "domainRank": { "type": "integer", "description": "Domain rank (authority), 0-1000; higher is stronger" }, "country": { "type": "string", "description": "ISO country code from the crawl" }, "language": { "type": "string", "description": "Detected content language" }, "lastVisited": { "type": "string", "description": "When the vendor last crawled the page" }, "emails": { "type": "array", "items": { "type": "string" }, "description": "Emails found on the page, if any" }, "phones": { "type": "array", "items": { "type": "string" }, "description": "Phone numbers found on the page, if any" } }, "description": "A domain whose HTML contains the search terms" }, "description": "Matching domains, ranked by authority" }, "total": { "type": "integer", "description": "Total domains matching across the full index (for pagination)" }, "creditCost": { "type": "number", "description": "Credits charged (actual vendor cost)" } }, "description": "Matching domains plus the total available and credits charged" } } } } }, "summary": "Find companies by the markup on their website.", "description": "Searches the technology index for domains whose live HTML contains the\ngiven terms \u2014 a `<script src>` path, a vendor host, or any tag/attribute.\nBecause it matches the page's raw source, it finds every site carrying a\ngiven widget or tech stack even when each site runs on its own domain, so\nit is the way to build a list of companies using a specific tool.\n\nReturns matching domains ranked by authority plus the total available for\npaging via `offset`. Billed at the vendor's actual per-result cost.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "searchTerms": { "type": "array", "items": { "type": "string" }, "description": "Up to 10 HTML terms to match against tags, attributes and their content. A script src path (\"/widget.js\"), a vendor host (\"cdn.customgpt.ai\") or any markup snippet works. Matched against the site's raw source, so the site's own domain is irrelevant \u2014 this is how you find every site carrying a given widget or tech." }, "keywords": { "type": "array", "items": { "type": "string" }, "description": "Optional: up to 10 keywords that must also appear in the page title, description or meta keywords, to narrow the results." }, "mode": { "type": "string", "description": "\"entry\" (default, order-insensitive) or \"strict_entry\" (exact match)." }, "limit": { "type": "integer", "description": "Rows to return, 1-1000 (default 100). Billed per result." }, "offset": { "type": "integer", "description": "Row offset for pagination, 0-9999 (default 0)." }, "excludeIps": { "type": "boolean", "description": "Drop bare-IP hosts (crawl noise). Default true." } }, "required": [ "companyId", "searchTerms" ], "description": "Find companies by markup in their website's live HTML" } } }, "description": "HTML terms to search for and paging options" } } }, "/api/v0/marketing-campaigns": { "get": { "tags": [ "Marketing Campaigns" ], "operationId": "marketing_campaigns_listCampaigns", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "description": "Filter by status (one of: draft, scheduled, sending, sent, failed, cancelled)" }, "description": "Filter by status (one of: draft, scheduled, sending, sent, failed, cancelled)" } ], "responses": { "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "List of marketing campaigns", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Campaign ID" }, "companyId": { "type": "string", "description": "Company this campaign belongs to" }, "uid": { "type": "string", "description": "User ID that created the campaign" }, "name": { "type": "string", "description": "Internal campaign name" }, "subject": { "type": "string", "description": "Email subject line" }, "fromName": { "type": "string", "description": "Display name shown in the From: header" }, "replyTo": { "type": "string", "description": "Reply-To email address used on outgoing emails" }, "bodyHtml": { "type": "string", "description": "HTML body of the email; rendered from bodyDocument when a document is supplied" }, "bodyDocument": { "type": "string", "description": "Visual-builder JSON document for the email body. When supplied, the server renders bodyHtml from this document and it takes precedence over HTML input. Alternatively, supply bodyHtml without a document. Envelope: {\"subject\": string, \"subTitle\": string, \"content\": <page node>}. Every node is {\"type\": string, \"attributes\": {MJML attributes as string values, e.g. \"padding\": \"10px 25px 10px 25px\", \"background-color\": \"#ffffff\", \"color\": \"#333333\", \"font-size\": \"16px\", \"align\": \"center\", \"width\": \"600px\", \"href\", \"src\"}, \"data\": {\"value\": {...}}, \"children\": [...]}; attribute values must be strings (numbers are dropped). Tree: page -> (wrapper | section) -> section -> column -> content blocks. Content block types: \"text\" (data.value.content = inline HTML string), \"image\" (attributes.src, alt, href, width), \"button\" (data.value.content = label, attributes.href), \"divider\", \"spacer\" (attributes.height), \"social\" (data.value.elements = [{src, href, content, target}]), \"navbar\" (data.value.links = [{href, content}]), \"raw\" (data.value.content = raw MJML/HTML), plus \"hero\", \"group\", \"accordion\", \"carousel\" and \"table\". Each also has an \"advanced_<type>\" variant (e.g. \"advanced_text\"), which is what the builder palette inserts; advanced content blocks placed directly under the page or a wrapper are auto-wrapped in a section/column. For a visual poll, insert one marketing_poll block: {\"type\": \"marketing_poll\", \"data\": {\"value\": {\"question\": \"Your question?\", \"options\": [\"Answer one\", \"Answer two\"]}}, \"attributes\": {}, \"children\": []}. Its attributes support padding, font-family, font-size, font-weight, color, background-color, button-background-color, button-text-color, button-font-size, and border-radius. The server derives the campaign poll from this block; do not maintain a separate poll definition. Page node: {\"type\": \"page\", \"attributes\": {\"background-color\": \"#efeeea\", \"width\": \"600px\"}, \"data\": {\"value\": {\"breakpoint\": \"480px\", \"font-family\": string, \"font-size\": \"14px\", \"line-height\": \"1.7\", \"font-weight\": \"400\", \"text-color\": \"#000000\", \"content-background-color\": string (optional), \"headStyles\": [{\"content\": css, \"inline\": bool}], \"fonts\": [{\"name\", \"href\"}], \"headAttributes\": \"\", \"responsive\": true}}}. Always set \"responsive\": true \u2014 a missing flag renders a fixed-width layout. Merge tokens pass through rendering untouched: {{content}} inside a text block marks where content-engine output is inserted when content is published as a campaign from this template; Smart-list merge tokens use the matching header normalized to camelCase: for example, `First Name` becomes {{firstName}} and `Company Name` becomes {{companyName}}. Tokens are replaced per recipient from the smart-list row; {{unsubscribe}} becomes the per-recipient unsubscribe link." }, "poll": { "type": "string", "description": "Optional one-click email poll definition and current response totals." }, "senderProfileId": { "type": "string", "description": "Sender profile ID" }, "listId": { "type": "string", "description": "Smart list ID whose rows become recipients" }, "fieldMappings": { "type": "object", "description": "Field mapping for resolving recipient email from a list row" }, "scheduleType": { "type": "string", "description": "Schedule type (now, scheduled)" }, "scheduledAt": { "type": "string", "description": "ISO timestamp at which sending begins (for scheduled campaigns)" }, "timezone": { "type": "string", "description": "IANA timezone used to interpret scheduledAt" }, "status": { "type": "string", "description": "Campaign status (draft, scheduled, sending, sent, failed, cancelled)" }, "sentCount": { "type": "integer", "description": "Number of recipients the email has been sent to" }, "failedCount": { "type": "integer", "description": "Number of recipients that failed to send" }, "skippedCount": { "type": "integer", "description": "Number of list rows skipped (missing email, duplicate, etc.)" }, "totalRecipients": { "type": "integer", "description": "Total rows in the associated smart list at read time" }, "startedAt": { "type": "string", "description": "ISO timestamp when sending started" }, "completedAt": { "type": "string", "description": "ISO timestamp when sending completed" }, "created_date": { "type": "string", "description": "ISO timestamp when the campaign was created" }, "updated_date": { "type": "string", "description": "ISO timestamp when the campaign was last updated" }, "smartList": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "description": "Summary of the associated smart list" }, "senderProfile": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "integrationId": { "type": "string" } }, "description": "Summary of the sender profile" } }, "description": "Marketing campaign object" } } }, "description": "List of marketing campaigns" } } } } }, "summary": "List marketing campaigns for the current company.", "description": "Returns all non-deleted campaigns ordered by creation date (newest first).\nOptionally filter by status (draft, scheduled, sending, sent, failed, cancelled)." }, "post": { "tags": [ "Marketing Campaigns" ], "operationId": "marketing_campaigns_createCampaign", "parameters": [], "responses": { "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "201": { "description": "The created marketing campaign (in draft status)", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Campaign ID" }, "companyId": { "type": "string", "description": "Company this campaign belongs to" }, "uid": { "type": "string", "description": "User ID that created the campaign" }, "name": { "type": "string", "description": "Internal campaign name" }, "subject": { "type": "string", "description": "Email subject line" }, "fromName": { "type": "string", "description": "Display name shown in the From: header" }, "replyTo": { "type": "string", "description": "Reply-To email address used on outgoing emails" }, "bodyHtml": { "type": "string", "description": "HTML body of the email; rendered from bodyDocument when a document is supplied" }, "bodyDocument": { "type": "string", "description": "Visual-builder JSON document for the email body. When supplied, the server renders bodyHtml from this document and it takes precedence over HTML input. Alternatively, supply bodyHtml without a document. Envelope: {\"subject\": string, \"subTitle\": string, \"content\": <page node>}. Every node is {\"type\": string, \"attributes\": {MJML attributes as string values, e.g. \"padding\": \"10px 25px 10px 25px\", \"background-color\": \"#ffffff\", \"color\": \"#333333\", \"font-size\": \"16px\", \"align\": \"center\", \"width\": \"600px\", \"href\", \"src\"}, \"data\": {\"value\": {...}}, \"children\": [...]}; attribute values must be strings (numbers are dropped). Tree: page -> (wrapper | section) -> section -> column -> content blocks. Content block types: \"text\" (data.value.content = inline HTML string), \"image\" (attributes.src, alt, href, width), \"button\" (data.value.content = label, attributes.href), \"divider\", \"spacer\" (attributes.height), \"social\" (data.value.elements = [{src, href, content, target}]), \"navbar\" (data.value.links = [{href, content}]), \"raw\" (data.value.content = raw MJML/HTML), plus \"hero\", \"group\", \"accordion\", \"carousel\" and \"table\". Each also has an \"advanced_<type>\" variant (e.g. \"advanced_text\"), which is what the builder palette inserts; advanced content blocks placed directly under the page or a wrapper are auto-wrapped in a section/column. For a visual poll, insert one marketing_poll block: {\"type\": \"marketing_poll\", \"data\": {\"value\": {\"question\": \"Your question?\", \"options\": [\"Answer one\", \"Answer two\"]}}, \"attributes\": {}, \"children\": []}. Its attributes support padding, font-family, font-size, font-weight, color, background-color, button-background-color, button-text-color, button-font-size, and border-radius. The server derives the campaign poll from this block; do not maintain a separate poll definition. Page node: {\"type\": \"page\", \"attributes\": {\"background-color\": \"#efeeea\", \"width\": \"600px\"}, \"data\": {\"value\": {\"breakpoint\": \"480px\", \"font-family\": string, \"font-size\": \"14px\", \"line-height\": \"1.7\", \"font-weight\": \"400\", \"text-color\": \"#000000\", \"content-background-color\": string (optional), \"headStyles\": [{\"content\": css, \"inline\": bool}], \"fonts\": [{\"name\", \"href\"}], \"headAttributes\": \"\", \"responsive\": true}}}. Always set \"responsive\": true \u2014 a missing flag renders a fixed-width layout. Merge tokens pass through rendering untouched: {{content}} inside a text block marks where content-engine output is inserted when content is published as a campaign from this template; Smart-list merge tokens use the matching header normalized to camelCase: for example, `First Name` becomes {{firstName}} and `Company Name` becomes {{companyName}}. Tokens are replaced per recipient from the smart-list row; {{unsubscribe}} becomes the per-recipient unsubscribe link." }, "poll": { "type": "string", "description": "Optional one-click email poll definition and current response totals." }, "senderProfileId": { "type": "string", "description": "Sender profile ID" }, "listId": { "type": "string", "description": "Smart list ID whose rows become recipients" }, "fieldMappings": { "type": "object", "description": "Field mapping for resolving recipient email from a list row" }, "scheduleType": { "type": "string", "description": "Schedule type (now, scheduled)" }, "scheduledAt": { "type": "string", "description": "ISO timestamp at which sending begins (for scheduled campaigns)" }, "timezone": { "type": "string", "description": "IANA timezone used to interpret scheduledAt" }, "status": { "type": "string", "description": "Campaign status (draft, scheduled, sending, sent, failed, cancelled)" }, "sentCount": { "type": "integer", "description": "Number of recipients the email has been sent to" }, "failedCount": { "type": "integer", "description": "Number of recipients that failed to send" }, "skippedCount": { "type": "integer", "description": "Number of list rows skipped (missing email, duplicate, etc.)" }, "totalRecipients": { "type": "integer", "description": "Total rows in the associated smart list at read time" }, "startedAt": { "type": "string", "description": "ISO timestamp when sending started" }, "completedAt": { "type": "string", "description": "ISO timestamp when sending completed" }, "created_date": { "type": "string", "description": "ISO timestamp when the campaign was created" }, "updated_date": { "type": "string", "description": "ISO timestamp when the campaign was last updated" }, "smartList": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "description": "Summary of the associated smart list" }, "senderProfile": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "integrationId": { "type": "string" } }, "description": "Summary of the sender profile" } }, "description": "Marketing campaign object" } } } } }, "summary": "Create a new marketing campaign in draft status.", "description": "A newly created campaign is always in draft status and does not send anything\nuntil you call /schedule (to queue it for a future time) or /send-now\n(to begin sending immediately). You can keep editing the campaign with PATCH\nuntil it enters sending status, when content, sender, and sending windows remain editable for remaining recipients.\n\nTo create a campaign from a template, GET /api/v0/marketing-campaign-templates/{templateId}\nand pass its subject, replyTo, bodyHtml, bodyDocument, senderProfileId, listId,\nand fieldMappings here.\n\nFor an HTML-only inline poll, provide poll plus bodyHtml containing styled\nanchors with href=\"{{pollUrl0}}\", href=\"{{pollUrl1}}\", etc. for every option.\nUse {{pollQuestion}} and {{pollOption0}} text tokens to keep labels synchronized.\nSee the poll field description for validation, ordering, and removal rules.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Internal campaign name" }, "subject": { "type": "string", "description": "Email subject line sent to recipients" }, "fromName": { "type": "string", "description": "Display name shown in the From: header" }, "replyTo": { "type": "string", "description": "Optional Reply-To email address. Must be a valid email if provided." }, "bodyHtml": { "type": "string", "description": "HTML email body. Supply without bodyDocument for HTML-based campaigns. On update, nonblank HTML replaces the previous body and clears the previous visual-builder document. Empty HTML preserves existing content. For an inline poll, supply the poll field and style anchors with href=\"{{pollUrl0}}\", href=\"{{pollUrl1}}\", etc., one for every option. Use {{pollQuestion}} and {{pollOption0}} etc. for text. See poll for the complete contract. " }, "bodyDocument": { "type": "string", "description": "Visual-builder JSON document for the email body. When supplied, the server renders bodyHtml from this document and it takes precedence over HTML input. Alternatively, supply bodyHtml without a document. Envelope: {\"subject\": string, \"subTitle\": string, \"content\": <page node>}. Every node is {\"type\": string, \"attributes\": {MJML attributes as string values, e.g. \"padding\": \"10px 25px 10px 25px\", \"background-color\": \"#ffffff\", \"color\": \"#333333\", \"font-size\": \"16px\", \"align\": \"center\", \"width\": \"600px\", \"href\", \"src\"}, \"data\": {\"value\": {...}}, \"children\": [...]}; attribute values must be strings (numbers are dropped). Tree: page -> (wrapper | section) -> section -> column -> content blocks. Content block types: \"text\" (data.value.content = inline HTML string), \"image\" (attributes.src, alt, href, width), \"button\" (data.value.content = label, attributes.href), \"divider\", \"spacer\" (attributes.height), \"social\" (data.value.elements = [{src, href, content, target}]), \"navbar\" (data.value.links = [{href, content}]), \"raw\" (data.value.content = raw MJML/HTML), plus \"hero\", \"group\", \"accordion\", \"carousel\" and \"table\". Each also has an \"advanced_<type>\" variant (e.g. \"advanced_text\"), which is what the builder palette inserts; advanced content blocks placed directly under the page or a wrapper are auto-wrapped in a section/column. For a visual poll, insert one marketing_poll block: {\"type\": \"marketing_poll\", \"data\": {\"value\": {\"question\": \"Your question?\", \"options\": [\"Answer one\", \"Answer two\"]}}, \"attributes\": {}, \"children\": []}. Its attributes support padding, font-family, font-size, font-weight, color, background-color, button-background-color, button-text-color, button-font-size, and border-radius. The server derives the campaign poll from this block; do not maintain a separate poll definition. Page node: {\"type\": \"page\", \"attributes\": {\"background-color\": \"#efeeea\", \"width\": \"600px\"}, \"data\": {\"value\": {\"breakpoint\": \"480px\", \"font-family\": string, \"font-size\": \"14px\", \"line-height\": \"1.7\", \"font-weight\": \"400\", \"text-color\": \"#000000\", \"content-background-color\": string (optional), \"headStyles\": [{\"content\": css, \"inline\": bool}], \"fonts\": [{\"name\", \"href\"}], \"headAttributes\": \"\", \"responsive\": true}}}. Always set \"responsive\": true \u2014 a missing flag renders a fixed-width layout. Merge tokens pass through rendering untouched: {{content}} inside a text block marks where content-engine output is inserted when content is published as a campaign from this template; Smart-list merge tokens use the matching header normalized to camelCase: for example, `First Name` becomes {{firstName}} and `Company Name` becomes {{companyName}}. Tokens are replaced per recipient from the smart-list row; {{unsubscribe}} becomes the per-recipient unsubscribe link." }, "poll": { "type": "object", "description": "For HTML-only campaigns, this field is the source of truth for the poll: {\"question\": \"Your question?\", \"options\": [\"Answer one\", \"Answer two\"]}. Require a non-empty question and two to six non-empty option strings. In bodyHtml, place {{pollQuestion}} and anchors such as <a href=\"{{pollUrl0}}\" style=\"background-color:#414141;color:#ffffff\">{{pollOption0}}</a>. Indices are zero-based and follow options order. Include a quoted href=\"{{pollUrlN}}\" for every option when using any poll token; partial inline polls are rejected. Question/option tokens are replaced with escaped text; URL tokens become per-recipient voting links when sending. Leave tokens intact: never invent or reuse recipient voting URLs. Inline polls suppress the default footer poll. With no poll tokens, a default poll is appended. Update poll and bodyHtml together when changing option count/order; literal HTML labels are not synchronized, so prefer text tokens. Set poll to null and remove all poll tokens from bodyHtml in the same update to remove an HTML poll. A poll-managed bodyDocument takes precedence and derives this field automatically; edit its marketing_poll block instead. Test-email links do not record votes." }, "senderProfileId": { "type": "string", "description": "ID of the SequenceSenderProfile used to send this campaign" }, "listId": { "type": "string", "description": "ID of the smart list whose rows become recipients" }, "fieldMappings": { "type": "object", "description": "Field mapping for resolving recipient email from a list row, e.g. {\"email\": [\"Email\", \"Work Email\"]}" }, "scheduleType": { "type": "string", "description": "Schedule type (one of: now, scheduled). Default: now" }, "scheduledAt": { "type": "string", "description": "ISO timestamp at which to send (required when scheduleType is \"scheduled\")" }, "timezone": { "type": "string", "description": "IANA timezone name used to interpret scheduledAt" }, "companyId": { "type": "string", "description": "Company ID (falls back to the authenticated user's current company)" } }, "required": [ "name" ], "description": "Request body for creating a marketing campaign. Only name is required; all other fields can be filled in later via PATCH or by calling /schedule or /send-now." } } }, "description": "Campaign fields. Only name is required up front." } } }, "/api/v0/marketing-campaigns/{campaignId}": { "get": { "tags": [ "Marketing Campaigns" ], "operationId": "marketing_campaigns_getCampaign", "parameters": [ { "name": "campaignId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Campaign not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "The requested marketing campaign", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Campaign ID" }, "companyId": { "type": "string", "description": "Company this campaign belongs to" }, "uid": { "type": "string", "description": "User ID that created the campaign" }, "name": { "type": "string", "description": "Internal campaign name" }, "subject": { "type": "string", "description": "Email subject line" }, "fromName": { "type": "string", "description": "Display name shown in the From: header" }, "replyTo": { "type": "string", "description": "Reply-To email address used on outgoing emails" }, "bodyHtml": { "type": "string", "description": "HTML body of the email; rendered from bodyDocument when a document is supplied" }, "bodyDocument": { "type": "string", "description": "Visual-builder JSON document for the email body. When supplied, the server renders bodyHtml from this document and it takes precedence over HTML input. Alternatively, supply bodyHtml without a document. Envelope: {\"subject\": string, \"subTitle\": string, \"content\": <page node>}. Every node is {\"type\": string, \"attributes\": {MJML attributes as string values, e.g. \"padding\": \"10px 25px 10px 25px\", \"background-color\": \"#ffffff\", \"color\": \"#333333\", \"font-size\": \"16px\", \"align\": \"center\", \"width\": \"600px\", \"href\", \"src\"}, \"data\": {\"value\": {...}}, \"children\": [...]}; attribute values must be strings (numbers are dropped). Tree: page -> (wrapper | section) -> section -> column -> content blocks. Content block types: \"text\" (data.value.content = inline HTML string), \"image\" (attributes.src, alt, href, width), \"button\" (data.value.content = label, attributes.href), \"divider\", \"spacer\" (attributes.height), \"social\" (data.value.elements = [{src, href, content, target}]), \"navbar\" (data.value.links = [{href, content}]), \"raw\" (data.value.content = raw MJML/HTML), plus \"hero\", \"group\", \"accordion\", \"carousel\" and \"table\". Each also has an \"advanced_<type>\" variant (e.g. \"advanced_text\"), which is what the builder palette inserts; advanced content blocks placed directly under the page or a wrapper are auto-wrapped in a section/column. For a visual poll, insert one marketing_poll block: {\"type\": \"marketing_poll\", \"data\": {\"value\": {\"question\": \"Your question?\", \"options\": [\"Answer one\", \"Answer two\"]}}, \"attributes\": {}, \"children\": []}. Its attributes support padding, font-family, font-size, font-weight, color, background-color, button-background-color, button-text-color, button-font-size, and border-radius. The server derives the campaign poll from this block; do not maintain a separate poll definition. Page node: {\"type\": \"page\", \"attributes\": {\"background-color\": \"#efeeea\", \"width\": \"600px\"}, \"data\": {\"value\": {\"breakpoint\": \"480px\", \"font-family\": string, \"font-size\": \"14px\", \"line-height\": \"1.7\", \"font-weight\": \"400\", \"text-color\": \"#000000\", \"content-background-color\": string (optional), \"headStyles\": [{\"content\": css, \"inline\": bool}], \"fonts\": [{\"name\", \"href\"}], \"headAttributes\": \"\", \"responsive\": true}}}. Always set \"responsive\": true \u2014 a missing flag renders a fixed-width layout. Merge tokens pass through rendering untouched: {{content}} inside a text block marks where content-engine output is inserted when content is published as a campaign from this template; Smart-list merge tokens use the matching header normalized to camelCase: for example, `First Name` becomes {{firstName}} and `Company Name` becomes {{companyName}}. Tokens are replaced per recipient from the smart-list row; {{unsubscribe}} becomes the per-recipient unsubscribe link." }, "poll": { "type": "string", "description": "Optional one-click email poll definition and current response totals." }, "senderProfileId": { "type": "string", "description": "Sender profile ID" }, "listId": { "type": "string", "description": "Smart list ID whose rows become recipients" }, "fieldMappings": { "type": "object", "description": "Field mapping for resolving recipient email from a list row" }, "scheduleType": { "type": "string", "description": "Schedule type (now, scheduled)" }, "scheduledAt": { "type": "string", "description": "ISO timestamp at which sending begins (for scheduled campaigns)" }, "timezone": { "type": "string", "description": "IANA timezone used to interpret scheduledAt" }, "status": { "type": "string", "description": "Campaign status (draft, scheduled, sending, sent, failed, cancelled)" }, "sentCount": { "type": "integer", "description": "Number of recipients the email has been sent to" }, "failedCount": { "type": "integer", "description": "Number of recipients that failed to send" }, "skippedCount": { "type": "integer", "description": "Number of list rows skipped (missing email, duplicate, etc.)" }, "totalRecipients": { "type": "integer", "description": "Total rows in the associated smart list at read time" }, "startedAt": { "type": "string", "description": "ISO timestamp when sending started" }, "completedAt": { "type": "string", "description": "ISO timestamp when sending completed" }, "created_date": { "type": "string", "description": "ISO timestamp when the campaign was created" }, "updated_date": { "type": "string", "description": "ISO timestamp when the campaign was last updated" }, "smartList": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "description": "Summary of the associated smart list" }, "senderProfile": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "integrationId": { "type": "string" } }, "description": "Summary of the sender profile" } }, "description": "Marketing campaign object" } } } } }, "summary": "Get a single marketing campaign by ID." }, "patch": { "tags": [ "Marketing Campaigns" ], "operationId": "marketing_campaigns_updateCampaign", "parameters": [ { "name": "campaignId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid parameters, edits to locked recipient/poll fields, or campaign already sent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Campaign not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "The updated marketing campaign", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Campaign ID" }, "companyId": { "type": "string", "description": "Company this campaign belongs to" }, "uid": { "type": "string", "description": "User ID that created the campaign" }, "name": { "type": "string", "description": "Internal campaign name" }, "subject": { "type": "string", "description": "Email subject line" }, "fromName": { "type": "string", "description": "Display name shown in the From: header" }, "replyTo": { "type": "string", "description": "Reply-To email address used on outgoing emails" }, "bodyHtml": { "type": "string", "description": "HTML body of the email; rendered from bodyDocument when a document is supplied" }, "bodyDocument": { "type": "string", "description": "Visual-builder JSON document for the email body. When supplied, the server renders bodyHtml from this document and it takes precedence over HTML input. Alternatively, supply bodyHtml without a document. Envelope: {\"subject\": string, \"subTitle\": string, \"content\": <page node>}. Every node is {\"type\": string, \"attributes\": {MJML attributes as string values, e.g. \"padding\": \"10px 25px 10px 25px\", \"background-color\": \"#ffffff\", \"color\": \"#333333\", \"font-size\": \"16px\", \"align\": \"center\", \"width\": \"600px\", \"href\", \"src\"}, \"data\": {\"value\": {...}}, \"children\": [...]}; attribute values must be strings (numbers are dropped). Tree: page -> (wrapper | section) -> section -> column -> content blocks. Content block types: \"text\" (data.value.content = inline HTML string), \"image\" (attributes.src, alt, href, width), \"button\" (data.value.content = label, attributes.href), \"divider\", \"spacer\" (attributes.height), \"social\" (data.value.elements = [{src, href, content, target}]), \"navbar\" (data.value.links = [{href, content}]), \"raw\" (data.value.content = raw MJML/HTML), plus \"hero\", \"group\", \"accordion\", \"carousel\" and \"table\". Each also has an \"advanced_<type>\" variant (e.g. \"advanced_text\"), which is what the builder palette inserts; advanced content blocks placed directly under the page or a wrapper are auto-wrapped in a section/column. For a visual poll, insert one marketing_poll block: {\"type\": \"marketing_poll\", \"data\": {\"value\": {\"question\": \"Your question?\", \"options\": [\"Answer one\", \"Answer two\"]}}, \"attributes\": {}, \"children\": []}. Its attributes support padding, font-family, font-size, font-weight, color, background-color, button-background-color, button-text-color, button-font-size, and border-radius. The server derives the campaign poll from this block; do not maintain a separate poll definition. Page node: {\"type\": \"page\", \"attributes\": {\"background-color\": \"#efeeea\", \"width\": \"600px\"}, \"data\": {\"value\": {\"breakpoint\": \"480px\", \"font-family\": string, \"font-size\": \"14px\", \"line-height\": \"1.7\", \"font-weight\": \"400\", \"text-color\": \"#000000\", \"content-background-color\": string (optional), \"headStyles\": [{\"content\": css, \"inline\": bool}], \"fonts\": [{\"name\", \"href\"}], \"headAttributes\": \"\", \"responsive\": true}}}. Always set \"responsive\": true \u2014 a missing flag renders a fixed-width layout. Merge tokens pass through rendering untouched: {{content}} inside a text block marks where content-engine output is inserted when content is published as a campaign from this template; Smart-list merge tokens use the matching header normalized to camelCase: for example, `First Name` becomes {{firstName}} and `Company Name` becomes {{companyName}}. Tokens are replaced per recipient from the smart-list row; {{unsubscribe}} becomes the per-recipient unsubscribe link." }, "poll": { "type": "string", "description": "Optional one-click email poll definition and current response totals." }, "senderProfileId": { "type": "string", "description": "Sender profile ID" }, "listId": { "type": "string", "description": "Smart list ID whose rows become recipients" }, "fieldMappings": { "type": "object", "description": "Field mapping for resolving recipient email from a list row" }, "scheduleType": { "type": "string", "description": "Schedule type (now, scheduled)" }, "scheduledAt": { "type": "string", "description": "ISO timestamp at which sending begins (for scheduled campaigns)" }, "timezone": { "type": "string", "description": "IANA timezone used to interpret scheduledAt" }, "status": { "type": "string", "description": "Campaign status (draft, scheduled, sending, sent, failed, cancelled)" }, "sentCount": { "type": "integer", "description": "Number of recipients the email has been sent to" }, "failedCount": { "type": "integer", "description": "Number of recipients that failed to send" }, "skippedCount": { "type": "integer", "description": "Number of list rows skipped (missing email, duplicate, etc.)" }, "totalRecipients": { "type": "integer", "description": "Total rows in the associated smart list at read time" }, "startedAt": { "type": "string", "description": "ISO timestamp when sending started" }, "completedAt": { "type": "string", "description": "ISO timestamp when sending completed" }, "created_date": { "type": "string", "description": "ISO timestamp when the campaign was created" }, "updated_date": { "type": "string", "description": "ISO timestamp when the campaign was last updated" }, "smartList": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "description": "Summary of the associated smart list" }, "senderProfile": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "integrationId": { "type": "string" } }, "description": "Summary of the sender profile" } }, "description": "Marketing campaign object" } } } } }, "summary": "Update a marketing campaign. While sending, content, sender and sending", "description": "windows can change for remaining recipients. Recipient targeting, launch\ntime and poll definitions are locked; delivery keeps its existing progress.\nFull editing is available in draft, scheduled, cancelled, or failed status.\nEditing a scheduled campaign drops it back to draft until re-scheduled.\nSent campaigns cannot be edited.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Internal campaign name" }, "subject": { "type": "string", "description": "Email subject line" }, "fromName": { "type": "string", "description": "Display name shown in the From: header" }, "replyTo": { "type": "string", "description": "Optional Reply-To email address. Must be a valid email if provided." }, "bodyHtml": { "type": "string", "description": "HTML email body. Supply without bodyDocument for HTML-based campaigns. On update, nonblank HTML replaces the previous body and clears the previous visual-builder document. Empty HTML preserves existing content. For an inline poll, supply the poll field and style anchors with href=\"{{pollUrl0}}\", href=\"{{pollUrl1}}\", etc., one for every option. Use {{pollQuestion}} and {{pollOption0}} etc. for text. See poll for the complete contract. " }, "bodyDocument": { "type": "string", "description": "Visual-builder JSON document for the email body. When supplied, the server renders bodyHtml from this document and it takes precedence over HTML input. Alternatively, supply bodyHtml without a document. Envelope: {\"subject\": string, \"subTitle\": string, \"content\": <page node>}. Every node is {\"type\": string, \"attributes\": {MJML attributes as string values, e.g. \"padding\": \"10px 25px 10px 25px\", \"background-color\": \"#ffffff\", \"color\": \"#333333\", \"font-size\": \"16px\", \"align\": \"center\", \"width\": \"600px\", \"href\", \"src\"}, \"data\": {\"value\": {...}}, \"children\": [...]}; attribute values must be strings (numbers are dropped). Tree: page -> (wrapper | section) -> section -> column -> content blocks. Content block types: \"text\" (data.value.content = inline HTML string), \"image\" (attributes.src, alt, href, width), \"button\" (data.value.content = label, attributes.href), \"divider\", \"spacer\" (attributes.height), \"social\" (data.value.elements = [{src, href, content, target}]), \"navbar\" (data.value.links = [{href, content}]), \"raw\" (data.value.content = raw MJML/HTML), plus \"hero\", \"group\", \"accordion\", \"carousel\" and \"table\". Each also has an \"advanced_<type>\" variant (e.g. \"advanced_text\"), which is what the builder palette inserts; advanced content blocks placed directly under the page or a wrapper are auto-wrapped in a section/column. For a visual poll, insert one marketing_poll block: {\"type\": \"marketing_poll\", \"data\": {\"value\": {\"question\": \"Your question?\", \"options\": [\"Answer one\", \"Answer two\"]}}, \"attributes\": {}, \"children\": []}. Its attributes support padding, font-family, font-size, font-weight, color, background-color, button-background-color, button-text-color, button-font-size, and border-radius. The server derives the campaign poll from this block; do not maintain a separate poll definition. Page node: {\"type\": \"page\", \"attributes\": {\"background-color\": \"#efeeea\", \"width\": \"600px\"}, \"data\": {\"value\": {\"breakpoint\": \"480px\", \"font-family\": string, \"font-size\": \"14px\", \"line-height\": \"1.7\", \"font-weight\": \"400\", \"text-color\": \"#000000\", \"content-background-color\": string (optional), \"headStyles\": [{\"content\": css, \"inline\": bool}], \"fonts\": [{\"name\", \"href\"}], \"headAttributes\": \"\", \"responsive\": true}}}. Always set \"responsive\": true \u2014 a missing flag renders a fixed-width layout. Merge tokens pass through rendering untouched: {{content}} inside a text block marks where content-engine output is inserted when content is published as a campaign from this template; Smart-list merge tokens use the matching header normalized to camelCase: for example, `First Name` becomes {{firstName}} and `Company Name` becomes {{companyName}}. Tokens are replaced per recipient from the smart-list row; {{unsubscribe}} becomes the per-recipient unsubscribe link." }, "poll": { "type": "object", "description": "For HTML-only campaigns, this field is the source of truth for the poll: {\"question\": \"Your question?\", \"options\": [\"Answer one\", \"Answer two\"]}. Require a non-empty question and two to six non-empty option strings. In bodyHtml, place {{pollQuestion}} and anchors such as <a href=\"{{pollUrl0}}\" style=\"background-color:#414141;color:#ffffff\">{{pollOption0}}</a>. Indices are zero-based and follow options order. Include a quoted href=\"{{pollUrlN}}\" for every option when using any poll token; partial inline polls are rejected. Question/option tokens are replaced with escaped text; URL tokens become per-recipient voting links when sending. Leave tokens intact: never invent or reuse recipient voting URLs. Inline polls suppress the default footer poll. With no poll tokens, a default poll is appended. Update poll and bodyHtml together when changing option count/order; literal HTML labels are not synchronized, so prefer text tokens. Set poll to null and remove all poll tokens from bodyHtml in the same update to remove an HTML poll. A poll-managed bodyDocument takes precedence and derives this field automatically; edit its marketing_poll block instead. Test-email links do not record votes." }, "senderProfileId": { "type": "string", "description": "Sender profile ID" }, "listId": { "type": "string", "description": "Smart list ID whose rows become recipients" }, "fieldMappings": { "type": "object", "description": "Field mapping for resolving recipient email from a list row" }, "scheduleType": { "type": "string", "description": "Schedule type (one of: now, scheduled)" }, "scheduledAt": { "type": "string", "description": "ISO timestamp at which to send" }, "timezone": { "type": "string", "description": "IANA timezone name" }, "scheduleSettings": { "type": "object", "description": "Sending windows: timezone (IANA name), plus monday through sunday, each with enabled, startTime and endTime (HH:MM). May be updated while sending; changes apply on the next sending cycle." } }, "description": "Request body for updating a marketing campaign (only include fields to change). While sending, name, subject, fromName, replyTo, bodyHtml, bodyDocument, senderProfileId, timezone, and scheduleSettings are editable; recipients and poll definitions are locked. Full editing is available in draft, scheduled, cancelled, or failed status. Sent campaigns are locked." } } }, "description": "Fields to update (include only fields you want to change)" } }, "delete": { "tags": [ "Marketing Campaigns" ], "operationId": "marketing_campaigns_deleteCampaign", "parameters": [ { "name": "campaignId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Campaign not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Deletion confirmation", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "description": "Result of deleting a campaign" } } } } }, "summary": "Soft-delete a marketing campaign. The campaign is hidden from lists but", "description": "the underlying send history and recipient rows are retained." } }, "/api/v0/marketing-campaigns/{campaignId}/versions": { "get": { "tags": [ "Marketing Campaigns" ], "operationId": "marketing_campaigns_listCampaignVersions", "parameters": [ { "name": "campaignId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Campaign not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "The campaign's saved content versions, newest first", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Version ID" }, "campaignId": { "type": "string", "description": "The campaign this version belongs to" }, "data": { "type": "string", "description": "Full snapshot of the campaign at this point in time (includes bodyDocument)" }, "bodyHtml": { "type": "string", "description": "Rendered email HTML for this version" }, "uid": { "type": "string", "description": "User who saved this version" }, "created_date": { "type": "string", "format": "date-time", "description": "When this version was captured" } }, "description": "A saved version of a campaign's content" } } }, "description": "A campaign's saved content versions, newest first" } } } } }, "summary": "List the saved content versions for a campaign, newest first. A version is", "description": "captured each time the campaign's email body changes." } }, "/api/v0/marketing-campaigns/{campaignId}/versions/{versionId}/restore": { "post": { "tags": [ "Marketing Campaigns" ], "operationId": "marketing_campaigns_restoreCampaignVersion", "parameters": [ { "name": "campaignId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "versionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid request parameters or campaign is already sending/sent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Campaign or version not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "The campaign after restoring the selected version", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Campaign ID" }, "companyId": { "type": "string", "description": "Company this campaign belongs to" }, "uid": { "type": "string", "description": "User ID that created the campaign" }, "name": { "type": "string", "description": "Internal campaign name" }, "subject": { "type": "string", "description": "Email subject line" }, "fromName": { "type": "string", "description": "Display name shown in the From: header" }, "replyTo": { "type": "string", "description": "Reply-To email address used on outgoing emails" }, "bodyHtml": { "type": "string", "description": "HTML body of the email; rendered from bodyDocument when a document is supplied" }, "bodyDocument": { "type": "string", "description": "Visual-builder JSON document for the email body. When supplied, the server renders bodyHtml from this document and it takes precedence over HTML input. Alternatively, supply bodyHtml without a document. Envelope: {\"subject\": string, \"subTitle\": string, \"content\": <page node>}. Every node is {\"type\": string, \"attributes\": {MJML attributes as string values, e.g. \"padding\": \"10px 25px 10px 25px\", \"background-color\": \"#ffffff\", \"color\": \"#333333\", \"font-size\": \"16px\", \"align\": \"center\", \"width\": \"600px\", \"href\", \"src\"}, \"data\": {\"value\": {...}}, \"children\": [...]}; attribute values must be strings (numbers are dropped). Tree: page -> (wrapper | section) -> section -> column -> content blocks. Content block types: \"text\" (data.value.content = inline HTML string), \"image\" (attributes.src, alt, href, width), \"button\" (data.value.content = label, attributes.href), \"divider\", \"spacer\" (attributes.height), \"social\" (data.value.elements = [{src, href, content, target}]), \"navbar\" (data.value.links = [{href, content}]), \"raw\" (data.value.content = raw MJML/HTML), plus \"hero\", \"group\", \"accordion\", \"carousel\" and \"table\". Each also has an \"advanced_<type>\" variant (e.g. \"advanced_text\"), which is what the builder palette inserts; advanced content blocks placed directly under the page or a wrapper are auto-wrapped in a section/column. For a visual poll, insert one marketing_poll block: {\"type\": \"marketing_poll\", \"data\": {\"value\": {\"question\": \"Your question?\", \"options\": [\"Answer one\", \"Answer two\"]}}, \"attributes\": {}, \"children\": []}. Its attributes support padding, font-family, font-size, font-weight, color, background-color, button-background-color, button-text-color, button-font-size, and border-radius. The server derives the campaign poll from this block; do not maintain a separate poll definition. Page node: {\"type\": \"page\", \"attributes\": {\"background-color\": \"#efeeea\", \"width\": \"600px\"}, \"data\": {\"value\": {\"breakpoint\": \"480px\", \"font-family\": string, \"font-size\": \"14px\", \"line-height\": \"1.7\", \"font-weight\": \"400\", \"text-color\": \"#000000\", \"content-background-color\": string (optional), \"headStyles\": [{\"content\": css, \"inline\": bool}], \"fonts\": [{\"name\", \"href\"}], \"headAttributes\": \"\", \"responsive\": true}}}. Always set \"responsive\": true \u2014 a missing flag renders a fixed-width layout. Merge tokens pass through rendering untouched: {{content}} inside a text block marks where content-engine output is inserted when content is published as a campaign from this template; Smart-list merge tokens use the matching header normalized to camelCase: for example, `First Name` becomes {{firstName}} and `Company Name` becomes {{companyName}}. Tokens are replaced per recipient from the smart-list row; {{unsubscribe}} becomes the per-recipient unsubscribe link." }, "poll": { "type": "string", "description": "Optional one-click email poll definition and current response totals." }, "senderProfileId": { "type": "string", "description": "Sender profile ID" }, "listId": { "type": "string", "description": "Smart list ID whose rows become recipients" }, "fieldMappings": { "type": "object", "description": "Field mapping for resolving recipient email from a list row" }, "scheduleType": { "type": "string", "description": "Schedule type (now, scheduled)" }, "scheduledAt": { "type": "string", "description": "ISO timestamp at which sending begins (for scheduled campaigns)" }, "timezone": { "type": "string", "description": "IANA timezone used to interpret scheduledAt" }, "status": { "type": "string", "description": "Campaign status (draft, scheduled, sending, sent, failed, cancelled)" }, "sentCount": { "type": "integer", "description": "Number of recipients the email has been sent to" }, "failedCount": { "type": "integer", "description": "Number of recipients that failed to send" }, "skippedCount": { "type": "integer", "description": "Number of list rows skipped (missing email, duplicate, etc.)" }, "totalRecipients": { "type": "integer", "description": "Total rows in the associated smart list at read time" }, "startedAt": { "type": "string", "description": "ISO timestamp when sending started" }, "completedAt": { "type": "string", "description": "ISO timestamp when sending completed" }, "created_date": { "type": "string", "description": "ISO timestamp when the campaign was created" }, "updated_date": { "type": "string", "description": "ISO timestamp when the campaign was last updated" }, "smartList": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "description": "Summary of the associated smart list" }, "senderProfile": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "integrationId": { "type": "string" } }, "description": "Summary of the sender profile" } }, "description": "Marketing campaign object" } } } } }, "summary": "Restore a campaign's body to a previously saved version. The restore is", "description": "itself captured as a new version, so it is always reversible. Only allowed\nwhile the campaign is editable (draft, scheduled, cancelled, or failed)." } }, "/api/v0/marketing-campaigns/{campaignId}/duplicate": { "post": { "tags": [ "Marketing Campaigns" ], "operationId": "marketing_campaigns_duplicateCampaign", "parameters": [ { "name": "campaignId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Campaign not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "A new draft campaign with copied content and targeting", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Campaign ID" }, "companyId": { "type": "string", "description": "Company this campaign belongs to" }, "uid": { "type": "string", "description": "User ID that created the campaign" }, "name": { "type": "string", "description": "Internal campaign name" }, "subject": { "type": "string", "description": "Email subject line" }, "fromName": { "type": "string", "description": "Display name shown in the From: header" }, "replyTo": { "type": "string", "description": "Reply-To email address used on outgoing emails" }, "bodyHtml": { "type": "string", "description": "HTML body of the email; rendered from bodyDocument when a document is supplied" }, "bodyDocument": { "type": "string", "description": "Visual-builder JSON document for the email body. When supplied, the server renders bodyHtml from this document and it takes precedence over HTML input. Alternatively, supply bodyHtml without a document. Envelope: {\"subject\": string, \"subTitle\": string, \"content\": <page node>}. Every node is {\"type\": string, \"attributes\": {MJML attributes as string values, e.g. \"padding\": \"10px 25px 10px 25px\", \"background-color\": \"#ffffff\", \"color\": \"#333333\", \"font-size\": \"16px\", \"align\": \"center\", \"width\": \"600px\", \"href\", \"src\"}, \"data\": {\"value\": {...}}, \"children\": [...]}; attribute values must be strings (numbers are dropped). Tree: page -> (wrapper | section) -> section -> column -> content blocks. Content block types: \"text\" (data.value.content = inline HTML string), \"image\" (attributes.src, alt, href, width), \"button\" (data.value.content = label, attributes.href), \"divider\", \"spacer\" (attributes.height), \"social\" (data.value.elements = [{src, href, content, target}]), \"navbar\" (data.value.links = [{href, content}]), \"raw\" (data.value.content = raw MJML/HTML), plus \"hero\", \"group\", \"accordion\", \"carousel\" and \"table\". Each also has an \"advanced_<type>\" variant (e.g. \"advanced_text\"), which is what the builder palette inserts; advanced content blocks placed directly under the page or a wrapper are auto-wrapped in a section/column. For a visual poll, insert one marketing_poll block: {\"type\": \"marketing_poll\", \"data\": {\"value\": {\"question\": \"Your question?\", \"options\": [\"Answer one\", \"Answer two\"]}}, \"attributes\": {}, \"children\": []}. Its attributes support padding, font-family, font-size, font-weight, color, background-color, button-background-color, button-text-color, button-font-size, and border-radius. The server derives the campaign poll from this block; do not maintain a separate poll definition. Page node: {\"type\": \"page\", \"attributes\": {\"background-color\": \"#efeeea\", \"width\": \"600px\"}, \"data\": {\"value\": {\"breakpoint\": \"480px\", \"font-family\": string, \"font-size\": \"14px\", \"line-height\": \"1.7\", \"font-weight\": \"400\", \"text-color\": \"#000000\", \"content-background-color\": string (optional), \"headStyles\": [{\"content\": css, \"inline\": bool}], \"fonts\": [{\"name\", \"href\"}], \"headAttributes\": \"\", \"responsive\": true}}}. Always set \"responsive\": true \u2014 a missing flag renders a fixed-width layout. Merge tokens pass through rendering untouched: {{content}} inside a text block marks where content-engine output is inserted when content is published as a campaign from this template; Smart-list merge tokens use the matching header normalized to camelCase: for example, `First Name` becomes {{firstName}} and `Company Name` becomes {{companyName}}. Tokens are replaced per recipient from the smart-list row; {{unsubscribe}} becomes the per-recipient unsubscribe link." }, "poll": { "type": "string", "description": "Optional one-click email poll definition and current response totals." }, "senderProfileId": { "type": "string", "description": "Sender profile ID" }, "listId": { "type": "string", "description": "Smart list ID whose rows become recipients" }, "fieldMappings": { "type": "object", "description": "Field mapping for resolving recipient email from a list row" }, "scheduleType": { "type": "string", "description": "Schedule type (now, scheduled)" }, "scheduledAt": { "type": "string", "description": "ISO timestamp at which sending begins (for scheduled campaigns)" }, "timezone": { "type": "string", "description": "IANA timezone used to interpret scheduledAt" }, "status": { "type": "string", "description": "Campaign status (draft, scheduled, sending, sent, failed, cancelled)" }, "sentCount": { "type": "integer", "description": "Number of recipients the email has been sent to" }, "failedCount": { "type": "integer", "description": "Number of recipients that failed to send" }, "skippedCount": { "type": "integer", "description": "Number of list rows skipped (missing email, duplicate, etc.)" }, "totalRecipients": { "type": "integer", "description": "Total rows in the associated smart list at read time" }, "startedAt": { "type": "string", "description": "ISO timestamp when sending started" }, "completedAt": { "type": "string", "description": "ISO timestamp when sending completed" }, "created_date": { "type": "string", "description": "ISO timestamp when the campaign was created" }, "updated_date": { "type": "string", "description": "ISO timestamp when the campaign was last updated" }, "smartList": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "description": "Summary of the associated smart list" }, "senderProfile": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "integrationId": { "type": "string" } }, "description": "Summary of the sender profile" } }, "description": "Marketing campaign object" } } } } }, "summary": "Duplicate a campaign into a fresh draft. Copies content, sender, list,", "description": "and sending windows, but never recipients, statistics, or scheduled launch.\nThe copy must be explicitly sent or scheduled before it delivers emails." } }, "/api/v0/marketing-campaigns/{campaignId}/send-now": { "post": { "tags": [ "Marketing Campaigns" ], "operationId": "marketing_campaigns_sendCampaignNow", "parameters": [ { "name": "campaignId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Campaign is missing required fields or is already sending/sent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Campaign not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "The campaign in sending status", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Campaign ID" }, "companyId": { "type": "string", "description": "Company this campaign belongs to" }, "uid": { "type": "string", "description": "User ID that created the campaign" }, "name": { "type": "string", "description": "Internal campaign name" }, "subject": { "type": "string", "description": "Email subject line" }, "fromName": { "type": "string", "description": "Display name shown in the From: header" }, "replyTo": { "type": "string", "description": "Reply-To email address used on outgoing emails" }, "bodyHtml": { "type": "string", "description": "HTML body of the email; rendered from bodyDocument when a document is supplied" }, "bodyDocument": { "type": "string", "description": "Visual-builder JSON document for the email body. When supplied, the server renders bodyHtml from this document and it takes precedence over HTML input. Alternatively, supply bodyHtml without a document. Envelope: {\"subject\": string, \"subTitle\": string, \"content\": <page node>}. Every node is {\"type\": string, \"attributes\": {MJML attributes as string values, e.g. \"padding\": \"10px 25px 10px 25px\", \"background-color\": \"#ffffff\", \"color\": \"#333333\", \"font-size\": \"16px\", \"align\": \"center\", \"width\": \"600px\", \"href\", \"src\"}, \"data\": {\"value\": {...}}, \"children\": [...]}; attribute values must be strings (numbers are dropped). Tree: page -> (wrapper | section) -> section -> column -> content blocks. Content block types: \"text\" (data.value.content = inline HTML string), \"image\" (attributes.src, alt, href, width), \"button\" (data.value.content = label, attributes.href), \"divider\", \"spacer\" (attributes.height), \"social\" (data.value.elements = [{src, href, content, target}]), \"navbar\" (data.value.links = [{href, content}]), \"raw\" (data.value.content = raw MJML/HTML), plus \"hero\", \"group\", \"accordion\", \"carousel\" and \"table\". Each also has an \"advanced_<type>\" variant (e.g. \"advanced_text\"), which is what the builder palette inserts; advanced content blocks placed directly under the page or a wrapper are auto-wrapped in a section/column. For a visual poll, insert one marketing_poll block: {\"type\": \"marketing_poll\", \"data\": {\"value\": {\"question\": \"Your question?\", \"options\": [\"Answer one\", \"Answer two\"]}}, \"attributes\": {}, \"children\": []}. Its attributes support padding, font-family, font-size, font-weight, color, background-color, button-background-color, button-text-color, button-font-size, and border-radius. The server derives the campaign poll from this block; do not maintain a separate poll definition. Page node: {\"type\": \"page\", \"attributes\": {\"background-color\": \"#efeeea\", \"width\": \"600px\"}, \"data\": {\"value\": {\"breakpoint\": \"480px\", \"font-family\": string, \"font-size\": \"14px\", \"line-height\": \"1.7\", \"font-weight\": \"400\", \"text-color\": \"#000000\", \"content-background-color\": string (optional), \"headStyles\": [{\"content\": css, \"inline\": bool}], \"fonts\": [{\"name\", \"href\"}], \"headAttributes\": \"\", \"responsive\": true}}}. Always set \"responsive\": true \u2014 a missing flag renders a fixed-width layout. Merge tokens pass through rendering untouched: {{content}} inside a text block marks where content-engine output is inserted when content is published as a campaign from this template; Smart-list merge tokens use the matching header normalized to camelCase: for example, `First Name` becomes {{firstName}} and `Company Name` becomes {{companyName}}. Tokens are replaced per recipient from the smart-list row; {{unsubscribe}} becomes the per-recipient unsubscribe link." }, "poll": { "type": "string", "description": "Optional one-click email poll definition and current response totals." }, "senderProfileId": { "type": "string", "description": "Sender profile ID" }, "listId": { "type": "string", "description": "Smart list ID whose rows become recipients" }, "fieldMappings": { "type": "object", "description": "Field mapping for resolving recipient email from a list row" }, "scheduleType": { "type": "string", "description": "Schedule type (now, scheduled)" }, "scheduledAt": { "type": "string", "description": "ISO timestamp at which sending begins (for scheduled campaigns)" }, "timezone": { "type": "string", "description": "IANA timezone used to interpret scheduledAt" }, "status": { "type": "string", "description": "Campaign status (draft, scheduled, sending, sent, failed, cancelled)" }, "sentCount": { "type": "integer", "description": "Number of recipients the email has been sent to" }, "failedCount": { "type": "integer", "description": "Number of recipients that failed to send" }, "skippedCount": { "type": "integer", "description": "Number of list rows skipped (missing email, duplicate, etc.)" }, "totalRecipients": { "type": "integer", "description": "Total rows in the associated smart list at read time" }, "startedAt": { "type": "string", "description": "ISO timestamp when sending started" }, "completedAt": { "type": "string", "description": "ISO timestamp when sending completed" }, "created_date": { "type": "string", "description": "ISO timestamp when the campaign was created" }, "updated_date": { "type": "string", "description": "ISO timestamp when the campaign was last updated" }, "smartList": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "description": "Summary of the associated smart list" }, "senderProfile": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "integrationId": { "type": "string" } }, "description": "Summary of the sender profile" } }, "description": "Marketing campaign object" } } } } }, "summary": "Begin sending a draft campaign immediately.", "description": "The campaign must have a senderProfileId, listId, subject, and bodyHtml.\nOnce this returns, the per-minute cron paces the actual sends so delivery\nis spread out over time \u2014 expect the status to stay in \"sending\" while the\nbacklog drains, then flip to \"sent\" when the list is exhausted." } }, "/api/v0/marketing-campaigns/{campaignId}/schedule": { "post": { "tags": [ "Marketing Campaigns" ], "operationId": "marketing_campaigns_scheduleCampaign", "parameters": [ { "name": "campaignId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Campaign is missing required fields or scheduledAt is invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Campaign not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "The scheduled campaign", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Campaign ID" }, "companyId": { "type": "string", "description": "Company this campaign belongs to" }, "uid": { "type": "string", "description": "User ID that created the campaign" }, "name": { "type": "string", "description": "Internal campaign name" }, "subject": { "type": "string", "description": "Email subject line" }, "fromName": { "type": "string", "description": "Display name shown in the From: header" }, "replyTo": { "type": "string", "description": "Reply-To email address used on outgoing emails" }, "bodyHtml": { "type": "string", "description": "HTML body of the email; rendered from bodyDocument when a document is supplied" }, "bodyDocument": { "type": "string", "description": "Visual-builder JSON document for the email body. When supplied, the server renders bodyHtml from this document and it takes precedence over HTML input. Alternatively, supply bodyHtml without a document. Envelope: {\"subject\": string, \"subTitle\": string, \"content\": <page node>}. Every node is {\"type\": string, \"attributes\": {MJML attributes as string values, e.g. \"padding\": \"10px 25px 10px 25px\", \"background-color\": \"#ffffff\", \"color\": \"#333333\", \"font-size\": \"16px\", \"align\": \"center\", \"width\": \"600px\", \"href\", \"src\"}, \"data\": {\"value\": {...}}, \"children\": [...]}; attribute values must be strings (numbers are dropped). Tree: page -> (wrapper | section) -> section -> column -> content blocks. Content block types: \"text\" (data.value.content = inline HTML string), \"image\" (attributes.src, alt, href, width), \"button\" (data.value.content = label, attributes.href), \"divider\", \"spacer\" (attributes.height), \"social\" (data.value.elements = [{src, href, content, target}]), \"navbar\" (data.value.links = [{href, content}]), \"raw\" (data.value.content = raw MJML/HTML), plus \"hero\", \"group\", \"accordion\", \"carousel\" and \"table\". Each also has an \"advanced_<type>\" variant (e.g. \"advanced_text\"), which is what the builder palette inserts; advanced content blocks placed directly under the page or a wrapper are auto-wrapped in a section/column. For a visual poll, insert one marketing_poll block: {\"type\": \"marketing_poll\", \"data\": {\"value\": {\"question\": \"Your question?\", \"options\": [\"Answer one\", \"Answer two\"]}}, \"attributes\": {}, \"children\": []}. Its attributes support padding, font-family, font-size, font-weight, color, background-color, button-background-color, button-text-color, button-font-size, and border-radius. The server derives the campaign poll from this block; do not maintain a separate poll definition. Page node: {\"type\": \"page\", \"attributes\": {\"background-color\": \"#efeeea\", \"width\": \"600px\"}, \"data\": {\"value\": {\"breakpoint\": \"480px\", \"font-family\": string, \"font-size\": \"14px\", \"line-height\": \"1.7\", \"font-weight\": \"400\", \"text-color\": \"#000000\", \"content-background-color\": string (optional), \"headStyles\": [{\"content\": css, \"inline\": bool}], \"fonts\": [{\"name\", \"href\"}], \"headAttributes\": \"\", \"responsive\": true}}}. Always set \"responsive\": true \u2014 a missing flag renders a fixed-width layout. Merge tokens pass through rendering untouched: {{content}} inside a text block marks where content-engine output is inserted when content is published as a campaign from this template; Smart-list merge tokens use the matching header normalized to camelCase: for example, `First Name` becomes {{firstName}} and `Company Name` becomes {{companyName}}. Tokens are replaced per recipient from the smart-list row; {{unsubscribe}} becomes the per-recipient unsubscribe link." }, "poll": { "type": "string", "description": "Optional one-click email poll definition and current response totals." }, "senderProfileId": { "type": "string", "description": "Sender profile ID" }, "listId": { "type": "string", "description": "Smart list ID whose rows become recipients" }, "fieldMappings": { "type": "object", "description": "Field mapping for resolving recipient email from a list row" }, "scheduleType": { "type": "string", "description": "Schedule type (now, scheduled)" }, "scheduledAt": { "type": "string", "description": "ISO timestamp at which sending begins (for scheduled campaigns)" }, "timezone": { "type": "string", "description": "IANA timezone used to interpret scheduledAt" }, "status": { "type": "string", "description": "Campaign status (draft, scheduled, sending, sent, failed, cancelled)" }, "sentCount": { "type": "integer", "description": "Number of recipients the email has been sent to" }, "failedCount": { "type": "integer", "description": "Number of recipients that failed to send" }, "skippedCount": { "type": "integer", "description": "Number of list rows skipped (missing email, duplicate, etc.)" }, "totalRecipients": { "type": "integer", "description": "Total rows in the associated smart list at read time" }, "startedAt": { "type": "string", "description": "ISO timestamp when sending started" }, "completedAt": { "type": "string", "description": "ISO timestamp when sending completed" }, "created_date": { "type": "string", "description": "ISO timestamp when the campaign was created" }, "updated_date": { "type": "string", "description": "ISO timestamp when the campaign was last updated" }, "smartList": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "description": "Summary of the associated smart list" }, "senderProfile": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "integrationId": { "type": "string" } }, "description": "Summary of the sender profile" } }, "description": "Marketing campaign object" } } } } }, "summary": "Schedule a campaign to begin sending at a specific time.", "description": "The campaign must have a senderProfileId, listId, subject, and bodyHtml.\nScheduling a campaign that is already sending or sent is rejected.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "scheduledAt": { "type": "string", "description": "ISO timestamp at which to begin sending" }, "timezone": { "type": "string", "description": "IANA timezone name used to interpret scheduledAt (e.g. \"America/Los_Angeles\")" } }, "required": [ "scheduledAt" ], "description": "Request body for scheduling a campaign" } } }, "description": "Scheduling details" } } }, "/api/v0/marketing-campaigns/{campaignId}/cancel": { "post": { "tags": [ "Marketing Campaigns" ], "operationId": "marketing_campaigns_cancelCampaign", "parameters": [ { "name": "campaignId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Only scheduled campaigns can be cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Campaign not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "The cancelled campaign", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Campaign ID" }, "companyId": { "type": "string", "description": "Company this campaign belongs to" }, "uid": { "type": "string", "description": "User ID that created the campaign" }, "name": { "type": "string", "description": "Internal campaign name" }, "subject": { "type": "string", "description": "Email subject line" }, "fromName": { "type": "string", "description": "Display name shown in the From: header" }, "replyTo": { "type": "string", "description": "Reply-To email address used on outgoing emails" }, "bodyHtml": { "type": "string", "description": "HTML body of the email; rendered from bodyDocument when a document is supplied" }, "bodyDocument": { "type": "string", "description": "Visual-builder JSON document for the email body. When supplied, the server renders bodyHtml from this document and it takes precedence over HTML input. Alternatively, supply bodyHtml without a document. Envelope: {\"subject\": string, \"subTitle\": string, \"content\": <page node>}. Every node is {\"type\": string, \"attributes\": {MJML attributes as string values, e.g. \"padding\": \"10px 25px 10px 25px\", \"background-color\": \"#ffffff\", \"color\": \"#333333\", \"font-size\": \"16px\", \"align\": \"center\", \"width\": \"600px\", \"href\", \"src\"}, \"data\": {\"value\": {...}}, \"children\": [...]}; attribute values must be strings (numbers are dropped). Tree: page -> (wrapper | section) -> section -> column -> content blocks. Content block types: \"text\" (data.value.content = inline HTML string), \"image\" (attributes.src, alt, href, width), \"button\" (data.value.content = label, attributes.href), \"divider\", \"spacer\" (attributes.height), \"social\" (data.value.elements = [{src, href, content, target}]), \"navbar\" (data.value.links = [{href, content}]), \"raw\" (data.value.content = raw MJML/HTML), plus \"hero\", \"group\", \"accordion\", \"carousel\" and \"table\". Each also has an \"advanced_<type>\" variant (e.g. \"advanced_text\"), which is what the builder palette inserts; advanced content blocks placed directly under the page or a wrapper are auto-wrapped in a section/column. For a visual poll, insert one marketing_poll block: {\"type\": \"marketing_poll\", \"data\": {\"value\": {\"question\": \"Your question?\", \"options\": [\"Answer one\", \"Answer two\"]}}, \"attributes\": {}, \"children\": []}. Its attributes support padding, font-family, font-size, font-weight, color, background-color, button-background-color, button-text-color, button-font-size, and border-radius. The server derives the campaign poll from this block; do not maintain a separate poll definition. Page node: {\"type\": \"page\", \"attributes\": {\"background-color\": \"#efeeea\", \"width\": \"600px\"}, \"data\": {\"value\": {\"breakpoint\": \"480px\", \"font-family\": string, \"font-size\": \"14px\", \"line-height\": \"1.7\", \"font-weight\": \"400\", \"text-color\": \"#000000\", \"content-background-color\": string (optional), \"headStyles\": [{\"content\": css, \"inline\": bool}], \"fonts\": [{\"name\", \"href\"}], \"headAttributes\": \"\", \"responsive\": true}}}. Always set \"responsive\": true \u2014 a missing flag renders a fixed-width layout. Merge tokens pass through rendering untouched: {{content}} inside a text block marks where content-engine output is inserted when content is published as a campaign from this template; Smart-list merge tokens use the matching header normalized to camelCase: for example, `First Name` becomes {{firstName}} and `Company Name` becomes {{companyName}}. Tokens are replaced per recipient from the smart-list row; {{unsubscribe}} becomes the per-recipient unsubscribe link." }, "poll": { "type": "string", "description": "Optional one-click email poll definition and current response totals." }, "senderProfileId": { "type": "string", "description": "Sender profile ID" }, "listId": { "type": "string", "description": "Smart list ID whose rows become recipients" }, "fieldMappings": { "type": "object", "description": "Field mapping for resolving recipient email from a list row" }, "scheduleType": { "type": "string", "description": "Schedule type (now, scheduled)" }, "scheduledAt": { "type": "string", "description": "ISO timestamp at which sending begins (for scheduled campaigns)" }, "timezone": { "type": "string", "description": "IANA timezone used to interpret scheduledAt" }, "status": { "type": "string", "description": "Campaign status (draft, scheduled, sending, sent, failed, cancelled)" }, "sentCount": { "type": "integer", "description": "Number of recipients the email has been sent to" }, "failedCount": { "type": "integer", "description": "Number of recipients that failed to send" }, "skippedCount": { "type": "integer", "description": "Number of list rows skipped (missing email, duplicate, etc.)" }, "totalRecipients": { "type": "integer", "description": "Total rows in the associated smart list at read time" }, "startedAt": { "type": "string", "description": "ISO timestamp when sending started" }, "completedAt": { "type": "string", "description": "ISO timestamp when sending completed" }, "created_date": { "type": "string", "description": "ISO timestamp when the campaign was created" }, "updated_date": { "type": "string", "description": "ISO timestamp when the campaign was last updated" }, "smartList": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "description": "Summary of the associated smart list" }, "senderProfile": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "integrationId": { "type": "string" } }, "description": "Summary of the sender profile" } }, "description": "Marketing campaign object" } } } } }, "summary": "Cancel a scheduled campaign so it will not begin sending.", "description": "Only campaigns in \"scheduled\" status can be cancelled. Campaigns that are\nalready sending or sent cannot be cancelled." } }, "/api/v0/marketing-campaigns/{campaignId}/test-send": { "post": { "tags": [ "Marketing Campaigns" ], "operationId": "marketing_campaigns_sendTestEmail", "parameters": [ { "name": "campaignId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Test send failed or campaign is missing required fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Result of the test send", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the test email was accepted by the provider" }, "message": { "type": "string", "description": "Provider message, when available" }, "error": { "type": "string", "description": "Error message when success is false" } }, "description": "Result of sending a test email" } } } } }, "summary": "Send a one-off test email for a campaign to a specific address.", "description": "Uses the campaign's configured sender profile, subject, and body but does\nnot affect the recipient list, counters, or send history.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "poll": { "type": "object", "description": "Override poll for a test email. Test answer links do not record votes." }, "testEmail": { "type": "string", "description": "Email address to send the test to" }, "subject": { "type": "string", "description": "Override subject to test with the current (unsaved) form value instead of the persisted campaign subject" }, "bodyHtml": { "type": "string", "description": "Override HTML body to test with the current (unsaved) form value instead of the persisted campaign body" }, "fromName": { "type": "string", "description": "Override sender display name for the test email" }, "senderProfileId": { "type": "string", "description": "Override sender profile to test with the current (unsaved) form selection instead of the persisted campaign sender" }, "replyTo": { "type": "string", "description": "Override reply-to address to test with the current (unsaved) form value" } }, "required": [ "testEmail" ], "description": "Request body for sending a one-off test email" } } }, "description": "Test email target" } } }, "/api/v0/marketing-campaigns/{campaignId}/recipients": { "get": { "tags": [ "Marketing Campaigns" ], "operationId": "marketing_campaigns_getCampaignRecipients", "parameters": [ { "name": "campaignId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "description": "Case-insensitive substring filter applied to the recipient email address" }, "description": "Case-insensitive substring filter applied to the recipient email address" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "1-indexed page; omit for legacy unpaginated results" }, "description": "1-indexed page; omit for legacy unpaginated results" }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "description": "Page size, 1-100, default 25" }, "description": "Page size, 1-100, default 25" } ], "responses": { "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Campaign not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "All recipient rows for this campaign, ordered most-recent first. Pass ?search= to filter by email substring.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Recipient ID" }, "campaignId": { "type": "string", "description": "Campaign this recipient belongs to" }, "listRowId": { "type": "string", "description": "Source smart list row, if any" }, "email": { "type": "string", "description": "Email address this recipient was sent to" }, "status": { "type": "string", "description": "Delivery status (pending, sent, failed, skipped, bounced)" }, "sentAt": { "type": "string", "description": "ISO timestamp when the email was sent" }, "errorMessage": { "type": "string", "description": "Error message if status is failed/skipped/bounced" }, "opened": { "type": "boolean", "description": "Whether the email has been opened at least once" }, "firstOpenedDate": { "type": "string", "description": "ISO timestamp of the first open" }, "lastOpenedDate": { "type": "string", "description": "ISO timestamp of the most recent open" }, "openCount": { "type": "integer", "description": "Number of times the email was opened" }, "clicked": { "type": "boolean", "description": "Whether a tracked link was clicked at least once" }, "firstClickedDate": { "type": "string", "description": "ISO timestamp of the first click" }, "lastClickedDate": { "type": "string", "description": "ISO timestamp of the most recent click" }, "clickCount": { "type": "integer", "description": "Number of times a tracked link was clicked" }, "created_date": { "type": "string", "description": "ISO timestamp when the recipient row was created" }, "updated_date": { "type": "string", "description": "ISO timestamp when the recipient row was last updated" } }, "description": "A single recipient of a marketing campaign" } }, "total": { "type": "integer" }, "metrics": { "type": "object", "properties": { "total": { "type": "integer", "description": "Total recipient rows for this campaign" }, "sent": { "type": "integer", "description": "Recipients the email was sent to (status sent or bounced)" }, "failed": { "type": "integer", "description": "Recipients with status failed" }, "skipped": { "type": "integer", "description": "Recipients with status skipped" }, "bounced": { "type": "integer", "description": "Recipients whose email bounced after it was sent" }, "opened": { "type": "integer", "description": "Unique recipients who opened the email" }, "clicked": { "type": "integer", "description": "Unique recipients who clicked a tracked link" }, "openRate": { "type": "number", "description": "opened / sent, 0.0-1.0" }, "clickRate": { "type": "number", "description": "clicked / sent, 0.0-1.0" }, "bounceRate": { "type": "number", "description": "bounced / sent, 0.0-1.0" } }, "description": "Aggregate metrics across all recipients (not just the returned page)" } }, "description": "List of recipients for a campaign" } } } } }, "summary": "List the recipients materialized for this campaign, including per-recipient", "description": "send status, open count, click count, and error message where applicable.\nRecipients are created when a campaign starts sending; for draft or scheduled\ncampaigns this list will usually be empty.\n\nOptionally pass ?search=<text> to filter the returned items to recipients\nwhose email address contains the given substring (case-insensitive). The\naggregate metrics object always reflects all recipients for the campaign,\nindependent of the search filter." } }, "/api/v0/marketing-campaigns/{campaignId}/recipients/{recipientId}": { "delete": { "tags": [ "Marketing Campaigns" ], "operationId": "marketing_campaigns_deleteCampaignRecipient", "parameters": [ { "name": "campaignId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "recipientId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Campaign or recipient not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Whether the recipient was soft-deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "description": "Result of deleting a campaign" } } } } }, "summary": "Soft-delete a single recipient from a campaign. The row is hidden from", "description": "listings, search, aggregate metrics, and the send pipeline, but is retained\nin the database. Open/click pixel hits that arrive after deletion still\nupdate the row but no longer flow through aggregates." } }, "/api/v0/marketing-campaigns/statistics": { "get": { "tags": [ "Marketing Campaigns" ], "operationId": "marketing_campaigns_getCampaignStatistics", "parameters": [], "responses": { "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Aggregate statistics across all marketing campaigns in the company", "content": { "application/json": { "schema": { "type": "object", "properties": { "totalCampaigns": { "type": "integer", "description": "Total number of campaigns (excluding deleted)" }, "activeCampaigns": { "type": "integer", "description": "Count of campaigns currently scheduled or sending" }, "totalSent": { "type": "integer", "description": "Total number of recipient emails sent" }, "totalOpened": { "type": "integer", "description": "Total number of unique recipients that opened an email" }, "totalClicked": { "type": "integer", "description": "Total number of unique recipients that clicked a tracked link" }, "totalBounced": { "type": "integer", "description": "Total number of recipient emails that bounced after sending" }, "openRate": { "type": "number", "description": "Opened / sent (0-1)" }, "clickRate": { "type": "number", "description": "Clicked / sent (0-1)" }, "bounceRate": { "type": "number", "description": "Bounced / sent (0-1)" } }, "description": "Aggregate counters across the company's marketing campaigns" } } } } }, "summary": "Return aggregate counters (total campaigns, active, sent, opened, clicked,", "description": "plus open and click rates) across all of the company's marketing campaigns." } }, "/api/v0/marketing-campaigns/timeseries": { "get": { "tags": [ "Marketing Campaigns" ], "operationId": "marketing_campaigns_getCampaignTimeseries", "parameters": [ { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "description": "Number of days of history to return (1-90, default 7)", "default": 7 }, "description": "Number of days of history to return (1-90, default 7)" }, { "name": "campaignId", "in": "query", "required": false, "schema": { "type": "string", "description": "Restrict the series to a single campaign" }, "description": "Restrict the series to a single campaign" } ], "responses": { "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Per-hour sent/opened/clicked/bounced counts for the last N days", "content": { "application/json": { "schema": { "type": "object", "properties": { "dates": { "type": "array", "items": { "type": "string" }, "description": "Hourly ISO timestamp bucket labels" }, "series": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "label": { "type": "string" }, "data": { "type": "array", "items": { "type": "integer" } } }, "description": "A single series in the timeseries response" } } }, "description": "Per-hour sent/opened/clicked/bounced counts for the last N days" } } } } }, "summary": "Return per-hour sent, opened, and clicked counts for the last N days", "description": "(default 7, max 90). Optionally restrict to a single campaign with\n?campaignId=\u2026" } }, "/api/v0/marketing-campaigns/{campaignId}/chat": { "post": { "tags": [ "Marketing Campaigns" ], "operationId": "marketing_campaigns_campaignEmailBuilderChat", "parameters": [ { "name": "campaignId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Missing required fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Campaign not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Chat with the visual builder AI agent about a campaign's email design.", "description": "Streams typed server-sent events (text / tool_call / tool_result /\nfiles_changed / done / error). The agent edits the campaign's bodyDocument,\nstarting from the bodyDocument sent in the request; each edit is saved and\nversioned like a visual builder save, and emits files_changed.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "message": { "type": "string", "description": "User message" }, "threadId": { "type": "string", "description": "Thread to continue (defaults to the active thread)" }, "clientMessageId": { "type": "string", "description": "Client-generated id for the user message" }, "attachments": { "type": "array", "items": { "type": "object" }, "description": "Image attachments (design references)" }, "bodyDocument": { "type": "string", "description": "The document currently open in the visual builder, including unsaved edits. The agent starts from it; defaults to the saved bodyDocument" }, "variables": { "type": "array", "items": { "type": "string" }, "description": "Smart list field tokens (without braces) the email may use" } }, "required": [ "companyId" ], "description": "Chat message for the visual email builder agent" } } }, "description": "Chat message" } } }, "/api/v0/marketing-campaigns/{campaignId}/threads": { "get": { "tags": [ "Marketing Campaigns" ], "operationId": "marketing_campaigns_listCampaignEmailBuilderThreads", "parameters": [ { "name": "campaignId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Missing companyId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Campaign not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "List a campaign's visual builder chat threads ({threads, activeThreadId})." }, "post": { "tags": [ "Marketing Campaigns" ], "operationId": "marketing_campaigns_createCampaignEmailBuilderThread", "parameters": [ { "name": "campaignId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Missing companyId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Campaign not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Create a new visual builder chat thread on a campaign (becomes the active thread).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "title": { "type": "string", "description": "Thread title" } }, "required": [ "companyId" ], "description": "Request body for creating a chat thread" } } }, "description": "Thread to create" } } }, "/api/v0/marketing-campaigns/{campaignId}/threads/{threadId}": { "get": { "tags": [ "Marketing Campaigns" ], "operationId": "marketing_campaigns_getCampaignEmailBuilderThread", "parameters": [ { "name": "campaignId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Missing companyId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Thread not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Get one campaign visual builder chat thread's messages." }, "patch": { "tags": [ "Marketing Campaigns" ], "operationId": "marketing_campaigns_updateCampaignEmailBuilderThread", "parameters": [ { "name": "campaignId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Missing required fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Thread not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Rename a campaign visual builder chat thread (`title`) or make it active (`active: true`).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "title": { "type": "string", "description": "New thread title" }, "active": { "type": "boolean", "description": "Set true to make this the active thread" } }, "required": [ "companyId" ], "description": "Rename or activate a chat thread" } } }, "description": "Rename or activate a thread" } }, "delete": { "tags": [ "Marketing Campaigns" ], "operationId": "marketing_campaigns_deleteCampaignEmailBuilderThread", "parameters": [ { "name": "campaignId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Missing companyId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Thread not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Delete a campaign visual builder chat thread; returns the refreshed thread view." } }, "/api/v0/marketing-campaigns/{campaignId}/threads/{threadId}/stop": { "post": { "tags": [ "Marketing Campaigns" ], "operationId": "marketing_campaigns_stopCampaignEmailBuilderThreadRun", "parameters": [ { "name": "campaignId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Missing companyId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Thread not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Ask the thread's in-flight agent run to wrap up (the partial reply is already saved)." } }, "/api/v0/marketing-campaigns/{campaignId}/upload": { "post": { "tags": [ "Marketing Campaigns" ], "operationId": "marketing_campaigns_campaignEmailBuilderUpload", "parameters": [ { "name": "campaignId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid file", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Campaign not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Upload an image to attach as a design reference in the campaign visual builder chat." } }, "/api/v0/marketing-campaign-templates/{templateId}/chat": { "post": { "tags": [ "Marketing Campaigns" ], "operationId": "marketing_campaigns_templateEmailBuilderChat", "parameters": [ { "name": "templateId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Missing required fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Template not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Chat with the visual builder AI agent about a template's email design.", "description": "Streams typed server-sent events (text / tool_call / tool_result /\nfiles_changed / done / error). The agent edits the template's bodyDocument,\nstarting from the bodyDocument sent in the request; each edit is saved and\nversioned like a visual builder save, and emits files_changed.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "message": { "type": "string", "description": "User message" }, "threadId": { "type": "string", "description": "Thread to continue (defaults to the active thread)" }, "clientMessageId": { "type": "string", "description": "Client-generated id for the user message" }, "attachments": { "type": "array", "items": { "type": "object" }, "description": "Image attachments (design references)" }, "bodyDocument": { "type": "string", "description": "The document currently open in the visual builder, including unsaved edits. The agent starts from it; defaults to the saved bodyDocument" }, "variables": { "type": "array", "items": { "type": "string" }, "description": "Smart list field tokens (without braces) the email may use" } }, "required": [ "companyId" ], "description": "Chat message for the visual email builder agent" } } }, "description": "Chat message" } } }, "/api/v0/marketing-campaign-templates/{templateId}/threads": { "get": { "tags": [ "Marketing Campaigns" ], "operationId": "marketing_campaigns_listTemplateEmailBuilderThreads", "parameters": [ { "name": "templateId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Missing companyId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Template not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "List a template's visual builder chat threads ({threads, activeThreadId})." }, "post": { "tags": [ "Marketing Campaigns" ], "operationId": "marketing_campaigns_createTemplateEmailBuilderThread", "parameters": [ { "name": "templateId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Missing companyId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Template not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Create a new visual builder chat thread on a template (becomes the active thread).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "title": { "type": "string", "description": "Thread title" } }, "required": [ "companyId" ], "description": "Request body for creating a chat thread" } } }, "description": "Thread to create" } } }, "/api/v0/marketing-campaign-templates/{templateId}/threads/{threadId}": { "get": { "tags": [ "Marketing Campaigns" ], "operationId": "marketing_campaigns_getTemplateEmailBuilderThread", "parameters": [ { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "templateId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Missing companyId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Thread not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Get one template visual builder chat thread's messages." }, "patch": { "tags": [ "Marketing Campaigns" ], "operationId": "marketing_campaigns_updateTemplateEmailBuilderThread", "parameters": [ { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "templateId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Missing required fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Thread not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Rename a template visual builder chat thread (`title`) or make it active (`active: true`).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID" }, "title": { "type": "string", "description": "New thread title" }, "active": { "type": "boolean", "description": "Set true to make this the active thread" } }, "required": [ "companyId" ], "description": "Rename or activate a chat thread" } } }, "description": "Rename or activate a thread" } }, "delete": { "tags": [ "Marketing Campaigns" ], "operationId": "marketing_campaigns_deleteTemplateEmailBuilderThread", "parameters": [ { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "templateId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Missing companyId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Thread not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Delete a template visual builder chat thread; returns the refreshed thread view." } }, "/api/v0/marketing-campaign-templates/{templateId}/threads/{threadId}/stop": { "post": { "tags": [ "Marketing Campaigns" ], "operationId": "marketing_campaigns_stopTemplateEmailBuilderThreadRun", "parameters": [ { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "templateId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Missing companyId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Thread not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Ask the thread's in-flight agent run to wrap up (the partial reply is already saved)." } }, "/api/v0/marketing-campaign-templates/{templateId}/upload": { "post": { "tags": [ "Marketing Campaigns" ], "operationId": "marketing_campaigns_templateEmailBuilderUpload", "parameters": [ { "name": "templateId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid file", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Template not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Upload an image to attach as a design reference in the template visual builder chat." } }, "/api/v0/marketing-campaign-templates": { "get": { "tags": [ "Marketing Campaigns" ], "operationId": "marketing_campaigns_listTemplates", "parameters": [ { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "description": "Case-insensitive substring match against template name and description" }, "description": "Case-insensitive substring match against template name and description" } ], "responses": { "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Marketing campaign templates in the company (optionally filtered by ?search=), most recently updated first", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Template ID" }, "companyId": { "type": "string", "description": "Company this template belongs to" }, "uid": { "type": "string", "description": "User ID that created the template" }, "name": { "type": "string", "description": "Template name" }, "description": { "type": "string", "description": "Optional note describing when to use this template" }, "subject": { "type": "string", "description": "Default email subject line" }, "replyTo": { "type": "string", "description": "Default Reply-To email address" }, "bodyHtml": { "type": "string", "description": "Email HTML rendered by the server from bodyDocument (read-only)" }, "bodyDocument": { "type": "string", "description": "Visual-builder JSON document for the email body (source of truth)" }, "senderProfileId": { "type": "string", "description": "Default sender profile ID" }, "listId": { "type": "string", "description": "Default smart list ID" }, "fieldMappings": { "type": "object", "description": "Field mapping for resolving recipient email from a list row" }, "scheduleSettings": { "type": "string", "description": "Optional sending-window settings" }, "created_date": { "type": "string", "description": "ISO timestamp when the template was created" }, "updated_date": { "type": "string", "description": "ISO timestamp when the template was last updated" }, "smartList": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "description": "Summary of the default smart list" }, "senderProfile": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "integrationId": { "type": "string" } }, "description": "Summary of the default sender profile" } }, "description": "A reusable marketing campaign template" } } }, "description": "List of marketing campaign templates, most recently updated first" } } } } }, "summary": "List marketing campaign templates.", "description": "Templates are reusable email designs (subject, visual-builder body\ndocument with its server-rendered HTML, default sender profile, smart\nlist, and field mappings). To start a campaign from one, pass its id as\ntemplateId when creating a campaign via POST /api/v0/marketing-campaigns." }, "post": { "tags": [ "Marketing Campaigns" ], "operationId": "marketing_campaigns_createTemplate", "parameters": [], "responses": { "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "201": { "description": "The created template", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Template ID" }, "companyId": { "type": "string", "description": "Company this template belongs to" }, "uid": { "type": "string", "description": "User ID that created the template" }, "name": { "type": "string", "description": "Template name" }, "description": { "type": "string", "description": "Optional note describing when to use this template" }, "subject": { "type": "string", "description": "Default email subject line" }, "replyTo": { "type": "string", "description": "Default Reply-To email address" }, "bodyHtml": { "type": "string", "description": "Email HTML rendered by the server from bodyDocument (read-only)" }, "bodyDocument": { "type": "string", "description": "Visual-builder JSON document for the email body (source of truth)" }, "senderProfileId": { "type": "string", "description": "Default sender profile ID" }, "listId": { "type": "string", "description": "Default smart list ID" }, "fieldMappings": { "type": "object", "description": "Field mapping for resolving recipient email from a list row" }, "scheduleSettings": { "type": "string", "description": "Optional sending-window settings" }, "created_date": { "type": "string", "description": "ISO timestamp when the template was created" }, "updated_date": { "type": "string", "description": "ISO timestamp when the template was last updated" }, "smartList": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "description": "Summary of the default smart list" }, "senderProfile": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "integrationId": { "type": "string" } }, "description": "Summary of the default sender profile" } }, "description": "A reusable marketing campaign template" } } } } }, "summary": "Create a marketing campaign template.", "description": "Author the email body as bodyDocument (the visual-builder JSON); the\nserver renders bodyHtml from it. Sending bodyHtml is rejected with 400.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Template name" }, "description": { "type": "string", "description": "Optional note describing when to use this template" }, "subject": { "type": "string", "description": "Default email subject line applied to campaigns created from this template" }, "replyTo": { "type": "string", "description": "Optional default Reply-To email address. Must be a valid email if provided." }, "bodyDocument": { "type": "string", "description": "Visual-builder JSON document for the email body. This is the single source of truth: the server renders bodyHtml from it (any bodyHtml you send is ignored). Envelope: {\"subject\": string, \"subTitle\": string, \"content\": <page node>}. Every node is {\"type\": string, \"attributes\": {MJML attributes as string values, e.g. \"padding\": \"10px 25px 10px 25px\", \"background-color\": \"#ffffff\", \"color\": \"#333333\", \"font-size\": \"16px\", \"align\": \"center\", \"width\": \"600px\", \"href\", \"src\"}, \"data\": {\"value\": {...}}, \"children\": [...]}; attribute values must be strings (numbers are dropped). Tree: page -> (wrapper | section) -> section -> column -> content blocks. Content block types: \"text\" (data.value.content = inline HTML string), \"image\" (attributes.src, alt, href, width), \"button\" (data.value.content = label, attributes.href), \"divider\", \"spacer\" (attributes.height), \"social\" (data.value.elements = [{src, href, content, target}]), \"navbar\" (data.value.links = [{href, content}]), \"raw\" (data.value.content = raw MJML/HTML), plus \"hero\", \"group\", \"accordion\", \"carousel\" and \"table\". Each also has an \"advanced_<type>\" variant (e.g. \"advanced_text\"), which is what the builder palette inserts; advanced content blocks placed directly under the page or a wrapper are auto-wrapped in a section/column. For a visual poll, insert one marketing_poll block: {\"type\": \"marketing_poll\", \"data\": {\"value\": {\"question\": \"Your question?\", \"options\": [\"Answer one\", \"Answer two\"]}}, \"attributes\": {}, \"children\": []}. Its attributes support padding, font-family, font-size, font-weight, color, background-color, button-background-color, button-text-color, button-font-size, and border-radius. The server derives the campaign poll from this block; do not maintain a separate poll definition. Page node: {\"type\": \"page\", \"attributes\": {\"background-color\": \"#efeeea\", \"width\": \"600px\"}, \"data\": {\"value\": {\"breakpoint\": \"480px\", \"font-family\": string, \"font-size\": \"14px\", \"line-height\": \"1.7\", \"font-weight\": \"400\", \"text-color\": \"#000000\", \"content-background-color\": string (optional), \"headStyles\": [{\"content\": css, \"inline\": bool}], \"fonts\": [{\"name\", \"href\"}], \"headAttributes\": \"\", \"responsive\": true}}}. Always set \"responsive\": true \u2014 a missing flag renders a fixed-width layout. Merge tokens pass through rendering untouched: {{content}} inside a text block marks where content-engine output is inserted when content is published as a campaign from this template; Smart-list merge tokens use the matching header normalized to camelCase: for example, `First Name` becomes {{firstName}} and `Company Name` becomes {{companyName}}. Tokens are replaced per recipient from the smart-list row; {{unsubscribe}} becomes the per-recipient unsubscribe link." }, "senderProfileId": { "type": "string", "description": "Default sender profile ID for campaigns created from this template" }, "listId": { "type": "string", "description": "Default smart list ID whose rows become recipients" }, "fieldMappings": { "type": "object", "description": "Field mapping for resolving recipient email from a list row, e.g. {\"email\": [\"Email\", \"Work Email\"]}" }, "scheduleSettings": { "type": "string", "description": "Optional sending-window settings copied onto campaigns created from this template" }, "companyId": { "type": "string", "description": "Company ID (falls back to the authenticated user's current company)" } }, "required": [ "name" ], "description": "Request body for creating a marketing campaign template. Only name is required; everything else can be filled in later via PATCH. The email body is authored as bodyDocument (visual-builder JSON); bodyHtml is rendered from it on the server and cannot be supplied directly." } } }, "description": "Template fields. Only name is required up front." } } }, "/api/v0/marketing-campaign-templates/{templateId}": { "get": { "tags": [ "Marketing Campaigns" ], "operationId": "marketing_campaigns_getTemplate", "parameters": [ { "name": "templateId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Template not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "The requested template", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Template ID" }, "companyId": { "type": "string", "description": "Company this template belongs to" }, "uid": { "type": "string", "description": "User ID that created the template" }, "name": { "type": "string", "description": "Template name" }, "description": { "type": "string", "description": "Optional note describing when to use this template" }, "subject": { "type": "string", "description": "Default email subject line" }, "replyTo": { "type": "string", "description": "Default Reply-To email address" }, "bodyHtml": { "type": "string", "description": "Email HTML rendered by the server from bodyDocument (read-only)" }, "bodyDocument": { "type": "string", "description": "Visual-builder JSON document for the email body (source of truth)" }, "senderProfileId": { "type": "string", "description": "Default sender profile ID" }, "listId": { "type": "string", "description": "Default smart list ID" }, "fieldMappings": { "type": "object", "description": "Field mapping for resolving recipient email from a list row" }, "scheduleSettings": { "type": "string", "description": "Optional sending-window settings" }, "created_date": { "type": "string", "description": "ISO timestamp when the template was created" }, "updated_date": { "type": "string", "description": "ISO timestamp when the template was last updated" }, "smartList": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "description": "Summary of the default smart list" }, "senderProfile": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "integrationId": { "type": "string" } }, "description": "Summary of the default sender profile" } }, "description": "A reusable marketing campaign template" } } } } }, "summary": "Get a single marketing campaign template, including its full HTML body." }, "patch": { "tags": [ "Marketing Campaigns" ], "operationId": "marketing_campaigns_updateTemplate", "parameters": [ { "name": "templateId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Template not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "The updated template", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Template ID" }, "companyId": { "type": "string", "description": "Company this template belongs to" }, "uid": { "type": "string", "description": "User ID that created the template" }, "name": { "type": "string", "description": "Template name" }, "description": { "type": "string", "description": "Optional note describing when to use this template" }, "subject": { "type": "string", "description": "Default email subject line" }, "replyTo": { "type": "string", "description": "Default Reply-To email address" }, "bodyHtml": { "type": "string", "description": "Email HTML rendered by the server from bodyDocument (read-only)" }, "bodyDocument": { "type": "string", "description": "Visual-builder JSON document for the email body (source of truth)" }, "senderProfileId": { "type": "string", "description": "Default sender profile ID" }, "listId": { "type": "string", "description": "Default smart list ID" }, "fieldMappings": { "type": "object", "description": "Field mapping for resolving recipient email from a list row" }, "scheduleSettings": { "type": "string", "description": "Optional sending-window settings" }, "created_date": { "type": "string", "description": "ISO timestamp when the template was created" }, "updated_date": { "type": "string", "description": "ISO timestamp when the template was last updated" }, "smartList": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "description": "Summary of the default smart list" }, "senderProfile": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "integrationId": { "type": "string" } }, "description": "Summary of the default sender profile" } }, "description": "A reusable marketing campaign template" } } } } }, "summary": "Update a marketing campaign template.", "description": "Changing bodyDocument re-renders bodyHtml on the server and saves a new\nversion in the template's history. An empty bodyDocument is ignored rather\nthan clearing the design. bodyHtml is not accepted as input (400).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Template name" }, "description": { "type": "string", "description": "Optional note describing when to use this template" }, "subject": { "type": "string", "description": "Default email subject line" }, "replyTo": { "type": "string", "description": "Default Reply-To email address. Must be a valid email if provided." }, "bodyDocument": { "type": "string", "description": "Visual-builder JSON document for the email body. This is the single source of truth: the server renders bodyHtml from it (any bodyHtml you send is ignored). Envelope: {\"subject\": string, \"subTitle\": string, \"content\": <page node>}. Every node is {\"type\": string, \"attributes\": {MJML attributes as string values, e.g. \"padding\": \"10px 25px 10px 25px\", \"background-color\": \"#ffffff\", \"color\": \"#333333\", \"font-size\": \"16px\", \"align\": \"center\", \"width\": \"600px\", \"href\", \"src\"}, \"data\": {\"value\": {...}}, \"children\": [...]}; attribute values must be strings (numbers are dropped). Tree: page -> (wrapper | section) -> section -> column -> content blocks. Content block types: \"text\" (data.value.content = inline HTML string), \"image\" (attributes.src, alt, href, width), \"button\" (data.value.content = label, attributes.href), \"divider\", \"spacer\" (attributes.height), \"social\" (data.value.elements = [{src, href, content, target}]), \"navbar\" (data.value.links = [{href, content}]), \"raw\" (data.value.content = raw MJML/HTML), plus \"hero\", \"group\", \"accordion\", \"carousel\" and \"table\". Each also has an \"advanced_<type>\" variant (e.g. \"advanced_text\"), which is what the builder palette inserts; advanced content blocks placed directly under the page or a wrapper are auto-wrapped in a section/column. For a visual poll, insert one marketing_poll block: {\"type\": \"marketing_poll\", \"data\": {\"value\": {\"question\": \"Your question?\", \"options\": [\"Answer one\", \"Answer two\"]}}, \"attributes\": {}, \"children\": []}. Its attributes support padding, font-family, font-size, font-weight, color, background-color, button-background-color, button-text-color, button-font-size, and border-radius. The server derives the campaign poll from this block; do not maintain a separate poll definition. Page node: {\"type\": \"page\", \"attributes\": {\"background-color\": \"#efeeea\", \"width\": \"600px\"}, \"data\": {\"value\": {\"breakpoint\": \"480px\", \"font-family\": string, \"font-size\": \"14px\", \"line-height\": \"1.7\", \"font-weight\": \"400\", \"text-color\": \"#000000\", \"content-background-color\": string (optional), \"headStyles\": [{\"content\": css, \"inline\": bool}], \"fonts\": [{\"name\", \"href\"}], \"headAttributes\": \"\", \"responsive\": true}}}. Always set \"responsive\": true \u2014 a missing flag renders a fixed-width layout. Merge tokens pass through rendering untouched: {{content}} inside a text block marks where content-engine output is inserted when content is published as a campaign from this template; Smart-list merge tokens use the matching header normalized to camelCase: for example, `First Name` becomes {{firstName}} and `Company Name` becomes {{companyName}}. Tokens are replaced per recipient from the smart-list row; {{unsubscribe}} becomes the per-recipient unsubscribe link." }, "senderProfileId": { "type": "string", "description": "Default sender profile ID" }, "listId": { "type": "string", "description": "Default smart list ID" }, "fieldMappings": { "type": "object", "description": "Field mapping for resolving recipient email from a list row" }, "scheduleSettings": { "type": "string", "description": "Optional sending-window settings" } }, "description": "Request body for updating a template (only include fields to change). An empty bodyDocument is ignored so saved designs are never wiped. bodyHtml is not accepted: send bodyDocument and the server re-renders the HTML." } } }, "description": "Fields to update (include only fields you want to change)" } }, "delete": { "tags": [ "Marketing Campaigns" ], "operationId": "marketing_campaigns_deleteTemplate", "parameters": [ { "name": "templateId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Template not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Deletion confirmation", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "description": "Result of deleting a template" } } } } }, "summary": "Delete a marketing campaign template. Campaigns already created from it are unaffected." } }, "/api/v0/marketing-campaign-templates/{templateId}/versions": { "get": { "tags": [ "Marketing Campaigns" ], "operationId": "marketing_campaigns_listTemplateVersions", "parameters": [ { "name": "templateId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Template not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "The template's saved content versions, newest first", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Version ID" }, "templateId": { "type": "string", "description": "The template this version belongs to" }, "data": { "type": "string", "description": "Full snapshot of the template at this point in time (includes bodyDocument)" }, "bodyHtml": { "type": "string", "description": "Rendered email HTML for this version" }, "uid": { "type": "string", "description": "User who saved this version" }, "created_date": { "type": "string", "format": "date-time", "description": "When this version was captured" } }, "description": "A saved version of a template's content" } } }, "description": "A template's saved content versions, newest first" } } } } }, "summary": "List a template's saved content versions.", "description": "A version is captured whenever the visual document (and therefore the\nrendered HTML body) changes." } }, "/api/v0/marketing-campaign-templates/{templateId}/versions/{versionId}/restore": { "post": { "tags": [ "Marketing Campaigns" ], "operationId": "marketing_campaigns_restoreTemplateVersion", "parameters": [ { "name": "versionId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "templateId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Feature not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Template or version not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "The template after restoring the selected version", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Template ID" }, "companyId": { "type": "string", "description": "Company this template belongs to" }, "uid": { "type": "string", "description": "User ID that created the template" }, "name": { "type": "string", "description": "Template name" }, "description": { "type": "string", "description": "Optional note describing when to use this template" }, "subject": { "type": "string", "description": "Default email subject line" }, "replyTo": { "type": "string", "description": "Default Reply-To email address" }, "bodyHtml": { "type": "string", "description": "Email HTML rendered by the server from bodyDocument (read-only)" }, "bodyDocument": { "type": "string", "description": "Visual-builder JSON document for the email body (source of truth)" }, "senderProfileId": { "type": "string", "description": "Default sender profile ID" }, "listId": { "type": "string", "description": "Default smart list ID" }, "fieldMappings": { "type": "object", "description": "Field mapping for resolving recipient email from a list row" }, "scheduleSettings": { "type": "string", "description": "Optional sending-window settings" }, "created_date": { "type": "string", "description": "ISO timestamp when the template was created" }, "updated_date": { "type": "string", "description": "ISO timestamp when the template was last updated" }, "smartList": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "description": "Summary of the default smart list" }, "senderProfile": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "integrationId": { "type": "string" } }, "description": "Summary of the default sender profile" } }, "description": "A reusable marketing campaign template" } } } } }, "summary": "Restore a previous version of a template's content.", "description": "The restore is itself saved as a new version, so it can always be undone." } }, "/api/v0/apps/{appId}/publish": { "post": { "tags": [ "Websites" ], "operationId": "builder_publishApp", "parameters": [ { "name": "appId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "companyId missing, not publishable, or a publish is already running", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Website not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "{ok: true} \u2014 the publish is queued", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } } }, "summary": "Publish a website or external app", "description": "Builds the live (main) version and deploys it to its public URL and custom\ndomain. Review branches are NOT included. Publishing runs in the\nbackground \u2014 poll publish-status until publishStatus is idle or failed.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID that owns the website" } }, "required": [ "companyId" ], "description": "Publish the live (main) version of a website" } } } } } }, "/api/v0/apps/{appId}/publish-status": { "get": { "tags": [ "Websites" ], "operationId": "builder_getPublishStatus", "parameters": [ { "name": "appId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID." }, "description": "Company ID." } ], "responses": { "400": { "description": "companyId missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Website not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Publish state", "content": { "application/json": { "schema": { "type": "object", "properties": { "publishStatus": { "type": "string", "description": "idle (no publish running; the last one finished), queued, building, or failed. Poll until it is idle or failed." }, "publishedBuildId": { "type": "string", "description": "Build currently served, or null if never published" }, "publishedAt": { "type": "string", "description": "When the served build went live (ISO 8601)" }, "lastPublishError": { "type": "string", "description": "Why the last publish failed, if it did" }, "publishedUrl": { "type": "string", "description": "The site's public URL (its custom domain when one is attached)" } } } } } } }, "summary": "Get a website's publish status", "description": "Reports whether a publish is queued, building, finished (idle) or failed,\nwhich build is live, when it went live, and the public URL." } }, "/api/v0/websites": { "post": { "tags": [ "Websites" ], "operationId": "site_builder_createWebsite", "parameters": [], "responses": { "400": { "description": "companyId missing, or brand kit / design style not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No company access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "201": { "description": "The new website", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "description": "The new website. Its id is the websiteId for every other Websites action." } } } } }, "summary": "Create a new website from scratch", "description": "Creates an empty starter website and returns its id. Choose its look\nhere: a brandKitId, or a designStyleId from the design style library\n(list design styles, medium=website) and/or a colorPalette.\n\nTo have the built-in website builder agent design and build it: list the\nsite's threads, move the first thread onto a review branch (update\nthread), run the agent in it with a description of the site, and read\nthe thread until the agent finishes. Only that first thread designs in\nthe chosen style. Or write the pages, layouts and assets onto a review\nbranch yourself (write file, upload asset).\n\nEither way, check the branch with validate and a preview link, approve\nit into main (merge), then publish to put it live.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID that owns the website" }, "name": { "type": "string", "description": "Website name (default \"Untitled website\")" }, "description": { "type": "string", "description": "Optional short description" }, "seedPrompt": { "type": "string", "description": "What the site is for. Used only to name the site when name is omitted; it does not build any pages." }, "brandKitId": { "type": "string", "description": "Brand kit to design with (an id from brand_kit_listBrandKits). Wins over designStyleId and colorPalette. Omit all three to use the company's default kit." }, "designStyleId": { "type": "string", "description": "Design style the site is designed in, when no brand kit is given. Get ids from design_styles_listDesignStyles with medium=website and pick the style whose name, category and description fit the site." }, "colorPalette": { "type": "object", "description": "Colors to use when no brand kit is given: {primary, secondary, accent, background, surface, text} as hex values. Combines with designStyleId." }, "useCompanyContext": { "type": "boolean", "description": "Let the site builder use the company profile as context" } }, "required": [ "companyId" ], "description": "Create a website" } } } } }, "get": { "tags": [ "Websites" ], "operationId": "site_builder_apiListWebsites", "parameters": [ { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID that owns the website" }, "description": "Company ID that owns the website" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "description": "Optional name filter" }, "description": "Optional name filter" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "description": "Max websites to return, 1-100 (default 24)" }, "description": "Max websites to return, 1-100 (default 24)" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "description": "Pagination offset (default 0)" }, "description": "Pagination offset (default 0)" } ], "responses": { "400": { "description": "companyId missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No company access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Websites owned by the company, with branch counts", "content": { "application/json": { "schema": { "type": "object", "properties": { "websites": { "type": "array", "items": { "type": "string" }, "description": "Websites with id, name, branchCount" }, "total": { "type": "integer" } } } } } } }, "summary": "List the company's websites", "description": "Start here: returns each website's id and name so you can audit or optimize\none. branchCount is how many review branches already have unmerged changes." } }, "/api/v0/websites/{websiteId}/preview-session": { "post": { "tags": [ "Websites" ], "operationId": "site_builder_createWebsitePreviewSession", "parameters": [ { "name": "websiteId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "invalid branch name", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Website not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "A link that opens the preview", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "Link that opens the preview in a browser; valid for 4 hours" }, "baseUrl": { "type": "string", "description": "The same preview as a path on the API host" } } } } } } }, "summary": "Get a preview link for a website or one of its review branches", "description": "Returns `url`, a link anyone can open in a browser for the next 4 hours to\nbrowse the site exactly as it will look \u2014 pass `branch` to preview a\nreview branch's changes before approving it, or omit it for the live\n(main) version.\n\nThe preview is a real navigable origin, not an HTML blob: the editor's\niframe cannot send a bearer header, so access is carried by a short-lived,\nwebsite-scoped token in the path. Everything under that prefix \u2014 pages\nand assets \u2014 resolves the way it will on the published site, so relative\nassets and links just work.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID that owns the website" }, "branch": { "type": "string", "description": "Review branch to preview. Omit (or \"main\") to preview the live version." } }, "required": [ "companyId" ], "description": "Preview a website or review branch" } } } } } }, "/api/v0/websites/{websiteId}/threads": { "get": { "tags": [ "Websites" ], "operationId": "site_builder_listWebsiteThreads", "parameters": [ { "name": "websiteId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID that owns the website" }, "description": "Company ID that owns the website" } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Website not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "The website's builder threads", "content": { "application/json": { "schema": { "type": "object", "properties": { "threads": { "type": "array", "items": { "type": "string" }, "description": "Threads, most recently updated first: {id, title, branch, createdAt, updatedAt, messageCount, totalCreditUsage}" }, "activeThreadId": { "type": "string", "description": "The thread open in the editor" } } } } } } }, "summary": "List a website's builder threads", "description": "Each thread is a conversation with the website builder agent and carries\nthe branch its edits go to. A new website has one thread, \"Main\", on\nmain: that first thread is the one that designs in the website's design\nstyle or palette, so move it onto a review branch (update thread) and run\nthe agent in it to build a new site." }, "post": { "tags": [ "Websites" ], "operationId": "site_builder_createWebsiteThread", "parameters": [ { "name": "websiteId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "invalid branch name", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Website not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "branch already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "The new thread", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "branch": { "type": "string" } }, "description": "The thread: {id, title, branch, createdAt, updatedAt, messageCount, totalCreditUsage}" } } } } }, "summary": "Start a new website builder thread", "description": "Starts a fresh conversation with the website builder agent, for a new\npiece of work on an existing site. Pass branch so the agent's edits land\non a review branch. To build a brand-new website, use its first thread\ninstead (list threads) \u2014 only that one designs in the chosen style.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID that owns the website" }, "title": { "type": "string", "description": "Optional title; the first message names the thread when omitted" }, "branch": { "type": "string", "description": "Review branch the thread's agent writes to, e.g. \"homepage-refresh\". Required before the agent can be run over the API." } }, "required": [ "companyId" ], "description": "Start a website builder thread" } } } } } }, "/api/v0/websites/{websiteId}/threads/{threadId}": { "get": { "tags": [ "Websites" ], "operationId": "site_builder_getWebsiteThreadMessages", "parameters": [ { "name": "websiteId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID that owns the website" }, "description": "Company ID that owns the website" } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Website or thread not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "The thread's messages", "content": { "application/json": { "schema": { "type": "object", "properties": { "messages": { "type": "array", "items": { "type": "string" }, "description": "Messages oldest first: {id, role, content, toolCalls, loading}. The agent is still working while the last assistant message has loading true." } } } } } } }, "summary": "Read a website builder thread", "description": "Returns the conversation with the agent, including each tool call it made.\nAfter running the agent, read this about every 30 seconds: the run is\nfinished when the last assistant message has loading false, and its\ncontent is the agent's summary of what it built." }, "patch": { "tags": [ "Websites" ], "operationId": "site_builder_patchWebsiteThread", "parameters": [ { "name": "websiteId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "invalid branch name", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Website or thread not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "branch already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "The updated thread", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "branch": { "type": "string" } }, "description": "The thread: {id, title, branch, createdAt, updatedAt, messageCount, totalCreditUsage}" } } } } }, "summary": "Move a website builder thread onto a review branch, or rename it", "description": "Pass branch to make the thread's agent write to that review branch\ninstead of main. Required before running the agent over the API.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID that owns the website" }, "branch": { "type": "string", "description": "Review branch for the thread's agent to write to. Use this on a new website's first thread before running the agent." }, "allowExisting": { "type": "boolean", "description": "Join a branch that already exists. Without it, a name already in use is refused (409)." }, "title": { "type": "string", "description": "New thread title (when branch is not given)" } }, "required": [ "companyId" ], "description": "Move a thread onto a review branch, or rename it" } } } } } }, "/api/v0/websites/{websiteId}/threads/{threadId}/stop": { "post": { "tags": [ "Websites" ], "operationId": "site_builder_stopWebsiteThreadRun", "parameters": [ { "name": "websiteId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Website or thread not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Whether a running turn was asked to stop", "content": { "application/json": { "schema": { "type": "object", "properties": { "stopped": { "type": "boolean", "description": "True when a running turn was asked to wrap up" } } } } } } }, "summary": "Stop the website builder agent", "description": "Asks the thread's running agent turn to wrap up. Its work so far is kept.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID that owns the website" } }, "required": [ "companyId" ], "description": "Company scope" } } } } } }, "/api/v0/websites/{websiteId}/chat": { "post": { "tags": [ "Websites" ], "operationId": "site_builder_websiteChat", "parameters": [ { "name": "websiteId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "message or threadId missing, or the thread is on main", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Website not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "202": { "description": "The agent is running", "content": { "application/json": { "schema": { "type": "object", "properties": { "threadId": { "type": "string" }, "messageId": { "type": "string", "description": "The agent's reply message; read the thread until it is no longer loading" }, "status": { "type": "string", "description": "\"running\"" } } } } } } }, "summary": "Run the website builder agent", "description": "Sends a message to the built-in website builder agent, which designs and\nwrites the site's pages, layouts and assets itself \u2014 the same agent as\nthe editor's chat. The thread must be on a review branch; the agent\nwrites there, never to main. Returns at once while the agent works (a\nfull site build takes several minutes): read the thread until its last\nmessage is no longer loading, check it with a preview link, then approve\nthe branch (merge) and publish. Send a follow-up message on the same\nthread to make changes.\n\nThe editor gets the turn as a server-sent event stream; API callers get\nthe 202 and read the thread instead.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID that owns the website" }, "threadId": { "type": "string", "description": "Thread to run in. It must be on a review branch (see the thread's branch)." }, "message": { "type": "string", "description": "What to build or change, as you would ask a web designer: the business, audience, pages, sections, copy and tone." } }, "required": [ "companyId", "threadId", "message" ], "description": "Run the website builder agent" } } } } } }, "/api/v0/websites/{websiteId}/branches/{branch}/merge": { "post": { "tags": [ "Websites" ], "operationId": "site_builder_mergeWebsiteBranch", "parameters": [ { "name": "websiteId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "branch", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "invalid branch, or the site would not render with the branch merged", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Website not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "The branch was merged into main", "content": { "application/json": { "schema": { "type": "object", "properties": { "merged": { "type": "boolean" }, "fileCount": { "type": "integer", "description": "How many files the branch changed on main" } } } } } } }, "summary": "Approve a review branch into the live (main) version of a website", "description": "Copies the branch's changed files onto main (branch wins) and deletes the\nbranch. This does not publish: call publish afterwards to deploy main to\nthe public site. Only approve a branch the owner has asked you to approve.\n\nThe merged tree is validated first \u2014 a branch that would leave the site\nunrenderable is refused with the problems, since it could never publish.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID that owns the website" } }, "required": [ "companyId" ], "description": "Approve a review branch into main" } } } } } }, "/api/v0/websites/{websiteId}/pages": { "get": { "tags": [ "Websites" ], "operationId": "site_builder_apiListWebsitePages", "parameters": [ { "name": "websiteId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID that owns the website" }, "description": "Company ID that owns the website" }, { "name": "branch", "in": "query", "required": false, "schema": { "type": "string", "description": "Review branch to read from or write to. Omit (or \"main\") to read the live site. To propose fixes, write files to a NEW branch name (e.g. \"seo-optimizer-2026-09-03\") \u2014 the branch is created on first write and is reviewed and approved by the owner. Writing to \"main\" is refused." }, "description": "Review branch to read from or write to. Omit (or \"main\") to read the live site. To propose fixes, write files to a NEW branch name (e.g. \"seo-optimizer-2026-09-03\") \u2014 the branch is created on first write and is reviewed and approved by the owner. Writing to \"main\" is refused." } ], "responses": { "400": { "description": "companyId or branch invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No company access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Website not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Pages (route -> file path)", "content": { "application/json": { "schema": { "type": "object", "properties": { "pages": { "type": "array", "items": { "type": "string" }, "description": "Pages with route -> file path" } } } } } } }, "summary": "List a website's pages", "description": "Each entry maps a public route (e.g. /about) to the file that renders it,\nso you know which files to read and where fixes belong." } }, "/api/v0/websites/{websiteId}/file": { "get": { "tags": [ "Websites" ], "operationId": "site_builder_apiReadWebsiteFile", "parameters": [ { "name": "websiteId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID that owns the website" }, "description": "Company ID that owns the website" }, { "name": "path", "in": "query", "required": true, "schema": { "type": "string", "description": "Absolute file path within the site, e.g. /pages/about.html" }, "description": "Absolute file path within the site, e.g. /pages/about.html" }, { "name": "branch", "in": "query", "required": false, "schema": { "type": "string", "description": "Review branch to read from or write to. Omit (or \"main\") to read the live site. To propose fixes, write files to a NEW branch name (e.g. \"seo-optimizer-2026-09-03\") \u2014 the branch is created on first write and is reviewed and approved by the owner. Writing to \"main\" is refused." }, "description": "Review branch to read from or write to. Omit (or \"main\") to read the live site. To propose fixes, write files to a NEW branch name (e.g. \"seo-optimizer-2026-09-03\") \u2014 the branch is created on first write and is reviewed and approved by the owner. Writing to \"main\" is refused." } ], "responses": { "400": { "description": "companyId/path/branch invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No company access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "File not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "The file content", "content": { "application/json": { "schema": { "type": "object", "properties": { "path": { "type": "string" }, "content": { "type": "string", "description": "File content; empty for a file held in object storage" }, "metadata": { "type": "object" }, "storage": { "type": "object", "description": "Present for a file held in object storage: {type, bytes, contentType, sha256}" } } } } } } }, "summary": "Read one website file", "description": "Returns the full content of a file so you can inspect it before proposing a\nchange. Pass a branch to read your in-progress version, or omit it for the\nlive file." }, "put": { "tags": [ "Websites" ], "operationId": "site_builder_apiWriteWebsiteFile", "parameters": [ { "name": "websiteId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "invalid path/branch, or branch is main", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No company access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Website not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "{ok: true}", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } } }, "summary": "Write a website file onto a review branch", "description": "Applies a fix. The branch is REQUIRED and must not be \"main\": the change\nlands on a review branch the owner approves, never the live site. The branch\nis created automatically on the first write. Branch changes reach the live\nsite only after the owner approves them; publishing deploys main only.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID that owns the website" }, "path": { "type": "string", "description": "Absolute file path within the site, e.g. /pages/about.html" }, "content": { "type": "string", "description": "Full new file content. For binary files (images, fonts, documents) this must be base64; to add an image or document use the upload-asset endpoint with sourceUrl instead." }, "metadata": { "type": "object", "description": "Structured metadata stored on this file row. For page HTML files: {title, description, seo: {pageType, image, noindex, faq}}. Omit to preserve existing metadata; pass null to clear it." }, "branch": { "type": "string", "description": "Review branch to read from or write to. Omit (or \"main\") to read the live site. To propose fixes, write files to a NEW branch name (e.g. \"seo-optimizer-2026-09-03\") \u2014 the branch is created on first write and is reviewed and approved by the owner. Writing to \"main\" is refused. Required here and must not be \"main\"." } }, "required": [ "companyId", "path", "content", "branch" ], "description": "Write a website file" } } } } }, "delete": { "tags": [ "Websites" ], "operationId": "site_builder_apiDeleteWebsiteFile", "parameters": [ { "name": "websiteId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID that owns the website" }, "description": "Company ID that owns the website" }, { "name": "path", "in": "query", "required": true, "schema": { "type": "string", "description": "Absolute file path within the site to delete" }, "description": "Absolute file path within the site to delete" }, { "name": "branch", "in": "query", "required": true, "schema": { "type": "string", "description": "Review branch to read from or write to. Omit (or \"main\") to read the live site. To propose fixes, write files to a NEW branch name (e.g. \"seo-optimizer-2026-09-03\") \u2014 the branch is created on first write and is reviewed and approved by the owner. Writing to \"main\" is refused. Required here and must not be \"main\"." }, "description": "Review branch to read from or write to. Omit (or \"main\") to read the live site. To propose fixes, write files to a NEW branch name (e.g. \"seo-optimizer-2026-09-03\") \u2014 the branch is created on first write and is reviewed and approved by the owner. Writing to \"main\" is refused. Required here and must not be \"main\"." } ], "responses": { "400": { "description": "invalid path/branch, or branch is main", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No company access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Website not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "{ok: true}", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } } }, "summary": "Delete a website file on a review branch", "description": "Removes a file on a review branch (a branch tombstone). The branch is\nREQUIRED and must not be \"main\"." } }, "/api/v0/websites/{websiteId}/validate": { "get": { "tags": [ "Websites" ], "operationId": "site_builder_apiValidateWebsite", "parameters": [ { "name": "websiteId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID that owns the website" }, "description": "Company ID that owns the website" }, { "name": "branch", "in": "query", "required": false, "schema": { "type": "string", "description": "Review branch to read from or write to. Omit (or \"main\") to read the live site. To propose fixes, write files to a NEW branch name (e.g. \"seo-optimizer-2026-09-03\") \u2014 the branch is created on first write and is reviewed and approved by the owner. Writing to \"main\" is refused." }, "description": "Review branch to read from or write to. Omit (or \"main\") to read the live site. To propose fixes, write files to a NEW branch name (e.g. \"seo-optimizer-2026-09-03\") \u2014 the branch is created on first write and is reviewed and approved by the owner. Writing to \"main\" is refused." } ], "responses": { "400": { "description": "companyId or branch invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No company access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Website not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "{ok, problems[]}", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "problems": { "type": "array", "items": { "type": "string" } } } } } } } }, "summary": "Validate a website renders cleanly", "description": "Reports broken includes, missing layouts, template cycles and invalid\nsite.json. Run this after writing fixes to a branch to confirm nothing broke." } }, "/api/v0/websites/{websiteId}/seo-audit": { "get": { "tags": [ "Websites" ], "operationId": "site_builder_apiSeoAuditWebsite", "parameters": [ { "name": "websiteId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID that owns the website" }, "description": "Company ID that owns the website" }, { "name": "branch", "in": "query", "required": false, "schema": { "type": "string", "description": "Review branch to read from or write to. Omit (or \"main\") to read the live site. To propose fixes, write files to a NEW branch name (e.g. \"seo-optimizer-2026-09-03\") \u2014 the branch is created on first write and is reviewed and approved by the owner. Writing to \"main\" is refused." }, "description": "Review branch to read from or write to. Omit (or \"main\") to read the live site. To propose fixes, write files to a NEW branch name (e.g. \"seo-optimizer-2026-09-03\") \u2014 the branch is created on first write and is reviewed and approved by the owner. Writing to \"main\" is refused." } ], "responses": { "400": { "description": "companyId or branch invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No company access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Website not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Full technical SEO/AEO report", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "description": "Full technical SEO/AEO report \u2014 score, per-page state, and issues worst-first" } } } } }, "summary": "Audit a website's SEO and AEO", "description": "Returns a score plus per-page state and issues (worst first): titles, meta\ndescriptions, canonical/robots, alt text, heading hierarchy, structured data,\nOpen Graph, broken internal links, orphan pages, and FAQ-schema opportunities.\nRead-only \u2014 pass no branch to audit the live site." } }, "/api/v0/websites/{websiteId}/lighthouse": { "get": { "tags": [ "Websites" ], "operationId": "site_builder_apiLighthouseWebsite", "parameters": [ { "name": "websiteId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID that owns the website" }, "description": "Company ID that owns the website" }, { "name": "route", "in": "query", "required": false, "schema": { "type": "string", "description": "Route of the page to score, e.g. '/' or '/about' (default '/')" }, "description": "Route of the page to score, e.g. '/' or '/about' (default '/')" }, { "name": "device", "in": "query", "required": false, "schema": { "type": "string", "description": "'mobile' (default) or 'desktop'" }, "description": "'mobile' (default) or 'desktop'" } ], "responses": { "400": { "description": "companyId missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No company access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Website not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Lighthouse scores + Core Web Vitals", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "description": "Full technical SEO/AEO report \u2014 score, per-page state, and issues worst-first" } } } } }, "summary": "Lighthouse-score a published page", "description": "Returns performance, accessibility, best-practices and SEO scores plus Core\nWeb Vitals for one live page. Only works after the site is published; for a\npre-publish check use the seo-audit endpoint instead." } }, "/api/v0/websites/{websiteId}/assets": { "post": { "tags": [ "Websites" ], "operationId": "site_builder_apiUploadWebsiteAsset", "parameters": [ { "name": "websiteId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "invalid source/path/branch, unsupported type, too large, or branch is main", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No company access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Website not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "201": { "description": "The stored file", "content": { "application/json": { "schema": { "type": "object", "properties": { "path": { "type": "string", "description": "Saved path \u2014 reference the file by this path" }, "storage": { "type": "string", "description": "'inline' (small file kept in the project) or 'object' (object storage)" }, "bytes": { "type": "integer", "description": "Stored size in bytes" }, "contentType": { "type": "string" }, "sha256": { "type": "string", "description": "Content hash (object-stored files)" }, "width": { "type": "integer", "description": "Image width, for the <img width> attribute" }, "height": { "type": "integer", "description": "Image height, for the <img height> attribute" }, "optimized": { "type": "boolean", "description": "True when an image was downscaled/re-encoded" } } } } } } }, "summary": "Upload an image, document or media file onto a review branch", "description": "Adds a binary file to the site: images (png, jpg, webp, gif, avif, ico),\ndocuments (pdf, doc/docx, xls/xlsx, ppt/pptx, zip), audio/video (mp4,\nwebm, mov, mp3, wav, ogg, m4a) and fonts. Pass sourceUrl to have the\nserver fetch a public URL (best for images), or contentBase64 for bytes\nyou already hold; multipart file uploads are also accepted. Images are\noptimized; documents download when linked. Up to 50MB. The branch is\nREQUIRED and must not be \"main\". Reference the file by the returned path.\nHTML, CSS, JS and SVG are source files \u2014 write those with the write-file\nendpoint.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID that owns the website" }, "path": { "type": "string", "description": "Where the file lives in the site, e.g. /assets/hero.jpg or /assets/files/sales-sheet.pdf. A bare file name lands in /assets/ (documents in /assets/files/). Defaults to the file name from sourceUrl. Raster images are optimized to WebP, so /assets/hero.jpg may be saved as /assets/hero.webp \u2014 use the returned path in links and <img src>." }, "sourceUrl": { "type": "string", "description": "Public http(s) URL to fetch the file from (preferred for images: no need to inline bytes). Private/internal addresses are refused. Send exactly one of sourceUrl or contentBase64." }, "contentBase64": { "type": "string", "description": "The file bytes, base64-encoded (a data: URL prefix is accepted). Only for files you already hold locally; prefer sourceUrl." }, "branch": { "type": "string", "description": "Review branch to read from or write to. Omit (or \"main\") to read the live site. To propose fixes, write files to a NEW branch name (e.g. \"seo-optimizer-2026-09-03\") \u2014 the branch is created on first write and is reviewed and approved by the owner. Writing to \"main\" is refused. Required here and must not be \"main\"." } }, "required": [ "companyId", "branch" ], "description": "Upload a website asset" } } } } } }, "/api/v0/websites/{websiteId}/branches": { "get": { "tags": [ "Websites" ], "operationId": "site_builder_apiListWebsiteBranches", "parameters": [ { "name": "websiteId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID that owns the website" }, "description": "Company ID that owns the website" }, { "name": "branch", "in": "query", "required": false, "schema": { "type": "string", "description": "Review branch to read from or write to. Omit (or \"main\") to read the live site. To propose fixes, write files to a NEW branch name (e.g. \"seo-optimizer-2026-09-03\") \u2014 the branch is created on first write and is reviewed and approved by the owner. Writing to \"main\" is refused." }, "description": "Review branch to read from or write to. Omit (or \"main\") to read the live site. To propose fixes, write files to a NEW branch name (e.g. \"seo-optimizer-2026-09-03\") \u2014 the branch is created on first write and is reviewed and approved by the owner. Writing to \"main\" is refused." } ], "responses": { "400": { "description": "companyId missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No company access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Website not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Review branches with unmerged changes", "content": { "application/json": { "schema": { "type": "object", "properties": { "branches": { "type": "array", "items": { "type": "string" }, "description": "Review branches with unmerged changes" } } } } } } }, "summary": "List a website's review branches", "description": "Shows the review branches you (or the owner) have created and how many files\neach changes, so you can see what is already staged before you audit again." } }, "/api/v0/websites/{websiteId}/branches/{branch}/diff": { "get": { "tags": [ "Websites" ], "operationId": "site_builder_apiWebsiteBranchDiff", "parameters": [ { "name": "websiteId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "branch", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID that owns the website" }, "description": "Company ID that owns the website" }, { "name": "branch", "in": "query", "required": false, "schema": { "type": "string", "description": "Review branch to read from or write to. Omit (or \"main\") to read the live site. To propose fixes, write files to a NEW branch name (e.g. \"seo-optimizer-2026-09-03\") \u2014 the branch is created on first write and is reviewed and approved by the owner. Writing to \"main\" is refused." }, "description": "Review branch to read from or write to. Omit (or \"main\") to read the live site. To propose fixes, write files to a NEW branch name (e.g. \"seo-optimizer-2026-09-03\") \u2014 the branch is created on first write and is reviewed and approved by the owner. Writing to \"main\" is refused." } ], "responses": { "400": { "description": "companyId missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No company access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Website not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Per-file diff of the branch against main", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "description": "Full technical SEO/AEO report \u2014 score, per-page state, and issues worst-first" } } } } }, "summary": "Diff a review branch against the live site", "description": "Returns the changed files and their before/after, i.e. exactly what the\nowner will review before approving." } }, "/api/v0/websites/collections": { "get": { "tags": [ "Websites" ], "operationId": "site_builder_apiListWebsiteCollections", "parameters": [ { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID that owns the website" }, "description": "Company ID that owns the website" } ], "responses": { "400": { "description": "companyId missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No company access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Every CMS collection the company owns", "content": { "application/json": { "schema": { "type": "object", "properties": { "collections": { "type": "array", "items": { "type": "string" }, "description": "Collections with id, name, label, entryCount and linked sites" }, "total": { "type": "integer" } } } } } } }, "summary": "List the company's CMS collections", "description": "Collections hold repeating content (blog posts, service-area pages). Each\nlists the websites that use it; a site renders a collection's entries as\npages through a /pages/<name>/[slug].html template." }, "post": { "tags": [ "Websites" ], "operationId": "site_builder_apiCreateWebsiteCollection", "parameters": [], "responses": { "400": { "description": "companyId missing or name invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No company access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Website not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "201": { "description": "The created collection", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "description": "The collection: id, name, label, description, entryCount" } } } } }, "summary": "Create a CMS collection", "description": "Creates an empty collection and, when websiteId is given, links it to that\nwebsite. Add entries with the create-entry endpoint.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID that owns the website" }, "name": { "type": "string", "description": "Machine name, slugified (e.g. \"service-areas\"). Templates loop over collections.<name>, and a /pages/<name>/[slug].html template serves one page per entry at /<name>/<slug>." }, "label": { "type": "string", "description": "Human label shown in the editor (defaults to name)" }, "description": { "type": "string", "description": "What the collection holds" }, "websiteId": { "type": "string", "description": "Website to link the collection to on creation (from list websites)" } }, "required": [ "companyId", "name" ], "description": "Create a collection" } } } } } }, "/api/v0/websites/collections/{collectionId}/entries": { "get": { "tags": [ "Websites" ], "operationId": "site_builder_apiListWebsiteEntries", "parameters": [ { "name": "collectionId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "description": "Company ID that owns the website" }, "description": "Company ID that owns the website" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "description": "'draft' or 'published'" }, "description": "'draft' or 'published'" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "description": "Title filter" }, "description": "Title filter" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Page, 1-indexed (default 1)" }, "description": "Page, 1-indexed (default 1)" }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "description": "Entries per page, 1-200 (default 50)" }, "description": "Entries per page, 1-200 (default 50)" } ], "responses": { "400": { "description": "companyId missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No company access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Collection not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Entries in the collection, paginated", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "string" }, "description": "Entries, newest first" }, "total": { "type": "integer" }, "page": { "type": "integer" }, "pageSize": { "type": "integer" } } } } } } }, "summary": "List a collection's entries", "description": "Paginated, newest first. Filter by status or title search." } }, "/api/v0/websites/entries": { "post": { "tags": [ "Websites" ], "operationId": "site_builder_apiCreateWebsiteEntry", "parameters": [], "responses": { "400": { "description": "companyId/collectionId/title invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No company access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "201": { "description": "The created draft entry", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "description": "The entry: id, collectionId, slug, title, body, status and SEO fields" } } } } }, "summary": "Create a draft CMS entry", "description": "Adds a draft entry to a collection. Drafts are not on the live site; the\nowner reviews and publishes them from the editor.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID that owns the website" }, "collectionId": { "type": "string", "description": "Collection to add the entry to" }, "title": { "type": "string", "description": "Entry title (the page H1)" }, "body": { "type": "string", "description": "Markdown body \u2014 the source of truth; HTML is rendered from it" }, "slug": { "type": "string", "description": "URL slug; derived from the title when omitted, made unique within the collection" }, "excerpt": { "type": "string", "description": "Short summary for listings" }, "metaDescription": { "type": "string", "description": "Search-result description" }, "seoTitle": { "type": "string", "description": "Search-result <title>" }, "focusKeyword": { "type": "string", "description": "The one search phrase the page targets" }, "heroImageUrl": { "type": "string", "description": "Hero image URL" }, "author": { "type": "string", "description": "Author name" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags" }, "data": { "type": "object", "description": "Extra structured fields the template reads as entry.data.<key>" } }, "required": [ "companyId", "collectionId", "title" ], "description": "Create a draft entry" } } } } } }, "/api/v0/websites/entries/{entryId}": { "patch": { "tags": [ "Websites" ], "operationId": "site_builder_apiUpdateWebsiteEntry", "parameters": [ { "name": "entryId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "companyId missing or entry not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No company access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "The updated entry", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "description": "The entry: id, collectionId, slug, title, body, status and SEO fields" } } } } }, "summary": "Update a CMS entry", "description": "Edits an entry's content and SEO fields. Only the fields sent are changed.\nStatus cannot be changed here.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Company ID that owns the website" }, "title": { "type": "string", "description": "Entry title (the page H1)" }, "body": { "type": "string", "description": "Markdown body \u2014 the source of truth; HTML is rendered from it" }, "slug": { "type": "string", "description": "URL slug; derived from the title when omitted, made unique within the collection" }, "excerpt": { "type": "string", "description": "Short summary for listings" }, "metaDescription": { "type": "string", "description": "Search-result description" }, "seoTitle": { "type": "string", "description": "Search-result <title>" }, "focusKeyword": { "type": "string", "description": "The one search phrase the page targets" }, "heroImageUrl": { "type": "string", "description": "Hero image URL" }, "author": { "type": "string", "description": "Author name" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags" }, "data": { "type": "object", "description": "Extra structured fields the template reads as entry.data.<key>" } }, "required": [ "companyId" ], "description": "Update an entry" } } } } } }, "/api/v0/skills": { "get": { "tags": [ "Skills" ], "operationId": "skills_listSkills", "parameters": [], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Available skills", "content": { "application/json": { "schema": { "type": "object", "properties": { "skills": { "type": "array", "items": { "type": "string" }, "description": "Available skills (slug + title, no body)" } } } } } } }, "summary": "List available agent skills", "description": "Returns each skill's slug and title. Fetch a skill's full instructions with\ngetSkill. Capabilities that have a related skill name its slug in their\nlisting (relatedSkills)." }, "post": { "tags": [ "Skills" ], "operationId": "skills_createSkill", "parameters": [], "responses": { "200": { "description": "Created user skill", "content": { "application/json": { "schema": { "type": "object", "properties": { "slug": { "type": "string" }, "title": { "type": "string" }, "body": { "type": "string", "description": "The full instruction text (Markdown)" } }, "description": "A skill: reusable capability instructions" } } } } }, "summary": "Create a user-owned, optionally company-shared multi-file skill.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": "string" }, "files": { "type": "object", "description": "Skill package files. Include SKILL.md; scripts and references stay in the sandbox until read there." }, "content": { "type": "string", "description": "Compatibility alias for files.SKILL.md" }, "priority": { "type": "integer" }, "sharedWithCompany": { "type": "boolean" }, "companyId": { "type": "string", "description": "Ignored for company API keys; use the authenticated company. Required in the legacy personal-assistant API when sharing." } }, "required": [ "name" ] } } } } } }, "/api/v0/skills/{slug}": { "get": { "tags": [ "Skills" ], "operationId": "skills_getSkill", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Skill not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "The skill, including its full instruction text", "content": { "application/json": { "schema": { "type": "object", "properties": { "slug": { "type": "string" }, "title": { "type": "string" }, "body": { "type": "string", "description": "The full instruction text (Markdown)" } }, "description": "A skill: reusable capability instructions" } } } } }, "summary": "Read a skill's full instructions", "description": "Returns the skill's Markdown instruction text. Read the relevant skill\nbefore using a capability's operations \u2014 e.g. read \"website-editing\" before\nediting a website, so you edit site.json instead of hand-writing tags the\nplatform generates automatically." }, "put": { "tags": [ "Skills" ], "operationId": "skills_updateUserSkill", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response" } }, "summary": "Update a skill you own. Set sharedWithCompany to share or unshare it.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": "string" }, "files": { "type": "object", "description": "Skill package files. Include SKILL.md; scripts and references stay in the sandbox until read there." }, "content": { "type": "string", "description": "Compatibility alias for files.SKILL.md" }, "priority": { "type": "integer" }, "sharedWithCompany": { "type": "boolean" }, "companyId": { "type": "string", "description": "Ignored for company API keys; use the authenticated company. Required in the legacy personal-assistant API when sharing." } }, "required": [ "name" ] } } } } }, "delete": { "tags": [ "Skills" ], "operationId": "skills_deleteUserSkill", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response" } }, "summary": "Delete a skill you own." } }, "/api/v0/skills/{slug}/sync": { "post": { "tags": [ "Skills" ], "operationId": "skills_syncSkillToSandbox", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response" } }, "summary": "Copy every skill file to the authenticated MCP workbench without returning file bodies." } } }, "components": { "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" } } } }, "securitySchemes": { "CompanyApiKey": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Company API key - scoped to a specific company. Generate from the Integrations page in your dashboard." }, "BearerAuth": { "type": "http", "scheme": "bearer", "description": "Bearer token authentication. Can use either a Company API Key or a Personal Access Key (starting with pak_). Personal Access Keys require X-Company-ID header." }, "CompanyId": { "type": "apiKey", "in": "header", "name": "X-Company-ID", "description": "Required when using Personal Access Keys. Specifies which company to access." } } }, "security": [ { "CompanyApiKey": [] }, { "BearerAuth": [], "CompanyId": [] } ] }