{"openapi":"3.0.3","info":{"title":"Octocom API","description":"\nThe Octocom API provides programmatic access to your customer support data and configuration.\n\n## Overview\n\nThis API allows you to retrieve and manage data from your Octocom account. The primary resource is **Conversations**, which contain the full history of customer interactions including messages, AI classifications, and agent notes.\n\n## Authentication\n\nAll API requests require authentication using an API key. Include your API key in the `X-API-Key` header with every request:\n\n```\nX-API-Key: your_api_key_here\n```\n\nYou can generate and manage your API keys from the **API Settings** page in your Octocom dashboard.\n\n## Rate Limiting\n\nAPI requests are rate limited. If you exceed the limit, you'll receive a `429 Too Many Requests` response.\n\n## Errors\n\nThe API uses standard HTTP status codes:\n- `200` - Success\n- `401` - Invalid or missing API key\n- `404` - Resource not found\n- `429` - Rate limit exceeded\n- `500` - Server error\n","version":"1.0.0"},"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"X-API-Key","in":"header","description":"API key for authentication. Get yours from the API Settings page in your dashboard."}},"schemas":{}},"paths":{"/rest/v1/conversations":{"get":{"summary":"List conversations","tags":["Conversations"],"description":"Retrieve a paginated list of conversations for your organization.\n\nReturns up to 50 conversations per page, sorted by creation date in ascending order.\nUse the date range parameters to filter conversations by when they were created.\nUse status and handedOff parameters to filter by conversation state.\nUse metadataKey and metadataValue together to filter by a specific metadata key-value pair.\n\n**Authentication:** Requires a valid API key in the `X-API-Key` header.","parameters":[{"schema":{"type":"string","format":"date-time"},"in":"query","name":"startDate","required":false,"description":"Filter conversations created on or after this date (ISO 8601 format, e.g., 2024-01-15T00:00:00Z)"},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"endDate","required":false,"description":"Filter conversations created on or before this date (ISO 8601 format, e.g., 2024-01-15T23:59:59Z)"},{"schema":{"type":"integer","exclusiveMinimum":true,"minimum":0,"default":1},"in":"query","name":"page","required":false,"description":"Page number for pagination (starts at 1)"},{"schema":{"type":"string","enum":["open","closed","snoozed"]},"in":"query","name":"status","required":false,"description":"Filter by conversation status (open = not closed and not snoozed, closed = has been closed, snoozed = currently snoozed)"},{"schema":{"type":"string","enum":["true","false"]},"in":"query","name":"handedOff","required":false,"description":"Filter by handed-off state (true = only handed-off conversations, false = only bot-handled conversations)"},{"schema":{"type":"string","maxLength":200},"in":"query","name":"metadataKey","required":false,"description":"Filter by metadata key. Must be used together with metadataValue. Returns only conversations that have this exact key-value metadata pair."},{"schema":{"type":"string","maxLength":50000},"in":"query","name":"metadataValue","required":false,"description":"Filter by metadata value. Must be used together with metadataKey. Returns only conversations that have this exact key-value metadata pair."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"description":"Successful response","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier","example":"550e8400-e29b-41d4-a716-446655440000"},"publicId":{"type":"string","description":"Public-facing ID for external references","example":"CONV-2024-001234"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp","example":"2024-01-15T10:30:00Z"},"closedAt":{"type":["string","null"],"format":"date-time","description":"When closed (null if open)"},"handedOffAt":{"type":["string","null"],"format":"date-time","description":"When handed to human agent (null if bot-only)"},"subject":{"type":"string","description":"Subject or title"},"lastMessageCreatedAt":{"type":"string","format":"date-time","description":"Most recent message timestamp"},"sentiment":{"type":["string","null"],"description":"AI-analyzed sentiment (e.g., 'Strongly Positive', 'Neutral')"},"topics":{"type":["array","null"],"items":{"type":"string"},"description":"AI-classified topics"},"type":{"type":"string","enum":["customer","external"],"description":"'customer' for direct, 'external' for third-party"},"isOutbound":{"type":"boolean","description":"Whether initiated by the business"},"businessSlug":{"type":"string","description":"Business identifier"},"initialChannel":{"type":["string","null"],"enum":["web","email","whatsapp","messenger","instagram","telegram","sms","phone-call","google-business-messages","google-reviews","trustpilot-reviews","facebookComment","facebookMention","instagramMention","instagramComment","amazon","ebay","aircall","brymec","echo","test-review","zoom-transcript","api",null],"description":"Channel where conversation started"},"latestChannel":{"type":["string","null"],"enum":["web","email","whatsapp","messenger","instagram","telegram","sms","phone-call","google-business-messages","google-reviews","trustpilot-reviews","facebookComment","facebookMention","instagramMention","instagramComment","amazon","ebay","aircall","brymec","echo","test-review","zoom-transcript","api",null],"description":"Channel of most recent message"},"tags":{"type":"array","items":{"type":"string"},"description":"User-applied tags"}},"required":["id","publicId","createdAt","subject","lastMessageCreatedAt","type","isOutbound","businessSlug","tags"]},"description":"List of conversations"},"pagination":{"type":"object","properties":{"page":{"type":"number","description":"Current page number"},"limit":{"type":"number","description":"Maximum items per page"},"hasMore":{"type":"boolean","description":"Whether more pages exist"}},"required":["page","limit","hasMore"]}},"required":["data","pagination"]}}}},"401":{"description":"Authentication failed - invalid or missing API key","content":{"application/json":{"schema":{"description":"Authentication failed - invalid or missing API key","type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}}}}},"/rest/v1/conversations/{id}":{"get":{"summary":"Get conversation details","tags":["Conversations"],"description":"Retrieve complete details for a single conversation, including full message history,\nAI analysis, agent notes, and bot activity.\n\n**Authentication:** Requires a valid API key in the `X-API-Key` header.\nThe conversation must belong to a business within your organization.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true,"description":"Conversation UUID"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"description":"Successful response","type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier"},"publicId":{"type":"string","description":"Public-facing ID for external references"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"closedAt":{"type":["string","null"],"format":"date-time","description":"When closed"},"handedOffAt":{"type":["string","null"],"format":"date-time","description":"When handed to human agent"},"language":{"type":"string","description":"Detected language (ISO 639-1 code)"},"subject":{"type":"string","description":"Subject or title"},"businessSlug":{"type":"string","description":"Business identifier"},"sentiment":{"type":["string","null"],"description":"AI-analyzed sentiment"},"sentimentReason":{"type":["string","null"],"description":"Explanation for sentiment classification"},"topics":{"type":["array","null"],"items":{"type":"string"},"description":"AI-classified topics"},"customer":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Customer unique identifier","example":"c1d2e3f4-5678-90ab-cdef-123456789abc"},"email":{"type":["string","null"],"format":"email","description":"Customer email address","example":"customer@example.com"},"phone":{"type":["string","null"],"description":"Customer phone number","example":"+1-555-123-4567"},"name":{"type":["string","null"],"description":"Customer display name","example":"John Smith"}},"required":["id"],"nullable":true,"description":"Customer associated with this conversation (null if no customer linked)"},"messages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier"},"sender":{"type":"string","description":"Sender type: 'customer', 'bot', 'agent', or 'external'"},"text":{"type":"string","description":"Message content"},"channel":{"type":"string","enum":["web","email","whatsapp","messenger","instagram","telegram","sms","phone-call","google-business-messages","google-reviews","trustpilot-reviews","facebookComment","facebookMention","instagramMention","instagramComment","amazon","ebay","aircall","brymec","echo","test-review","zoom-transcript","api"],"description":"Channel the message was sent through"},"createdAt":{"type":"string","format":"date-time","description":"Message timestamp"},"agentName":{"type":["string","null"],"description":"Agent name if sender is 'agent'"}},"required":["id","sender","text","channel","createdAt"]},"description":"Complete message history"},"dataCollectionResults":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","description":"Data field identifier"},"value":{"type":"string","description":"Collected value"},"createdAt":{"type":"string","format":"date-time","description":"Collection timestamp"}},"required":["key","value","createdAt"]},"description":"AI-extracted data from conversation"},"notes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier"},"text":{"type":"string","description":"Note content"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"userId":{"type":"string","format":"uuid","description":"ID of user who created the note"}},"required":["id","text","createdAt","userId"]},"description":"Internal notes added by agents"},"events":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier"},"event":{"type":"string","description":"Event type identifier"},"createdAt":{"type":"string","format":"date-time","description":"Event timestamp"},"metadata":{"description":"Event-specific metadata"}},"required":["id","event","createdAt"]},"description":"Conversation lifecycle events"},"botFunctionCalls":{"type":"array","items":{"type":"object","properties":{"toolName":{"type":"string","description":"Name of the function/tool called"},"toolArguments":{"type":"string","description":"JSON string of arguments passed"},"content":{"type":"string","description":"Result from the function call"},"createdAt":{"type":"string","format":"date-time","description":"Call timestamp"}},"required":["toolName","toolArguments","content","createdAt"]},"description":"Functions invoked by the bot"},"tags":{"type":"array","items":{"type":"string"},"description":"User-applied tags"},"workflows":{"type":"array","items":{"type":"string"},"description":"Deduplicated workflow names used across all bot responses"},"variants":{"type":"array","items":{"type":"string"},"description":"Deduplicated workflow variant names (format: 'WorkflowName / VariantName')"},"metadata":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","description":"Metadata key"},"value":{"type":"string","description":"Metadata value"},"createdAt":{"type":"string","format":"date-time","description":"When first created"},"updatedAt":{"type":"string","format":"date-time","description":"When last updated"}},"required":["key","value","createdAt","updatedAt"]},"description":"Key-value metadata pairs"}},"required":["id","publicId","createdAt","language","subject","businessSlug","messages","dataCollectionResults","notes","events","botFunctionCalls","tags","workflows","variants","metadata"]}},"required":["data"]}}}},"401":{"description":"Authentication failed - invalid or missing API key","content":{"application/json":{"schema":{"description":"Authentication failed - invalid or missing API key","type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}},"404":{"description":"Conversation not found or not accessible","content":{"application/json":{"schema":{"description":"Conversation not found or not accessible","type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}}}}},"/rest/v1/customers":{"get":{"summary":"List customers","tags":["Customers"],"description":"Retrieve a paginated list of customers across all businesses in your organization.\n\nReturns up to 50 customers per page, sorted by creation date.\n\n**Authentication:** Requires a valid API key in the `X-API-Key` header.","parameters":[{"schema":{"type":"string","format":"date-time"},"in":"query","name":"startDate","required":false,"description":"Filter customers created on or after this date (ISO 8601 format, e.g., 2024-01-15T00:00:00Z)"},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"endDate","required":false,"description":"Filter customers created on or before this date (ISO 8601 format, e.g., 2024-01-15T23:59:59Z)"},{"schema":{"type":"integer","exclusiveMinimum":true,"minimum":0,"default":1},"in":"query","name":"page","required":false,"description":"Page number for pagination"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"description":"Successful response","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier","example":"c1d2e3f4-5678-90ab-cdef-123456789abc"},"email":{"type":["string","null"],"format":"email","description":"Customer email address","example":"customer@example.com"},"phone":{"type":["string","null"],"description":"Customer phone number","example":"+1-555-123-4567"},"name":{"type":["string","null"],"description":"Customer display name","example":"John Smith"},"businessSlug":{"type":"string","description":"Business identifier","example":"acme-corp"},"createdAt":{"type":["string","null"],"format":"date-time","description":"When the customer was first seen","example":"2024-01-10T08:00:00Z"},"conversationIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"IDs of conversations associated with this customer","example":["550e8400-e29b-41d4-a716-446655440000"]}},"required":["id","businessSlug","conversationIds"]},"description":"List of customers"},"pagination":{"type":"object","properties":{"page":{"type":"number","description":"Current page number"},"limit":{"type":"number","description":"Maximum items per page"},"hasMore":{"type":"boolean","description":"Whether more pages exist"}},"required":["page","limit","hasMore"]}},"required":["data","pagination"]}}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"description":"Authentication failed","type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}}}}},"/rest/v1/custom-data":{"get":{"summary":"List custom data classifications","tags":["Custom Data"],"description":"Retrieve a paginated list of AI-classified data from conversations.\n\nUse this endpoint to get aggregated classification results without fetching full conversations.\nSupports filtering by classification key and custom page sizes up to 200.\n\n**Authentication:** Requires a valid API key in the `X-API-Key` header.","parameters":[{"schema":{"type":"string"},"in":"query","name":"businessSlug","required":true,"description":"Business identifier (required)"},{"schema":{"type":"string"},"in":"query","name":"key","required":false,"description":"Filter by classification key"},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"startDate","required":false,"description":"Filter by classification date (ISO 8601 format, e.g., 2024-01-15T00:00:00Z)"},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"endDate","required":false,"description":"Filter by classification date (ISO 8601 format, e.g., 2024-01-15T23:59:59Z)"},{"schema":{"type":"integer","exclusiveMinimum":true,"minimum":0,"default":1},"in":"query","name":"page","required":false,"description":"Page number"},{"schema":{"type":"integer","exclusiveMinimum":true,"minimum":0,"maximum":200,"default":50},"in":"query","name":"limit","required":false,"description":"Items per page (max 200)"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"description":"Successful response","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier","example":"d4e5f6a7-8901-2345-bcde-f67890123456"},"conversationId":{"type":"string","format":"uuid","description":"Associated conversation ID","example":"550e8400-e29b-41d4-a716-446655440000"},"key":{"type":"string","description":"Classification key (e.g., 'issue_type', 'sentiment')","example":"issue_type"},"value":{"type":"string","description":"Classified value for this key","example":"billing_inquiry"},"createdAt":{"type":"string","format":"date-time","description":"When the classification was made","example":"2024-01-15T10:35:00Z"}},"required":["id","conversationId","key","value","createdAt"]},"description":"List of classification results"},"pagination":{"type":"object","properties":{"page":{"type":"number","description":"Current page number"},"limit":{"type":"number","description":"Maximum items per page"},"hasMore":{"type":"boolean","description":"Whether more pages exist"}},"required":["page","limit","hasMore"]}},"required":["data","pagination"]}}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"description":"Authentication failed","type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}},"404":{"description":"Business not found","content":{"application/json":{"schema":{"description":"Business not found","type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}}}}},"/rest/v1/users":{"get":{"summary":"List organization users","tags":["Users"],"description":"Retrieve a paginated list of users in your organization.\n\nReturns active users only (excludes archived users).\n\n**Authentication:** Requires a valid API key in the `X-API-Key` header.","parameters":[{"schema":{"type":"integer","exclusiveMinimum":true,"minimum":0,"default":1},"in":"query","name":"page","required":false,"description":"Page number"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"description":"Successful response","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier","example":"u1234567-89ab-cdef-0123-456789abcdef"},"email":{"type":"string","format":"email","description":"User email","example":"agent@company.com"},"fullName":{"type":"string","description":"User's full name","example":"Jane Doe"},"isAgent":{"type":"boolean","description":"Whether user can handle conversations","example":true},"isManager":{"type":"boolean","description":"Whether user has manager privileges","example":false},"teamId":{"type":["string","null"],"format":"uuid","description":"Team the user belongs to","example":"t9876543-21fe-dcba-9876-543210fedcba"}},"required":["id","email","fullName","isAgent","isManager"]},"description":"List of users"},"pagination":{"type":"object","properties":{"page":{"type":"number","description":"Current page number"},"limit":{"type":"number","description":"Maximum items per page"},"hasMore":{"type":"boolean","description":"Whether more pages exist"}},"required":["page","limit","hasMore"]}},"required":["data","pagination"]}}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"description":"Authentication failed","type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}}}}},"/rest/v1/teams":{"get":{"summary":"List organization teams","tags":["Teams"],"description":"Retrieve a paginated list of teams in your organization.\n\n**Authentication:** Requires a valid API key in the `X-API-Key` header.","parameters":[{"schema":{"type":"integer","exclusiveMinimum":true,"minimum":0,"default":1},"in":"query","name":"page","required":false,"description":"Page number"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"description":"Successful response","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier","example":"t9876543-21fe-dcba-9876-543210fedcba"},"name":{"type":"string","description":"Team name","example":"Support Team"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp","example":"2024-01-01T00:00:00Z"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp","example":"2024-06-15T14:30:00Z"}},"required":["id","name","createdAt","updatedAt"]},"description":"List of teams"},"pagination":{"type":"object","properties":{"page":{"type":"number","description":"Current page number"},"limit":{"type":"number","description":"Maximum items per page"},"hasMore":{"type":"boolean","description":"Whether more pages exist"}},"required":["page","limit","hasMore"]}},"required":["data","pagination"]}}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"description":"Authentication failed","type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}}}}},"/rest/v1/macros":{"get":{"summary":"List macros","tags":["Macros"],"description":"Retrieve a paginated list of response macros in your organization.\n\nMacros are reusable response templates that agents can use to quickly respond to common inquiries.\n\n**Authentication:** Requires a valid API key in the `X-API-Key` header.","parameters":[{"schema":{"type":"integer","exclusiveMinimum":true,"minimum":0,"default":1},"in":"query","name":"page","required":false,"description":"Page number"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"description":"Successful response","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier","example":"m1234567-89ab-cdef-0123-456789abcdef"},"title":{"type":"string","description":"Macro title","example":"Shipping Delay Response"},"content":{"type":["string","null"],"description":"Macro response template","example":"We apologize for the delay with your order. Our team is working to resolve this as quickly as possible."},"businessSlug":{"type":["string","null"],"description":"Business scope (null = organization-wide)","example":"acme-corp"}},"required":["id","title"]},"description":"List of macros"},"pagination":{"type":"object","properties":{"page":{"type":"number","description":"Current page number"},"limit":{"type":"number","description":"Maximum items per page"},"hasMore":{"type":"boolean","description":"Whether more pages exist"}},"required":["page","limit","hasMore"]}},"required":["data","pagination"]}}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"description":"Authentication failed","type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}}}}},"/rest/v1/workflows":{"get":{"summary":"List workflows","tags":["Workflows"],"description":"Retrieve a paginated list of bot workflows for a specific business.\n\nWorkflows define automated conversation flows and bot behaviors.\n\n**Authentication:** Requires a valid API key in the `X-API-Key` header.","parameters":[{"schema":{"type":"string"},"in":"query","name":"businessSlug","required":true,"description":"Business identifier (required)"},{"schema":{"type":"integer","exclusiveMinimum":true,"minimum":0,"default":1},"in":"query","name":"page","required":false,"description":"Page number"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"description":"Successful response","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier","example":"w1234567-89ab-cdef-0123-456789abcdef"},"title":{"type":"string","description":"Workflow name","example":"Order Status Inquiry"},"slug":{"type":"string","description":"URL-friendly identifier","example":"order-status-inquiry"},"isLive":{"type":"boolean","description":"Whether workflow is active","example":true},"whenToFollow":{"type":"string","description":"Trigger condition for the workflow","example":"When a customer asks about their order status"},"priority":{"type":"number","description":"Execution priority (lower = higher priority)","example":10},"availableChannels":{"type":"array","items":{"type":"string"},"description":"Channels where this workflow applies","example":["web","email","whatsapp"]},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp","example":"2024-02-01T09:00:00Z"}},"required":["id","title","slug","isLive","whenToFollow","priority","availableChannels","createdAt"]},"description":"List of workflows"},"pagination":{"type":"object","properties":{"page":{"type":"number","description":"Current page number"},"limit":{"type":"number","description":"Maximum items per page"},"hasMore":{"type":"boolean","description":"Whether more pages exist"}},"required":["page","limit","hasMore"]}},"required":["data","pagination"]}}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"description":"Authentication failed","type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}},"404":{"description":"Business not found","content":{"application/json":{"schema":{"description":"Business not found","type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}}}},"post":{"summary":"Create a workflow","tags":["Workflows"],"description":"Create a new bot workflow with one or more variants.\n\nWorkflows control how the bot responds to different situations. Each workflow needs at least one variant with bot instructions.\n\n**Embedded workflows** must have exactly one variant.\n\n**Authentication:** Requires a valid API key in the `X-API-Key` header.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"businessSlug":{"type":"string","description":"Business identifier (required)"},"title":{"type":"string","minLength":1,"description":"Workflow title"},"whenToFollow":{"type":"string","minLength":1,"description":"Human-readable condition for when this workflow applies (e.g., 'Customer asks about returns')"},"isLive":{"type":"boolean","description":"Whether the workflow is active"},"variants":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string","minLength":1,"description":"Variant name"},"botInstructions":{"type":"string","minLength":1,"description":"Instructions for the bot to follow"},"actionNames":{"type":"array","items":{"type":"string"},"default":[],"description":"Available actions for this variant"},"requiredConditions":{"type":"array","items":{"type":"string"},"default":[],"description":"Conditions that must be true for this variant"}},"required":["title","botInstructions"],"additionalProperties":false},"minItems":1,"description":"At least one variant required"},"availableChannels":{"type":"array","items":{"type":"string"},"description":"Limit to specific channels (omit or empty array for all channels)"},"isEmbedded":{"type":"boolean","default":false,"description":"Whether this is an embedded workflow (must have exactly 1 variant)"}},"required":["businessSlug","title","whenToFollow","isLive","variants"],"additionalProperties":false}}}},"responses":{"201":{"description":"Workflow created successfully","content":{"application/json":{"schema":{"description":"Workflow created successfully","type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier","example":"w1234567-89ab-cdef-0123-456789abcdef"},"title":{"type":"string","description":"Workflow name","example":"Order Status Inquiry"},"slug":{"type":"string","description":"URL-friendly identifier","example":"order-status-inquiry"},"isLive":{"type":"boolean","description":"Whether workflow is active","example":true},"whenToFollow":{"type":"string","description":"Trigger condition for the workflow","example":"When a customer asks about their order status"},"priority":{"type":"number","description":"Execution priority (lower = higher priority)","example":10},"availableChannels":{"type":"array","items":{"type":"string"},"description":"Channels where this workflow applies","example":["web","email","whatsapp"]},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp","example":"2024-02-01T09:00:00Z"},"isEmbedded":{"type":"boolean","description":"Whether the workflow is embedded (must have exactly 1 variant)","example":false},"variants":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique variant identifier","example":"v1234567-89ab-cdef-0123-456789abcdef"},"title":{"type":"string","description":"Variant name","example":"Default"},"position":{"type":"number","description":"Order position (0-based)","example":0},"botInstructions":{"type":"string","description":"Instructions for the bot to follow","example":"Help the customer track their order using the order ID."},"actionNames":{"type":"array","items":{"type":"string"},"description":"Available actions for this variant","example":["getOrderStatus"]},"requiredConditions":{"type":"array","items":{"type":"string"},"description":"Conditions that must be true for this variant","example":[]}},"required":["id","title","position","botInstructions","actionNames","requiredConditions"]},"description":"Workflow variants with bot instructions"}},"required":["id","title","slug","isLive","whenToFollow","priority","availableChannels","createdAt","isEmbedded","variants"]}},"required":["data"]}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"description":"Invalid request body","type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"description":"Authentication failed","type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}},"404":{"description":"Business not found","content":{"application/json":{"schema":{"description":"Business not found","type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}}}}},"/rest/v1/workflows/{id}":{"delete":{"summary":"Delete a workflow","tags":["Workflows"],"description":"Delete a workflow by ID. This will also delete all associated variants. A backup is saved before deletion.\n\n**Authentication:** Requires a valid API key in the `X-API-Key` header.\nThe workflow must belong to a business within your organization.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true,"description":"Workflow UUID"}],"responses":{"200":{"description":"Workflow deleted successfully","content":{"application/json":{"schema":{"description":"Workflow deleted successfully","type":"object","properties":{"success":{"type":"boolean","description":"Whether the operation succeeded","example":true},"message":{"type":"string","description":"Success message","example":"Workflow deleted successfully"}},"required":["success","message"]}}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"description":"Authentication failed","type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}},"404":{"description":"Workflow not found or not accessible","content":{"application/json":{"schema":{"description":"Workflow not found or not accessible","type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}}}},"patch":{"summary":"Update workflow top-level fields","tags":["Workflows"],"description":"Patch top-level workflow fields (title/whenToFollow/isLive/priority). Creates a new version entry. To replace variants, use the dashboard or POST a new workflow.\n\n**Authentication:** Requires a valid API key in the `X-API-Key` header.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"businessSlug":{"type":"string","description":"Business identifier"},"title":{"type":"string"},"whenToFollow":{"type":"string"},"isLive":{"type":"boolean"},"priority":{"type":"integer"}},"required":["businessSlug"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true,"description":"Workflow UUID"}],"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"description":"Updated","type":"object"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}}}}},"/rest/v1/workflows/{id}/versions":{"get":{"summary":"List workflow version history","tags":["Workflows"],"description":"Return the change history for a workflow (including variant changes), newest first.\n\n**Authentication:** Requires a valid API key in the `X-API-Key` header.","parameters":[{"schema":{"type":"string"},"in":"query","name":"businessSlug","required":true,"description":"Business identifier"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true,"description":"Workflow UUID"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"description":"Successful response","type":"object"}}}}}}},"/rest/v1/workflows/{id}/restore":{"post":{"summary":"Restore a workflow to a previous version","tags":["Workflows"],"description":"Restore a workflow (and its variants) to the state captured in a given version. Works on soft-deleted workflows too.\n\n**Authentication:** Requires a valid API key in the `X-API-Key` header.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"businessSlug":{"type":"string","description":"Business identifier"},"versionId":{"type":"string","format":"uuid","description":"The version ID to restore to"}},"required":["businessSlug","versionId"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true,"description":"Workflow UUID"}],"responses":{"200":{"description":"Restored","content":{"application/json":{"schema":{"description":"Restored","type":"object"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}}}}},"/rest/v1/workflows/deleted":{"get":{"summary":"List soft-deleted workflows","tags":["Workflows"],"description":"List workflows soft-deleted but still restorable.\n\n**Authentication:** Requires a valid API key in the `X-API-Key` header.","parameters":[{"schema":{"type":"string"},"in":"query","name":"businessSlug","required":true,"description":"Business identifier"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"description":"Successful response","type":"object"}}}}}}},"/rest/v1/articles":{"get":{"summary":"List knowledge base articles","tags":["Articles"],"description":"Retrieve a paginated list of knowledge base articles for a specific business.\n\nArticles are used by the AI bot to answer customer questions.\n\n**Authentication:** Requires a valid API key in the `X-API-Key` header.","parameters":[{"schema":{"type":"string"},"in":"query","name":"businessSlug","required":true,"description":"Business identifier (required)"},{"schema":{"type":"integer","exclusiveMinimum":true,"minimum":0,"default":1},"in":"query","name":"page","required":false,"description":"Page number"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"description":"Successful response","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier","example":"a1234567-89ab-cdef-0123-456789abcdef"},"title":{"type":"string","description":"Article title","example":"How to Track Your Order"},"isPublic":{"type":"boolean","description":"Whether article is publicly visible","example":true},"isActive":{"type":"boolean","description":"Whether article is active","example":true},"language":{"type":["string","null"],"description":"Article language (ISO 639-1)","example":"en"},"categoryId":{"type":["string","null"],"format":"uuid","description":"Category the article belongs to","example":"cat12345-6789-abcd-ef01-234567890abc"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp","example":"2024-03-10T11:00:00Z"}},"required":["id","title","isPublic","isActive","createdAt"]},"description":"List of articles"},"pagination":{"type":"object","properties":{"page":{"type":"number","description":"Current page number"},"limit":{"type":"number","description":"Maximum items per page"},"hasMore":{"type":"boolean","description":"Whether more pages exist"}},"required":["page","limit","hasMore"]}},"required":["data","pagination"]}}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"description":"Authentication failed","type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}},"404":{"description":"Business not found","content":{"application/json":{"schema":{"description":"Business not found","type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}}}},"post":{"summary":"Create an article","tags":["Articles"],"description":"Create a new knowledge base article for a business.\n\n**Authentication:** Requires a valid API key in the `X-API-Key` header.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"businessSlug":{"type":"string","description":"Business identifier (required)"},"title":{"type":"string","minLength":1,"description":"Article title"},"content":{"type":"string","minLength":1,"description":"Article body content"},"isPublic":{"type":"boolean"},"isActive":{"type":"boolean"},"categoryId":{"type":"string","format":"uuid"}},"required":["businessSlug","title","content"],"additionalProperties":false}}}},"responses":{"201":{"description":"Article created","content":{"application/json":{"schema":{"description":"Article created","type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier","example":"a1234567-89ab-cdef-0123-456789abcdef"},"title":{"type":"string","description":"Article title","example":"How to Track Your Order"},"isPublic":{"type":"boolean","description":"Whether article is publicly visible","example":true},"isActive":{"type":"boolean","description":"Whether article is active","example":true},"language":{"type":["string","null"],"description":"Article language (ISO 639-1)","example":"en"},"categoryId":{"type":["string","null"],"format":"uuid","description":"Category the article belongs to","example":"cat12345-6789-abcd-ef01-234567890abc"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp","example":"2024-03-10T11:00:00Z"}},"required":["id","title","isPublic","isActive","createdAt"]}},"required":["data"]}}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"description":"Authentication failed","type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}},"404":{"description":"Business not found","content":{"application/json":{"schema":{"description":"Business not found","type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}}}}},"/rest/v1/articles/{id}":{"patch":{"summary":"Update an article","tags":["Articles"],"description":"Update an article. Omitted fields are unchanged. Creates a new version entry.\n\n**Authentication:** Requires a valid API key in the `X-API-Key` header.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"businessSlug":{"type":"string","description":"Business identifier (required)"},"title":{"type":"string","minLength":1},"content":{"type":"string","minLength":1},"isPublic":{"type":"boolean"},"isActive":{"type":"boolean"},"categoryId":{"type":"string","format":"uuid"}},"required":["businessSlug"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true,"description":"Article UUID"}],"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"description":"Updated","type":"object"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}}}},"delete":{"summary":"Soft-delete an article","tags":["Articles"],"description":"Soft-delete an article. Recoverable via /articles/:id/restore.\n\n**Authentication:** Requires a valid API key in the `X-API-Key` header.","parameters":[{"schema":{"type":"string"},"in":"query","name":"businessSlug","required":true,"description":"Business identifier (required)"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true,"description":"Article UUID"}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"description":"Deleted","type":"object"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}}}}},"/rest/v1/articles/{id}/versions":{"get":{"summary":"List article version history","tags":["Articles"],"description":"Return the change history for an article, newest first.\n\n**Authentication:** Requires a valid API key in the `X-API-Key` header.","parameters":[{"schema":{"type":"string"},"in":"query","name":"businessSlug","required":true,"description":"Business identifier (required)"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true,"description":"Article UUID"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"description":"Successful response","type":"object"}}}}}}},"/rest/v1/articles/{id}/restore":{"post":{"summary":"Restore an article to a previous version","tags":["Articles"],"description":"Restore an article (including soft-deleted ones) to the state captured in a given version.\n\n**Authentication:** Requires a valid API key in the `X-API-Key` header.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"businessSlug":{"type":"string","description":"Business identifier (required)"},"versionId":{"type":"string","format":"uuid","description":"The version ID to restore to"}},"required":["businessSlug","versionId"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true,"description":"Article UUID"}],"responses":{"200":{"description":"Restored","content":{"application/json":{"schema":{"description":"Restored","type":"object"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}}}}},"/rest/v1/articles/deleted":{"get":{"summary":"List soft-deleted articles","tags":["Articles"],"description":"List articles soft-deleted but still restorable.\n\n**Authentication:** Requires a valid API key in the `X-API-Key` header.","parameters":[{"schema":{"type":"string"},"in":"query","name":"businessSlug","required":true,"description":"Business identifier (required)"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"description":"Successful response","type":"object"}}}}}}},"/rest/v1/bot-rules":{"get":{"summary":"List bot rules","tags":["Bot Rules"],"description":"Retrieve a paginated list of custom bot rules for a specific business.\n\nBot rules define additional instructions and constraints for the AI bot's behavior.\n\n**Authentication:** Requires a valid API key in the `X-API-Key` header.","parameters":[{"schema":{"type":"string"},"in":"query","name":"businessSlug","required":true,"description":"Business identifier (required)"},{"schema":{"type":"integer","exclusiveMinimum":true,"minimum":0,"default":1},"in":"query","name":"page","required":false,"description":"Page number"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"description":"Successful response","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier","example":"r1234567-89ab-cdef-0123-456789abcdef"},"title":{"type":"string","description":"Rule title","example":"No Competitor Mentions"},"rule":{"type":"string","description":"Rule instruction text","example":"Never mention competitor products or services. Focus only on our offerings."},"channels":{"type":["array","null"],"items":{"type":"string"},"description":"Channels this rule applies to (null = all channels)","example":["web","email"]}},"required":["id","title","rule"]},"description":"List of bot rules"},"pagination":{"type":"object","properties":{"page":{"type":"number","description":"Current page number"},"limit":{"type":"number","description":"Maximum items per page"},"hasMore":{"type":"boolean","description":"Whether more pages exist"}},"required":["page","limit","hasMore"]}},"required":["data","pagination"]}}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"description":"Authentication failed","type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}},"404":{"description":"Business not found","content":{"application/json":{"schema":{"description":"Business not found","type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}}}},"post":{"summary":"Create a bot rule","tags":["Bot Rules"],"description":"Create a new custom bot rule for a specific business.\n\nBot rules define additional instructions and constraints for the AI bot's behavior.\n\n**Authentication:** Requires a valid API key in the `X-API-Key` header.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"businessSlug":{"type":"string","description":"Business identifier (required)"},"title":{"type":"string","minLength":1,"description":"Rule title"},"rule":{"type":"string","minLength":1,"description":"Rule instruction text for the bot"},"channels":{"type":"array","items":{"type":"string","enum":["web","email","whatsapp","messenger","instagram","telegram","sms","phone-call","google-business-messages","google-reviews","trustpilot-reviews","facebookComment","facebookMention","instagramMention","instagramComment","amazon","ebay","aircall","brymec","echo","test-review","zoom-transcript","api"]},"description":"Channels this rule applies to (omit for all channels)"}},"required":["businessSlug","title","rule"],"additionalProperties":false}}}},"responses":{"201":{"description":"Bot rule created successfully","content":{"application/json":{"schema":{"description":"Bot rule created successfully","type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier","example":"r1234567-89ab-cdef-0123-456789abcdef"},"title":{"type":"string","description":"Rule title","example":"No Competitor Mentions"},"rule":{"type":"string","description":"Rule instruction text","example":"Never mention competitor products or services. Focus only on our offerings."},"channels":{"type":["array","null"],"items":{"type":"string"},"description":"Channels this rule applies to (null = all channels)","example":["web","email"]}},"required":["id","title","rule"]}},"required":["data"]}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"description":"Invalid request body","type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"description":"Authentication failed","type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}},"404":{"description":"Business not found","content":{"application/json":{"schema":{"description":"Business not found","type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}}}}},"/rest/v1/bot-rules/{id}":{"delete":{"summary":"Delete a bot rule","tags":["Bot Rules"],"description":"Delete a bot rule by ID.\n\n**Authentication:** Requires a valid API key in the `X-API-Key` header.\nThe bot rule must belong to a business within your organization.","parameters":[{"schema":{"type":"string"},"in":"query","name":"businessSlug","required":true,"description":"Business identifier (required)"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true,"description":"Bot rule UUID"}],"responses":{"200":{"description":"Bot rule deleted successfully","content":{"application/json":{"schema":{"description":"Bot rule deleted successfully","type":"object","properties":{"success":{"type":"boolean","description":"Whether the operation succeeded","example":true},"message":{"type":"string","description":"Success message","example":"Bot rule deleted successfully"}},"required":["success","message"]}}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"description":"Authentication failed","type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}},"404":{"description":"Bot rule not found or not accessible","content":{"application/json":{"schema":{"description":"Bot rule not found or not accessible","type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}}}},"patch":{"summary":"Update a bot rule","tags":["Bot Rules"],"description":"Update a bot rule by ID. Omitted fields are left unchanged. Creates a new version entry.\n\n**Authentication:** Requires a valid API key in the `X-API-Key` header.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"businessSlug":{"type":"string","description":"Business identifier (required)"},"title":{"type":"string","minLength":1,"description":"New rule title"},"rule":{"type":"string","minLength":1,"description":"New rule instruction text"},"channels":{"type":"array","items":{"type":"string","enum":["web","email","whatsapp","messenger","instagram","telegram","sms","phone-call","google-business-messages","google-reviews","trustpilot-reviews","facebookComment","facebookMention","instagramMention","instagramComment","amazon","ebay","aircall","brymec","echo","test-review","zoom-transcript","api"]},"nullable":true,"description":"Channels (omit to leave unchanged, null to apply to all)"}},"required":["businessSlug"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true,"description":"Bot rule UUID"}],"responses":{"200":{"description":"Bot rule updated successfully","content":{"application/json":{"schema":{"description":"Bot rule updated successfully","type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier","example":"r1234567-89ab-cdef-0123-456789abcdef"},"title":{"type":"string","description":"Rule title","example":"No Competitor Mentions"},"rule":{"type":"string","description":"Rule instruction text","example":"Never mention competitor products or services. Focus only on our offerings."},"channels":{"type":["array","null"],"items":{"type":"string"},"description":"Channels this rule applies to (null = all channels)","example":["web","email"]}},"required":["id","title","rule"]}},"required":["data"]}}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"description":"Authentication failed","type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}},"404":{"description":"Bot rule not found","content":{"application/json":{"schema":{"description":"Bot rule not found","type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}}}}},"/rest/v1/bot-rules/{id}/versions":{"get":{"summary":"List bot rule versions","tags":["Bot Rules"],"description":"Return the change history for a bot rule, newest first. Each entry includes who made the change, when, and the rule contents at that point.\n\n**Authentication:** Requires a valid API key in the `X-API-Key` header.","parameters":[{"schema":{"type":"string"},"in":"query","name":"businessSlug","required":true,"description":"Business identifier (required)"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true,"description":"Bot rule UUID"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"description":"Successful response","type":"object"}}}},"404":{"description":"Bot rule not found","content":{"application/json":{"schema":{"description":"Bot rule not found","type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}}}}},"/rest/v1/bot-rules/{id}/restore":{"post":{"summary":"Restore a bot rule to a previous version","tags":["Bot Rules"],"description":"Restore a bot rule (including soft-deleted ones) to the state captured in a given version. Creates a new 'restored' version entry.\n\n**Authentication:** Requires a valid API key in the `X-API-Key` header.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"businessSlug":{"type":"string","description":"Business identifier (required)"},"versionId":{"type":"string","format":"uuid","description":"The entityVersions ID to restore to"}},"required":["businessSlug","versionId"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true,"description":"Bot rule UUID"}],"responses":{"200":{"description":"Bot rule restored","content":{"application/json":{"schema":{"description":"Bot rule restored","type":"object"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}}}}},"/rest/v1/bot-rules/deleted":{"get":{"summary":"List soft-deleted bot rules","tags":["Bot Rules"],"description":"List bot rules that have been soft-deleted but can still be restored via /bot-rules/:id/restore.\n\n**Authentication:** Requires a valid API key in the `X-API-Key` header.","parameters":[{"schema":{"type":"string"},"in":"query","name":"businessSlug","required":true,"description":"Business identifier (required)"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"description":"Successful response","type":"object"}}}},"404":{"description":"Business not found","content":{"application/json":{"schema":{"description":"Business not found","type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}}}}},"/rest/v1/businesses":{"get":{"summary":"List businesses","tags":["Businesses"],"description":"Retrieve a list of all businesses in your organization.\n\nUse the returned `slug` values when calling business-scoped endpoints like workflows, articles, and bot rules.\n\n**Authentication:** Requires a valid API key in the `X-API-Key` header.","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"description":"Successful response","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier","example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"},"slug":{"type":"string","description":"Business slug (use this for business-scoped API calls)","example":"acme-corp"},"name":{"type":"string","description":"Business display name","example":"Acme Corporation"}},"required":["id","slug","name"]},"description":"List of businesses"}},"required":["data"]}}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"description":"Authentication failed","type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}}}}},"/rest/v1/sheets/rows":{"post":{"summary":"Add a row to a Google Sheet","tags":["Google Sheets"],"description":"Add a new row to the first sheet of a Google Sheets document.\n\n**Prerequisites:**\n1. Share your Google Sheet with the Octocom service account as an editor:\n   `octocom-google-sheets@octocom.iam.gserviceaccount.com`\n2. Get the spreadsheet ID from your Google Sheets URL (the part between /d/ and /edit)\n\n**How it works:**\n- The keys in your `data` object become column headers\n- The values become the row data\n- If headers don't exist, they will be created\n\n**Authentication:** Requires a valid API key in the `X-API-Key` header.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"spreadsheetId":{"type":"string","minLength":1,"description":"The Google Sheets spreadsheet ID (from the URL between /d/ and /edit)"},"data":{"type":"object","additionalProperties":{"type":"string"},"description":"Key-value pairs where keys are column headers and values are cell data"}},"required":["spreadsheetId","data"],"additionalProperties":false}}}},"responses":{"200":{"description":"Row added successfully","content":{"application/json":{"schema":{"description":"Row added successfully","type":"object","properties":{"success":{"type":"boolean","description":"Whether the operation succeeded","example":true},"message":{"type":"string","description":"Success or error message","example":"Row added successfully"}},"required":["success","message"]}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"description":"Invalid request body","type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}},"401":{"description":"Authentication failed - invalid or missing API key","content":{"application/json":{"schema":{"description":"Authentication failed - invalid or missing API key","type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}},"403":{"description":"Service account doesn't have editor access to the spreadsheet","content":{"application/json":{"schema":{"description":"Service account doesn't have editor access to the spreadsheet","type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}},"404":{"description":"Spreadsheet not found","content":{"application/json":{"schema":{"description":"Spreadsheet not found","type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}},"500":{"description":"Google Sheets API error","content":{"application/json":{"schema":{"description":"Google Sheets API error","type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}}}}},"/rest/v1/conversations/tags":{"post":{"summary":"Add a tag to a conversation","tags":["Conversations"],"description":"Add a tag to a conversation. If the tag doesn't exist in your organization, it will be created automatically.\n\n**How it works:**\n- Provide the conversation ID (UUID or publicId) and the tag text\n- If the tag already exists, it will be linked to the conversation\n- If the tag is already on the conversation, the operation succeeds without duplicating\n\n**Authentication:** Requires a valid API key in the `X-API-Key` header.\nThe conversation must belong to a business within your organization.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"conversationId":{"type":"string","minLength":1,"description":"The conversation UUID or publicId"},"tag":{"type":"string","minLength":1,"maxLength":100,"description":"The tag text to add to the conversation"}},"required":["conversationId","tag"],"additionalProperties":false}}}},"responses":{"200":{"description":"Tag added successfully","content":{"application/json":{"schema":{"description":"Tag added successfully","type":"object","properties":{"success":{"type":"boolean","description":"Whether the operation succeeded","example":true},"message":{"type":"string","description":"Success or error message","example":"Tag added successfully"},"tagId":{"type":"string","format":"uuid","description":"ID of the created or existing tag","example":"t1234567-89ab-cdef-0123-456789abcdef"}},"required":["success","message","tagId"]}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"description":"Invalid request body","type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}},"401":{"description":"Authentication failed - invalid or missing API key","content":{"application/json":{"schema":{"description":"Authentication failed - invalid or missing API key","type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}},"404":{"description":"Conversation not found or not accessible","content":{"application/json":{"schema":{"description":"Conversation not found or not accessible","type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}}}}},"/rest/v1/conversations/events":{"post":{"summary":"Create a conversation event","tags":["Conversations"],"description":"Create a custom event for a conversation.\n\n**How it works:**\n- Provide the conversation ID (UUID or publicId) and the event text\n- The event is stored as a raw string event in the conversation timeline\n\n**Authentication:** Requires a valid API key in the `X-API-Key` header.\nThe conversation must belong to a business within your organization.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"conversationId":{"type":"string","minLength":1,"description":"The conversation UUID or publicId"},"event":{"type":"string","minLength":1,"maxLength":1000,"description":"The event text to record"}},"required":["conversationId","event"],"additionalProperties":false}}}},"responses":{"200":{"description":"Event created successfully","content":{"application/json":{"schema":{"description":"Event created successfully","type":"object","properties":{"success":{"type":"boolean","description":"Whether the operation succeeded","example":true},"message":{"type":"string","description":"Success or error message","example":"Event created successfully"},"eventId":{"type":"string","format":"uuid","description":"ID of the created event","example":"e1234567-89ab-cdef-0123-456789abcdef"}},"required":["success","message","eventId"]}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"description":"Invalid request body","type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}},"401":{"description":"Authentication failed - invalid or missing API key","content":{"application/json":{"schema":{"description":"Authentication failed - invalid or missing API key","type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}},"404":{"description":"Conversation not found or not accessible","content":{"application/json":{"schema":{"description":"Conversation not found or not accessible","type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}}}}},"/rest/v1/conversations/outbound-email":{"post":{"summary":"Send an outbound email and create a handed-off conversation","tags":["Conversations"],"description":"Send an outbound email from a business in your organization to an arbitrary recipient. Creates a new conversation that is already handed off so the bot will not respond.\n\n**How it works:**\n- Provide the `businessSlug` of the business that should send the email — it must have an email integration installed\n- Provide the recipient address, subject and plain-text body\n- Optionally attach a list of tags to the created conversation\n- The conversation is created with `isOutbound: true` and is handed off\n\n**Authentication:** Requires a valid API key in the `X-API-Key` header. The business must belong to your organization.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"businessSlug":{"type":"string","minLength":1,"description":"Slug of the business to send the email from"},"to":{"type":"string","format":"email","description":"Recipient email address"},"subject":{"type":"string","minLength":1,"maxLength":998,"description":"Email subject line"},"text":{"type":"string","minLength":1,"description":"Plain-text body of the email"},"customerName":{"type":"string","description":"Optional recipient name"},"tags":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"description":"Optional tags to attach to the created conversation"}},"required":["businessSlug","to","subject","text"],"additionalProperties":false}}}},"responses":{"200":{"description":"Outbound email queued successfully","content":{"application/json":{"schema":{"description":"Outbound email queued successfully","type":"object","properties":{"success":{"type":"boolean","description":"Whether the operation succeeded","example":true},"conversationId":{"type":"string","format":"uuid","description":"ID of the created conversation","example":"550e8400-e29b-41d4-a716-446655440000"},"publicId":{"type":"string","description":"Public-facing ID of the created conversation","example":"CONV-2024-001234"}},"required":["success","conversationId","publicId"]}}}},"400":{"description":"Invalid request body, or business has no email integration configured","content":{"application/json":{"schema":{"description":"Invalid request body, or business has no email integration configured","type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}},"401":{"description":"Authentication failed - invalid or missing API key","content":{"application/json":{"schema":{"description":"Authentication failed - invalid or missing API key","type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}},"404":{"description":"Business not found or not accessible","content":{"application/json":{"schema":{"description":"Business not found or not accessible","type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}}}}},"/rest/v1/conversations/{id}/metadata":{"post":{"summary":"Set a metadata key-value pair for a conversation","tags":["Conversations"],"description":"Store a metadata key-value pair scoped to a specific conversation.\n\n**Limitations:**\n- Key: maximum 200 characters\n- Value: maximum 50,000 characters\n- Maximum 200 pairs per conversation\n\nIf the key already exists, the value is updated.\n\n**Authentication:** Requires a valid API key in the `X-API-Key` header.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":200,"description":"Metadata key (max 200 chars)"},"value":{"type":"string","maxLength":50000,"description":"Value to store (max 50,000 chars)"}},"required":["key","value"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true,"description":"Conversation UUID"}],"responses":{"200":{"description":"Value stored successfully","content":{"application/json":{"schema":{"description":"Value stored successfully","type":"object","properties":{"success":{"type":"boolean","description":"Whether the operation succeeded"},"message":{"type":"string","description":"Success or error message"},"key":{"type":"string","description":"The metadata key"},"value":{"type":"string","description":"The metadata value"}},"required":["success","message"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"description":"Invalid request","type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"description":"Authentication failed","type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}},"404":{"description":"Conversation not found","content":{"application/json":{"schema":{"description":"Conversation not found","type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}},"429":{"description":"Pair limit exceeded","content":{"application/json":{"schema":{"description":"Pair limit exceeded","type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}}}},"get":{"summary":"Get all metadata key-value pairs for a conversation","tags":["Conversations"],"description":"Retrieve all metadata key-value pairs for a specific conversation.\n\n**Authentication:** Requires a valid API key in the `X-API-Key` header.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true,"description":"Conversation UUID"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"description":"Successful response","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","description":"Metadata key","maxLength":200},"value":{"type":"string","description":"Metadata value","maxLength":50000},"createdAt":{"type":"string","format":"date-time","description":"When first created"},"updatedAt":{"type":"string","format":"date-time","description":"When last updated"}},"required":["key","value","createdAt","updatedAt"]}}}}}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"description":"Authentication failed","type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}}}}},"/rest/v1/conversations/{id}/metadata/{key}":{"get":{"summary":"Get a specific metadata value for a conversation","tags":["Conversations"],"description":"Retrieve a specific metadata value by key for a conversation.\n\n**Authentication:** Requires a valid API key in the `X-API-Key` header.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true,"description":"Conversation UUID"},{"schema":{"type":"string","minLength":1},"in":"path","name":"key","required":true,"description":"Metadata key"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"description":"Successful response","type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"}}}}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"description":"Authentication failed","type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}},"404":{"description":"Key not found","content":{"application/json":{"schema":{"description":"Key not found","type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}}}},"delete":{"summary":"Delete a metadata key from a conversation","tags":["Conversations"],"description":"Delete a specific metadata key-value pair from a conversation.\n\n**Authentication:** Requires a valid API key in the `X-API-Key` header.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true,"description":"Conversation UUID"},{"schema":{"type":"string","minLength":1},"in":"path","name":"key","required":true,"description":"Metadata key to delete"}],"responses":{"200":{"description":"Key deleted successfully","content":{"application/json":{"schema":{"description":"Key deleted successfully","type":"object","properties":{"success":{"type":"boolean","description":"Whether the operation succeeded"},"message":{"type":"string","description":"Success or error message"},"key":{"type":"string","description":"The metadata key"},"value":{"type":"string","description":"The metadata value"}},"required":["success","message"]}}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"description":"Authentication failed","type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}},"404":{"description":"Key not found","content":{"application/json":{"schema":{"description":"Key not found","type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}}}}},"/rest/v1/customers/{id}":{"patch":{"summary":"Update a customer and optionally set metadata","tags":["Customers"],"description":"Update a customer's standard fields (name, phone, email) and/or upsert metadata key-value pairs in a single call.\n\n**Authentication:** Requires a valid API key in the `X-API-Key` header.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"phone":{"type":"string"},"email":{"type":"string"},"metadata":{"type":"object","additionalProperties":{"type":"string"}}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true,"description":"Customer UUID"}],"responses":{"200":{"description":"Default Response"}}}},"/rest/v1/customers/{id}/metadata":{"post":{"summary":"Set a metadata key-value pair for a customer","tags":["Customers"],"description":"Store or update a metadata key-value pair scoped to a specific customer.\n\n**Authentication:** Requires a valid API key in the `X-API-Key` header.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":200,"description":"Metadata key"},"value":{"type":"string","minLength":1,"maxLength":50000,"description":"Metadata value"}},"required":["key","value"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true,"description":"Customer UUID"}],"responses":{"200":{"description":"Default Response"}}}},"/rest/v1/bot/conversations":{"post":{"summary":"Start a bot conversation","tags":["Bot Conversations"],"description":"Start a new conversation with the Octocom bot.\n\n**How it works:**\n- Send input text (simulating customer input) and receive the bot's response\n- The bot processes your input using the business's knowledge base, workflows, and configuration\n- You cannot create agent messages or bypass the bot - all responses come from the bot\n\n**Async mode:**\n- Set `async: true` to return immediately without waiting for the bot response\n- Poll `GET /rest/v1/conversations/:id` to retrieve the conversation with the bot's response\n- Useful for avoiding timeouts with complex queries or high latency\n\n**Metadata:**\n- Optionally attach key-value metadata pairs at creation time\n- Same limits as the metadata endpoint: keys max 200 chars, values max 50,000 chars, max 200 pairs per conversation\n\n**Rate limits:**\n- Maximum 100 conversations per hour per organization\n- Maximum 50 messages per conversation\n\n**Authentication:** Requires a valid API key in the `X-API-Key` header.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"businessSlug":{"type":"string","minLength":1,"description":"Business identifier (use /rest/v1/businesses to list)"},"message":{"type":"string","minLength":1,"maxLength":5000,"description":"The input to send to the bot (max 5000 characters)"},"async":{"type":"boolean","default":false,"description":"When true, returns immediately without waiting for bot response. Poll GET /rest/v1/conversations/:id to retrieve the bot's response."},"customer":{"type":"object","properties":{"email":{"type":"string","format":"email","description":"Customer email to associate with the conversation"},"name":{"type":"string","description":"Customer name"},"phone":{"type":"string","description":"Customer phone number"}},"additionalProperties":false,"description":"Optional customer information to link to the conversation"},"metadata":{"type":"object","additionalProperties":{"type":"string","maxLength":50000},"description":"Optional key-value metadata pairs to attach to the conversation (max 200 pairs, keys max 200 chars, values max 50,000 chars)"}},"required":["businessSlug","message"],"additionalProperties":false}}}},"responses":{"200":{"description":"Conversation started successfully","content":{"application/json":{"schema":{"description":"Conversation started successfully","type":"object","properties":{"data":{"type":"object","properties":{"conversationId":{"type":"string","format":"uuid","description":"Unique conversation identifier"},"publicId":{"type":"string","description":"Human-readable conversation ID","example":"CONV-2024-001234"},"customerMessageId":{"type":"string","format":"uuid","description":"ID of the customer message that was created"},"botResponse":{"type":"string","description":"The bot's response (only present in synchronous mode when bot responds)"}},"required":["conversationId","publicId","customerMessageId"]}},"required":["data"]}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"description":"Invalid request body","type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}},"401":{"description":"Authentication failed - invalid or missing API key","content":{"application/json":{"schema":{"description":"Authentication failed - invalid or missing API key","type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}},"404":{"description":"Business not found","content":{"application/json":{"schema":{"description":"Business not found","type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}},"408":{"description":"Bot response timeout (30 seconds, only in synchronous mode)","content":{"application/json":{"schema":{"description":"Bot response timeout (30 seconds, only in synchronous mode)","type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}},"429":{"description":"Rate limit exceeded (100 conversations per hour)","content":{"application/json":{"schema":{"description":"Rate limit exceeded (100 conversations per hour)","type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}}}}},"/rest/v1/bot/conversations/{id}/messages":{"post":{"summary":"Send a message to the bot","tags":["Bot Conversations"],"description":"Send a follow-up message in an existing bot conversation and receive the bot's response.\n\n**How it works:**\n- Send input text and receive the bot's response\n- The bot maintains conversation context from previous messages\n- You cannot create agent messages or bypass the bot - all responses come from the bot\n\n**Async mode:**\n- Set `async: true` to return immediately without waiting for the bot response\n- Poll `GET /rest/v1/conversations/:id` to retrieve the conversation with the bot's response\n- Useful for avoiding timeouts with complex queries or high latency\n\n**Rate limits:**\n- Maximum 50 messages per conversation\n\n**Authentication:** Requires a valid API key in the `X-API-Key` header.\nThe conversation must have been created via this API by your organization.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","minLength":1,"maxLength":5000,"description":"The input to send to the bot (max 5000 characters)"},"async":{"type":"boolean","default":false,"description":"When true, returns immediately without waiting for bot response. Poll GET /rest/v1/conversations/:id to retrieve the bot's response."}},"required":["message"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"id","required":true,"description":"Conversation ID (UUID or publicId)"}],"responses":{"200":{"description":"Message sent successfully","content":{"application/json":{"schema":{"description":"Message sent successfully","type":"object","properties":{"data":{"type":"object","properties":{"customerMessageId":{"type":"string","format":"uuid","description":"ID of the customer message that was created"},"botResponse":{"type":"string","description":"The bot's response (only present in synchronous mode when bot responds)"}},"required":["customerMessageId"]}},"required":["data"]}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"description":"Invalid request body","type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}},"401":{"description":"Authentication failed - invalid or missing API key","content":{"application/json":{"schema":{"description":"Authentication failed - invalid or missing API key","type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}},"403":{"description":"Conversation not created via API by your organization","content":{"application/json":{"schema":{"description":"Conversation not created via API by your organization","type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}},"404":{"description":"Conversation not found","content":{"application/json":{"schema":{"description":"Conversation not found","type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}},"408":{"description":"Bot response timeout (30 seconds, only in synchronous mode)","content":{"application/json":{"schema":{"description":"Bot response timeout (30 seconds, only in synchronous mode)","type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}},"429":{"description":"Message limit exceeded (50 messages per conversation)","content":{"application/json":{"schema":{"description":"Message limit exceeded (50 messages per conversation)","type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}}}}},"/rest/v1/browser-sessions/{browserSessionId}/purchases":{"post":{"summary":"Record a purchase for a browser session","tags":["Browser Sessions"],"description":"Record a purchase associated with a browser session.\n\nThis endpoint allows you to track purchases made by users during their browser session.\nThis endpoint is called from websites and does not require authentication, only rate limiting.\n\n**Rate Limits:** Maximum 100 requests per minute per IP address.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"lineItems":{"anyOf":[{"type":"array","items":{}},{"type":"object","additionalProperties":{}}],"description":"Purchase line items (will be stored as JSON)"},"totalPrice":{"type":"number","exclusiveMinimum":true,"minimum":0,"description":"Total price of the purchase"},"currencyCode":{"type":"string","minLength":1,"description":"Currency code (e.g., 'USD', 'EUR')"},"provider":{"type":"string","minLength":1,"default":"api","description":"Provider identifier (e.g., 'shopify', 'api')"},"orderId":{"type":"string","minLength":1,"description":"Optional merchant-defined order identifier for reconciliation (any string, e.g. '#1042' or 'order_abc123')."}},"required":["lineItems","totalPrice","currencyCode"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"browserSessionId","required":true,"description":"Browser session UUID"}],"responses":{"201":{"description":"Purchase recorded successfully","content":{"application/json":{"schema":{"description":"Purchase recorded successfully","type":"object","properties":{"success":{"type":"boolean","description":"Whether the operation succeeded","example":true},"message":{"type":"string","description":"Success message","example":"Purchase recorded successfully"},"id":{"type":"string","format":"uuid","description":"ID of the created purchase record"}},"required":["success","message","id"]}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"description":"Invalid request body","type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}},"404":{"description":"Browser session not found","content":{"application/json":{"schema":{"description":"Browser session not found","type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"description":"Rate limit exceeded","type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}}}}}}}},"servers":[{"url":"https://api.octocom.ai","description":"Production"}],"tags":[{"name":"Businesses","description":"List businesses in your organization. Use business slugs when calling business-scoped endpoints."},{"name":"Conversations","description":"Access customer conversation data including messages, AI analysis, and agent notes."},{"name":"Customers","description":"Retrieve customer contact information and profiles."},{"name":"Custom Data","description":"Access AI-classified data extracted from conversations for analytics and reporting."},{"name":"Users","description":"List team members and agents in your organization."},{"name":"Teams","description":"View team structure and organization."},{"name":"Macros","description":"Access response templates used by agents."},{"name":"Workflows","description":"Manage bot automation workflows that handle customer inquiries."},{"name":"Articles","description":"Access knowledge base articles used by the AI to answer questions."},{"name":"Bot Rules","description":"View custom instructions that guide AI bot behavior."},{"name":"Google Sheets","description":"Add data to Google Sheets. Share your sheet with octocom-google-sheets@octocom.iam.gserviceaccount.com as editor."},{"name":"Browser Sessions","description":"Record purchases for browser sessions (e.g. custom sale attribution). No authentication; rate limited by IP."}]}