{ "openapi": "3.0.3", "info": { "title": "Fernand API Documentation", "version": "3.0", "description": "This is the documentation for the [Fernand](https://getfernand.com) API.", "termsOfService": "https://getfernand.com/terms", "contact": { "name": "Fernand Support", "url": "https://getfernand.com", "email": "support@getfernand.com" }, "x-logo": { "url": "https://app.getfernand.com/images/favicon/icon_128.png" } }, "servers": [ { "url": "https://api.getfernand.com", "description": "", "x-last-modified": 1764750693905 } ], "paths": { "/agents/pending": { "get": { "operationId": "listPendingInvites", "tags": [ "Agents" ], "responses": { "200": { "description": "Successfully retrieved pending invitations. Returns empty array if actor lacks teammate.invite permission.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AgentInvite" } } } } }, "401": { "description": "Unauthorized if API authentication is invalid or missing.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } }, "summary": "Retrieve pending agent invitations", "description": "Returns all pending agent invitations for the organization.", "x-mint": { "metadata": { "description": "" }, "content": "Returns all pending agent invitations for the organization." }, "x-computed-hash": "b9b074aafcf4f2171edfec35282ee43861ce1227516623eebc4e2c5d35fa59b7", "x-last-modified": 1769076834 } }, "/agents": { "get": { "operationId": "listAgents", "tags": [ "Agents" ], "parameters": [ { "name": "complete", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "If true, includes roles and owner status in the response." } ], "responses": { "200": { "description": "Successfully retrieved the list of agents.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Agent" } } } } }, "401": { "description": "Unauthorized if API authentication is invalid or missing.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } }, "summary": "Retrieve all the agents", "description": "Returns a list of all active agents in the organization.", "x-mint": { "metadata": { "description": "" }, "content": "Returns a list of all active agents in the organization." }, "x-computed-hash": "84b0b2761b5befb857390496878af4b569107f6627d14597f3b3df034ffc75da", "x-last-modified": 1769076834 } }, "/contacts": { "get": { "operationId": "searchContacts", "tags": [ "Contacts" ], "parameters": [ { "name": "query", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Search query string. If contains \"@\", searches email only. Otherwise searches both name and email.", "example": "richard" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 10, "maximum": 99, "minimum": 1 }, "description": "Maximum number of contacts to return." } ], "responses": { "200": { "description": "List of contacts matching the search query.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" } } } } }, "400": { "description": "Invalid limit parameter (must be between 1 and 99).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } }, "summary": "Search for contacts", "description": "Retrieves a list of contacts that match the provided query string. The search behavior depends on whether the query contains an \"@\" symbol: if present, it searches by email only; otherwise, it searches both name and email fields. Only trusted contacts (session_uuid is null) are returned in the results.", "x-mint": { "metadata": { "description": "" }, "content": "Retrieves a list of contacts that match the provided query string. The search behavior depends on whether the query contains an \"@\" symbol: if present, it searches by email only; otherwise, it searches both name and email fields. Only trusted contacts (session_uuid is null) are returned in the results." }, "x-computed-hash": "639c3fd18b46777ca2303bc0ba615b83570dcc337fd98a434dfb41511fd4f33d", "x-last-modified": 1769076834 } }, "/contacts/suppressed": { "get": { "operationId": "listSuppressedContacts", "tags": [ "Contact Suppressions" ], "parameters": [ { "name": "order_by", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "contact", "blocked", "created" ], "default": "created" }, "description": "Field to order results by. \"contact\" orders by domain name.", "example": "created" }, { "name": "way", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" }, "description": "Sort direction for the results.", "example": "desc" } ], "responses": { "200": { "description": "List of suppressed contacts retrieved successfully.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "Unique identifier for the suppression record", "example": 123 }, "email": { "type": "string", "description": "Suppressed email address or domain pattern (e.g., \"*@domain.com\")", "example": "spam@hooli.com" }, "created": { "type": "string", "format": "date-time", "description": "Timestamp when the suppression was created (UTC)", "example": "2024-01-15T10:30:00Z" }, "blocked": { "type": "integer", "description": "Number of times emails to this address/domain have been blocked", "example": 5 }, "is_common": { "type": "boolean", "description": "Whether this is a common webmail domain (true) or a company domain (false)", "example": true } } } } } } }, "400": { "description": "Invalid order_by or way parameter.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } }, "summary": "List all suppressed contacts or domains", "description": "Retrieves a list of all suppressed email addresses and domains within the organization. Results can be sorted by contact/domain, blocked count, or creation date in ascending or descending order. Suppressed entries prevent emails from being received from those addresses or domains.", "x-mint": { "metadata": { "description": "" }, "content": "Retrieves a list of all suppressed email addresses and domains within the organization. Results can be sorted by contact/domain, blocked count, or creation date in ascending or descending order. Suppressed entries prevent emails from being received from those addresses or domains." }, "x-computed-hash": "4d758ab9c798ddafc358b536a8d5b02f649971639c05b59edea363f4fbaeba2d", "x-last-modified": 1769076834 }, "post": { "operationId": "addSuppressedContact", "tags": [ "Contact Suppressions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "Email address to suppress, or domain pattern \"*@domain.com\" to suppress entire domain.", "example": "galvin@hooli.com" } }, "required": [ "email" ] } } } }, "responses": { "200": { "description": "Email or domain suppressed successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "Unique identifier for the suppression record" }, "email": { "type": "string", "description": "Suppressed email or domain pattern" }, "created": { "type": "string", "format": "date-time", "description": "Timestamp when the suppression was created (UTC)" }, "blocked": { "type": "integer", "description": "Number of times emails to this address/domain have been blocked" }, "is_common": { "type": "boolean", "description": "Whether this is a common webmail domain (true) or a company domain (false)" } } } } } }, "400": { "description": "Invalid email format or email/domain already suppressed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "The email spam@example.com is already suppressed." } } } } } } }, "summary": "Add an email or domain to the suppression list", "description": "Suppresses an email address or entire domain to prevent sending emails to them. For domain-level suppression, use the pattern \"*@domain.com\" which will suppress all emails from that domain and consolidate existing suppressions for that domain. The endpoint validates the email format and prevents duplicate suppressions.", "x-mint": { "metadata": { "description": "" }, "content": "Suppresses an email address or entire domain to prevent sending emails to them. For domain-level suppression, use the pattern \"*@domain.com\" which will suppress all emails from that domain and consolidate existing suppressions for that domain. The endpoint validates the email format and prevents duplicate suppressions." }, "x-computed-hash": "d4160da1fb588edb24dbebf9c86b38cbbf4d67da28f2f0ce68015848ad882a72", "x-last-modified": 1769076834 } }, "/conversations": { "get": { "operationId": "listConversations", "tags": [ "Conversations" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 3, "maximum": 250, "default": 25 }, "description": "Maximum number of conversations to return per page." }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Search query string. Supports filtering by status, agent, tags, and keywords.\nExamples:\n - \"status:opened\" - Filter by status (opened, closed, spam, snoozed)\n - \"assigned:jared@piedpiper.com\" - Filter by agent email\n - \"unassigned:true\" - Show only unassigned conversations\n - \"tag:urgent\" - Filter by tag\n - \"keyword search\" - Full-text search in conversation content\n" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Pagination cursor from the previous response to fetch the next page." }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "priority", "oldest", "newest", "longest" ], "default": "priority" }, "description": "Sort order for conversations (priority, oldest, newest, or longest)." } ], "responses": { "200": { "description": "List of conversations retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Conversation" } }, "cursor": { "type": "string", "nullable": true, "description": "Cursor for fetching the next page, or null if no more results." } } } } } }, "400": { "description": "Invalid parameters provided.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } }, "summary": "List conversations", "description": "Retrieves a paginated list of conversations for the authenticated organization. Supports filtering by status, agent assignment, tags, and full-text search. Results can be ordered by priority, date, or longest wait time. Pagination is cursor-based for efficient traversal of large datasets.", "x-mint": { "metadata": { "description": "" }, "content": "Retrieves a paginated list of conversations for the authenticated organization. Supports filtering by status, agent assignment, tags, and full-text search. Results can be ordered by priority, date, or longest wait time. Pagination is cursor-based for efficient traversal of large datasets." }, "x-computed-hash": "3ca518a8063300691a736cc5435ee6ca4ef6c8babc921c702d3f0fb00b658341", "x-last-modified": 1769076869 } }, "/conversations/bulk": { "post": { "operationId": "bulkUpdateConversations", "tags": [ "Conversations" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "integer", "format": "int64" }, "description": "Array of conversation IDs to update." }, "status": { "type": "string", "enum": [ "OPENED", "CLOSED", "SPAM", "SNOOZED", "DELETE" ], "description": "New status for the conversations. DELETE will permanently delete them." }, "snooze_until": { "type": "string", "description": "When status is SNOOZED, specifies when to unsnooze. Formats:\n- \"5m\", \"+30\" (minutes from now)\n- \"tomorrow\", \"monday\", \"tuesday\", etc. (next occurrence at 9am)\n- \"one week\", \"one month\" (relative periods)\n- ISO 8601 timestamp (absolute time)\n" }, "agent_id": { "type": "integer", "format": "int64", "nullable": true, "description": "ID of agent to assign. Use null to unassign." }, "agent_email": { "type": "string", "description": "Email of agent to assign (alternative to agent_id)." }, "tag": { "type": "string", "maxLength": 50, "description": "Tag name to add to the conversations." }, "untag": { "type": "string", "description": "Tag name to remove from the conversations." }, "block": { "type": "boolean", "description": "When marking as SPAM, whether to also block the contact (requires contact.block permission)." } }, "required": [ "ids" ] } } } }, "responses": { "200": { "description": "Conversations updated successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "conversations": { "type": "array", "items": { "$ref": "#/components/schemas/Conversation" }, "description": "Array of successfully updated conversations." } } } } } }, "400": { "description": "Invalid input or agent not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Missing required permission for the requested operation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } }, "summary": "Bulk update multiple conversations", "description": "Updates multiple conversations in a single request. Supports changing status, assigning agents, and managing tags. Status changes to SPAM can optionally block the contact. Changes are applied atomically per conversation, and only successful updates are returned.", "x-mint": { "metadata": { "description": "" }, "content": "Updates multiple conversations in a single request. Supports changing status, assigning agents, and managing tags. Status changes to SPAM can optionally block the contact. Changes are applied atomically per conversation, and only successful updates are returned." }, "x-computed-hash": "108c525b4bc0768236c715668410aebab4ca61b08dd03b60fafd0794816710b7", "x-last-modified": 1769076834 } }, "/conversations/compose": { "post": { "operationId": "composeEmail", "tags": [ "Conversations" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "channel_id": { "type": "integer", "format": "int64", "description": "ID of the channel to send from (determines the sender email address)." }, "to": { "type": "string", "description": "Comma-separated list of recipient email addresses (can include names like `Monica Hall `)." }, "cc": { "type": "string", "description": "Comma-separated list of CC recipient email addresses (optional)." }, "bcc": { "type": "string", "description": "Comma-separated list of BCC recipient email addresses (optional)." }, "subject": { "type": "string", "maxLength": 150, "description": "Subject line of the email (optional)." }, "content": { "type": "object", "description": "Email content and metadata.", "properties": { "content": { "type": "string", "description": "HTML content of the email body (required)." }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Filename of the attachment." }, "type": { "type": "string", "description": "MIME type of the attachment." }, "content": { "type": "string", "format": "byte", "description": "Base64-encoded file content (max 5MB per file)." } } }, "description": "Array of file attachments (optional)." }, "actions": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the action to execute (e.g., teammates.assign, status.close)." }, "data": { "type": "object", "description": "Action-specific parameters." }, "snippet_id": { "type": "integer", "description": "ID of the snippet this action came from (for tracking)." } } }, "description": "Automated actions to execute after sending (optional)." } } }, "delay": { "type": "integer", "minimum": 0, "maximum": 86400, "default": 7, "description": "Delay in seconds before sending the email (0-86400, default 7 seconds)." }, "agent_id": { "type": "integer", "format": "int64", "description": "ID of the agent sending this email (required, to know which agent will be the sender)." }, "agent_email": { "type": "string", "description": "Email of the agent sending this email (required if agent_id is not provided)." }, "generated_id": { "type": "string", "description": "Client-generated ID to track the message in the response (optional, returned unchanged)." } }, "required": [ "channel_id", "content" ] } } } }, "responses": { "200": { "description": "Message sent successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } } }, "202": { "description": "Actions were executed but no message was sent (action-only request).", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input, missing recipients, or attachments too large.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Missing required permission (Selected agent doesn't have the right to send).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Channel or agent not found, or organization expired.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Rate limit exceeded (too many requests in a short time).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } }, "summary": "Create a new conversation", "description": "Creates a new conversation and sends an email message to specified recipients. Supports attachments, delayed sending, and automated actions via snippets. The email is sent from the specified channel and can include to, cc, and bcc recipients.", "x-mint": { "metadata": { "description": "" }, "content": "Creates a new conversation and sends an email message to specified recipients. Supports attachments, delayed sending, and automated actions via snippets. The email is sent from the specified channel and can include to, cc, and bcc recipients." }, "x-computed-hash": "c69723da37285b1bb92614f32eee81b48e4213e507fb827d52425b7bafd01dfb", "x-last-modified": 1773150592 } }, "/organization": { "get": { "operationId": "getOrganization", "tags": [ "Organizations" ], "responses": { "200": { "description": "Organization details retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Organization" } } } } }, "summary": "Retrieve organization details", "description": "Returns the complete organization object.", "x-mint": { "metadata": { "description": "" }, "content": "Returns the complete organization object." }, "x-computed-hash": "ddb70af762dfa16ef302edafa59ae7dd69a12ec9121e64ade663432b634e47e3", "x-last-modified": 1769076834 }, "patch": { "operationId": "updateOrganization", "tags": [ "Organizations" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 250, "description": "Organization name.", "example": "PiedPiper Inc." }, "line1": { "type": "string", "maxLength": 250, "description": "Address line 1.", "example": "5230 Newell Road" }, "line2": { "type": "string", "maxLength": 250, "description": "Address line 2 (optional)." }, "zipcode": { "type": "string", "maxLength": 25, "description": "Postal/ZIP code.", "example": 94303 }, "city": { "type": "string", "maxLength": 250, "description": "City name.", "example": "Palo Alto" }, "state": { "type": "string", "maxLength": 250, "description": "State or province (optional).", "example": "California" }, "country": { "type": "string", "maxLength": 2, "description": "Two-letter ISO country code.", "example": "US" }, "company_vat": { "type": "string", "maxLength": 250, "description": "VAT number (validated for EU countries)." }, "billing_email": { "type": "string", "format": "email", "maxLength": 250, "description": "Email address for billing notifications.", "example": "billing@piedpiper.com" }, "from_name": { "type": "string", "maxLength": 100, "description": "Email sender name template (supports variables like ${agent_name}, ${organization_name}).", "example": "${agent_name} from ${organization_name}" }, "is_ai_chat_enabled": { "type": "boolean", "description": "Enable AI chat feature.", "example": true } } } } } }, "responses": { "200": { "description": "Organization updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Organization" } } } }, "400": { "description": "Invalid input or validation error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } }, "summary": "Update organization details", "description": "Updates the organization's profile.", "x-mint": { "metadata": { "description": "" }, "content": "Updates the organization's profile." }, "x-computed-hash": "a4a9a32bce5a8335444073fa5797c1ef619391f92530987d4c623418bdb92c39", "x-last-modified": 1769076834 } }, "/organization/invoices": { "get": { "operationId": "getOrganizationInvoices", "tags": [ "Organizations" ], "responses": { "200": { "description": "Invoices retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "invoices": { "type": "array", "description": "List of invoices.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Stripe invoice ID.", "example": "in_1A2B3C4D5E6F7G8H" }, "amount": { "type": "integer", "description": "Amount paid in cents.", "example": 4900 }, "url": { "type": "string", "format": "uri", "description": "URL to download invoice PDF.", "example": "https://pay.stripe.com/invoice/..." }, "reference": { "type": "string", "description": "Invoice reference number.", "example": "ABC-1234" }, "members": { "type": "string", "description": "Number of team members billed (may show progression if changed during period).", "example": 5 }, "paid": { "type": "string", "format": "date-time", "description": "Payment date in ISO 8601 format.", "example": "2025-01-15T10:30:00+00:00" } } } }, "details": { "type": "object", "description": "Active discount details (optional).", "properties": { "name": { "type": "string", "description": "Coupon name.", "example": "Early Adopter Discount" }, "offer": { "type": "integer", "description": "Discount amount in cents.", "example": 1000 } } } } } } } } }, "summary": "Retrieve organization invoices", "description": "Returns a list of all invoices for the organization.", "x-mint": { "metadata": { "description": "" }, "content": "Returns a list of all invoices for the organization." }, "x-computed-hash": "62858e48da08a25313de45d3f42dff8fa87ce1f799fe601d1574951ed05a8528", "x-last-modified": 1769076834 } }, "/organization/hours": { "post": { "operationId": "setOrganizationHours", "tags": [ "Organizations" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "timezone": { "type": "string", "description": "IANA timezone identifier (required).", "example": "America/New_York" }, "hours": { "type": "array", "description": "Array of business hours by day (can be empty to clear hours).", "items": { "type": "object", "properties": { "day": { "type": "string", "enum": [ "monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday" ], "description": "Day of the week.", "example": "monday" }, "start": { "type": "string", "pattern": "^([01]?[0-9]|2[0-3]):[0-5][0-9]$", "description": "Opening time in HH:MM format (UTC).", "example": "09:00" }, "end": { "type": "string", "pattern": "^([01]?[0-9]|2[0-3]):[0-5][0-9]$", "description": "Closing time in HH:MM format (UTC, must be after start).", "example": 1020 } } } } }, "required": [ "timezone" ], "example": { "timezone": "America/New_York", "hours": [ { "day": "monday", "start": "09:00", "end": "17:00" }, { "day": "tuesday", "start": "09:00", "end": "17:00" } ] } } } } }, "responses": { "200": { "description": "Business hours updated successfully.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input or validation error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 400 }, "error": { "type": "object", "properties": { "day": { "type": "string", "description": "Day that caused the error.", "example": "monday" }, "reason": { "type": "string", "description": "Error message.", "example": "End hour must be higher than start for monday" } } } } } } } } }, "summary": "Set organization business hours", "description": "Configure the organization's business hours for each day of the week. Hours must be provided in UTC timezone and will not be converted automatically. The client application must handle timezone conversion based on user preferences.\nValidates that hours are properly formatted, non-overlapping, and within valid time ranges.", "x-mint": { "metadata": { "description": "" }, "content": "Configure the organization's business hours for each day of the week. Hours must be provided in UTC timezone and will not be converted automatically. The client application must handle timezone conversion based on user preferences.\nValidates that hours are properly formatted, non-overlapping, and within valid time ranges." }, "x-computed-hash": "fc1da0b9948947cb3caea64b192c485ffb62aade08100761b3275b2236da27ec", "x-last-modified": 1769076834 } }, "/organization/channels": { "post": { "operationId": "createChannel", "tags": [ "Channels" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 50, "description": "Display name for the channel.", "example": "Support" }, "email": { "type": "string", "format": "email", "maxLength": 250, "description": "Email address for the channel (domain must not exceed 65 characters).", "example": "support@piedpiper.com" } }, "required": [ "name", "email" ] } } } }, "responses": { "200": { "description": "Channel created successfully.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Channel" }, { "type": "object", "properties": { "domain": { "type": "object", "description": "Domain verification details.", "properties": { "name": { "type": "string", "example": "piedpiper.com" }, "dns": { "type": "array", "items": { "type": "object" } }, "is_valid": { "type": "boolean", "example": false }, "is_pending": { "type": "boolean", "example": true } } } } } ] } } } }, "400": { "description": "Invalid input or channel already exists.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } }, "summary": "Create a new channel", "description": "Creates a new email channel for the organization with the specified name and email address.", "x-mint": { "metadata": { "description": "" }, "content": "Creates a new email channel for the organization with the specified name and email address." }, "x-computed-hash": "8f2cd834c767a34ad4eda93e4955f4369d5255dc51b8e9b4afd4f14c86e3a8cf", "x-last-modified": 1769076834 }, "get": { "operationId": "listChannels", "tags": [ "Channels" ], "parameters": [ { "name": "complete", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Include domain verification details for each channel." } ], "responses": { "200": { "description": "Channels retrieved successfully.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Channel" } } } } } }, "summary": "List all channels", "description": "Returns all email channels configured for the organization. When complete=true, includes domain verification status and DNS settings for each channel, optimized to avoid duplicate domain queries.", "x-mint": { "metadata": { "description": "" }, "content": "Returns all email channels configured for the organization. When complete=true, includes domain verification status and DNS settings for each channel, optimized to avoid duplicate domain queries." }, "x-computed-hash": "ce9ca1fdded848aa4000d720cc9b5185d4a53b895530e54498b9b30beb211f5b", "x-last-modified": 1769076834 } }, "/organization/chat": { "put": { "operationId": "updateChatConfiguration", "tags": [ "Chat Widget" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "channel": { "type": "integer", "description": "Default channel ID for chat conversations (required).", "example": 12345 }, "domains": { "type": "string", "description": "Comma-separated list of allowed domains for chat widget (optional).", "example": "piedpiper.com,piedpiper.dev,piedpiper.xyz" } }, "required": [ "channel" ] } } } }, "responses": { "200": { "description": "Chat configuration updated successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "secret": { "type": "string", "description": "Secure key for HMAC authentication of chat widget.", "example": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0" }, "settings": { "type": "object", "description": "Chat widget settings.", "properties": { "channel": { "type": "integer", "description": "Default channel ID for chat conversations.", "example": 12345 }, "domains": { "type": "array", "description": "List of allowed domains for chat widget.", "items": { "type": "string" }, "example": [ "piedpiper.com", "piedpiper.dev", "piedpiper.xyz" ] } } } } } } } }, "400": { "description": "Invalid channel or domain provided.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } }, "summary": "Update chat widget configuration", "description": "Updates the organization's chat widget settings. The channel property must be a valid channel ID belonging to the organization.", "x-mint": { "metadata": { "description": "" }, "content": "Updates the organization's chat widget settings. The channel property must be a valid channel ID belonging to the organization." }, "x-computed-hash": "a49a667ab81bf30cf9edace7bc41ec9c31171d3dd9f13dde3b21dbccdf0b584c", "x-last-modified": 1769102070 }, "get": { "operationId": "getChatConfiguration", "tags": [ "Chat Widget" ], "responses": { "200": { "description": "Chat configuration retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "secret": { "type": "string", "description": "Secure key for HMAC authentication of chat widget.", "example": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0" }, "settings": { "type": "object", "description": "Chat widget settings.", "properties": { "channel": { "type": "integer", "description": "Default channel ID for chat conversations.", "example": 12345 }, "domains": { "type": "array", "description": "List of allowed domains for chat widget.", "items": { "type": "string" }, "example": [ "piedpiper.com", "piedpiper.dev", "piedpiper.xyz" ] } } } } } } } } }, "summary": "Get chat widget configuration", "description": "Returns the organization's chat widget settings.", "x-mint": { "metadata": { "description": "" }, "content": "Returns the organization's chat widget settings." }, "x-computed-hash": "f09e247ea117d0e169d48eb24772ea30f2e9cbf991d175c03161f93c4711dd42", "x-last-modified": 1769102070 } }, "/organization/custom-data/logs": { "get": { "operationId": "getCustomDataLogs", "tags": [ "Custom Data" ], "responses": { "200": { "description": "Logs retrieved successfully.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "method": { "type": "string", "description": "HTTP method used.", "example": "POST" }, "url": { "type": "string", "description": "Endpoint URL called.", "example": "https://api.piedpiper.com/customer-data" }, "status": { "type": "integer", "description": "HTTP status code returned.", "example": 200 }, "response": { "type": "string", "description": "Response message or error details.", "example": "Success" }, "email": { "type": "string", "format": "email", "description": "Customer email used in the request.", "example": "customer@example.com" }, "executed_at": { "type": "string", "format": "date-time", "description": "Timestamp when the request was executed.", "example": "2025-01-15T10:30:00+00:00" } } } } } } } }, "summary": "Get custom data API logs", "description": "Returns the last 20 API calls made to the custom data endpoint. Useful for debugging integration issues.", "x-mint": { "metadata": { "description": "" }, "content": "Returns the last 20 API calls made to the custom data endpoint. Useful for debugging integration issues." }, "x-computed-hash": "ac7c6af0c4a706c1646402ad11d95a81fa102631c93e57250cd1760804bdaab7", "x-last-modified": 1769076834 } }, "/organization/custom-data": { "get": { "operationId": "getCustomDataConfiguration", "tags": [ "Custom Data" ], "responses": { "200": { "description": "Custom data configuration retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "endpoint": { "type": "string", "format": "uri", "description": "API endpoint URL to fetch custom data.", "example": "https://api.piedpiper.com/customer-data" }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Custom HTTP headers for API requests.", "example": { "Authorization": "Bearer token123", "X-API-Key": "key456" } }, "template": { "type": "string", "description": "Jinja2 template for rendering custom data.", "example": "
{{ customer.name }}
" }, "is_enabled": { "type": "boolean", "description": "Whether custom data panel is enabled.", "example": true }, "test_email": { "type": "string", "format": "email", "description": "Test email address for template validation.", "example": "test@customer.com" } } } } } } }, "summary": "Get custom data configuration", "description": "Returns the organization's custom data panel settings.", "x-mint": { "metadata": { "description": "" }, "content": "Returns the organization's custom data panel settings." }, "x-computed-hash": "ce71f5e159af9d767e6ff4a60f93440e2b20bed37d71f14fef5ec17010838b46", "x-last-modified": 1769076834 }, "delete": { "operationId": "deleteCustomDataConfiguration", "tags": [ "Custom Data" ], "responses": { "200": { "description": "Custom data configuration deleted successfully.", "content": { "application/json": { "schema": { "type": "object" } } } } }, "summary": "Delete custom data configuration", "description": "Completely removes the custom data configuration. Also clears all related cache entries.", "x-mint": { "metadata": { "description": "" }, "content": "Completely removes the custom data configuration. Also clears all related cache entries." }, "x-computed-hash": "3131d4a21797d62e16380c845cf2208bd267f582f131e579ef71d07105a4f6b4", "x-last-modified": 1769076834 }, "patch": { "operationId": "updateCustomDataConfiguration", "tags": [ "Custom Data" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "endpoint": { "type": "string", "format": "uri", "maxLength": 250, "description": "API endpoint URL (must use HTTPS in production).", "example": "https://api.piedpiper.com/customer-data" }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Custom HTTP headers (max 4096 chars when serialized).", "example": { "Authorization": "Bearer token123", "X-API-Key": "key456" } }, "template": { "type": "string", "maxLength": 25000, "description": "Jinja2 template for rendering (set to empty string to clear).", "example": "

{{ customer.name }}

{{ customer.email }}

" }, "test_email": { "type": "string", "format": "email", "description": "Test email for template validation (set to empty string to clear).", "example": "test@customer.com" } } } } } }, "responses": { "200": { "description": "Custom data configuration updated successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "endpoint": { "type": "string", "format": "uri", "example": "https://api.piedpiper.com/customer-data" }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "Authorization": "Bearer token123" } }, "template": { "type": "string", "example": "
{{ customer.name }}
" }, "test_email": { "type": "string", "format": "email", "example": "test@customer.com" }, "is_enabled": { "type": "boolean", "example": true } } } } } }, "400": { "description": "Invalid input or template validation error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } }, "summary": "Update custom data configuration", "description": "Updates the custom data settings. The template is validated for security (no includes, imports, or macros allowed) and HTML safety. Setting a new endpoint automatically disables the panel until template validation passes.", "x-mint": { "metadata": { "description": "" }, "content": "Updates the custom data settings. The template is validated for security (no includes, imports, or macros allowed) and HTML safety. Setting a new endpoint automatically disables the panel until template validation passes." }, "x-computed-hash": "e5757f951e64eb4833dde0a2c33a4edcc18b6db6d93fc6cbba7378d3b3068045", "x-last-modified": 1769076834 } }, "/organization/rag/sources/urls": { "post": { "operationId": "addAIUrlSource", "tags": [ "RAG (AI data)" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "maxLength": 250, "description": "URL to add to the knowledge base (must start with http/https).", "example": "https://docs.piedpiper.com/getting-started" }, "crawl": { "type": "boolean", "description": "Whether to crawl the entire website from this URL.", "example": false } }, "required": [ "url", "crawl" ] } } } }, "responses": { "202": { "description": "URL source queued for processing.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid URL or knowledge base URL detected.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "You can't add your knowledge base URL as a source." } } } } } } }, "summary": "Add URL source to your AI Data", "description": "Adds a web page to the vector store. Can optionally crawl the entire website starting from the provided URL. The content is fetched and processed asynchronously.", "x-mint": { "metadata": { "description": "" }, "content": "Adds a web page to the vector store. Can optionally crawl the entire website starting from the provided URL. The content is fetched and processed asynchronously." }, "x-computed-hash": "fe486a03d6eb5747eb095cb8ff47822f5d7f903e5e21515c7143e37badd7a3f8", "x-last-modified": 1769076834 } }, "/organization/rag/sources/retrain": { "post": { "operationId": "retrainAISources", "tags": [ "RAG (AI data)" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "uuids": { "type": "array", "description": "Array of source UUIDs to retrain.", "items": { "type": "string" }, "example": [ "a1b2c3d4e5f6g7h8i9j0", "b2c3d4e5f6g7h8i9j0k1" ] } }, "required": [ "uuids" ] } } } }, "responses": { "202": { "description": "Sources queued for retraining.", "content": { "application/json": { "schema": { "type": "object" } } } } }, "summary": "Retrain multiple URL sources", "description": "Refreshes multiple URL sources by re-fetching their content. Only processes URL sources that haven't been updated in the last 5 minutes to prevent rapid retries. Useful for updating stale content.", "x-mint": { "metadata": { "description": "" }, "content": "Refreshes multiple URL sources by re-fetching their content. Only processes URL sources that haven't been updated in the last 5 minutes to prevent rapid retries. Useful for updating stale content." }, "x-computed-hash": "953661774e42dc2d845d063286c9b51fe8ee222387b1eebc79abe840800971a0", "x-last-modified": 1769076834 } }, "/organization/rag/sources/files": { "post": { "operationId": "addAIFileSources", "tags": [ "RAG (AI data)" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "files": { "type": "array", "description": "Array of files to upload (max 10MB per file).", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "File name with extension.", "example": "documentation.pdf" }, "type": { "type": "string", "enum": [ "application/pdf", "application/msword", "application/vnd.openxmlformats-officedocument.wordprocessingml.document", "text/plain" ], "description": "MIME type of the file.", "example": "application/pdf" }, "content": { "type": "string", "format": "byte", "description": "Base64 encoded file content.", "example": "JVBERi0xLjQKJeLjz9MK..." } }, "required": [ "name", "type", "content" ] } } }, "required": [ "files" ] } } } }, "responses": { "202": { "description": "Files queued for processing.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid file format or size limit exceeded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Maximum size of the vector store exceeded." } } } } } } }, "summary": "Add file to the AI store", "description": "Uploads one or more files to the AI store. Supports PDF, DOC, DOCX, and TXT formats. Files must be base64 encoded and cannot exceed the organization's vector store size limit. All files are processed asynchronously.", "x-mint": { "metadata": { "description": "" }, "content": "Uploads one or more files to the AI store. Supports PDF, DOC, DOCX, and TXT formats. Files must be base64 encoded and cannot exceed the organization's vector store size limit. All files are processed asynchronously." }, "x-computed-hash": "7f32f177bd4236080e66414ee59acc8e5a1bd7a989aa864f5a2b5d936cf260a1", "x-last-modified": 1769076834 } }, "/organization/rag/sources": { "delete": { "operationId": "deleteAISources", "tags": [ "RAG (AI data)" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "uuids": { "type": "array", "description": "Array of source UUIDs to delete.", "items": { "type": "string" }, "example": [ "a1b2c3d4e5f6g7h8i9j0", "b2c3d4e5f6g7h8i9j0k1" ] } }, "required": [ "uuids" ] } } } }, "responses": { "200": { "description": "Sources queued for deletion.", "content": { "application/json": { "schema": { "type": "object" } } } } }, "summary": "Delete multiple AI sources", "description": "Permanently removes multiple sources from the AI store. The deletion is processed asynchronously.", "x-mint": { "metadata": { "description": "" }, "content": "Permanently removes multiple sources from the AI store. The deletion is processed asynchronously." }, "x-computed-hash": "79699c6a40d836a672300d43b8d60e13b87603851ac59b022a6ee24244a1c5a4", "x-last-modified": 1769076834 } }, "/organization/rag/sources/texts": { "post": { "operationId": "addAITextSource", "tags": [ "RAG (AI data)" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string", "maxLength": 50000, "description": "Text content to add to the knowledge base.", "example": "This is important information about our product features..." } }, "required": [ "text" ] } } } }, "responses": { "202": { "description": "Text source queued for processing.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input or size limit exceeded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Maximum size of the vector store exceeded." } } } } } } }, "summary": "Add text to the AI Store", "description": "Adds plain text content to the vector store. Useful for adding custom documentation, notes, or any text-based information. Content is limited to 50,000 characters.", "x-mint": { "metadata": { "description": "" }, "content": "Adds plain text content to the vector store. Useful for adding custom documentation, notes, or any text-based information. Content is limited to 50,000 characters." }, "x-computed-hash": "6a2834adfb117b3c804a1509d1ada3e8b803d5ceb9899b7c3951ea21fd9b5ec5", "x-last-modified": 1769076834 } }, "/organization/rag/sources/urls/stop": { "post": { "operationId": "stopAIUrlCrawl", "tags": [ "RAG (AI data)" ], "responses": { "202": { "description": "Crawling process stopped.", "content": { "application/json": { "schema": { "type": "object" } } } } }, "summary": "Stop URL crawling process", "description": "Stops the current website crawling operation if one is in progress. This only affects ongoing crawls and does not remove already processed pages.", "x-mint": { "metadata": { "description": "" }, "content": "Stops the current website crawling operation if one is in progress. This only affects ongoing crawls and does not remove already processed pages." }, "x-computed-hash": "7c670969c054f503233b54495712550292e19b1a4c441407ae71561aef084c07", "x-last-modified": 1769076834 } }, "/organization/rag": { "get": { "operationId": "listAISources", "tags": [ "RAG (AI data)" ], "responses": { "200": { "description": "RAG sources retrieved successfully.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/VectorStoreFile" } } } } } }, "summary": "List all public AI sources", "description": "Returns all public sources in our store used for AI. Limited to 250 most recent entries.", "x-mint": { "metadata": { "description": "" }, "content": "Returns all public sources in our store used for AI. Limited to 250 most recent entries." }, "x-computed-hash": "762e8cff1b6f856a5407929b1126b47b641d760060aff277c63a097a55f4378e", "x-last-modified": 1769076834 }, "patch": { "operationId": "updateAISettings", "tags": [ "RAG (AI data)" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "is_ai_articles_enabled": { "type": "boolean", "description": "Enable automatic sync of knowledge base articles to vector store.", "example": true }, "is_ai_messages_enabled": { "type": "boolean", "description": "Enable automatic sync of conversation messages to vector store.", "example": false } } } } } }, "responses": { "200": { "description": "AI Data settings updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Organization" } } } }, "400": { "description": "Invalid input or process already running.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "A process is already running for the articles. Please try again later." } } } } } } }, "summary": "Update AI Data auto-sync settings", "description": "Enables or disables automatic synchronization of knowledge base articles and conversation messages to the vector store. When toggling these settings, background tasks are queued to add or remove the respective content.", "x-mint": { "metadata": { "description": "" }, "content": "Enables or disables automatic synchronization of knowledge base articles and conversation messages to the vector store. When toggling these settings, background tasks are queued to add or remove the respective content." }, "x-computed-hash": "5958d4e85c35a962ca1000214e1271388482763e444b9881cde8ef68cb5df313", "x-last-modified": 1769076834 } }, "/organization/rag/sources/questions": { "post": { "operationId": "addAIQuestionSource", "tags": [ "RAG (AI data)" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "questions": { "type": "array", "description": "Array of question variations (max 250 chars each).", "items": { "type": "string", "maxLength": 250 }, "example": [ "How do I reset my password?", "What's the process for password recovery?" ] }, "answer": { "type": "string", "maxLength": 5000, "description": "Answer to the questions.", "example": "To reset your password, click on the \"Forgot Password\" link on the login page..." } }, "required": [ "questions", "answer" ] } } } }, "responses": { "202": { "description": "Q&A source queued for processing.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input or size limit exceeded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } }, "summary": "Add Q&A to the AI store", "description": "Creates a new question-answer pair in the AI store. Multiple question variations can be provided for the same answer to improve matching. The content is formatted and stored for AI retrieval.", "x-mint": { "metadata": { "description": "" }, "content": "Creates a new question-answer pair in the AI store. Multiple question variations can be provided for the same answer to improve matching. The content is formatted and stored for AI retrieval." }, "x-computed-hash": "3b4309983e2bf9fc4ede750d1702ee29118a8c9113cd3f90a43fa194c8018ad7", "x-last-modified": 1769076834 } }, "/organization/rag/statistics": { "get": { "operationId": "getAIStatistics", "tags": [ "RAG (AI data)" ], "responses": { "200": { "description": "Statistics retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "max_size": { "type": "integer", "description": "Maximum vector store size in bytes.", "example": 10485760 }, "statistics": { "type": "object", "description": "Statistics by content type.", "properties": { "messages": { "type": "object", "properties": { "count": { "type": "integer", "example": 150 }, "size": { "type": "integer", "description": "Total size in bytes.", "example": 2048576 } } }, "articles": { "type": "object", "properties": { "count": { "type": "integer", "example": 25 }, "size": { "type": "integer", "example": 1024000 } } }, "links": { "type": "object", "properties": { "count": { "type": "integer", "example": 10 }, "size": { "type": "integer", "example": 512000 } } }, "questions": { "type": "object", "properties": { "count": { "type": "integer", "example": 40 }, "size": { "type": "integer", "example": 204800 } } }, "texts": { "type": "object", "properties": { "count": { "type": "integer", "example": 15 }, "size": { "type": "integer", "example": 307200 } } }, "files": { "type": "object", "properties": { "count": { "type": "integer", "example": 5 }, "size": { "type": "integer", "example": 4096000 } } } } }, "status": { "type": "object", "description": "Processing status.", "properties": { "is_articles_processing": { "type": "boolean", "description": "Whether articles are currently being processed.", "example": false }, "is_messages_processing": { "type": "boolean", "description": "Whether messages are currently being processed.", "example": false }, "processing_urls": { "type": "string", "description": "URL currently being processed (if any).", "example": "https://example.com/page" } } } } } } } } }, "summary": "Get AI usage statistics", "description": "Returns statistics about the organization's AI data used for RAG (Vector Store).", "x-mint": { "metadata": { "description": "" }, "content": "Returns statistics about the organization's AI data used for RAG (Vector Store)." }, "x-computed-hash": "c829917284968da919608399b37597fa0ae8c85ffe00fbd757f91ad688669e21", "x-last-modified": 1769076834 } }, "/organization/rules": { "post": { "operationId": "createRuleset", "tags": [ "Rulesets" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 250, "description": "Name of the ruleset (required).", "example": "Auto-assign incoming messages" }, "trigger": { "type": "string", "maxLength": 50, "description": "Event that triggers this rule (required). Must be one of:\nmessages.new_conversation, messages.incoming, messages.response, messages.disable_ai, messages.delivery_failure, messages.spam, messages.note, status.closed, status.opened, status.snoozed, status.unsnoozed, teammates.assigned, teammate.mentioned, time.unanswered_by_client, time.unanswered_by_team, tickets.ticket_done\n", "example": "messages.incoming" }, "trigger_data": { "type": "string", "description": "Additional data for the trigger (optional, required for certain triggers):\n- For \"teammates.assigned\" or \"teammate.mentioned\": \"no_one\", \"anyone\", or an Agent ID\n- For \"time.*\" triggers: duration and period in format \"{duration} {period}\" (e.g., \"2 hours\", \"3 days\")\n", "example": "anyone" }, "filters": { "type": "array", "description": "Array of filter conditions (optional). Filters determine when the rule should execute based on entity properties.", "items": { "type": "object" }, "example": [ { "field": "conversation.status", "operator": "equals", "value": "OPENED" } ] }, "actions": { "type": "array", "description": "Array of actions to execute when rule matches (required). Must contain at least one action.", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the action to execute" }, "data": { "type": "object", "description": "Optional data for the action" } } }, "example": [ { "name": "conversation.assign", "data": { "agent_id": 123 } } ] }, "status": { "type": "string", "enum": [ "PAUSED", "LIVE" ], "description": "Initial status of the ruleset (optional, defaults to LIVE).", "example": "LIVE" }, "stop": { "type": "boolean", "description": "If true, stops processing subsequent rules when this rule matches (optional, defaults to false).", "example": false }, "priority": { "type": "integer", "description": "Priority order for rule execution (optional). If not specified, rule is added at the end. Lower numbers execute first.", "example": 0 } }, "required": [ "name", "trigger", "actions" ] } } } }, "responses": { "200": { "description": "Ruleset created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ruleset" } } } }, "400": { "description": "Invalid input, validation failed, or trigger/filter/action configuration error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message describing what went wrong" } } } } } } }, "summary": "Create a new ruleset", "description": "Creates a new automation ruleset with specified trigger conditions, filters, and actions. The ruleset can be created in either LIVE or PAUSED status. When a priority is specified, all existing rules at or below that priority are shifted down. For time-based triggers (time.unanswered_by_client, time.unanswered_by_team), matching conversations are automatically excluded from future processing. Validates that the trigger exists, filters are valid for the trigger type, and actions are properly configured.", "x-mint": { "metadata": { "description": "" }, "content": "Creates a new automation ruleset with specified trigger conditions, filters, and actions. The ruleset can be created in either LIVE or PAUSED status. When a priority is specified, all existing rules at or below that priority are shifted down. For time-based triggers (time.unanswered_by_client, time.unanswered_by_team), matching conversations are automatically excluded from future processing. Validates that the trigger exists, filters are valid for the trigger type, and actions are properly configured." }, "x-computed-hash": "7ffb650a6904c837fc12e3c7d8e976ad3b78dc3473b2e677dc182f725c75d71b", "x-last-modified": 1776152542 }, "get": { "operationId": "listRulesets", "tags": [ "Rulesets" ], "responses": { "200": { "description": "List of rulesets retrieved successfully.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Ruleset" } } } } } }, "summary": "Retrieve all rulesets", "description": "Returns a list of all rulesets belonging to the authenticated user's organization, ordered by priority. This endpoint provides a complete overview of all automation rules configured for the organization.", "x-mint": { "metadata": { "description": "" }, "content": "Returns a list of all rulesets belonging to the authenticated user's organization, ordered by priority. This endpoint provides a complete overview of all automation rules configured for the organization." }, "x-computed-hash": "4488a0ce0b99a549575b35c4cf5d70b3a8417e53c340cbb26b71a1aea676437a", "x-last-modified": 1769076834 } }, "/snippets": { "get": { "operationId": "listSnippets", "tags": [ "Snippets" ], "responses": { "200": { "description": "Snippets retrieved successfully.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Snippet" } } } } } }, "summary": "List all snippets", "description": "Retrieves all snippets belonging to the authenticated user's organization.", "x-mint": { "metadata": { "description": "" }, "content": "Retrieves all snippets belonging to the authenticated user's organization." }, "x-computed-hash": "6058615285763cde7215ccd0867ae3487095e0922e598bb6743ed03f37da0c88", "x-last-modified": 1769076834 }, "post": { "operationId": "createSnippet", "tags": [ "Snippets" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 50, "description": "Title of the snippet (required).", "example": "Welcome Message" }, "shortcut": { "type": "string", "maxLength": 40, "pattern": "^[a-z0-9-]*$", "nullable": true, "description": "Optional keyboard shortcut (lowercase, numbers, and dashes only).", "example": "welcome" }, "categories": { "type": "array", "items": { "type": "integer" }, "nullable": true, "description": "Array of category IDs to assign this snippet to.", "example": [ 1, 3 ] }, "actions": { "type": "array", "minItems": 1, "maxItems": 10, "items": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "status", "assign", "snooze", "reply", "note", "tag" ], "description": "Name of the action to apply.", "example": "status" }, "data": { "type": "object", "description": "Action-specific data payload.", "example": { "status": "closed" } } } }, "description": "Array of actions to apply when snippet is used (1-10 actions required).", "example": [ { "name": "status", "data": { "status": "closed" } }, { "name": "reply", "data": { "content": "Thank you for contacting us!" } } ] } }, "required": [ "title", "actions" ] } } } }, "responses": { "200": { "description": "Snippet created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Snippet" } } } }, "400": { "description": "Invalid input or validation error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } }, "summary": "Create a new snippet", "description": "Creates a new snippet. The snippet can be used to quickly insert pre-defined content and apply automated actions to conversations. Actions are validated to ensure they are supported (status, assign, snooze, reply, note, tag) with a maximum of 10 actions per snippet.", "x-mint": { "metadata": { "description": "" }, "content": "Creates a new snippet. The snippet can be used to quickly insert pre-defined content and apply automated actions to conversations. Actions are validated to ensure they are supported (status, assign, snooze, reply, note, tag) with a maximum of 10 actions per snippet." }, "x-computed-hash": "ba28dbdafb566293297f3016923185de47fd005148c7736d2b716aab05b5fff1", "x-last-modified": 1769076834 } }, "/snippets/categories": { "get": { "operationId": "listSnippetCategories", "tags": [ "Snippet Categories" ], "responses": { "200": { "description": "Categories retrieved successfully.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SnippetCategory" } } } } } }, "summary": "List all snippet categories", "description": "Retrieves all snippet categories, ordered by their sort position. Categories can be nested with parent-child relationships.", "x-mint": { "metadata": { "description": "" }, "content": "Retrieves all snippet categories, ordered by their sort position. Categories can be nested with parent-child relationships." }, "x-computed-hash": "550574827e510844141ce74273fe9773be7c1b8d9a99e3b34105ac255fb917ce", "x-last-modified": 1769076834 }, "post": { "operationId": "createSnippetCategory", "tags": [ "Snippet Categories" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 50, "description": "Name of the category (required).", "example": "Customer Support" }, "parent_id": { "type": "integer", "nullable": true, "description": "ID of the parent category (optional, null for root-level category).", "example": 2 } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Category created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SnippetCategory" } } } }, "400": { "description": "Invalid input or parent category not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } }, "summary": "Create a new snippet category", "description": "Creates a new snippet category with the specified name and optional parent category. The category is automatically assigned a sort position at the end of its siblings. Categories can be nested to create hierarchical organization structures.", "x-mint": { "metadata": { "description": "" }, "content": "Creates a new snippet category with the specified name and optional parent category. The category is automatically assigned a sort position at the end of its siblings. Categories can be nested to create hierarchical organization structures." }, "x-computed-hash": "ef177e0ad2f7f38ab9d919efed1f28f7cabfe07989aa059dd815b561dc794afd", "x-last-modified": 1769076834 } }, "/tags": { "post": { "operationId": "createTag", "tags": [ "Tags" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 50, "description": "Name of the tag", "example": "VIP Customer" }, "color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$", "description": "Hex color code for the tag (e.g.,", "example": "#FF5733" } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Tag created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tag" } } } }, "400": { "description": "Invalid input or validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Color must be a hexadecimal (#RRGGBB)." } } } } } } }, "summary": "Create a new tag", "description": "Creates a new tag with the specified name and optional color. The slug is automatically generated from the name. If no color is provided, a default gray color (#BEC2C8) is assigned. The tag name must be unique within the organization.", "x-mint": { "metadata": { "description": "" }, "content": "Creates a new tag with the specified name and optional color. The slug is automatically generated from the name. If no color is provided, a default gray color (#BEC2C8) is assigned. The tag name must be unique within the organization." }, "x-computed-hash": "7a34599ad2069ffb9be28195d46f4fe0a61f177370519b0c1ad48854056bb704", "x-last-modified": 1769076834 }, "get": { "operationId": "listTags", "tags": [ "Tags" ], "responses": { "200": { "description": "List of tags retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Tag" } } } } } }, "summary": "List all tags", "description": "Retrieves a list of all tags. Tags are returned sorted alphabetically by name. Each tag includes its color, slug, and the count of conversations it's associated with.", "x-mint": { "metadata": { "description": "" }, "content": "Retrieves a list of all tags. Tags are returned sorted alphabetically by name. Each tag includes its color, slug, and the count of conversations it's associated with." }, "x-computed-hash": "14093adbc77a0bd2d572ca423268735bc6f9f6950bc63e3a4386dc4b11be3973", "x-last-modified": 1769076834 } }, "/knowledge": { "patch": { "operationId": "updateKnowledgeBase", "tags": [ "Knowledge Base" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 250, "description": "Main title for the knowledge base homepage.", "example": "PiedPiper Help Center" }, "description": { "type": "string", "maxLength": 1000, "nullable": true, "description": "Description text shown on the knowledge base homepage." }, "company_name": { "type": "string", "maxLength": 250, "nullable": true, "description": "Company name displayed in the knowledge base.", "example": "PiedPiper" }, "company_url": { "type": "string", "maxLength": 250, "nullable": true, "description": "Company website URL (without http/https prefix).", "example": "piedpiper.com" }, "subdomain": { "type": "string", "maxLength": 50, "description": "Subdomain for accessing the knowledge base (e.g., 'piedpiper' for piedpiper.fernand.help).", "pattern": "^[a-z0-9]{1}[a-z0-9_\\-]{1,58}[a-z0-9]{1}$", "example": "piedpiper" }, "custom_domain": { "type": "string", "maxLength": 250, "nullable": true, "description": "Custom domain for the knowledge base (without http/https prefix).", "example": "help.piedpiper.com" }, "favicon": { "type": "string", "nullable": true, "description": "Favicon URL or base64-encoded PNG image data." }, "language": { "type": "string", "maxLength": 5, "nullable": true, "description": "Language code for the knowledge base (null for browser detection).", "enum": [ "en", "fr", "de", "es", "it", "pt", "pl", "tr", "sv", "nl", "dk" ], "example": "en" }, "color_scheme": { "type": "string", "nullable": true, "enum": [ "light", "dark" ], "description": "Color scheme preference for the knowledge base." }, "light_logo": { "type": "string", "nullable": true, "description": "Logo URL or base64-encoded image for light mode (jpg, png, svg)." }, "light_accent_color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$", "description": "Accent color for light mode (hex color code).", "example": "#00a0ff" }, "dark_logo": { "type": "string", "nullable": true, "description": "Logo URL or base64-encoded image for dark mode (jpg, png, svg)." }, "dark_accent_color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$", "description": "Accent color for dark mode (hex color code).", "example": "#00a0ff" }, "custom_css": { "type": "string", "maxLength": 8000000, "nullable": true, "description": "Custom CSS to apply to the knowledge base (max 8MB)." }, "custom_js": { "type": "string", "maxLength": 8000000, "nullable": true, "description": "Custom JavaScript to apply to the knowledge base (max 8MB)." }, "indexable": { "type": "boolean", "description": "Whether the knowledge base should be indexed by search engines." } } } } } }, "responses": { "200": { "description": "Knowledge base settings updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeLang" } } } }, "400": { "description": "Invalid input or domain already in use.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } }, "summary": "Update knowledge base settings and configuration", "description": "Updates the knowledge base configuration. Changes to custom domains are validated and configured with the hosting provider. Image assets can be provided as URLs or base64-encoded data and are automatically uploaded to CDN storage.", "x-mint": { "metadata": { "description": "" }, "content": "Updates the knowledge base configuration. Changes to custom domains are validated and configured with the hosting provider. Image assets can be provided as URLs or base64-encoded data and are automatically uploaded to CDN storage." }, "x-computed-hash": "1c9d772cc2dc221299705e3b445bc0f5bfccd696bfd79b9e495848f4c3d3b073", "x-last-modified": 1769076834 }, "get": { "operationId": "getKnowledgeBase", "tags": [ "Knowledge Base" ], "responses": { "200": { "description": "Knowledge base settings retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeLang" } } } }, "404": { "description": "Knowledge base not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } }, "summary": "Retrieve knowledge base settings", "description": "Returns the complete knowledge base configuration. The knowledge base serves as the central hub for managing help center content and appearance.", "x-mint": { "metadata": { "description": "" }, "content": "Returns the complete knowledge base configuration. The knowledge base serves as the central hub for managing help center content and appearance." }, "x-computed-hash": "e2d1c2cc1f32996be995ebe4ac69a0a5a14dd0ad10665ae21f94bb9f1f646c12", "x-last-modified": 1769076834 } }, "/knowledge/structure": { "get": { "operationId": "getKnowledgeStructure", "tags": [ "Knowledge Base" ], "responses": { "200": { "description": "Knowledge base structure retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "base_url": { "type": "string", "description": "Base URL of the knowledge base (either custom domain or subdomain).", "example": "https://help.piedpiper.com" }, "articles": { "type": "object", "description": "Map of article IDs to article objects with metadata and computed URLs.", "additionalProperties": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique identifier for the article." }, "title": { "type": "string", "description": "Title of the article." }, "seo_title": { "type": "string", "description": "SEO-optimized title for search engines." }, "uuid": { "type": "string", "format": "uuid", "description": "Unique UUID for the article." }, "slug": { "type": "string", "description": "URL-safe slug for the article." }, "description": { "type": "string", "nullable": true, "description": "Brief description of the article content." }, "created": { "type": "string", "format": "date-time", "description": "Timestamp when the article was created." }, "last_updated": { "type": "string", "format": "date-time", "description": "Timestamp when the article was last updated." }, "visibility": { "type": "string", "enum": [ "public", "chat", "chat_auth" ], "description": "Visibility setting for the article." }, "previous_url": { "type": "string", "nullable": true, "description": "Previous URL if migrated from another system." }, "published": { "type": "boolean", "description": "Whether the article is published." }, "url": { "type": "string", "description": "Full computed URL path including collection hierarchy.", "example": "https://help.piedpiper.com/getting-started/introduction" } } } }, "collections": { "type": "object", "description": "Map of collection IDs to collection objects with their articles.", "additionalProperties": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique identifier for the collection." }, "parent_id": { "type": "integer", "nullable": true, "description": "ID of the parent collection, or null for top-level collections." }, "title": { "type": "string", "description": "Title of the collection." }, "slug": { "type": "string", "description": "URL-safe slug for the collection." }, "description": { "type": "string", "nullable": true, "description": "Description of the collection content." }, "seo_title": { "type": "string", "description": "SEO-optimized title." }, "seo_description": { "type": "string", "nullable": true, "description": "SEO-optimized description." }, "icon": { "type": "string", "nullable": true, "description": "Emoji icon identifier for the collection." }, "created": { "type": "string", "format": "date-time", "description": "Timestamp when the collection was created." }, "sort": { "type": "integer", "description": "Sort order within parent collection." }, "articles": { "type": "array", "items": { "type": "integer" }, "description": "Array of article IDs contained in this collection." } } } } } } } } }, "404": { "description": "Knowledge base not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } }, "summary": "Retrieve the complete knowledge base structure", "description": "Returns the full hierarchical structure of the knowledge base. Collections are organized in a tree structure where collections can contain articles and nested sub-collections. The structure includes computed URLs for all articles based on their collection path. Note that some collections may have zero articles but serve as parent containers for nested collections.", "x-mint": { "metadata": { "description": "" }, "content": "Returns the full hierarchical structure of the knowledge base. Collections are organized in a tree structure where collections can contain articles and nested sub-collections. The structure includes computed URLs for all articles based on their collection path. Note that some collections may have zero articles but serve as parent containers for nested collections." }, "x-computed-hash": "950c4be790c6a2e1aaa02bf225a546f27dec200e1a1ab3ab1dfc88599af2700f", "x-last-modified": 1769076834 } }, "/knowledge/verify": { "get": { "operationId": "verifyKnowledgeDomain", "tags": [ "Knowledge Base" ], "responses": { "200": { "description": "Domain verification status retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "verified", "pending" ], "description": "Current verification status of the custom domain.", "example": "verified" }, "verification": { "type": "object", "description": "DNS configuration records required for domain verification.", "properties": { "type": { "type": "string", "description": "DNS record type (e.g., CNAME, A).", "example": "CNAME" }, "name": { "type": "string", "description": "DNS record name/host.", "example": "help.piedpiper.com" }, "value": { "type": "string", "description": "DNS record value/target.", "example": "help.getfernand.com." } } } } } } } }, "400": { "description": "No custom domain defined to verify.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Knowledge base not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } }, "summary": "Verify custom domain DNS configuration", "description": "Checks if the custom domain's DNS records are properly configured to point to the knowledge base hosting infrastructure. Returns the current verification status and the required DNS configuration records. If verification succeeds, the custom domain is marked as valid and can be used to access the knowledge base. This endpoint is rate-limited to 5 requests per minute to prevent abuse.", "x-mint": { "metadata": { "description": "" }, "content": "Checks if the custom domain's DNS records are properly configured to point to the knowledge base hosting infrastructure. Returns the current verification status and the required DNS configuration records. If verification succeeds, the custom domain is marked as valid and can be used to access the knowledge base. This endpoint is rate-limited to 5 requests per minute to prevent abuse." }, "x-computed-hash": "ee3a1785f63dc32803aff806fd7750501b4b7e19154dcba4a9caa4952324aefb", "x-last-modified": 1769076834 } }, "/knowledge/collections": { "post": { "operationId": "createCollection", "tags": [ "Knowledge Collections" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 250, "description": "Display title of the collection (required).", "example": "Getting Started" }, "slug": { "type": "string", "maxLength": 250, "pattern": "^[a-z0-9_-]+$", "description": "URL-safe slug for the collection (required, lowercase alphanumeric with dashes/underscores).", "example": "getting-started" }, "icon": { "type": "string", "maxLength": 25, "nullable": true, "description": "Emoji icon identifier for the collection (optional).", "example": "\ud83d\ude80" }, "description": { "type": "string", "maxLength": 1000, "nullable": true, "description": "Description of the collection content (optional)." }, "parent_id": { "type": "integer", "nullable": true, "description": "ID of the parent collection for nesting (optional, null for root-level)." }, "seo_title": { "type": "string", "maxLength": 250, "nullable": true, "description": "SEO-optimized title for search engines (optional, defaults to title)." }, "seo_description": { "type": "string", "maxLength": 1250, "nullable": true, "description": "SEO-optimized description for search engines (optional)." } }, "required": [ "title", "slug" ] } } } }, "responses": { "200": { "description": "Collection created successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique identifier for the collection." }, "parent_id": { "type": "integer", "nullable": true, "description": "ID of the parent collection." }, "title": { "type": "string", "description": "Title of the collection." }, "slug": { "type": "string", "description": "URL-safe slug." }, "description": { "type": "string", "nullable": true, "description": "Collection description." }, "seo_title": { "type": "string", "description": "SEO-optimized title." }, "seo_description": { "type": "string", "nullable": true, "description": "SEO-optimized description." }, "icon": { "type": "string", "nullable": true, "description": "Emoji icon identifier." }, "created": { "type": "string", "format": "date-time", "description": "Creation timestamp." }, "last_updated": { "type": "string", "format": "date-time", "description": "Last update timestamp." }, "sort": { "type": "integer", "description": "Sort order within parent." } } } } } }, "400": { "description": "Invalid input or slug already in use.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } }, "summary": "Create a new collection", "description": "Creates a new collection for organizing articles. Collections can be nested by specifying a parent_id to create sub-collections. The slug must be unique within the knowledge base and URL-safe. If no seo_title is provided, the regular title is used. Collections are automatically assigned a sort order based on their position within their parent. An icon can be specified using emoji identifiers for visual distinction.", "x-mint": { "metadata": { "description": "" }, "content": "Creates a new collection for organizing articles. Collections can be nested by specifying a parent_id to create sub-collections. The slug must be unique within the knowledge base and URL-safe. If no seo_title is provided, the regular title is used. Collections are automatically assigned a sort order based on their position within their parent. An icon can be specified using emoji identifiers for visual distinction." }, "x-computed-hash": "ed92d2227c9b48012cc74b9bbfef5add1c3205e02764f3278d12edc6a7a539a5", "x-last-modified": 1769076834 }, "get": { "operationId": "listCollections", "tags": [ "Knowledge Collections" ], "parameters": [ { "name": "parent_id", "in": "query", "required": false, "schema": { "type": "integer", "nullable": true }, "description": "Filter collections by parent ID. Omit to get all collections, or provide a collection ID to get its children, or null to get root-level collections." } ], "responses": { "200": { "description": "Collections retrieved successfully.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Collection" } } } } } }, "summary": "List collections", "description": "Returns all collections in the knowledge base, optionally filtered by parent collection. Collections are returned in sort order. When parent_id is provided, only direct children of that collection are returned. Without parent_id, all collections across all levels are returned. Collections organize articles into hierarchical categories for better content organization and navigation.", "x-mint": { "metadata": { "description": "" }, "content": "Returns all collections in the knowledge base, optionally filtered by parent collection. Collections are returned in sort order. When parent_id is provided, only direct children of that collection are returned. Without parent_id, all collections across all levels are returned. Collections organize articles into hierarchical categories for better content organization and navigation." }, "x-computed-hash": "5ffce3fb8c4d86047dfb6e5095d72bec9c098bdb2cb90619cc135c8b961e5b5a", "x-last-modified": 1769076834 } }, "/knowledge/articles": { "post": { "operationId": "createArticle", "tags": [ "Knowledge Articles" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 250, "description": "Display title of the article (required).", "example": "How to get started" }, "seo_title": { "type": "string", "maxLength": 250, "nullable": true, "description": "SEO-optimized title for search engines (optional, defaults to title)." }, "slug": { "type": "string", "maxLength": 250, "pattern": "^[a-z0-9_-]+$", "description": "URL-safe slug for the article (required, lowercase alphanumeric with dashes/underscores).", "example": "how-to-get-started" }, "previous_url": { "type": "string", "maxLength": 250, "nullable": true, "description": "Previous URL if migrating from another help system (optional)." }, "description": { "type": "string", "maxLength": 250, "nullable": true, "description": "Brief description of the article for SEO and previews (optional)." }, "content": { "type": "string", "maxLength": 16000000, "nullable": true, "description": "HTML content of the article (optional, max 10MB). Images can be base64-encoded or URLs." }, "template": { "type": "string", "maxLength": 250, "pattern": "^[a-z\\-]+$", "nullable": true, "description": "Template name to load predefined content (optional)." }, "visibility": { "type": "string", "maxLength": 10, "enum": [ "public", "chat", "chat_auth" ], "default": "public", "description": "Visibility setting - public (visible to all), chat (only in chat widget), chat_auth (only in chat for authenticated users)." }, "collections": { "type": "array", "items": { "type": "integer", "nullable": true }, "description": "Array of collection IDs where the article should be placed (required, at least one, can include null for root).", "example": [ 1, 2 ] }, "published": { "type": "boolean", "description": "Whether the article should be published immediately (required)." } }, "required": [ "title", "slug", "collections", "published" ] } } } }, "responses": { "200": { "description": "Article created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Article" } } } }, "400": { "description": "Invalid input or slug already in use.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } }, "summary": "Create an article", "description": "Creates a new help article. Articles must belong to at least one collection. The slug must be unique and URL-safe. Content can include HTML with images (as URLs or base64 data), which are automatically processed and uploaded to our CDN storage.\nWhen published, the article generates a social banner, processes content images, updates search indexes, and optionally indexes into the AI vector store for chat functionality. SEO title defaults to the regular title if not provided.", "x-mint": { "metadata": { "description": "" }, "content": "Creates a new help article. Articles must belong to at least one collection. The slug must be unique and URL-safe. Content can include HTML with images (as URLs or base64 data), which are automatically processed and uploaded to our CDN storage.\nWhen published, the article generates a social banner, processes content images, updates search indexes, and optionally indexes into the AI vector store for chat functionality. SEO title defaults to the regular title if not provided." }, "x-computed-hash": "9afb435de2fbf6a31c45ec2eb008cdb54eae014eb916f99e6164fc7e1c1d98c9", "x-last-modified": 1769076834 } }, "/knowledge/links": { "get": { "operationId": "listLinks", "tags": [ "Knowledge Links" ], "parameters": [ { "name": "position", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "HEADER", "FOOTER" ] }, "description": "Position where links should be displayed (case-insensitive).", "example": "HEADER" } ], "responses": { "200": { "description": "Links retrieved successfully.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/KnowledgeLinkLang" } } } } } }, "summary": "List links", "description": "Returns all navigation links configured for the specified position (HEADER or FOOTER) in the knowledge base. Links are returned in sort order. These links appear in the knowledge base navigation to provide quick access to external resources or important pages. Links are language-specific based on the default language setting.", "x-mint": { "metadata": { "description": "" }, "content": "Returns all navigation links configured for the specified position (HEADER or FOOTER) in the knowledge base. Links are returned in sort order. These links appear in the knowledge base navigation to provide quick access to external resources or important pages. Links are language-specific based on the default language setting." }, "x-computed-hash": "bd7d8564875c40a676161836ffc78b1db7528959af361cb0f5f8ca0156c0f744", "x-last-modified": 1769076834 }, "post": { "operationId": "createLink", "tags": [ "Knowledge Links" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 60, "description": "Display text for the link (required).", "example": "Contact Us" }, "url": { "type": "string", "maxLength": 250, "description": "Destination URL (required, automatically prefixed with https:// if missing).", "example": "https://piedpiper.com/contact" }, "target": { "type": "string", "maxLength": 6, "enum": [ "_blank", "_self" ], "description": "Link target behavior - _blank opens in new tab, _self opens in same window (required).", "example": "_blank" }, "position": { "type": "string", "maxLength": 6, "enum": [ "HEADER", "FOOTER" ], "description": "Where the link should be displayed (required, case-insensitive).", "example": "HEADER" } }, "required": [ "title", "url", "target", "position" ] } } } }, "responses": { "200": { "description": "Link created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeLinkLang" } } } }, "400": { "description": "Invalid input or duplicate link.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } }, "summary": "Create a new link", "description": "Creates a new navigation link in the knowledge base header or footer. Links are automatically assigned a sort order based on their position among existing links. URLs are automatically prefixed with https:// if no protocol is provided. The combination of URL and position must be unique within the knowledge base.", "x-mint": { "metadata": { "description": "" }, "content": "Creates a new navigation link in the knowledge base header or footer. Links are automatically assigned a sort order based on their position among existing links. URLs are automatically prefixed with https:// if no protocol is provided. The combination of URL and position must be unique within the knowledge base." }, "x-computed-hash": "58630f79dcff1fa26a2fc3d36d1877f5934cd9880190c6bbcb8dd6d8482a811f", "x-last-modified": 1769076834 } }, "/integrations/github/properties": { "get": { "operationId": "getGithubProperties", "tags": [ "GitHub Integration" ], "responses": { "200": { "description": "GitHub properties retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "repositories": { "type": "array", "description": "List of available GitHub repositories.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the repository.", "example": "R_kgDOABCDEF" }, "name": { "type": "string", "description": "Full name of the repository (owner/repo).", "example": "piedpiper/algorithm" } } } }, "labels": { "type": "array", "description": "List of available labels across all repositories.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the label.", "example": "LA_kwDOABCDEF" }, "name": { "type": "string", "description": "Name of the label.", "example": "Bug" }, "color": { "type": "string", "description": "Color hex code of the label.", "example": "d73a4a" }, "repository_id": { "type": "string", "description": "ID of the repository this label belongs to.", "example": "R_kgDOABCDEF" } } } }, "milestones": { "type": "array", "description": "List of open milestones across all repositories.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the milestone (null for \"No milestone\" option).", "example": "M_kwDOABCDEF" }, "title": { "type": "string", "description": "Title of the milestone.", "example": "Version 1.0" }, "repository_id": { "type": "string", "description": "ID of the repository this milestone belongs to (null for \"No milestone\" option).", "example": "R_kgDOABCDEF" } } } }, "projects": { "type": "array", "description": "List of available GitHub projects.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the project.", "example": "PVT_kwDOABCDEF" }, "title": { "type": "string", "description": "Title of the project.", "example": "Roadmap" }, "repository_id": { "type": "string", "description": "ID of the repository this project belongs to.", "example": "R_kgDOABCDEF" } } } }, "workflows": { "type": "array", "description": "List of project workflows.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the workflow.", "example": "W_kwDOABCDEF" }, "name": { "type": "string", "description": "Name of the workflow.", "example": "Development" }, "project_id": { "type": "string", "description": "ID of the project this workflow belongs to.", "example": "PVT_kwDOABCDEF" }, "repository_id": { "type": "string", "description": "ID of the repository.", "example": "R_kgDOABCDEF" } } } }, "teams": { "type": "array", "description": "List of project teams.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the team.", "example": "T_kwDOABCDEF" }, "name": { "type": "string", "description": "Name of the team.", "example": "PiedPiper" }, "project_id": { "type": "string", "description": "ID of the project this team belongs to.", "example": "PVT_kwDOABCDEF" }, "repository_id": { "type": "string", "description": "ID of the repository.", "example": "R_kgDOABCDEF" } } } }, "users": { "type": "array", "description": "List of assignable users across all repositories.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the user (null for \"Unassigned\" option).", "example": "U_kgDOABCDEF" }, "name": { "type": "string", "description": "Display name of the user.", "example": "Bertram Gilfoyle" }, "avatar_url": { "type": "string", "description": "URL to the user's avatar image (null for \"Unassigned\" option).", "example": "https://avatars.githubusercontent.com/u/123456" }, "repository_id": { "type": "string", "description": "ID of the repository (null for \"Unassigned\" option).", "example": "R_kgDOABCDEF" } } } }, "types": { "type": "array", "description": "List of available issue types.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the issue type (null for \"No type\" option).", "example": "IT_kwDOABCDEF" }, "name": { "type": "string", "description": "Name of the issue type.", "example": "Feature" }, "color": { "type": "string", "description": "Color hex code of the issue type.", "example": "0e8a16" }, "repository_id": { "type": "string", "description": "ID of the repository this type belongs to (null for \"No type\" option).", "example": "R_kgDOABCDEF" } } } } } } } } } } }, "400": { "description": "Error loading data from GitHub.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "An unknown error occured while trying to load data on Github" } } } } } }, "404": { "description": "GitHub integration not found for this organization." } }, "summary": "Get GitHub integration properties", "description": "Retrieves all available GitHub properties for the authenticated organization. Returns a 404 error if the GitHub integration is not configured for the organization.", "x-mint": { "metadata": { "description": "" }, "content": "Retrieves all available GitHub properties for the authenticated organization. Returns a 404 error if the GitHub integration is not configured for the organization." }, "x-computed-hash": "12ec16209f995908692034ef1a5b938fd2ce38d1428ec91dfb929a1e8d59b874", "x-last-modified": 1769076834 } }, "/integrations/github/search": { "post": { "operationId": "searchGithubIssues", "tags": [ "GitHub Integration" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "description": "Search query string (supports GitHub search syntax).", "example": "login bug" } } } } } }, "responses": { "200": { "description": "Search results retrieved successfully.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the GitHub issue.", "example": "I_kwDOABCDEF" }, "number": { "type": "integer", "description": "Issue number within the repository.", "example": 42 }, "title": { "type": "string", "description": "Title of the issue.", "example": "Fix login bug" }, "url": { "type": "string", "description": "URL to view the issue on GitHub.", "example": "https://github.com/piedpiper/www/issues/42" }, "state_reason": { "type": "string", "description": "Reason for the current state (COMPLETED, NOT_PLANNED, REOPENED, or null if open).", "example": null }, "repository": { "type": "string", "description": "Full name of the repository (owner/repo).", "example": "piedpiper/www" }, "type": { "type": "object", "description": "Issue type (null if no type is set).", "properties": { "id": { "type": "string", "description": "Unique identifier of the issue type.", "example": "IT_kwDOABCDEF" }, "name": { "type": "string", "description": "Name of the issue type.", "example": "Bug" }, "color": { "type": "string", "description": "Color hex code of the issue type.", "example": "d73a4a" } } } } } } } } }, "404": { "description": "GitHub integration not found for this organization." } }, "summary": "Search for GitHub issues across all connected repositories", "description": "Searches for GitHub issues across all repositories that the GitHub integration has access to. The search query can include any GitHub search syntax. Returns up to 20 matching issues with their details including title, number, URL, state, repository, and issue type.", "x-mint": { "metadata": { "description": "" }, "content": "Searches for GitHub issues across all repositories that the GitHub integration has access to. The search query can include any GitHub search syntax. Returns up to 20 matching issues with their details including title, number, URL, state, repository, and issue type." }, "x-computed-hash": "166eb9dff98a6789391c0b12b89761fdcd789333d5584377e7f3da0b34f1ff6e", "x-last-modified": 1769076834 } }, "/integrations/linear/properties": { "get": { "operationId": "getLinearProperties", "tags": [ "Linear Integration" ], "responses": { "200": { "description": "Linear properties retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "states": { "type": "array", "description": "List of available workflow states (excluding completed and canceled states).", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the workflow state.", "example": "8a7b93d1-18f7-4a9f-b5c6-3e2d1f9a8c7b" }, "name": { "type": "string", "description": "Name of the workflow state.", "example": "In Progress" }, "type": { "type": "string", "description": "Type of the workflow state (triage, backlog, unstarted, started).", "example": "started" }, "color": { "type": "string", "description": "Color hex code of the workflow state.", "example": "#f2c94c" }, "position": { "type": "number", "description": "Position order of the state in the workflow.", "example": 2 }, "team_id": { "type": "string", "description": "ID of the team this state belongs to.", "example": "7b8c9d0e-1f2a-3b4c-5d6e-7f8a9b0c1d2e" } } } }, "priorities": { "type": "array", "description": "List of available issue priorities.", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Priority level (0=No priority, 1=Urgent, 2=High, 3=Medium, 4=Low).", "example": 1 }, "name": { "type": "string", "description": "Display name of the priority level.", "example": "Urgent" } } } }, "users": { "type": "array", "description": "List of assignable users in the organization.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the user (null for \"Unassigned\" option).", "example": "9c0d1e2f-3a4b-5c6d-7e8f-9a0b1c2d3e4f" }, "name": { "type": "string", "description": "Display name of the user.", "example": "Richard Hendricks" }, "avatar_url": { "type": "string", "description": "URL to the user's avatar image (null for \"Unassigned\" option).", "example": "https://avatar.linear.app/9c0d1e2f" } } } }, "labels": { "type": "array", "description": "List of available issue labels.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the label.", "example": "0d1e2f3a-4b5c-6d7e-8f9a-0b1c2d3e4f5a" }, "color": { "type": "string", "description": "Color hex code of the label.", "example": "#5e6ad2" }, "name": { "type": "string", "description": "Name of the label.", "example": "Bug" }, "team_id": { "type": "string", "description": "ID of the team this label belongs to (null if organization-wide).", "example": "7b8c9d0e-1f2a-3b4c-5d6e-7f8a9b0c1d2e" } } } }, "teams": { "type": "array", "description": "List of teams in the organization.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the team.", "example": "7b8c9d0e-1f2a-3b4c-5d6e-7f8a9b0c1d2e" }, "name": { "type": "string", "description": "Name of the team.", "example": "Engineering" } } } }, "projects": { "type": "array", "description": "List of available projects.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the project (null for \"No project\" option).", "example": "1e2f3a4b-5c6d-7e8f-9a0b-1c2d3e4f5a6b" }, "name": { "type": "string", "description": "Name of the project.", "example": "Q1 2026 Roadmap" }, "teams": { "type": "array", "description": "Array of team IDs this project belongs to (null for \"No project\" option).", "items": { "type": "string" }, "example": [ "7b8c9d0e-1f2a-3b4c-5d6e-7f8a9b0c1d2e" ] } } } } } } } } } } }, "400": { "description": "Error loading data from Linear.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "An unknown error occured while trying to load data on Linear" } } } } } }, "404": { "description": "Linear integration not found for this organization." } }, "summary": "Get Linear properties", "description": "Retrieves all available Linear properties needed.\nReturns a 404 error if the Linear integration is not configured for the organization.", "x-mint": { "metadata": { "description": "" }, "content": "Retrieves all available Linear properties needed.\nReturns a 404 error if the Linear integration is not configured for the organization." }, "x-computed-hash": "f5d731d215054119b75b7d8ddc0b6485c122b51b89a98f76d91b69da4e579077", "x-last-modified": 1769076834 } }, "/integrations/linear/search": { "post": { "operationId": "searchLinearIssues", "tags": [ "Linear Integration" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "description": "Search query string (optional, if empty returns recent issues).", "example": "authentication bug" } } } } } }, "responses": { "200": { "description": "Search results retrieved successfully.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the Linear issue.", "example": "8a7b93d1-18f7-4a9f-b5c6-3e2d1f9a8c7b" }, "title": { "type": "string", "description": "Title of the issue.", "example": "Fix authentication bug" }, "url": { "type": "string", "description": "URL to view the issue in Linear.", "example": "https://linear.app/team/issue/ENG-123" }, "identifier": { "type": "string", "description": "Human-readable issue identifier.", "example": "ENG-123" }, "assignee": { "type": "object", "description": "Assigned user (null if unassigned).", "properties": { "name": { "type": "string", "description": "Display name of the assignee.", "example": "Richard Hendricks" }, "avatar_url": { "type": "string", "description": "URL to the assignee's avatar image.", "example": "https://avatar.linear.app/9c0d1e2f" } } }, "state": { "type": "object", "description": "Current workflow state of the issue.", "properties": { "name": { "type": "string", "description": "Name of the workflow state.", "example": "In Progress" }, "type": { "type": "string", "description": "Type of the workflow state.", "example": "started" }, "color": { "type": "string", "description": "Color hex code of the workflow state.", "example": "#f2c94c" }, "last_updated_at": { "type": "string", "description": "ISO 8601 timestamp of when the issue entered this state.", "example": "2026-01-15T10:30:00Z" } } }, "labels": { "type": "array", "description": "List of labels applied to the issue.", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the label.", "example": "bug" }, "color": { "type": "string", "description": "Color hex code of the label.", "example": "#5e6ad2" } } } }, "priority": { "type": "integer", "description": "Priority level (0=No priority, 1=Urgent, 2=High, 3=Medium, 4=Low).", "example": 1 }, "priority_label": { "type": "string", "description": "Display name of the priority level.", "example": "Urgent" }, "last_updated_at": { "type": "string", "description": "ISO 8601 timestamp of the last update.", "example": "2026-01-15T10:30:00Z" } } } } } } }, "404": { "description": "Linear integration not found for this organization." } }, "summary": "Search for Linear issues", "description": "Searches for Linear issues in the organization based on the provided search query. If no query is provided, returns the most recent issues. Only returns issues in non-completed states (triage, unstarted, started, backlog). Results are limited to 20 issues, sorted by creation date.", "x-mint": { "metadata": { "description": "" }, "content": "Searches for Linear issues in the organization based on the provided search query. If no query is provided, returns the most recent issues. Only returns issues in non-completed states (triage, unstarted, started, backlog). Results are limited to 20 issues, sorted by creation date." }, "x-computed-hash": "a03f8913d0fc2882fd3703ad3b03eb9dbbd1c59040b13f260eaa8d987c447e11", "x-last-modified": 1769076834 } }, "/reporting/knowledge/articles": { "get": { "operationId": "getKnowledgeArticles", "tags": [ "Knowledge Base Reporting" ], "parameters": [ { "name": "start", "in": "query", "required": true, "schema": { "type": "string", "format": "date" }, "description": "Start date for the statistics range in YYYY-MM-DD format.", "example": "2026-01-01" }, { "name": "end", "in": "query", "required": true, "schema": { "type": "string", "format": "date" }, "description": "End date for the statistics range in YYYY-MM-DD format.", "example": "2026-01-31" }, { "name": "order_by", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "last_updated", "total_views", "disappointed", "neutral", "happy" ], "default": "total_views" }, "description": "Field to order results by.", "example": "total_views" }, { "name": "order_way", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ASC", "DESC" ], "default": "DESC" }, "description": "Sort direction (ascending or descending).", "example": "DESC" } ], "responses": { "200": { "description": "Articles retrieved successfully.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique identifier of the article.", "example": 789 }, "title": { "type": "string", "description": "Title of the article.", "example": "How to reset your password" }, "link": { "type": "string", "format": "uri", "description": "Full URL to view the article.", "example": "https://help.piedpiper.com/articles/789-how-to-reset-your-password" }, "category_id": { "type": "integer", "nullable": true, "description": "ID of the collection/category this article belongs to.", "example": 12 }, "last_updated": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the article was last updated.", "example": "2026-01-15T14:30:00Z" }, "views": { "type": "integer", "description": "Total number of views during the specified date range.", "example": 1847 }, "score": { "type": "object", "description": "Breakdown of user satisfaction ratings for this article.", "properties": { "disappointed": { "type": "integer", "description": "Number of negative ratings (score = -1).", "example": 5 }, "neutral": { "type": "integer", "description": "Number of neutral ratings (score = 0).", "example": 12 }, "happy": { "type": "integer", "description": "Number of positive ratings (score = 1).", "example": 48 } } } } } } } } }, "400": { "description": "Invalid input parameters, date validation error, or invalid ordering field.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message describing the validation failure.", "example": "Invalid ordering field. Only 'last_updated', 'total_views', 'disappointed', 'neutral' or 'happy' are accepted" } } } } } }, "403": { "description": "Insufficient permissions to access reporting data.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message.", "example": "Access denied" } } } } } } }, "summary": "Retrieve articles statistics for the Knowledge Base", "description": "Returns the top 20 articles for the specified date range. Results can be ordered by various metrics to identify high-performing or problematic articles.", "x-mint": { "metadata": { "description": "" }, "content": "Returns the top 20 articles for the specified date range. Results can be ordered by various metrics to identify high-performing or problematic articles." }, "x-computed-hash": "6207918822903346182eb67fc9496ffb02a8320ad24420199c59ef6a94ddb205", "x-last-modified": 1769076834 } }, "/reporting/knowledge/searches": { "get": { "operationId": "getKnowledgeSearches", "tags": [ "Knowledge Base Reporting" ], "parameters": [ { "name": "start", "in": "query", "required": true, "schema": { "type": "string", "format": "date" }, "description": "Start date for the statistics range in YYYY-MM-DD format.", "example": "2026-01-01" }, { "name": "end", "in": "query", "required": true, "schema": { "type": "string", "format": "date" }, "description": "End date for the statistics range in YYYY-MM-DD format.", "example": "2026-01-31" } ], "responses": { "200": { "description": "Search analytics retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "most_searched": { "type": "array", "description": "Top 10 most frequently searched terms across all searches.", "items": { "type": "object", "properties": { "term": { "type": "string", "description": "The search term.", "example": "password reset" }, "quantity": { "type": "integer", "description": "Number of times this term was searched.", "example": 847 } } } }, "no_results": { "type": "array", "description": "Top 10 most common search terms that returned zero results, indicating potential content gaps.", "items": { "type": "object", "properties": { "term": { "type": "string", "description": "The search term that found no matches.", "example": "api documentation" }, "quantity": { "type": "integer", "description": "Number of times this term was searched with no results.", "example": 94 } } } } } } } } }, "400": { "description": "Invalid input parameters or date validation error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message describing the validation failure.", "example": "Invalid date for 'start'" } } } } } }, "403": { "description": "Insufficient permissions to access reporting data.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message.", "example": "Access denied" } } } } } } }, "summary": "Retrieve search statistics from the knowledge base", "description": "Returns analytics on knowledge base search behavior, including the 10 most frequently searched terms and the 10 most common searches that returned no results. This data helps identify content gaps and popular topics in the knowledge base.", "x-mint": { "metadata": { "description": "" }, "content": "Returns analytics on knowledge base search behavior, including the 10 most frequently searched terms and the 10 most common searches that returned no results. This data helps identify content gaps and popular topics in the knowledge base." }, "x-computed-hash": "23546b07be34b4a6e02e1f8bbf5697ee7d38fab46520504b2c58b61e54c6a5d5", "x-last-modified": 1769076834 } }, "/reporting/knowledge/statistics": { "get": { "operationId": "getKnowledgeStatistics", "tags": [ "Knowledge Base Reporting" ], "parameters": [ { "name": "start", "in": "query", "required": true, "schema": { "type": "string", "format": "date" }, "description": "Start date for the statistics range in YYYY-MM-DD format.", "example": "2026-01-01" }, { "name": "end", "in": "query", "required": true, "schema": { "type": "string", "format": "date" }, "description": "End date for the statistics range in YYYY-MM-DD format.", "example": "2026-01-31" } ], "responses": { "200": { "description": "Knowledge base statistics retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "visitors": { "type": "object", "description": "Unique visitor counts grouped by date. Each key is a formatted date string based on the interval.", "additionalProperties": { "type": "integer", "description": "Number of unique visitors for this date." }, "example": { "2026-01-01": 42, "2026-01-02": 38, "2026-01-03": 51 } }, "views": { "type": "object", "description": "Total article view counts grouped by date. Each key is a formatted date string based on the interval.", "additionalProperties": { "type": "integer", "description": "Number of article views for this date." }, "example": { "2026-01-01": 156, "2026-01-02": 142, "2026-01-03": 189 } }, "searches": { "type": "object", "description": "Count of searches with no matching results, grouped by date. Each key is a formatted date string based on the interval.", "additionalProperties": { "type": "integer", "description": "Number of searches with zero matches for this date." }, "example": { "2026-01-01": 8, "2026-01-02": 12, "2026-01-03": 6 } }, "total_searches": { "type": "integer", "description": "Total number of all searches (including those with results) during the entire period.", "example": 427 } } } } } }, "400": { "description": "Invalid input parameters or date validation error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message describing the validation failure.", "example": "Invalid date for 'end'" } } } } } }, "403": { "description": "Insufficient permissions to access reporting data.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message.", "example": "Access denied" } } } } } } }, "summary": "Retrieve knowledge base statistics", "description": "Returns time-series data for knowledge base usage metrics. Data is aggregated by date based on the specified or automatically determined interval. The response includes total search count for the period.", "x-mint": { "metadata": { "description": "" }, "content": "Returns time-series data for knowledge base usage metrics. Data is aggregated by date based on the specified or automatically determined interval. The response includes total search count for the period." }, "x-computed-hash": "866c6aa147c9c36431daed18e81828f3f3011a6937a560a5a0d876a7f53d1e62", "x-last-modified": 1769076834 } }, "/reporting/general": { "get": { "operationId": "getGeneralStatistics", "tags": [ "Reporting" ], "parameters": [ { "name": "start", "in": "query", "required": true, "schema": { "type": "string", "format": "date" }, "description": "Start date for the statistics range in YYYY-MM-DD format.", "example": "2026-01-01" }, { "name": "end", "in": "query", "required": true, "schema": { "type": "string", "format": "date" }, "description": "End date for the statistics range in YYYY-MM-DD format.", "example": "2026-01-31" }, { "name": "interval", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "hours", "days", "weeks", "months", "years" ] }, "description": "Granularity of the time-based aggregation. If not specified, automatically determined based on date range (<=3 days=hours, <=31 days=days, <=90 days=days, >90 days=months).", "example": "days" }, { "name": "tag", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter statistics to only conversations with this tag slug.", "example": "support" } ], "responses": { "200": { "description": "Statistics retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "inbox": { "type": "object", "description": "Number of conversations created, grouped by date with breakdowns by channel, source, and assigned agent.", "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "channel_id": { "type": "integer", "nullable": true, "description": "ID of the channel.", "example": 123 }, "source": { "type": "string", "description": "Source of the conversation (e.g., EMAIL, CHAT).", "enum": [ "EMAIL", "CHAT" ], "example": "EMAIL" }, "agent_id": { "type": "integer", "nullable": true, "description": "ID of the agent assigned to the conversation.", "example": 456 }, "value": { "type": "integer", "description": "Count of conversations matching these dimensions.", "example": 42 } } } } }, "assigned": { "type": "object", "description": "Number of conversations assigned to an agent, grouped by date with breakdowns by channel, source, and agent.", "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "channel_id": { "type": "integer", "nullable": true, "description": "ID of the channel.", "example": 123 }, "source": { "type": "string", "description": "Source of the conversation.", "example": "CHAT" }, "agent_id": { "type": "integer", "description": "ID of the assigned agent.", "example": 456 }, "value": { "type": "integer", "description": "Count of conversations assigned.", "example": 35 } } } } }, "closed": { "type": "object", "description": "Number of conversations closed, grouped by date with breakdowns by channel, source, and closing agent.", "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "channel_id": { "type": "integer", "nullable": true, "description": "ID of the channel.", "example": 123 }, "source": { "type": "string", "description": "Source of the conversation.", "example": "EMAIL" }, "agent_id": { "type": "integer", "description": "ID of the agent who closed the conversation.", "example": 456 }, "value": { "type": "integer", "description": "Count of conversations closed.", "example": 28 } } } } }, "responded": { "type": "object", "description": "Number of conversations that received first response, grouped by date with breakdowns by channel, source, and responding agent.", "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "channel_id": { "type": "integer", "nullable": true, "description": "ID of the channel.", "example": 123 }, "source": { "type": "string", "description": "Source of the conversation.", "example": "TWITTER" }, "agent_id": { "type": "integer", "description": "ID of the agent who first responded.", "example": 456 }, "value": { "type": "integer", "description": "Count of conversations responded to.", "example": 40 } } } } }, "resolved": { "type": "object", "description": "Number of conversations resolved, grouped by date with breakdowns by channel, source, and resolving agent.", "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "channel_id": { "type": "integer", "nullable": true, "description": "ID of the channel.", "example": 123 }, "source": { "type": "string", "description": "Source of the conversation.", "example": "EMAIL" }, "agent_id": { "type": "integer", "description": "ID of the agent who resolved the conversation.", "example": 456 }, "value": { "type": "integer", "description": "Count of conversations resolved.", "example": 30 } } } } }, "ttfr": { "type": "object", "description": "Average time to first response in seconds, grouped by date with breakdowns by channel, source, and responding agent.", "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "channel_id": { "type": "integer", "nullable": true, "description": "ID of the channel.", "example": 123 }, "source": { "type": "string", "description": "Source of the conversation.", "example": "CHAT" }, "agent_id": { "type": "integer", "description": "ID of the responding agent.", "example": 456 }, "value": { "type": "number", "format": "float", "description": "Average time to first response in seconds.", "example": 1847.5 } } } } }, "ttr": { "type": "object", "description": "Average time to resolution in seconds, grouped by date with breakdowns by channel, source, and resolving agent.", "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "channel_id": { "type": "integer", "nullable": true, "description": "ID of the channel.", "example": 123 }, "source": { "type": "string", "description": "Source of the conversation.", "example": "EMAIL" }, "agent_id": { "type": "integer", "description": "ID of the resolving agent.", "example": 456 }, "value": { "type": "number", "format": "float", "description": "Average time to resolution in seconds.", "example": 86400.0 } } } } } } } } } }, "400": { "description": "Invalid input parameters or date validation error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message describing the validation failure.", "example": "Invalid date for 'start'" } } } } } }, "403": { "description": "Insufficient permissions to access reporting data.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message.", "example": "Access denied" } } } } } } }, "summary": "Retrieve general conversation statistics", "description": "Returns comprehensive conversation metrics broken down by date, channel, source, and agent. Data can be filtered by date range, tag, and aggregated by custom intervals (hours, days, weeks, months, years).", "x-mint": { "metadata": { "description": "" }, "content": "Returns comprehensive conversation metrics broken down by date, channel, source, and agent. Data can be filtered by date range, tag, and aggregated by custom intervals (hours, days, weeks, months, years)." }, "x-computed-hash": "46ca98bdfcd00514b6b8abde6f3135996e406eb6227e5f97b4304b3832ca5369", "x-last-modified": 1769076834 } }, "/contacts/{id}": { "patch": { "operationId": "updateContact", "tags": [ "Contacts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "ID of the contact to update.", "example": 12345 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 250, "nullable": true, "description": "New name for the contact. If matches original name, local_name is cleared.", "example": "Richard H." } } } } } }, "responses": { "200": { "description": "Contact updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contact" } } } }, "400": { "description": "Invalid input data.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Contact not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } }, "summary": "Update the contact", "description": "Updates the contact's local name within the organization. If the provided name matches the contact's original name, the local_name is cleared (set to null). Otherwise, the local_name is set to the provided value, which will override the default name when displayed.\nReturns the updated contact without financial information.", "x-mint": { "metadata": { "description": "" }, "content": "Updates the contact's local name within the organization. If the provided name matches the contact's original name, the local_name is cleared (set to null). Otherwise, the local_name is set to the provided value, which will override the default name when displayed.\nReturns the updated contact without financial information." }, "x-computed-hash": "3bdf96722f2f9e7fa943a21b9d548dbfc1b05c8eef0cab6ede1ce45e92986947", "x-last-modified": 1769076834 }, "get": { "operationId": "getContactDetails", "tags": [ "Contacts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "ID of the contact to retrieve.", "example": 12345 } ], "responses": { "200": { "description": "Contact details retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contact" } } } }, "404": { "description": "Contact not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Not Found" } } } } } } }, "summary": "Retrieve contact informations", "description": "Fetches the complete contact record including financial information such as payment sources, subscriptions, and payment history.\nReturns 404 if the contact does not exist.", "x-mint": { "metadata": { "description": "" }, "content": "Fetches the complete contact record including financial information such as payment sources, subscriptions, and payment history.\nReturns 404 if the contact does not exist." }, "x-computed-hash": "d77367738e20a30702e20825bf281a5be870bd87531ef31d4c24c47fed1d3fff", "x-last-modified": 1769076834 } }, "/contacts/{id}/payment-email": { "delete": { "operationId": "unlinkPaymentEmail", "tags": [ "Contact Payments" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "ID of the contact to unlink the payment email from.", "example": 12345 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "STRIPE", "PADDLE", "LEMON" ], "description": "Payment processor source (case-insensitive, will be converted to uppercase).", "example": "STRIPE" }, "email": { "type": "string", "format": "email", "description": "Payment email address to unlink from the contact. Cannot be the same as the contact's primary email.", "example": "billing@piedpiper.com" } }, "required": [ "source", "email" ] } } } }, "responses": { "204": { "description": "Payment email unlinked successfully." }, "400": { "description": "Invalid input (trying to unlink the contact's primary email or invalid source).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "You cannot unlink the same email as the contact email." } } } } } }, "404": { "description": "Contact not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } }, "summary": "Unlink a payment email from a contact", "description": "Removes the association between a contact and a payment email from a payment processor. Deletes the payment email link record and clears the contact's financial information (financials, subscription_status, and subscription_start). The payment email being unlinked cannot be the same as the contact's primary email.", "x-mint": { "metadata": { "description": "" }, "content": "Removes the association between a contact and a payment email from a payment processor. Deletes the payment email link record and clears the contact's financial information (financials, subscription_status, and subscription_start). The payment email being unlinked cannot be the same as the contact's primary email." }, "x-computed-hash": "736ad7ddcd5dadb194e87f1e350c100337243cdbb46a600c3970f46439a9d59e", "x-last-modified": 1769076834 }, "post": { "operationId": "linkPaymentEmail", "tags": [ "Contact Payments" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "ID of the contact to link the payment email to.", "example": 12345 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "STRIPE", "PADDLE", "LEMON" ], "description": "Payment processor source (case-insensitive, will be converted to uppercase).", "example": "STRIPE" }, "email": { "type": "string", "format": "email", "description": "Payment email address to link to the contact.", "example": "billing@piedpiper.com" } }, "required": [ "source", "email" ] } } } }, "responses": { "200": { "description": "Payment email linked successfully with financial data returned.", "content": { "application/json": { "schema": { "type": "object", "properties": { "subscription_status": { "type": "string", "nullable": true, "enum": [ "active", "past_due", "unpaid", "canceled", "churned", "incomplete", "trialing" ] }, "subscription_start": { "type": "string", "format": "date-time", "nullable": true }, "financials": { "type": "object", "nullable": true } } } } } }, "204": { "description": "Payment email link created, financial data will be processed asynchronously." }, "400": { "description": "Invalid source or email format.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Contact not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } }, "summary": "Link a payment email to a contact", "description": "Associates a payment email from a payment processor (Stripe, Paddle, or Lemon Squeezy) with a contact. If the payment email differs from the contact's primary email, it creates or updates the payment email link. The endpoint then either propagates existing financial data or triggers an asynchronous task to fetch and propagate financial information from the payment processor.\nReturns financial data immediately if available, otherwise returns empty response while processing continues in the background.", "x-mint": { "metadata": { "description": "" }, "content": "Associates a payment email from a payment processor (Stripe, Paddle, or Lemon Squeezy) with a contact. If the payment email differs from the contact's primary email, it creates or updates the payment email link. The endpoint then either propagates existing financial data or triggers an asynchronous task to fetch and propagate financial information from the payment processor.\nReturns financial data immediately if available, otherwise returns empty response while processing continues in the background." }, "x-computed-hash": "067be52b9b16f889a50af299fde0b93800c6d880a94319ad075ffd8c07f15315", "x-last-modified": 1769076834 } }, "/contacts/suppressed/{email}": { "delete": { "operationId": "removeSuppressedContact", "tags": [ "Contact Suppressions" ], "parameters": [ { "name": "email", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Email address or domain pattern to remove from suppression list.", "example": "galvin@hooli.com" } ], "responses": { "204": { "description": "Email or domain removed from suppression list successfully." }, "400": { "description": "Invalid email format.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } }, "summary": "Remove an email or domain from the suppression list", "description": "Removes a suppression record for the specified email address or domain pattern within the organization. If the suppression exists, it is deleted and emails can be received from that address/domain again.\nIf the suppression does not exist, the operation completes successfully without error.", "x-mint": { "metadata": { "description": "" }, "content": "Removes a suppression record for the specified email address or domain pattern within the organization. If the suppression exists, it is deleted and emails can be received from that address/domain again.\nIf the suppression does not exist, the operation completes successfully without error." }, "x-computed-hash": "428533ade8f850a2c5eb04d30d611e834928b454768e6660cf3fc4159ef37ec4", "x-last-modified": 1769076834 } }, "/conversations/{conv_id}/drafts": { "post": { "operationId": "createDraft", "tags": [ "Conversation Drafts" ], "parameters": [ { "name": "conv_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "ID of the conversation to create the draft in." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "author_id": { "type": "integer", "description": "ID of the agent authoring the draft (optional if author_email is provided).", "example": 123 }, "author_email": { "type": "string", "description": "Email of the agent authoring the draft (optional if author_id is provided).", "example": "jared.dunns@piedpiper.com" }, "target_id": { "type": "integer", "description": "ID of the agent the draft is targeted to (optional)." }, "target_email": { "type": "string", "description": "Email of the agent the draft is targeted to (optional).", "example": "richard.hendricks@piedpiper.com" }, "title": { "type": "string", "description": "Title of the draft (optional).", "example": "Lawyer response" }, "content": { "type": "object", "description": "JSON object containing the draft content and metadata (required).\nExample:\n {\n \"content\": \"string\",\n \"attachments\": [\n {\n \"type\": \"application/pdf\",\n \"name\": \"report.pdf\",\n \"content\": \"<... base64 encoded content ...>\"\n }\n ],\n \"inlines\": [\n {\n \"type\": \"image/png\",\n \"name\": \"screenshot.png\",\n \"content\": \"<... base64 encoded content ...>\",\n \"cid\": \"random-cid-12345\"\n }\n ],\n \"actions\": [\n {\n \"name\": \"status.close\",\n \"snippet_id\": 123,\n \"data\": {}\n }\n ]\n }\n" } }, "required": [ "content" ] } } } }, "responses": { "200": { "description": "Draft created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageDraft" } } } }, "400": { "description": "Invalid input or referenced agent not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Conversation not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } }, "summary": "Create a new draft", "description": "Creates a message draft within the specified conversation, allowing the author and optional target agent to be set by ID or email.", "x-mint": { "metadata": { "description": "" }, "content": "Creates a message draft within the specified conversation, allowing the author and optional target agent to be set by ID or email." }, "x-computed-hash": "07cfbdd92199710d2d6c3625ee259ca67f788ab12f63b459a2a3ba5b0daf414d", "x-last-modified": 1772789112 } }, "/conversations/{id}/export": { "get": { "operationId": "exportConversation", "tags": [ "Conversations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "ID of the conversation to export." } ], "responses": { "200": { "description": "PDF generated and returned successfully.", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } }, "headers": { "Content-Disposition": { "description": "Specifies the filename for download.", "schema": { "type": "string", "example": "attachment; filename=\"conversation-12345.pdf\"" } } } }, "404": { "description": "Conversation not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "PDF generation failed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } }, "summary": "Export conversation as PDF", "description": "Generates and returns a PDF document containing the full conversation history including all messages, notes, and events. The PDF is formatted for archival and sharing purposes. Includes up to 100 entries from the conversation.", "x-mint": { "metadata": { "description": "" }, "content": "Generates and returns a PDF document containing the full conversation history including all messages, notes, and events. The PDF is formatted for archival and sharing purposes. Includes up to 100 entries from the conversation." }, "x-computed-hash": "c68d3d763ec4e13187a0696936ab00ab90e20601c6095e738806ef38fd4aeefe", "x-last-modified": 1769076834 } }, "/conversations/{id}/reply": { "post": { "operationId": "replyToConversation", "tags": [ "Conversations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "ID of the conversation to reply to." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "description": "HTML content of the reply message (optional if only executing actions)." }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Filename of the attachment." }, "type": { "type": "string", "description": "MIME type of the attachment." }, "content": { "type": "string", "format": "byte", "description": "Base64-encoded file content (max 5MB per file)." } } }, "description": "Array of file attachments (optional)." }, "actions": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the action to execute (e.g., teammates.assign, status.close)." }, "data": { "type": "object", "description": "Action-specific parameters." }, "snippet_id": { "type": "integer", "description": "ID of the snippet this action came from (for tracking)." } } }, "description": "Automated actions to execute after sending (optional)." }, "delay": { "type": "integer", "minimum": 0, "maximum": 86400, "default": 7, "description": "Delay in seconds before sending the reply (0-86400, default 7 seconds)." }, "agent_id": { "type": "integer", "format": "int64", "description": "ID of the agent sending this reply (required, to know which agent will be the sender)." }, "agent_email": { "type": "string", "description": "Email of the agent sending this reply (required if agent_id is not provided)." }, "generated_id": { "type": "string", "description": "Client-generated ID to track the message in the response (optional, returned unchanged)." } } } } } }, "responses": { "200": { "description": "Reply sent successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } } }, "202": { "description": "Actions were executed but no message was sent (action-only request).", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input, no recipients, or attachments too large.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Missing required permission (Selected agent does not have the \"conversation.reply\" role).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Conversation, agent not found, or organization expired.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Rate limit exceeded (too many requests in a short time).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } }, "summary": "Reply to conversation", "description": "Sends a reply message to all recipients in an existing conversation. Automatically includes all to/cc recipients from the original conversation. Supports attachments, delayed sending, and automated actions. Disables AI automation when an agent replies.", "x-mint": { "metadata": { "description": "" }, "content": "Sends a reply message to all recipients in an existing conversation. Automatically includes all to/cc recipients from the original conversation. Supports attachments, delayed sending, and automated actions. Disables AI automation when an agent replies." }, "x-computed-hash": "f29bf1362fbf1f78d3d8571b28cd8254e215352207b159db8aa908873381fc71", "x-last-modified": 1769076834 } }, "/conversations/{id}": { "delete": { "operationId": "deleteConversation", "tags": [ "Conversations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "ID of the conversation to delete." } ], "responses": { "204": { "description": "Conversation deleted successfully (no content returned)." }, "403": { "description": "Missing required permission (conversation.delete).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Conversation not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } }, "summary": "Delete a conversation", "description": "Permanently removes a conversation and all associated data including messages, notes, attachments, and events.\nThis action cannot be undone.", "x-mint": { "metadata": { "description": "" }, "content": "Permanently removes a conversation and all associated data including messages, notes, attachments, and events.\nThis action cannot be undone." }, "x-computed-hash": "40ae852379a6d00ed13bb13a65881a945f636c93664d720856ad30828b0f7208", "x-last-modified": 1769076834 }, "get": { "operationId": "getConversation", "tags": [ "Conversations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Unique identifier of the conversation to retrieve." } ], "responses": { "200": { "description": "Conversation retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conversation" } } } }, "404": { "description": "Conversation not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } }, "summary": "Retrieve a conversation", "description": "Fetches the full details of a specific conversation.\nReturns a 404 error if the conversation is not found.", "x-mint": { "metadata": { "description": "" }, "content": "Fetches the full details of a specific conversation.\nReturns a 404 error if the conversation is not found." }, "x-computed-hash": "a29df0033456b7095e0f4dceed29eb7ea2fde4394c206698b1d96683e5c534f8", "x-last-modified": 1769076834 }, "patch": { "operationId": "updateConversation", "tags": [ "Conversations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "ID of the conversation to update." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OPENED", "CLOSED", "SPAM", "SNOOZED" ], "description": "New status for the conversation (requires conversation.status permission)." }, "snooze_until": { "type": "string", "description": "When status is SNOOZED, specifies when to unsnooze. Formats:\n- \"5m\", \"+30\" (minutes from now)\n- \"tomorrow\", \"monday\", \"tuesday\", etc. (next occurrence at 9am)\n- \"one week\", \"one month\" (relative periods)\n- ISO 8601 timestamp (absolute time)\n" }, "agent_id": { "type": "integer", "format": "int64", "nullable": true, "description": "ID of agent to assign. Use null to unassign (requires conversation.assign permission)." }, "agent_email": { "type": "string", "description": "Email of agent to assign (alternative to agent_id, requires conversation.assign permission)." }, "subject": { "type": "string", "maxLength": 80, "description": "New subject line for the conversation (requires conversation.update permission)." }, "contact_id": { "type": "integer", "format": "int64", "description": "ID of an existing recipient to set as the primary contact." } } } } } }, "responses": { "200": { "description": "Conversation updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conversation" } } } }, "400": { "description": "Invalid input or agent not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Missing required permission for the requested operation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Conversation not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } }, "summary": "Update a conversation", "description": "Updates properties of a specific conversation. Status changes and agent assignments trigger automated workflows and notifications. Only changed fields need to be included in the request.", "x-mint": { "metadata": { "description": "" }, "content": "Updates properties of a specific conversation. Status changes and agent assignments trigger automated workflows and notifications. Only changed fields need to be included in the request." }, "x-computed-hash": "c0d532521b04ce3caad408f091886d5d2ce7ead199bc6d061809f5ea6e5bd3f8", "x-last-modified": 1769076834 } }, "/conversations/{id}/messages/{message_id}": { "delete": { "operationId": "deleteMessage", "tags": [ "Messages" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "ID of the conversation containing the message." }, { "name": "message_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "UUID or ID of the message to delete." } ], "responses": { "204": { "description": "Message deleted successfully (no content returned)." }, "403": { "description": "Missing required permission (message.delete).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Conversation or message not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } }, "summary": "Delete a message", "description": "Permanently removes a message and all associated data including attachments from storage. If the message is the last entry in the conversation, the entire conversation is also deleted. This action cannot be undone.", "x-mint": { "metadata": { "description": "" }, "content": "Permanently removes a message and all associated data including attachments from storage. If the message is the last entry in the conversation, the entire conversation is also deleted. This action cannot be undone." }, "x-computed-hash": "68f954acad0aa2b4384e5c90a525f46cfa6ea0700539b5b43be9b363bee155e4", "x-last-modified": 1769076834 } }, "/conversations/{id}/messages": { "get": { "operationId": "listConversationMessages", "tags": [ "Messages" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "ID of the conversation to retrieve messages from." }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Timestamp or Unix epoch (in seconds or milliseconds) to fetch messages before.\nAccepts ISO 8601 format or Unix timestamp. Used for pagination to load older messages.\n" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 5, "maximum": 100, "default": 20 }, "description": "Maximum number of entries to return." } ], "responses": { "200": { "description": "Messages retrieved successfully.", "content": { "application/json": { "schema": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/Message" }, { "$ref": "#/components/schemas/ConversationNote" }, { "$ref": "#/components/schemas/ConversationEvent" } ] } } } } }, "400": { "description": "Invalid timestamp or limit provided.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Conversation not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } }, "summary": "List messages in a conversation", "description": "Retrieves messages, notes, and events from a specific conversation in reverse chronological order. Supports pagination using the before parameter to fetch older entries. Returns a mix of messages, notes, and conversation events in a unified timeline.", "x-mint": { "content": "**Upcoming changes!**

This endpoint returns `id` in the form `[x]-[id]`, such as `m-1234` for messages, `n-4321` for notes, and `e-6789` for events, but the messages and notes endpoints expects the id as integer, without the first part.

We will soon update this endpoint API **without notification** to remove the first parts (`m-`, `n-` and `e-`) so you should conditionnaly strip these, and rely on the `type` property to know if it's a message, note or event.

Thank you for your understanding." }, "x-computed-hash": "40261be86072720c00dfe2304d2b9660179472ffc303bef3edb4a7b3a7f883d7", "x-last-modified": 1769076834 } }, "/conversations/{id}/notes/{note_id}": { "delete": { "operationId": "deleteConversationNote", "tags": [ "Notes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "ID of the conversation containing the note." }, { "name": "note_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "ID of the note to delete." } ], "responses": { "204": { "description": "Note deleted successfully (no content returned)." }, "400": { "description": "User is not the author of the note.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Missing required permission (conversation.note).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Conversation or note not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } }, "summary": "Delete a note", "description": "Permanently removes a note from a conversation.\nOnly the author of the note can delete it, or an administrator can delete an automated note.\nIf the note is the last entry in the conversation, the entire conversation is also deleted. This action cannot be undone.", "x-mint": { "metadata": { "description": "" }, "content": "Permanently removes a note from a conversation.\nOnly the author of the note can delete it, or an administrator can delete an automated note.\nIf the note is the last entry in the conversation, the entire conversation is also deleted. This action cannot be undone." }, "x-computed-hash": "1774b2c852fe8605ee8832ab76e7af37d9a8e20158c046b6f611dcc0f8c25db2", "x-last-modified": 1776152542 }, "patch": { "operationId": "updateConversationNote", "tags": [ "Notes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "ID of the conversation containing the note." }, { "name": "note_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "ID of the note to update." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "maxLength": 10485760, "description": "Updated HTML content of the note (required, max 8MB)." }, "mentions": { "type": "array", "items": { "type": "string" }, "description": "Updated array of agent IDs or special mentions to notify.\nUse \"everyone\" to notify all team members.\n", "example": [ "42", "everyone" ] } }, "required": [ "content" ] } } } }, "responses": { "200": { "description": "Note updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationNote" } } } }, "400": { "description": "Invalid input, note content too large, or user is not the author.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Missing required permission (conversation.note).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Conversation or note not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } }, "summary": "Update a note", "description": "Modifies the content of an existing note. Only the author of the note can edit it. The edited_at timestamp is automatically updated. Supports updating @mentions to notify additional team members. Maximum content size is 8MB.", "x-mint": { "metadata": { "description": "" }, "content": "Modifies the content of an existing note. Only the author of the note can edit it. The edited_at timestamp is automatically updated. Supports updating @mentions to notify additional team members. Maximum content size is 8MB." }, "x-computed-hash": "33c56347124365ea425baf58cc36573f2894f0d7bd431676109d3ee466fe769e", "x-last-modified": 1769076834 } }, "/conversations/{id}/notes": { "post": { "operationId": "addConversationNote", "tags": [ "Notes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "ID of the conversation to add the note to." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "maxLength": 10485760, "description": "HTML content of the note (required, max 8MB)." }, "mentions": { "type": "array", "items": { "type": "string" }, "description": "Array of agent IDs or special mentions to notify.\nUse \"everyone\" to notify all team members.\n", "example": [ "42", "everyone" ] }, "actions": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the action to execute (e.g., teammates.assign, status.close)." }, "data": { "type": "object", "description": "Action-specific parameters." }, "snippet_id": { "type": "integer", "description": "ID of the snippet this action came from (for tracking)." } } }, "description": "Automated actions to execute after creating the note (optional)." }, "note_id": { "type": "integer", "format": "int64", "description": "If updating an existing draft note, provide its ID (optional)." }, "generated_id": { "type": "string", "description": "Client-generated ID to track the note in the response (optional, returned unchanged)." } }, "required": [ "content" ] } } } }, "responses": { "200": { "description": "Note added successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationNote" } } } }, "400": { "description": "Invalid input or note content too large.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Missing required permission (conversation.note).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Conversation not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } }, "summary": "Add a note to a conversation", "description": "Creates an internal note within a conversation that is only visible to team members. Notes support HTML content, @mentions to notify specific agents, and can trigger automated actions. Maximum size is 8MB.", "x-mint": { "metadata": { "description": "" }, "content": "Creates an internal note within a conversation that is only visible to team members. Notes support HTML content, @mentions to notify specific agents, and can trigger automated actions. Maximum size is 8MB." }, "x-computed-hash": "9d28748a9d90f7a8fae1de940a4b7345d323addcc1c3ff621e2981c2b818f468", "x-last-modified": 1769076834 } }, "/conversations/{id}/tags": { "post": { "operationId": "addConversationTag", "tags": [ "Conversation Tags" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "ID of the conversation to tag." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 50, "description": "Name of the tag to add. Will be created if it doesn't exist.", "example": "urgent" } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Tag added successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tag" } } } }, "400": { "description": "Invalid input or tag name too long.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Missing required permission (conversation.tag).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Conversation not found or unable to create tag.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } }, "summary": "Add a tag to a conversation", "description": "Associates an existing tag with a conversation, or creates a new tag if it doesn't exist.\nTags help categorize and filter conversations.\nIf the tag already exists on the conversation, nothing will be done.", "x-mint": { "metadata": { "description": "" }, "content": "Associates an existing tag with a conversation, or creates a new tag if it doesn't exist.\nTags help categorize and filter conversations.\nIf the tag already exists on the conversation, nothing will be done." }, "x-computed-hash": "392f240afdcc0c6e718d1ae7aa8211e460034800efd4e3c34f6ba3187793dc52", "x-last-modified": 1769155111 } }, "/conversations/{id}/tags/{tag}": { "delete": { "operationId": "removeConversationTag", "tags": [ "Conversation Tags" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "ID of the conversation to untag." }, { "name": "tag", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Name or slug of the tag to remove from the conversation." } ], "responses": { "200": { "description": "Tag removed successfully. Returns the updated conversation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conversation" } } } }, "403": { "description": "Missing required permission (conversation.tag).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Conversation not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } }, "summary": "Remove a tag from a conversation", "description": "Disassociates a tag from a conversation.\nThe tag itself is not deleted and can still be used on other conversations.\nIf the tag is not currently on the conversation, nothing will be done.", "x-mint": { "metadata": { "description": "" }, "content": "Disassociates a tag from a conversation.\nThe tag itself is not deleted and can still be used on other conversations.\nIf the tag is not currently on the conversation, nothing will be done." }, "x-computed-hash": "6e9e9020f82ab98375e223b20397e21e1ebf0cd999ba863304520110ea78b50b", "x-last-modified": 1769155111 } }, "/organization/channels/{email}/verify": { "get": { "operationId": "verifyChannel", "tags": [ "Channels" ], "parameters": [ { "name": "email", "in": "path", "required": true, "schema": { "type": "string", "format": "email" }, "description": "Email address of the channel to verify.", "example": "support@piedpiper.com" } ], "responses": { "200": { "description": "Channel verification details retrieved successfully.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Channel" }, { "type": "object", "properties": { "domain": { "type": "object", "description": "Domain verification status and DNS records.", "properties": { "name": { "type": "string", "description": "Domain name.", "example": "piedpiper.com" }, "dns": { "type": "array", "description": "DNS records to configure.", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "TXT", "CNAME" ], "description": "DNS record type.", "example": "CNAME" }, "key": { "type": "string", "description": "DNS record name.", "example": "fernand20220202._domainkey" }, "value": { "type": "string", "description": "DNS record value.", "example": "fernand20220202._domainkey.piedpiper.com." }, "is_valid": { "type": "boolean", "description": "Whether this record is correctly configured.", "example": true }, "method": { "type": "string", "description": "Verification method used.", "example": "dns" }, "verified": { "type": "integer", "description": "Timestamp of last verification (milliseconds).", "example": 1642896000000 } } } }, "is_valid": { "type": "boolean", "description": "Whether all DNS records are valid.", "example": true }, "is_pending": { "type": "boolean", "description": "Whether domain setup is still pending.", "example": false } } } } } ] } } } }, "404": { "description": "Channel not found." } }, "summary": "Verify channel domain DNS settings", "description": "Checks the DNS configuration for the channel's domain by querying DNS records and validating against our DNS requirements. Returns the channel details along with current DNS verification status including DKIM, Return-Path, and custom CNAME records. This endpoint is limited to 5 queries per minutes to avoid unecessary abuses.", "x-mint": { "metadata": { "description": "" }, "content": "Checks the DNS configuration for the channel's domain by querying DNS records and validating against our DNS requirements. Returns the channel details along with current DNS verification status including DKIM, Return-Path, and custom CNAME records. This endpoint is limited to 5 queries per minutes to avoid unecessary abuses." }, "x-computed-hash": "9f7cbbc66600ea5288076d40d3b1b3b4b3b70bb3b26ef0da8f28819c52676176", "x-last-modified": 1769076834 } }, "/organization/channels/{email}": { "patch": { "operationId": "updateChannel", "tags": [ "Channels" ], "parameters": [ { "name": "email", "in": "path", "required": true, "schema": { "type": "string", "format": "email" }, "description": "Email address of the channel to update.", "example": "support@piedpiper.com" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 3, "maxLength": 50, "description": "New display name for the channel.", "example": "Customer Support" } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Channel updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Channel" } } } }, "400": { "description": "Invalid name provided.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Channel not found." } }, "summary": "Update a channel's name", "description": "Updates the display name of an existing channel identified by its email address. The email address itself cannot be changed.", "x-mint": { "metadata": { "description": "" }, "content": "Updates the display name of an existing channel identified by its email address. The email address itself cannot be changed." }, "x-computed-hash": "7377157b05ce19029cd00eda0a354d94ead355a157558acbf7d800f81755a27c", "x-last-modified": 1769076834 }, "delete": { "operationId": "deleteChannel", "tags": [ "Channels" ], "parameters": [ { "name": "email", "in": "path", "required": true, "schema": { "type": "string", "format": "email" }, "description": "Email address of the channel to delete.", "example": "support@piedpiper.com" } ], "responses": { "200": { "description": "Channel deleted successfully.", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Channel not found." } }, "summary": "Delete a channel", "description": "Permanently deletes a channel and reassigns all associated conversations to another available channel.", "x-mint": { "metadata": { "description": "" }, "content": "Permanently deletes a channel and reassigns all associated conversations to another available channel." }, "x-computed-hash": "6e72d6b63181d9c8090be5a7d12698249d57428c86b7b3e19fe2274e72d7aaad", "x-last-modified": 1769076834 } }, "/organization/rag/sources/questions/{uuid}": { "patch": { "operationId": "updateAIQuestionSource", "tags": [ "RAG (AI data)" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "UUID of the Q&A source to update.", "example": "a1b2c3d4e5f6g7h8i9j0" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "questions": { "type": "array", "items": { "type": "string", "maxLength": 250 }, "example": [ "How do I reset my password?" ] }, "answer": { "type": "string", "maxLength": 5000, "example": "To reset your password..." } }, "required": [ "questions", "answer" ] } } } }, "responses": { "202": { "description": "Q&A source queued for update.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input or source is not a Question type.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "You can only update Questions" } } } } } }, "404": { "description": "Q&A source not found." } }, "summary": "Update Q&A source", "description": "Updates an existing Q&A source identified by its UUID. Only sources of type \"Question\" can be updated through this endpoint.", "x-mint": { "metadata": { "description": "" }, "content": "Updates an existing Q&A source identified by its UUID. Only sources of type \"Question\" can be updated through this endpoint." }, "x-computed-hash": "8489f53a82ccaec0824cdfcd3db2fde42d7c8424af0d0a8645a5a3a9a96dc0ca", "x-last-modified": 1769076834 } }, "/organization/rag/sources/{uuid}/content": { "get": { "operationId": "getAISourceContent", "tags": [ "RAG (AI data)" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "UUID of the source to retrieve.", "example": "a1b2c3d4e5f6g7h8i9j0" } ], "responses": { "200": { "description": "Source content retrieved successfully.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "Question source content.", "properties": { "questions": { "type": "array", "items": { "type": "string" }, "example": [ "How do I reset my password?", "What's the password recovery process?" ] }, "answer": { "type": "string", "example": "To reset your password, click on..." } } }, { "type": "object", "description": "Text source content.", "properties": { "text": { "type": "string", "example": "This is the stored text content..." } } } ] } } } }, "400": { "description": "Source type does not support content retrieval.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "You can only retrieve the content of Questions or Texts" } } } } } }, "404": { "description": "Source not found." } }, "summary": "Get AI data source content", "description": "Retrieves the stored content of a Question or Text source. For Questions, returns parsed questions array and answer. For Texts, returns the raw text content. Other source types cannot be retrieved through this endpoint.", "x-mint": { "metadata": { "description": "" }, "content": "Retrieves the stored content of a Question or Text source. For Questions, returns parsed questions array and answer. For Texts, returns the raw text content. Other source types cannot be retrieved through this endpoint." }, "x-computed-hash": "ac595f4a08d8e85d1465c55a0d62fc2b25fd291bc62feb85ff169468151397ff", "x-last-modified": 1769076834 } }, "/organization/rag/sources/questions/{message_id}": { "patch": { "operationId": "updateAIQuestionFromMessage", "tags": [ "RAG (AI data)" ], "parameters": [ { "name": "message_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "ID of the message to update.", "example": 12345 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "questions": { "type": "array", "items": { "type": "string", "maxLength": 250 }, "example": [ "How do I reset my password?" ] }, "answer": { "type": "string", "maxLength": 5000, "example": "To reset your password..." } }, "required": [ "questions", "answer" ] } } } }, "responses": { "202": { "description": "Q&A source queued for update.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } }, "summary": "Update Q&A message", "description": "Updates an existing Q&A source that was created from a conversation message. If the source doesn't exist yet, it will be created. This allows editing auto-generated Q&A pairs.", "x-mint": { "metadata": { "description": "" }, "content": "Updates an existing Q&A source that was created from a conversation message. If the source doesn't exist yet, it will be created. This allows editing auto-generated Q&A pairs." }, "x-computed-hash": "5271d41a6b0acabdab12661cfab368ed59ef5c30349596636e8efaeda1b3d20a", "x-last-modified": 1769076834 } }, "/organization/rag/sources/{uuid}/retrain": { "post": { "operationId": "retrainAISource", "tags": [ "RAG (AI data)" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "UUID of the URL source to retrain.", "example": "a1b2c3d4e5f6g7h8i9j0" } ], "responses": { "202": { "description": "Source queued for retraining.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request or too recent update.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Only URLs can be refreshed" } } } } } }, "404": { "description": "Source not found." } }, "summary": "Retrain a single URL source", "description": "Refreshes a URL source by re-fetching its content from the web. Only works for URL sources and prevents retraining if the source was updated in the last 5 minutes.", "x-mint": { "metadata": { "description": "" }, "content": "Refreshes a URL source by re-fetching its content from the web. Only works for URL sources and prevents retraining if the source was updated in the last 5 minutes." }, "x-computed-hash": "d083f56ffda185e75e3f9d0a376a7327c907a4575c7f684262f839092ad4d0a2", "x-last-modified": 1769076834 } }, "/organization/rag/sources/{uuid}": { "delete": { "operationId": "deleteAISource", "tags": [ "RAG (AI data)" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "UUID of the source to delete.", "example": "a1b2c3d4e5f6g7h8i9j0" } ], "responses": { "200": { "description": "Source queued for deletion.", "content": { "application/json": { "schema": { "type": "object" } } } } }, "summary": "Delete a single AI source", "description": "Permanently removes a source from the AI store by its UUID. The deletion is processed asynchronously.", "x-mint": { "metadata": { "description": "" }, "content": "Permanently removes a source from the AI store by its UUID. The deletion is processed asynchronously." }, "x-computed-hash": "d3cb5c9fcd0c4965e895109e170bd8ee6a87a22a90b818acd922f433fe2c875e", "x-last-modified": 1769076834 } }, "/organization/rag/sources/texts/{uuid}": { "patch": { "operationId": "updateAITextSource", "tags": [ "RAG (AI data)" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "UUID of the text source to update.", "example": "a1b2c3d4e5f6g7h8i9j0" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string", "maxLength": 50000, "description": "Updated text content.", "example": "This is updated information about our product features..." } }, "required": [ "text" ] } } } }, "responses": { "202": { "description": "Text source queued for update.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input or source is not a Text type.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "You can only update Text sources" } } } } } }, "404": { "description": "Text source not found." } }, "summary": "Update text source", "description": "Updates an existing text source identified by its UUID. Only sources of type \"Text\" can be updated through this endpoint.", "x-mint": { "metadata": { "description": "" }, "content": "Updates an existing text source identified by its UUID. Only sources of type \"Text\" can be updated through this endpoint." }, "x-computed-hash": "a0f37395b829e28ae11ffe04c2506b118bb535b7dc662fb74753a38468ef102e", "x-last-modified": 1769076834 } }, "/conversations/{id}/recipients": { "get": { "operationId": "listConversationRecipients", "tags": [ "Conversations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "ID of the conversation", "example": 12345 } ], "responses": { "200": { "description": "List of recipients retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Recipient" } } } } }, "404": { "description": "Conversation not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } }, "summary": "List all recipients for a conversation", "description": "Retrieves all recipients (to, cc, bcc, reply-to) associated with a specific conversation. Recipients are contacts who are part of the conversation thread and will receive messages sent to it.", "x-mint": { "metadata": { "description": "" }, "content": "Retrieves all recipients (to, cc, bcc, reply-to) associated with a specific conversation. Recipients are contacts who are part of the conversation thread and will receive messages sent to it." }, "x-computed-hash": "0b1165080d48cbe0c9c803d312614ac3594eef3cbcaf798c0c20f46610811ae7", "x-last-modified": 1769076834 }, "post": { "operationId": "addConversationRecipient", "tags": [ "Conversations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "ID of the conversation", "example": 12345 }, { "name": "email", "in": "query", "required": true, "schema": { "type": "string", "format": "email" }, "description": "Email address of the recipient, optionally with name", "example": "Monica Hall " } ], "responses": { "200": { "description": "Recipient added successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Recipient" } } } }, "400": { "description": "Invalid email format", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Invalid email provided" } } } } } }, "404": { "description": "Conversation not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } }, "summary": "Add a recipient to a conversation", "description": "Adds a new recipient to an existing conversation.\nThe recipient can be specified by email address with optional name (in `Name ` format).\nA new contact is created if the email doesn't exist.\nIf this is the first recipient being added to the conversation, they become the 'from' contact; otherwise, they're added as 'cc'.", "x-mint": { "metadata": { "description": "" }, "content": "Adds a new recipient to an existing conversation.\nThe recipient can be specified by email address with optional name (in `Name ` format).\nA new contact is created if the email doesn't exist.\nIf this is the first recipient being added to the conversation, they become the 'from' contact; otherwise, they're added as 'cc'." }, "x-computed-hash": "a129a9ee269ce8613f2d428a7b41cc2114851980a83c34dd4c61f9c4c03e56e5", "x-last-modified": 1773150592 } }, "/conversations/{id}/recipients/{email}": { "delete": { "operationId": "removeConversationRecipient", "tags": [ "Conversations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "ID of the conversation", "example": 12345 }, { "name": "email", "in": "path", "required": true, "schema": { "type": "string", "format": "email" }, "description": "Email address of the recipient to remove", "example": "monica.hall@raviga.com" } ], "responses": { "200": { "description": "Recipient removed successfully", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Cannot remove the main contact from the conversation", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "You cannot remove the main contact from the conversation." } } } } } }, "404": { "description": "Conversation or recipient not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } }, "summary": "Remove a recipient from a conversation", "description": "Removes a recipient identified by their email address from a conversation. The main contact (the original 'from' contact) cannot be removed.", "x-mint": { "metadata": { "description": "" }, "content": "Removes a recipient identified by their email address from a conversation. The main contact (the original 'from' contact) cannot be removed." }, "x-computed-hash": "7a84d3cffd5ed674ed74ee106baeee9758a5e6a821ac67292f05774b2843d6f4", "x-last-modified": 1769076834 } }, "/organization/rules/{id}": { "delete": { "operationId": "deleteRuleset", "tags": [ "Rulesets" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "ID of the ruleset to delete." } ], "responses": { "204": { "description": "Ruleset deleted successfully." }, "404": { "description": "Ruleset not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } }, "summary": "Delete a ruleset", "description": "Permanently deletes a ruleset and all its associated execution history. All rules with higher priority values are automatically shifted up to fill the gap. This action cannot be undone.", "x-mint": { "metadata": { "description": "" }, "content": "Permanently deletes a ruleset and all its associated execution history. All rules with higher priority values are automatically shifted up to fill the gap. This action cannot be undone." }, "x-computed-hash": "8c3afbf2185acb85b3f9ff2142f6be3755cfc24bd73a767a043c8160de454ca6", "x-last-modified": 1769076834 }, "patch": { "operationId": "updateRuleset", "tags": [ "Rulesets" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "ID of the ruleset to update." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 250, "description": "Name of the ruleset (optional).", "example": "Updated rule name" }, "trigger": { "type": "string", "maxLength": 50, "description": "Event that triggers this rule (optional). Must be one of:\nmessages.new_conversation, messages.incoming, messages.response, messages.disable_ai, messages.delivery_failure, messages.spam, messages.note, status.closed, status.opened, status.snoozed, status.unsnoozed, teammates.assigned, teammate.mentioned, time.unanswered_by_client, time.unanswered_by_team, tickets.ticket_done\n", "example": "messages.response" }, "trigger_data": { "type": "string", "description": "Additional data for the trigger (optional):\n- For \"teammates.assigned\" or \"teammate.mentioned\": \"no_one\", \"anyone\", or an Agent ID\n- For \"time.*\" triggers: duration and period in format \"{duration} {period}\" (e.g., \"2 hours\", \"3 days\")\n", "example": "3 hours" }, "filters": { "type": "array", "description": "Array of filter conditions (optional).", "items": { "type": "object" }, "example": [ { "field": "message.content", "operator": "contains", "value": "urgent" } ] }, "actions": { "type": "array", "description": "Array of actions to execute when rule matches (optional).", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the action to execute" }, "data": { "type": "object", "description": "Optional data for the action" } } }, "example": [ { "name": "conversation.tag", "data": { "tag": "urgent" } } ] }, "status": { "type": "string", "enum": [ "PAUSED", "LIVE" ], "description": "Status of the ruleset (optional).", "example": "PAUSED" }, "stop": { "type": "boolean", "description": "If true, stops processing subsequent rules when this rule matches (optional).", "example": true }, "priority": { "type": "integer", "description": "Priority order for rule execution (optional). Other rules are automatically reordered.", "example": 1 } } } } } }, "responses": { "200": { "description": "Ruleset updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ruleset" } } } }, "400": { "description": "Invalid input or validation failed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message describing what went wrong" } } } } } }, "404": { "description": "Ruleset not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } }, "summary": "Update a ruleset", "description": "Updates one or more properties of an existing ruleset. All fields are optional - only provided fields will be updated. When updating priority, the system automatically reorders other rules to maintain consistent priority ordering. Validates that any updated trigger, filters, or actions are properly configured and compatible with each other.", "x-mint": { "metadata": { "description": "" }, "content": "Updates one or more properties of an existing ruleset. All fields are optional - only provided fields will be updated. When updating priority, the system automatically reorders other rules to maintain consistent priority ordering. Validates that any updated trigger, filters, or actions are properly configured and compatible with each other." }, "x-computed-hash": "7e5b670dc4532916c8596d382cf39ce6e187283ceaef97c2475ddaf6ff827344", "x-last-modified": 1776152542 } }, "/organization/rules/{id}/enable": { "post": { "operationId": "enableRuleset", "tags": [ "Rulesets" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "ID of the ruleset to enable." } ], "responses": { "200": { "description": "Ruleset enabled successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ruleset" } } } }, "404": { "description": "Ruleset not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } }, "summary": "Enable a ruleset", "description": "Sets the ruleset status to LIVE, allowing it to be triggered and executed. If the ruleset is already LIVE, no changes are made. An enabled ruleset will automatically execute its actions when its trigger conditions and filters are met.", "x-mint": { "metadata": { "description": "" }, "content": "Sets the ruleset status to LIVE, allowing it to be triggered and executed. If the ruleset is already LIVE, no changes are made. An enabled ruleset will automatically execute its actions when its trigger conditions and filters are met." }, "x-computed-hash": "494e31d3febb1d385e110b35da5512f4c9831c2aefaf81aa70510c5cfd9a9dc3", "x-last-modified": 1769076834 } }, "/organization/rules/{id}/disable": { "post": { "operationId": "disableRuleset", "tags": [ "Rulesets" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "ID of the ruleset to disable." } ], "responses": { "200": { "description": "Ruleset disabled successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ruleset" } } } }, "404": { "description": "Ruleset not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } }, "summary": "Disable a ruleset", "description": "Sets the ruleset status to PAUSED, preventing it from being triggered and executed. If the ruleset is already PAUSED, no changes are made. A disabled ruleset will not execute even if its trigger conditions and filters are met.", "x-mint": { "metadata": { "description": "" }, "content": "Sets the ruleset status to PAUSED, preventing it from being triggered and executed. If the ruleset is already PAUSED, no changes are made. A disabled ruleset will not execute even if its trigger conditions and filters are met." }, "x-computed-hash": "ed52b68e125a7ddb7aaa3ee9c44840961acede5ef70b045b16327699ebd20dab", "x-last-modified": 1769076834 } }, "/snippets/{id}/categories": { "post": { "operationId": "updateSnippetCategories", "tags": [ "Snippets" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "ID of the snippet to update categories for." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "categories": { "type": "array", "items": { "type": "integer" }, "description": "Array of category IDs to assign to this snippet (replaces existing assignments).", "example": [ 1, 3, 5 ] } }, "required": [ "categories" ] } } } }, "responses": { "200": { "description": "Categories updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Snippet" } } } }, "404": { "description": "Snippet not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } }, "summary": "Update snippet's categories", "description": "Updates the categories assigned to a snippet. This endpoint replaces all existing categories with the provided list.", "x-mint": { "metadata": { "description": "" }, "content": "Updates the categories assigned to a snippet. This endpoint replaces all existing categories with the provided list." }, "x-computed-hash": "02f49ecfaba498eb6fa0f131a1d0ab7f85d10a5020f6d8e0b57b7e23e4216cf0", "x-last-modified": 1769076834 } }, "/snippets/{id}": { "delete": { "operationId": "deleteSnippet", "tags": [ "Snippets" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "ID of the snippet to delete." } ], "responses": { "200": { "description": "Snippet deleted successfully.", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Snippet not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } }, "summary": "Delete a snippet", "description": "Permanently deletes the specified snippet and all its associated data including actions and category assignments. This operation cannot be undone.", "x-mint": { "metadata": { "description": "" }, "content": "Permanently deletes the specified snippet and all its associated data including actions and category assignments. This operation cannot be undone." }, "x-computed-hash": "31ba1718fc6386c384c12d6d048b766f24d24c15b9ac872e13db2fae2e1507b8", "x-last-modified": 1769076834 }, "patch": { "operationId": "updateSnippet", "tags": [ "Snippets" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "ID of the snippet to update." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 50, "nullable": true, "description": "New title for the snippet (optional).", "example": "Updated Welcome Message" }, "shortcut": { "type": "string", "maxLength": 40, "pattern": "^[a-z0-9-]*$", "nullable": true, "description": "New keyboard shortcut (optional, lowercase, numbers, and dashes only).", "example": "welcome2" }, "categories": { "type": "array", "items": { "type": "integer" }, "nullable": true, "description": "New array of category IDs (optional, replaces existing categories).", "example": [ 2, 4 ] }, "actions": { "type": "array", "minItems": 1, "maxItems": 10, "items": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "status", "assign", "snooze", "reply", "note", "tag" ], "description": "Name of the action to apply.", "example": "assign" }, "data": { "type": "object", "description": "Action-specific data payload.", "example": { "agent_id": 5 } } } }, "nullable": true, "description": "New array of actions (optional, 1-10 actions if provided).", "example": [ { "name": "assign", "data": { "agent_id": 5 } } ] } } } } } }, "responses": { "200": { "description": "Snippet updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Snippet" } } } }, "400": { "description": "Invalid input or validation error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Snippet not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } }, "summary": "Update a snippet", "description": "Updates an existing snippet. All fields are optional, allowing partial updates. If categories are included in the request, they will replace the existing category assignments. Actions are validated to ensure they are supported with a maximum of 10 actions per snippet.", "x-mint": { "metadata": { "description": "" }, "content": "Updates an existing snippet. All fields are optional, allowing partial updates. If categories are included in the request, they will replace the existing category assignments. Actions are validated to ensure they are supported with a maximum of 10 actions per snippet." }, "x-computed-hash": "d280f0df2df5a8d683d71a44ff1387f7dba778d00a926f99bcccd057aebfdd81", "x-last-modified": 1769076834 } }, "/snippets/categories/{id}": { "get": { "operationId": "getSnippetCategory", "tags": [ "Snippet Categories" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "ID of the category to retrieve." } ], "responses": { "200": { "description": "Category retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SnippetCategory" } } } }, "404": { "description": "Category not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } }, "summary": "Get details of a snippet category", "description": "Retrieves the details of a single snippet category by its ID.", "x-mint": { "metadata": { "description": "" }, "content": "Retrieves the details of a single snippet category by its ID." }, "x-computed-hash": "d76046f2b8e969b667e43c0fd41d258c1f8478ca13038452f9ff2c0347f0d23b", "x-last-modified": 1769076834 }, "patch": { "operationId": "updateSnippetCategory", "tags": [ "Snippet Categories" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "ID of the category to update." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 50, "nullable": true, "description": "New name for the category (optional).", "example": "Updated Support" } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Category updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SnippetCategory" } } } }, "400": { "description": "Invalid input.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Category not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } }, "summary": "Update a snippet category's name", "description": "Updates the name of an existing snippet category. The parent relationship and sort position are managed through the separate position endpoint.", "x-mint": { "metadata": { "description": "" }, "content": "Updates the name of an existing snippet category. The parent relationship and sort position are managed through the separate position endpoint." }, "x-computed-hash": "43af18e1f50bec1d114fb3010c539b47c9d7eed2a8d2c6c356cdc3ffe6af5abd", "x-last-modified": 1769076834 }, "delete": { "operationId": "deleteSnippetCategory", "tags": [ "Snippet Categories" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "ID of the category to delete." } ], "responses": { "200": { "description": "Category deleted successfully.", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Category not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } }, "summary": "Delete a snippet category", "description": "Permanently deletes the specified snippet category and all its child categories recursively. This operation also removes all snippet assignments to the deleted categories. This operation cannot be undone.", "x-mint": { "metadata": { "description": "" }, "content": "Permanently deletes the specified snippet category and all its child categories recursively. This operation also removes all snippet assignments to the deleted categories. This operation cannot be undone." }, "x-computed-hash": "1da160459b602f32c7812ef64b9dcbccd6e407e97efa4480f0df7635f523e024", "x-last-modified": 1769076834 } }, "/snippets/categories/{id}/position": { "patch": { "operationId": "updateSnippetCategoryPosition", "tags": [ "Snippet Categories" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "ID of the category to reposition." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "parent_id": { "type": "integer", "nullable": true, "description": "ID of the new parent category (optional, null for root-level).", "example": 3 }, "position": { "type": "integer", "description": "New position within the parent (0-based index, required).", "example": 2 } }, "required": [ "position" ] } } } }, "responses": { "200": { "description": "Category position updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SnippetCategory" } } } }, "400": { "description": "Invalid input or parent category not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Category not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } }, "summary": "Update a category's position and parent", "description": "Updates the sort position and parent relationship of a snippet category. This endpoint allows you to reorder categories within their parent or move them to a different parent category. The position is 0-based, and all sibling categories are automatically reordered to maintain a consistent sequence.", "x-mint": { "metadata": { "description": "" }, "content": "Updates the sort position and parent relationship of a snippet category. This endpoint allows you to reorder categories within their parent or move them to a different parent category. The position is 0-based, and all sibling categories are automatically reordered to maintain a consistent sequence." }, "x-computed-hash": "983cb2eb67fef9be82ae74eb4cd59272c99798c58cb0e4f1aab7d32a309270f8", "x-last-modified": 1769076834 } }, "/tags/{slug}": { "delete": { "operationId": "deleteTag", "tags": [ "Tags" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Slug of the tag to delete", "example": "old-tag" }, { "name": "force", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Force deletion even if tag is used in rules or snippets", "example": true } ], "responses": { "200": { "description": "Tag deleted successfully", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Cannot delete system tag", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "You can not delete a restricted tag." } } } } } }, "404": { "description": "Tag not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "428": { "description": "Precondition required - tag is used in rules/snippets and force parameter is needed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "The tag \"VIP\" is used on the Rule \"Assign VIP customers\". Are you sure you want to delete it?" } } } } } } }, "summary": "Delete a tag", "description": "Deletes a tag identified by its slug. System tags cannot be deleted. If the tag is used in any rules or snippets, the deletion requires a force parameter. When forced, the tag is removed from all rules where it's used, and rules with no remaining actions are also deleted.", "x-mint": { "metadata": { "description": "" }, "content": "Deletes a tag identified by its slug. System tags cannot be deleted. If the tag is used in any rules or snippets, the deletion requires a force parameter. When forced, the tag is removed from all rules where it's used, and rules with no remaining actions are also deleted." }, "x-computed-hash": "8b34a148d4096d04de332b30fb2f532a033e767ec205b80c7006da89e8b0db1a", "x-last-modified": 1769076834 }, "patch": { "operationId": "updateTag", "tags": [ "Tags" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Slug of the tag to update", "example": "vip-customer" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 50, "description": "New name for the tag", "example": "Premium Customer" }, "color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$", "description": "New hex color code for the tag", "example": "#00FF00" } } } } } }, "responses": { "200": { "description": "Tag updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tag" } } } }, "400": { "description": "Invalid input or validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Tag not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } }, "summary": "Update a tag", "description": "Updates the name and/or color of an existing tag identified by its slug. If the name is changed, the slug will be automatically regenerated. System tags cannot be modified.", "x-mint": { "metadata": { "description": "" }, "content": "Updates the name and/or color of an existing tag identified by its slug. If the name is changed, the slug will be automatically regenerated. System tags cannot be modified." }, "x-computed-hash": "8a54d7fa0dec1df9530c654e82fcb42096d3a13190a347f0eb77947b738a8efb", "x-last-modified": 1769076834 } }, "/knowledge/collections/{id}": { "patch": { "operationId": "updateCollection", "tags": [ "Knowledge Collections" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "ID of the collection to update." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 250, "description": "Display title of the collection (optional)." }, "slug": { "type": "string", "maxLength": 250, "pattern": "^[a-z0-9_-]+$", "description": "URL-safe slug (optional, lowercase alphanumeric with dashes/underscores)." }, "icon": { "type": "string", "maxLength": 25, "nullable": true, "description": "Emoji icon identifier (optional)." }, "description": { "type": "string", "maxLength": 1000, "nullable": true, "description": "Collection description (optional)." }, "parent_id": { "type": "integer", "nullable": true, "description": "ID of the parent collection (optional, null for root-level)." }, "seo_title": { "type": "string", "maxLength": 250, "nullable": true, "description": "SEO-optimized title (optional)." }, "seo_description": { "type": "string", "maxLength": 1250, "nullable": true, "description": "SEO-optimized description (optional)." }, "sort": { "type": "integer", "description": "New sort position (zero-based, optional). When provided, only updates sort order and ignores other fields." } } } } } }, "responses": { "200": { "description": "Collection updated successfully. Returns empty response when only sort was updated, otherwise returns the updated collection.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Collection" }, { "type": "object", "properties": {}, "description": "Empty response when sort order was updated." } ] } } } }, "400": { "description": "Invalid input or slug already in use.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Collection not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } }, "summary": "Update a collection", "description": "Updates collection properties. When updating the sort order, provide only the 'sort' field with the new zero-based position - this will reorder the collection within its parent and adjust neighboring collections automatically. When updating other fields, the slug uniqueness is validated if changed. Parent_id can be modified to move collections between parents or to root level.", "x-mint": { "metadata": { "description": "" }, "content": "Updates collection properties. When updating the sort order, provide only the 'sort' field with the new zero-based position - this will reorder the collection within its parent and adjust neighboring collections automatically. When updating other fields, the slug uniqueness is validated if changed. Parent_id can be modified to move collections between parents or to root level." }, "x-computed-hash": "57d610974286a34454d0c93408248ebcf37ea3cda2b972eb1fd48807ce54a8ff", "x-last-modified": 1769076834 }, "delete": { "operationId": "deleteCollection", "tags": [ "Knowledge Collections" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "ID of the collection to delete." } ], "responses": { "200": { "description": "Collection deleted successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "400": { "description": "Collection is not empty and cannot be deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Cannot delete this collection because it isn't empty." } } } } } }, "404": { "description": "Collection not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } }, "summary": "Delete a collection", "description": "Permanently deletes a collection from the knowledge base. The collection must be empty - it cannot contain any articles or sub-collections. This prevents accidental deletion of content. If the collection has articles or nested collections, you must first move or delete them before deleting the parent collection. After deletion, the sort order of remaining sibling collections is automatically adjusted.", "x-mint": { "metadata": { "description": "" }, "content": "Permanently deletes a collection from the knowledge base. The collection must be empty - it cannot contain any articles or sub-collections. This prevents accidental deletion of content. If the collection has articles or nested collections, you must first move or delete them before deleting the parent collection. After deletion, the sort order of remaining sibling collections is automatically adjusted." }, "x-computed-hash": "f69f9aed2ce50a629a4850e30ba6d71a3af0f6760f5bda4e8371e236234af600", "x-last-modified": 1769076834 } }, "/knowledge/articles/{id}": { "patch": { "operationId": "updateArticle", "tags": [ "Knowledge Articles" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "ID of the article to update." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 250, "description": "Display title of the article (optional)." }, "seo_title": { "type": "string", "maxLength": 250, "nullable": true, "description": "SEO-optimized title (optional)." }, "slug": { "type": "string", "maxLength": 250, "pattern": "^[a-z0-9_-]+$", "description": "URL-safe slug (optional, must be unique)." }, "previous_url": { "type": "string", "maxLength": 250, "nullable": true, "description": "Previous URL for migration tracking (optional)." }, "description": { "type": "string", "maxLength": 250, "nullable": true, "description": "Brief description for SEO (optional)." }, "content": { "type": "string", "maxLength": 16000000, "nullable": true, "description": "HTML content with images (optional)." }, "collections": { "type": "array", "items": { "type": "integer", "nullable": true }, "nullable": true, "description": "Array of collection IDs (optional, at least one if provided)." }, "published": { "type": "boolean", "description": "Publication status (optional)." }, "visibility": { "type": "string", "maxLength": 10, "enum": [ "public", "chat", "chat_auth" ], "nullable": true, "description": "Visibility setting (optional)." } } } } } }, "responses": { "200": { "description": "Article updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Article" } } } }, "400": { "description": "Invalid input or slug already in use.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Article not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } }, "summary": "Update an article", "description": "Updates article properties. Publishing an article generates a social banner and processes content. Collection assignments can be modified - new collections are added, removed collections trigger sort order updates. If the article URL changes (slug or collections), internal references are updated. Changes to content or slug update the AI data store if enabled.", "x-mint": { "metadata": { "description": "" }, "content": "Updates article properties. Publishing an article generates a social banner and processes content. Collection assignments can be modified - new collections are added, removed collections trigger sort order updates. If the article URL changes (slug or collections), internal references are updated. Changes to content or slug update the AI data store if enabled." }, "x-computed-hash": "f784d487aa5c22c402a2e7c247987f4509df1d3178113643d341ae984a2e9180", "x-last-modified": 1769076834 }, "delete": { "operationId": "deleteArticle", "tags": [ "Knowledge Articles" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "ID of the article to delete." } ], "responses": { "200": { "description": "Article deleted successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "404": { "description": "Article not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } }, "summary": "Delete an article", "description": "Delete an article from the Knowledge Base. The article is removed from all collections it belongs to, and collection sort orders are automatically adjusted. The article is removed from the knowledge base structure and search indexes. If the article had a URL that changes due to deletion, internal references are updated to prevent broken links.", "x-mint": { "metadata": { "description": "" }, "content": "Delete an article from the Knowledge Base. The article is removed from all collections it belongs to, and collection sort orders are automatically adjusted. The article is removed from the knowledge base structure and search indexes. If the article had a URL that changes due to deletion, internal references are updated to prevent broken links." }, "x-computed-hash": "5e124803d68a106f1975d7f42c21f5256d753a2faebc752dc0263a9aa21bbd91", "x-last-modified": 1769076834 }, "get": { "operationId": "getArticle", "tags": [ "Knowledge Articles" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "ID of the article to retrieve." } ], "responses": { "200": { "description": "Article retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Article" } } } }, "404": { "description": "Article not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } }, "summary": "Retrieve an article", "description": "Returns the complete article data. This endpoint includes the full HTML content and all associated metadata for displaying or editing the article.", "x-mint": { "metadata": { "description": "" }, "content": "Returns the complete article data. This endpoint includes the full HTML content and all associated metadata for displaying or editing the article." }, "x-computed-hash": "19748ed6734636c501b96d9f3a590e2b7054cf7ed63a7e7b14581e7b74da84e2", "x-last-modified": 1769076834 } }, "/knowledge/articles/{id}/collections": { "patch": { "operationId": "updateArticleSort", "tags": [ "Knowledge Articles" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "ID of the article to reorder." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sort": { "type": "integer", "description": "New zero-based sort position within the collection (required).", "example": 2 }, "collection_id": { "type": "integer", "nullable": true, "description": "ID of the collection to reorder within (required, null for root level)." } }, "required": [ "sort", "collection_id" ] } } } }, "responses": { "200": { "description": "Article sort order updated successfully.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ArticleInCollection" }, "description": "Updated list of all collection assignments for this article with their sort positions." } } } }, "400": { "description": "Invalid sort position or collection_id.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Article or collection assignment not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } }, "summary": "Update the position of an article", "description": "Changes the display order of an article within a specific collection. The article maintains its position in other collections it belongs to. Provide the zero-based sort position and the collection_id (or null for root). The endpoint automatically adjusts the sort order of surrounding articles to maintain sequence integrity. This is collection-scoped - it reorders the article within one collection, not across all collections the article belongs to.", "x-mint": { "metadata": { "description": "" }, "content": "Changes the display order of an article within a specific collection. The article maintains its position in other collections it belongs to. Provide the zero-based sort position and the collection_id (or null for root). The endpoint automatically adjusts the sort order of surrounding articles to maintain sequence integrity. This is collection-scoped - it reorders the article within one collection, not across all collections the article belongs to." }, "x-computed-hash": "0d72c4b1c981ad1d615ffb65a38d06b4d7385d3569e063ccb65a49f0810b4faf", "x-last-modified": 1769076834 } }, "/knowledge/links/{id}": { "patch": { "operationId": "updateLink", "tags": [ "Knowledge Links" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "ID of the link to update." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 60, "description": "Display text for the link (optional)." }, "url": { "type": "string", "maxLength": 250, "description": "Destination URL (optional, automatically prefixed with https:// if missing)." }, "target": { "type": "string", "maxLength": 6, "enum": [ "_blank", "_self" ], "description": "Link target behavior (optional)." }, "position": { "type": "string", "maxLength": 6, "enum": [ "HEADER", "FOOTER" ], "description": "Display position (optional, case-insensitive)." }, "sort": { "type": "integer", "description": "New sort position (zero-based, optional). When provided, only updates sort order and returns empty response." } } } } } }, "responses": { "200": { "description": "Link updated successfully. Returns empty response when only sort was updated, otherwise returns the updated link.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/KnowledgeLinkLang" }, { "type": "object", "properties": {}, "description": "Empty response when sort order was updated." } ] } } } }, "400": { "description": "Invalid input.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Link not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } }, "summary": "Update a link", "description": "Updates link properties. When updating the sort order, provide only the 'sort' field with the new zero-based position - this will reorder the link within its position (HEADER or FOOTER) and adjust neighboring links automatically. When updating other fields, all link properties can be modified individually or together. URLs are automatically prefixed with https:// if no protocol is provided.", "x-mint": { "metadata": { "description": "" }, "content": "Updates link properties. When updating the sort order, provide only the 'sort' field with the new zero-based position - this will reorder the link within its position (HEADER or FOOTER) and adjust neighboring links automatically. When updating other fields, all link properties can be modified individually or together. URLs are automatically prefixed with https:// if no protocol is provided." }, "x-computed-hash": "d299af7940fb2557daf6056fd127c5b8e0ccd7804a433878a4bc99360d7e7538", "x-last-modified": 1769076834 }, "delete": { "operationId": "deleteLink", "tags": [ "Knowledge Links" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "ID of the link to delete." } ], "responses": { "200": { "description": "Link deleted successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "404": { "description": "Link not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } }, "summary": "Delete a link", "description": "Permanently removes a navigation link from the knowledge base. After deletion, the sort order of remaining links in the same position is automatically adjusted to maintain proper sequence.", "x-mint": { "metadata": { "description": "" }, "content": "Permanently removes a navigation link from the knowledge base. After deletion, the sort order of remaining links in the same position is automatically adjusted to maintain proper sequence." }, "x-computed-hash": "64b0ca5cfb245f00220a02b45bdd84e174cf7048f64e523cda85e7f9bf86684f", "x-last-modified": 1769076834 } }, "/integrations/github/{conversation_id}/tickets/{ticket_id}": { "put": { "operationId": "attachGithubTicket", "tags": [ "GitHub Integration" ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "ID of the conversation to attach the issue to.", "example": 12345 }, { "name": "ticket_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the GitHub issue to attach.", "example": "I_kwDOABCDEF" } ], "responses": { "200": { "description": "GitHub issue attached successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the GitHub issue.", "example": "I_kwDOABCDEF" }, "number": { "type": "integer", "description": "Issue number within the repository.", "example": 42 }, "title": { "type": "string", "description": "Title of the issue.", "example": "Fix login bug" }, "url": { "type": "string", "description": "URL to view the issue on GitHub.", "example": "https://github.com/piedpiper/www/issues/42" }, "state_reason": { "type": "string", "description": "Reason for the current state (COMPLETED, NOT_PLANNED, REOPENED, or null if open).", "example": null }, "updated_at": { "type": "string", "description": "ISO 8601 timestamp of last update.", "example": "2024-01-15T10:30:00Z" }, "closed_at": { "type": "string", "description": "ISO 8601 timestamp when the issue was closed (null if open).", "example": null }, "assignee": { "type": "object", "description": "Assigned user (null if unassigned).", "properties": { "id": { "type": "string", "description": "Unique identifier of the assignee.", "example": "U_kgDOABCDEF" }, "login": { "type": "string", "description": "GitHub username of the assignee.", "example": "richard.hendricks" }, "name": { "type": "string", "description": "Display name of the assignee.", "example": "Richard H." }, "avatar_url": { "type": "string", "description": "URL to the assignee's avatar image.", "example": "https://avatars.githubusercontent.com/u/123456" } } }, "labels": { "type": "array", "description": "List of labels applied to the issue.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the label.", "example": "LA_kwDOABCDEF" }, "name": { "type": "string", "description": "Name of the label.", "example": "bug" }, "color": { "type": "string", "description": "Color hex code of the label.", "example": "d73a4a" } } } }, "type": { "type": "object", "description": "Issue type (null if no type is set).", "properties": { "id": { "type": "string", "description": "Unique identifier of the issue type.", "example": "IT_kwDOABCDEF" }, "name": { "type": "string", "description": "Name of the issue type.", "example": "Bug" }, "color": { "type": "string", "description": "Color hex code of the issue type.", "example": "d73a4a" } } } } } } } }, "404": { "description": "GitHub integration, conversation, or issue not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Unable to find the given ticket at Github" } } } } } } }, "summary": "Attach a GitHub issue to a conversation", "description": "Attaches an existing GitHub issue to the specified conversation. The issue must exist in one of the repositories that the GitHub integration has access to. A comment is added to the issue with a link to the related conversation in Fernand. Returns a 404 error if the issue cannot be found.", "x-mint": { "metadata": { "description": "" }, "content": "Attaches an existing GitHub issue to the specified conversation. The issue must exist in one of the repositories that the GitHub integration has access to. A comment is added to the issue with a link to the related conversation in Fernand. Returns a 404 error if the issue cannot be found." }, "x-computed-hash": "a68ec8681d327c98c82aa80cd7dee6f22bf23b3beda597a3f6e1e8c7edbd47d0", "x-last-modified": 1769076834 }, "delete": { "operationId": "detachGithubTicket", "tags": [ "GitHub Integration" ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "ID of the conversation to detach the issue from.", "example": 12345 }, { "name": "ticket_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the GitHub issue to detach.", "example": "I_kwDOABCDEF" } ], "responses": { "200": { "description": "GitHub issue detached successfully.", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Conversation not found." } }, "summary": "Detach a GitHub issue from a conversation", "description": "Removes the association between a GitHub issue and the specified conversation. This does not delete the issue on GitHub, only removes the link between the conversation and the issue. Returns an empty response on success.", "x-mint": { "metadata": { "description": "" }, "content": "Removes the association between a GitHub issue and the specified conversation. This does not delete the issue on GitHub, only removes the link between the conversation and the issue. Returns an empty response on success." }, "x-computed-hash": "3a85b4ff481fd110481fbcf74647e5346d646a58ea9eb599726520ca96c58a1d", "x-last-modified": 1769076834 } }, "/integrations/github/{conversation_id}/tickets": { "get": { "operationId": "listGithubTickets", "tags": [ "GitHub Integration" ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "ID of the conversation to retrieve tickets for.", "example": 12345 } ], "responses": { "200": { "description": "GitHub tickets retrieved successfully.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the GitHub issue.", "example": "I_kwDOABCDEF" }, "number": { "type": "integer", "description": "Issue number within the repository.", "example": 42 }, "title": { "type": "string", "description": "Title of the issue.", "example": "Fix login bug" }, "url": { "type": "string", "description": "URL to view the issue on GitHub.", "example": "https://github.com/piedpiper/www/issues/42" }, "state_reason": { "type": "string", "description": "Reason for the current state (COMPLETED, NOT_PLANNED, REOPENED, or null if open).", "example": "COMPLETED" }, "updated_at": { "type": "string", "description": "ISO 8601 timestamp of last update.", "example": "2024-01-15T10:30:00Z" }, "closed_at": { "type": "string", "description": "ISO 8601 timestamp when the issue was closed (null if open).", "example": "2024-01-15T10:30:00Z" }, "assignee": { "type": "object", "description": "Assigned user (null if unassigned).", "properties": { "id": { "type": "string", "description": "Unique identifier of the assignee.", "example": "U_kgDOABCDEF" }, "login": { "type": "string", "description": "GitHub username of the assignee.", "example": "richard.hendricks" }, "name": { "type": "string", "description": "Display name of the assignee.", "example": "Richard H." }, "avatar_url": { "type": "string", "description": "URL to the assignee's avatar image.", "example": "https://avatars.githubusercontent.com/u/123456" } } }, "labels": { "type": "array", "description": "List of labels applied to the issue.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the label.", "example": "LA_kwDOABCDEF" }, "name": { "type": "string", "description": "Name of the label.", "example": "bug" }, "color": { "type": "string", "description": "Color hex code of the label.", "example": "d73a4a" } } } }, "type": { "type": "object", "description": "Issue type (null if no type is set).", "properties": { "id": { "type": "string", "description": "Unique identifier of the issue type.", "example": "IT_kwDOABCDEF" }, "name": { "type": "string", "description": "Name of the issue type.", "example": "Bug" }, "color": { "type": "string", "description": "Color hex code of the issue type.", "example": "d73a4a" } } } } } } } } }, "404": { "description": "GitHub integration not found for this organization." }, "502": { "description": "Error occurred at GitHub while fetching tickets.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "An error occured at Github" } } } } } } }, "summary": "Get GitHub tickets attached to a conversation", "description": "Returns a list of GitHub issues attached to the specified conversation.\nReturns a 404 error if the GitHub integration is not configured for the organization.", "x-mint": { "metadata": { "description": "" }, "content": "Returns a list of GitHub issues attached to the specified conversation.\nReturns a 404 error if the GitHub integration is not configured for the organization." }, "x-computed-hash": "be1008e9821c8efc1d91248656b9cde6e76fd5d1f6d888c09b2733a7e2f51721", "x-last-modified": 1769076834 }, "post": { "operationId": "createGithubTicket", "tags": [ "GitHub Integration" ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "ID of the conversation to attach the issue to.", "example": 12345 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "Title of the GitHub issue (required, max 250 characters).", "example": "Fix login authentication bug" }, "description": { "type": "string", "description": "Description/body of the issue (optional, max 250,000 characters).", "example": "Users are unable to log in with their credentials. The authentication service returns a 500 error." }, "repository": { "type": "string", "description": "ID of the repository to create the issue in (required).", "example": "R_kgDOABCDEF" }, "assignee": { "type": "string", "description": "ID of the user to assign the issue to (optional).", "example": "U_kgDOABCDEF" }, "milestone": { "type": "string", "description": "ID of the milestone to associate the issue with (optional).", "example": "M_kwDOABCDEF" }, "type": { "type": "string", "description": "ID of the issue type (optional).", "example": "IT_kwDOABCDEF" }, "labels": { "type": "array", "description": "Array of label IDs to apply to the issue (optional).", "items": { "type": "string" }, "example": [ "LA_kwDOABCDEF", "LA_kwDOXYZ123" ] }, "projects": { "type": "array", "description": "Array of project IDs to add the issue to (optional).", "items": { "type": "string" }, "example": [ "PVT_kwDOABCDEF" ] } }, "required": [ "title", "repository" ] } } } }, "responses": { "200": { "description": "GitHub issue created and attached successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the created GitHub issue.", "example": "I_kwDOABCDEF" }, "number": { "type": "integer", "description": "Issue number within the repository.", "example": 42 }, "title": { "type": "string", "description": "Title of the issue.", "example": "Fix login authentication bug" }, "url": { "type": "string", "description": "URL to view the issue on GitHub.", "example": "https://github.com/piedpiper/www/issues/42" }, "state_reason": { "type": "string", "description": "Reason for the current state (null for newly created issues).", "example": null }, "updated_at": { "type": "string", "description": "ISO 8601 timestamp of last update.", "example": "2024-01-15T10:30:00Z" }, "closed_at": { "type": "string", "description": "ISO 8601 timestamp when the issue was closed (null for open issues).", "example": null }, "assignee": { "type": "object", "description": "Assigned user (null if unassigned).", "properties": { "id": { "type": "string", "description": "Unique identifier of the assignee.", "example": "U_kgDOABCDEF" }, "login": { "type": "string", "description": "GitHub username of the assignee.", "example": "richard.hendricks" }, "name": { "type": "string", "description": "Display name of the assignee.", "example": "Richard H." }, "avatar_url": { "type": "string", "description": "URL to the assignee's avatar image.", "example": "https://avatars.githubusercontent.com/u/123456" } } }, "labels": { "type": "array", "description": "List of labels applied to the issue.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the label.", "example": "LA_kwDOABCDEF" }, "name": { "type": "string", "description": "Name of the label.", "example": "bug" }, "color": { "type": "string", "description": "Color hex code of the label.", "example": "d73a4a" } } } }, "type": { "type": "object", "description": "Issue type (null if no type is set).", "properties": { "id": { "type": "string", "description": "Unique identifier of the issue type.", "example": "IT_kwDOABCDEF" }, "name": { "type": "string", "description": "Name of the issue type.", "example": "Bug" }, "color": { "type": "string", "description": "Color hex code of the issue type.", "example": "d73a4a" } } } } } } } }, "400": { "description": "Invalid input or error creating issue at GitHub.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Github response errors: Invalid repository ID" } } } } } }, "404": { "description": "GitHub integration or conversation not found." }, "502": { "description": "Error occurred at GitHub while creating the issue.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "An error occured at Github" } } } } } } }, "summary": "Create a new GitHub issue and attach it to a conversation", "description": "Creates a new GitHub issue with the provided details and automatically attaches it to the specified conversation. The issue is created in the specified repository. A comment is added to the issue with a link to the related conversation in Fernand.", "x-mint": { "metadata": { "description": "" }, "content": "Creates a new GitHub issue with the provided details and automatically attaches it to the specified conversation. The issue is created in the specified repository. A comment is added to the issue with a link to the related conversation in Fernand." }, "x-computed-hash": "e2ff410a597c3b553f5b47159bd1326963185b3273f20b2a51aebc32aacb3cd1", "x-last-modified": 1769076834 } }, "/integrations/linear/{conversation_id}/tickets/{linear_id}": { "patch": { "operationId": "updateLinearTicket", "tags": [ "Linear Integration" ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "ID of the conversation the issue is attached to.", "example": 12345 }, { "name": "linear_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the Linear issue to update.", "example": "8a7b93d1-18f7-4a9f-b5c6-3e2d1f9a8c7b" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "priority": { "type": "integer", "description": "Priority level - 0 (No priority), 1 (Urgent), 2 (High), 3 (Medium), 4 (Low) (required).", "example": 2 } }, "required": [ "priority" ] } } } }, "responses": { "200": { "description": "Linear issue updated successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the Linear issue.", "example": "8a7b93d1-18f7-4a9f-b5c6-3e2d1f9a8c7b" }, "title": { "type": "string", "description": "Title of the issue.", "example": "Fix authentication bug" }, "url": { "type": "string", "description": "URL to view the issue in Linear.", "example": "https://linear.app/team/issue/ENG-123" }, "identifier": { "type": "string", "description": "Human-readable issue identifier.", "example": "ENG-123" }, "assignee": { "type": "object", "description": "Assigned user (null if unassigned).", "properties": { "name": { "type": "string", "description": "Display name of the assignee.", "example": "Richard Hendricks" }, "avatar_url": { "type": "string", "description": "URL to the assignee's avatar image.", "example": "https://avatar.linear.app/9c0d1e2f" } } }, "state": { "type": "object", "description": "Current workflow state of the issue.", "properties": { "name": { "type": "string", "description": "Name of the workflow state.", "example": "In Progress" }, "type": { "type": "string", "description": "Type of the workflow state.", "example": "started" }, "color": { "type": "string", "description": "Color hex code of the workflow state.", "example": "#f2c94c" }, "verbose": { "type": "string", "description": "ISO 8601 timestamp verbose format.", "example": "2024-01-15T10:30:00+00:00" }, "last_updated_at": { "type": "string", "description": "ISO 8601 timestamp of when the issue entered this state.", "example": "2024-01-15T10:30:00Z" } } }, "labels": { "type": "array", "description": "List of labels applied to the issue.", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the label.", "example": "bug" }, "color": { "type": "string", "description": "Color hex code of the label.", "example": "#5e6ad2" } } } }, "priority": { "type": "integer", "description": "Priority level (0=No priority, 1=Urgent, 2=High, 3=Medium, 4=Low).", "example": 2 }, "priority_label": { "type": "string", "description": "Display name of the priority level.", "example": "High" }, "last_updated_at": { "type": "string", "description": "ISO 8601 timestamp of the last update.", "example": "2024-01-15T10:30:00Z" } } } } } }, "404": { "description": "Linear integration or conversation not found." } }, "summary": "Update a Linear issue", "description": "Updates properties of a Linear issue that is attached to the specified conversation. Currently only supports updating the priority level of the issue. The priority must be a valid value between 0 (No priority) and 4 (Low). Returns the updated issue details.", "x-mint": { "metadata": { "description": "" }, "content": "Updates properties of a Linear issue that is attached to the specified conversation. Currently only supports updating the priority level of the issue. The priority must be a valid value between 0 (No priority) and 4 (Low). Returns the updated issue details." }, "x-computed-hash": "1158b4b80fc260cbe43085af3f44de0d1c8e668ec4f7425daf3d8fb3c6586dba", "x-last-modified": 1769076834 }, "delete": { "operationId": "detachLinearTicket", "tags": [ "Linear Integration" ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "ID of the conversation to detach the issue from.", "example": 12345 }, { "name": "linear_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the Linear issue to detach.", "example": "8a7b93d1-18f7-4a9f-b5c6-3e2d1f9a8c7b" } ], "responses": { "200": { "description": "Linear issue detached successfully.", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Linear integration or conversation not found." } }, "summary": "Detach a Linear issue from a conversation", "description": "Removes the association between a Linear issue and the specified conversation. This does not delete the issue in Linear, only removes the link between the conversation and the issue. Also removes any Fernand-created attachments and customer links from the Linear issue. Returns an empty response on success.", "x-mint": { "metadata": { "description": "" }, "content": "Removes the association between a Linear issue and the specified conversation. This does not delete the issue in Linear, only removes the link between the conversation and the issue. Also removes any Fernand-created attachments and customer links from the Linear issue. Returns an empty response on success." }, "x-computed-hash": "a2b559f38276c2f1dce1f5c591d341a15115631ef1fad0e95e8df991682d1cda", "x-last-modified": 1769076834 }, "put": { "operationId": "attachLinearTicket", "tags": [ "Linear Integration" ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "ID of the conversation to attach the issue to.", "example": 12345 }, { "name": "linear_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the Linear issue to attach.", "example": "8a7b93d1-18f7-4a9f-b5c6-3e2d1f9a8c7b" } ], "responses": { "200": { "description": "Linear issue attached successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the Linear issue.", "example": "8a7b93d1-18f7-4a9f-b5c6-3e2d1f9a8c7b" }, "title": { "type": "string", "description": "Title of the issue.", "example": "Fix authentication bug" }, "url": { "type": "string", "description": "URL to view the issue in Linear.", "example": "https://linear.app/team/issue/ENG-123" }, "identifier": { "type": "string", "description": "Human-readable issue identifier.", "example": "ENG-123" }, "assignee": { "type": "object", "description": "Assigned user (null if unassigned).", "properties": { "name": { "type": "string", "description": "Display name of the assignee.", "example": "John Doe" }, "avatar_url": { "type": "string", "description": "URL to the assignee's avatar image.", "example": "https://avatar.linear.app/9c0d1e2f" } } }, "state": { "type": "object", "description": "Current workflow state of the issue.", "properties": { "name": { "type": "string", "description": "Name of the workflow state.", "example": "In Progress" }, "type": { "type": "string", "description": "Type of the workflow state.", "example": "started" }, "color": { "type": "string", "description": "Color hex code of the workflow state.", "example": "#f2c94c" }, "verbose": { "type": "string", "description": "ISO 8601 timestamp verbose format.", "example": "2026-01-15T10:30:00+00:00" }, "last_updated_at": { "type": "string", "description": "ISO 8601 timestamp of when the issue entered this state.", "example": "2026-01-15T10:30:00Z" } } }, "labels": { "type": "array", "description": "List of labels applied to the issue.", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the label.", "example": "bug" }, "color": { "type": "string", "description": "Color hex code of the label.", "example": "#5e6ad2" } } } }, "attachments": { "type": "array", "description": "List of attachments on the issue.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the attachment.", "example": "2f3a4b5c-6d7e-8f9a-0b1c-2d3e4f5a6b7c" }, "url": { "type": "string", "description": "URL of the attachment.", "example": "https://app.getfernand.com/conversations/12345" } } } }, "priority": { "type": "integer", "description": "Priority level (0=No priority, 1=Urgent, 2=High, 3=Medium, 4=Low).", "example": 1 }, "priority_label": { "type": "string", "description": "Display name of the priority level.", "example": "Urgent" }, "last_updated_at": { "type": "string", "description": "ISO 8601 timestamp of the last update.", "example": "2026-01-15T10:30:00Z" } } } } } }, "404": { "description": "Linear integration, conversation, or issue not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Unable to find the given ticket at Linear" } } } } } } }, "summary": "Attach a Linear issue to a conversation", "description": "Attaches an existing Linear issue to the specified conversation. The issue must exist at Linear. An attachment and customer link are added to the issue linking it to the conversation in Fernand. Returns a 404 error if the issue cannot be found.", "x-mint": { "metadata": { "description": "" }, "content": "Attaches an existing Linear issue to the specified conversation. The issue must exist at Linear. An attachment and customer link are added to the issue linking it to the conversation in Fernand. Returns a 404 error if the issue cannot be found." }, "x-computed-hash": "12451006b962d917b81877bf95d680672f84e420373b8a5fa77c5e9f8fb15bdf", "x-last-modified": 1769076834 } }, "/integrations/linear/{conversation_id}/tickets": { "get": { "operationId": "listLinearTickets", "tags": [ "Linear Integration" ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "ID of the conversation to retrieve issues for.", "example": 12345 } ], "responses": { "200": { "description": "Linear issues retrieved successfully.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the Linear issue.", "example": "8a7b93d1-18f7-4a9f-b5c6-3e2d1f9a8c7b" }, "title": { "type": "string", "description": "Title of the issue.", "example": "Fix authentication bug" }, "url": { "type": "string", "description": "URL to view the issue in Linear.", "example": "https://linear.app/team/issue/ENG-123" }, "identifier": { "type": "string", "description": "Human-readable issue identifier.", "example": "ENG-123" }, "assignee": { "type": "object", "description": "Assigned user (null if unassigned).", "properties": { "name": { "type": "string", "description": "Display name of the assignee.", "example": "Richard Hendricks" }, "avatar_url": { "type": "string", "description": "URL to the assignee's avatar image.", "example": "https://avatar.linear.app/9c0d1e2f" } } }, "state": { "type": "object", "description": "Current workflow state of the issue.", "properties": { "name": { "type": "string", "description": "Name of the workflow state.", "example": "In Progress" }, "type": { "type": "string", "description": "Type of the workflow state (triage, backlog, unstarted, started, completed, canceled).", "example": "started" }, "color": { "type": "string", "description": "Color hex code of the workflow state.", "example": "#f2c94c" }, "verbose": { "type": "string", "description": "ISO 8601 timestamp verbose format.", "example": "2026-01-15T10:30:00+00:00" }, "last_updated_at": { "type": "string", "description": "ISO 8601 timestamp of when the issue entered this state.", "example": "2026-01-15T10:30:00Z" } } }, "labels": { "type": "array", "description": "List of labels applied to the issue.", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the label.", "example": "bug" }, "color": { "type": "string", "description": "Color hex code of the label.", "example": "#5e6ad2" } } } }, "attachments": { "type": "array", "description": "List of attachments on the issue.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the attachment.", "example": "2f3a4b5c-6d7e-8f9a-0b1c-2d3e4f5a6b7c" }, "url": { "type": "string", "description": "URL of the attachment.", "example": "https://app.getfernand.com/conversations/12345" } } } }, "priority": { "type": "integer", "description": "Priority level (0=No priority, 1=Urgent, 2=High, 3=Medium, 4=Low).", "example": 1 }, "priority_label": { "type": "string", "description": "Display name of the priority level.", "example": "Urgent" }, "last_updated_at": { "type": "string", "description": "ISO 8601 timestamp of the last update.", "example": "2026-01-15T10:30:00Z" } } } } } } }, "404": { "description": "Linear integration not found for this organization." }, "502": { "description": "Error occurred at Linear while fetching issues.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "An error occured at Linear" } } } } } } }, "summary": "Get Linear issues attached to a conversation", "description": "Returns a list of Linear issues attached to the specified conversation.\nReturns a 404 error if the Linear integration is not configured for the organization.", "x-mint": { "metadata": { "description": "" }, "content": "Returns a list of Linear issues attached to the specified conversation.\nReturns a 404 error if the Linear integration is not configured for the organization." }, "x-computed-hash": "d877b96f4f696a4f0f6a00b32c4645afdf9fd9a44035a206933404f70e708e12", "x-last-modified": 1769076834 }, "post": { "operationId": "createLinearTicket", "tags": [ "Linear Integration" ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "ID of the conversation to attach the issue to.", "example": 12345 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "Title of the Linear issue (required, max 250 characters).", "example": "Fix user authentication flow" }, "description": { "type": "string", "description": "Description of the issue in HTML or Markdown format (optional, max 250,000 characters, will be converted to Markdown).", "example": "

Users are unable to log in with their credentials.

" }, "state": { "type": "string", "description": "UUID of the workflow state for the issue (required).", "example": "8a7b93d1-18f7-4a9f-b5c6-3e2d1f9a8c7b" }, "team": { "type": "string", "description": "UUID of the team to create the issue in (required).", "example": "7b8c9d0e-1f2a-3b4c-5d6e-7f8a9b0c1d2e" }, "priority": { "type": "integer", "description": "Priority level - 0 (No priority), 1 (Urgent), 2 (High), 3 (Medium), 4 (Low) (optional).", "example": 1 }, "assignee": { "type": "string", "description": "UUID of the user to assign the issue to (optional).", "example": "9c0d1e2f-3a4b-5c6d-7e8f-9a0b1c2d3e4f" }, "labels": { "type": "array", "description": "Array of label UUIDs to apply to the issue (optional).", "items": { "type": "string" }, "example": [ "0d1e2f3a-4b5c-6d7e-8f9a-0b1c2d3e4f5a" ] }, "project": { "type": "string", "description": "UUID of the project to add the issue to (optional).", "example": "1e2f3a4b-5c6d-7e8f-9a0b-1c2d3e4f5a6b" } }, "required": [ "title", "state", "team" ] } } } }, "responses": { "200": { "description": "Linear issue created and attached successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the created Linear issue.", "example": "8a7b93d1-18f7-4a9f-b5c6-3e2d1f9a8c7b" }, "title": { "type": "string", "description": "Title of the issue.", "example": "Fix user authentication flow" }, "url": { "type": "string", "description": "URL to view the issue in Linear.", "example": "https://linear.app/team/issue/ENG-123" }, "identifier": { "type": "string", "description": "Human-readable issue identifier.", "example": "ENG-123" }, "assignee": { "type": "object", "description": "Assigned user (null if unassigned).", "properties": { "name": { "type": "string", "description": "Display name of the assignee.", "example": "Richard Hendricks" }, "avatar_url": { "type": "string", "description": "URL to the assignee's avatar image.", "example": "https://avatar.linear.app/9c0d1e2f" } } }, "state": { "type": "object", "description": "Current workflow state of the issue.", "properties": { "name": { "type": "string", "description": "Name of the workflow state.", "example": "Todo" }, "type": { "type": "string", "description": "Type of the workflow state.", "example": "backlog" }, "color": { "type": "string", "description": "Color hex code of the workflow state.", "example": "#e2e2e2" }, "verbose": { "type": "string", "description": "ISO 8601 timestamp verbose format.", "example": "2024-01-15T10:30:00+00:00" }, "last_updated_at": { "type": "string", "description": "ISO 8601 timestamp of when the issue entered this state.", "example": "2024-01-15T10:30:00Z" } } }, "labels": { "type": "array", "description": "List of labels applied to the issue.", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the label.", "example": "bug" }, "color": { "type": "string", "description": "Color hex code of the label.", "example": "#5e6ad2" } } } }, "priority": { "type": "integer", "description": "Priority level (0=No priority, 1=Urgent, 2=High, 3=Medium, 4=Low).", "example": 1 }, "priority_label": { "type": "string", "description": "Display name of the priority level.", "example": "Urgent" }, "last_updated_at": { "type": "string", "description": "ISO 8601 timestamp of the last update.", "example": "2025-01-15T10:30:00Z" } } } } } }, "400": { "description": "Invalid input or error creating issue at Linear.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Invalid state ID" } } } } } }, "404": { "description": "Linear integration or conversation not found." }, "502": { "description": "Error occurred at Linear while creating the issue.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "An error occured at Linear" } } } } } } }, "summary": "Create a new Linear issue and attach it to a conversation", "description": "Creates a new Linear issue with the provided details and automatically attaches it to the specified conversation. An attachment and customer link are added to the issue linking it to the conversation in Fernand.", "x-mint": { "metadata": { "description": "" }, "content": "Creates a new Linear issue with the provided details and automatically attaches it to the specified conversation. An attachment and customer link are added to the issue linking it to the conversation in Fernand." }, "x-computed-hash": "0998a36496c98ddd12fc5098dd7634c80730bcff90fc28f5e4ea929847b7767c", "x-last-modified": 1769076834 } }, "/conversations/{conv_id}/drafts/{draft_id}": { "delete": { "operationId": "deleteDraft", "tags": [ "Conversation Drafts" ], "parameters": [ { "name": "conv_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "ID of the conversation containing the draft." }, { "name": "draft_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "ID of the draft to delete." } ], "responses": { "204": { "description": "Draft deleted successfully." }, "400": { "description": "You do not have permission to delete this draft.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Draft not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } }, "summary": "Delete a draft", "description": "Deletes a specific message draft in the given conversation.", "x-mint": { "metadata": { "description": "" }, "content": "Deletes a specific message draft in the given conversation." }, "x-computed-hash": "619a105d872feb3088ac99445092304fe3297ed781820a1ff3abb455948d8d40", "x-last-modified": 1776152542 } } }, "components": { "securitySchemes": { "apiKeyHeader": { "type": "apiKey", "description": "Authenticate your account by including your secret key in API requests.\nYou can manage your API keys in the [Dashboard](https://app.getfernand.com/).\n\nAuthentication to the API is performed by using the HTTP Header X-API-Key.", "name": "X-API-Key", "in": "header", "x-last-modified": 1764750344730 } }, "schemas": { "AgentInvite": { "type": "object", "properties": { "id": { "type": "integer", "format": "int32", "description": "Unique identifier for the agent invitation", "example": 42 }, "name": { "type": "string", "description": "Display name derived from the email address (before @ symbol, formatted)", "example": "Richard Hendricks" }, "email": { "type": "string", "format": "email", "maxLength": 250, "description": "Email address of the invited agent", "example": "richard.hendricks@piedpiper.com" }, "roles": { "type": "array", "items": { "type": "string" }, "description": "List of permission roles to be assigned when the invite is accepted", "example": [ "conversation.create", "conversation.reply" ] }, "avatar": { "type": "string", "format": "uri", "description": "Avatar's URL of the user", "example": "https://api.getfernand.com/contacts/richard.hendricks@piedpiper.com/avatar" }, "last_email_sent_ts": { "type": "integer", "format": "int64", "description": "Unix timestamp (milliseconds) when the invitation email was last sent", "example": 1234567890000 } }, "required": [ "id", "name", "email", "roles", "avatar", "last_email_sent_ts" ], "x-computed-hash": "61060edda97a355bfa4c6ee5d6e4dcd8862fe74343647fe89c71ab9742986bac", "x-last-modified": 1769075324 }, "Agent": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "Unique identifier for the agent", "example": 12345 }, "name": { "type": "string", "maxLength": 250, "nullable": true, "description": "Display name of the agent", "example": "Richard Hendricks" }, "firstname": { "type": "string", "description": "First name extracted from the agent's name", "example": "Richard" }, "email": { "type": "string", "format": "email", "maxLength": 250, "description": "Primary email address of the agent", "example": "richard.hendricks@piedpiper.com" }, "notification_email": { "type": "string", "format": "email", "maxLength": 250, "nullable": true, "description": "Alternative email for receiving notifications (if different from primary email)", "example": "richard.piper44@gmail.com" }, "timezone": { "type": "string", "maxLength": 250, "nullable": true, "description": "Agent's timezone (e.g., America/New_York, Europe/Paris)", "example": "America/Los_Angeles" }, "signature": { "type": "string", "nullable": true, "description": "Email signature for the agent (HTML allowed)", "example": "

Best regards,
Richard H.

" }, "avatar": { "type": "string", "maxLength": 250, "nullable": true, "description": "URL to the agent's avatar image. Either at Gravatar (default) or on our CDN if imported.", "example": "https://www.gravatar.com/avatar/6d918cc24709975e61413ea4c2fb93f6?s=80&d=404" }, "dark_mode": { "type": "boolean", "nullable": true, "description": "Whether dark mode is enabled (null means system default)", "example": true }, "is_mfa_enabled": { "type": "boolean", "description": "Whether multi-factor authentication is enabled for this agent", "example": false }, "is_paying": { "type": "boolean", "description": "Whether this agent occupies a paid seat in the organization", "example": true }, "is_removed": { "type": "boolean", "description": "Whether this agent has been removed from the organization", "example": false }, "is_current_user": { "type": "boolean", "description": "Whether this agent is the currently authenticated user", "example": true }, "roles": { "type": "array", "items": { "type": "string" }, "description": "List of permission roles assigned to the agent", "example": [ "conversation.create", "conversation.reply", "teammate.invite" ] }, "owner": { "type": "boolean", "description": "Whether this agent is the organization owner", "example": false }, "prev_next": { "type": "string", "enum": [ "historical", "natural" ], "description": "Navigation preference for keyboard shortcuts (only for current user)", "example": "historical" }, "newsletter": { "type": "boolean", "description": "Whether agent is subscribed to the newsletter (only for current user)", "example": true }, "notifications": { "type": "object", "description": "Notification preferences organized by target and event (only for current user)", "example": { "BROWSER": { "INCOMING_EMAIL": true, "MENTIONED": true }, "EMAIL": { "INCOMING_EMAIL": true, "ASSIGNED_ACTIVITY": false } } }, "ai_prompt_answer": { "type": "string", "description": "Custom AI prompt template for generating responses (only for current user)", "example": "Your name is ${agent_firstname}. Reply to ${contact_name} concisely." }, "fernand_hash": { "type": "string", "nullable": true, "description": "Secure key for signing emails in the Fernand chat integration (only for current user)", "example": "abc123def456..." }, "bounce_error": { "type": "string", "maxLength": 250, "nullable": true, "description": "Error message if email has bounced (only for current user)", "example": "Mailbox full" }, "custom_inboxes": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "query": { "type": "object" } } }, "description": "Custom inbox configurations (only for current user)", "example": [ { "key": "60977abb694a6b2061de23fe26429ace", "name": "Inbox", "query": { "assigned": "me+none", "is": "opened", "order": "priority" } } ] }, "lock_reason": { "type": "string", "maxLength": 250, "nullable": true, "description": "Reason account is locked (email, bounced, ban) - only for current locked user", "example": "email" }, "locked_ts": { "type": "integer", "format": "int64", "description": "Unix timestamp (milliseconds) when account was locked - only for current locked user", "example": 1234567890000 } }, "required": [ "id", "email", "is_paying", "is_removed" ], "x-computed-hash": "21eea128ff5bdf8d8bf0e07ab393cdc4ad23991f171cb3892276f0f844b86fce", "x-last-modified": 1769075324 }, "Contact": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "Unique identifier for the contact", "example": 12345 }, "name": { "type": "string", "maxLength": 250, "nullable": true, "description": "Display name of the contact, can be set locally or derived from various sources. Returns local_name if set, otherwise the name field, or generates a name from the email address.", "example": "Richard Hendricks" }, "firstname": { "type": "string", "nullable": true, "description": "First name extracted from the contact's full name", "example": "Richard" }, "email": { "type": "string", "maxLength": 250, "description": "Email address of the contact, stored in lowercase and decoded from punycode if applicable", "example": "richard.hendricks@piedpiper.com" }, "avatar": { "type": "string", "format": "uri", "description": "URL to the contact's avatar image, fetched from Gravatar or domain favicon", "example": "https://api.getfernand.com/contacts/richard.hendricks@piedpiper.com/avatar" }, "company": { "type": "object", "nullable": true, "description": "Company information associated with the contact's email domain", "properties": { "id": { "type": "integer", "format": "int64", "description": "Company unique identifier", "example": 123 }, "name": { "type": "string", "description": "Company name", "example": "PiedPiper" }, "domain": { "type": "string", "description": "Company domain", "example": "piedpiper.com" }, "logo": { "type": "string", "format": "uri", "description": "Company logo URL, provided by Fetchlab.net", "example": "https://api.fetchlab.net/icons/piedpiper.com" }, "url": { "type": "string", "format": "uri", "description": "Company website URL", "example": "https://piedpiper.com" } } }, "is_role": { "type": "boolean", "description": "Indicates if the email is a role-based address (e.g., support@, info@, contact@)", "example": false }, "is_trusted": { "type": "boolean", "description": "Indicates if the contact is trusted (Untrusted contacts come from unverified live chat sessions).", "example": true }, "subscription_status": { "type": "string", "nullable": true, "enum": [ "active", "past_due", "unpaid", "canceled", "churned", "incomplete", "trialing" ], "description": "Current subscription status from payment processor, only available when complete serialization is requested", "example": "active" }, "subscription_start": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp when the subscription started (UTC), only available when complete serialization is requested", "example": "2024-01-15T10:30:00Z" }, "financials": { "type": "object", "nullable": true, "description": "Financial information including payment sources, subscriptions, and payment history, only available when complete serialization is requested", "properties": { "sources": { "type": "object", "description": "Payment processor sources (Stripe, Paddle, Lemon Squeezy) with customer information" }, "subscriptions": { "type": "object", "properties": { "total": { "type": "integer", "description": "Total number of subscriptions" }, "latest": { "type": "object", "nullable": true, "description": "Latest subscription details" } } }, "payments": { "type": "object", "properties": { "total": { "type": "integer", "description": "Total number of payments" }, "data": { "type": "array", "description": "Latest 5 payments", "items": { "type": "object" } } } } } } }, "required": [ "id", "email" ], "x-computed-hash": "5a3ac876cb3cfdd7545e5e793f2eda98e10d4b4e76f789c690533ff39c29cd1f", "x-last-modified": 1769075324 }, "Conversation": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "Unique identifier for the conversation", "example": 12345 }, "agent_id": { "type": "integer", "format": "int64", "nullable": true, "description": "ID of the agent assigned to this conversation, or null if unassigned", "example": 42 }, "channel_id": { "type": "integer", "format": "int64", "nullable": true, "description": "ID of the channel through which this conversation is conducted", "example": 1 }, "contact_id": { "type": "integer", "format": "int64", "description": "ID of the primary contact who initiated the conversation", "example": 789 }, "subject": { "type": "string", "maxLength": 250, "description": "Subject line of the conversation, derived from the first message or manually set", "example": "Question about billing" }, "status": { "type": "string", "enum": [ "OPENED", "CLOSED", "SPAM", "SNOOZED" ], "description": "Current status of the conversation", "example": "OPENED" }, "snooze_until": { "type": "string", "format": "date-time", "nullable": true, "description": "ISO 8601 timestamp indicating when a snoozed conversation should reappear, or null if not snoozed", "example": "2026-01-22T09:00:00Z" }, "last_update": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of the last incoming message in the conversation", "example": "2026-01-21T14:30:00Z" }, "cursor": { "type": "string", "nullable": true, "description": "Pagination cursor for retrieving the next page of conversations in a list", "example": "cur_1234567890" }, "tags": { "type": "array", "items": { "type": "integer", "format": "int32" }, "description": "Array of tag IDs associated with this conversation", "example": [ 1, 5, 12 ] }, "recipients": { "type": "array", "items": { "$ref": "#/components/schemas/Recipient" }, "description": "Array of recipients in the conversation (to, cc, bcc)" } }, "required": [ "id", "contact_id", "subject", "status", "last_update", "tags", "recipients" ], "x-computed-hash": "a4fe82348d6bfb626498c4e69d74844e7073707db3d01b4a3c48aa6f18ab85b1", "x-last-modified": 1769075324 }, "Recipient": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "Unique identifier for the recipient", "example": 12345 }, "contact_id": { "type": "integer", "format": "int64", "description": "ID of the contact that is a recipient of this conversation", "example": 789 }, "kind": { "type": "string", "enum": [ "to", "cc", "bcc", "from", "reply-to" ], "description": "Type of recipient (to, cc, bcc, from, or reply-to)", "example": "cc" }, "conversation_id": { "type": "integer", "format": "int64", "description": "ID of the conversation this recipient belongs to", "example": 456 } }, "required": [ "id", "contact_id", "kind", "conversation_id" ], "x-computed-hash": "cbb8eb868425947be377f9afbf0493c64e9e4591063f9430fa398020dbe2863c", "x-last-modified": 1769075324 }, "Message": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the message", "example": "m-123456" }, "conversation_id": { "type": "integer", "format": "int64", "description": "ID of the conversation this message belongs to", "example": 12345 }, "type": { "type": "string", "enum": [ "MESSAGE" ], "description": "Type of entry (always MESSAGE for messages)", "example": "MESSAGE" }, "download_url": { "type": "string", "nullable": true, "description": "URL to download the original email file (.eml), if available", "example": "https://api.getfernand.com/conversations/a1b2c3d4-e5f6-7890-abcd-ef1234567890/original.eml?token=abc123" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the message was created", "example": "2026-01-21T14:30:00Z" }, "agent_id": { "type": "integer", "format": "int64", "nullable": true, "description": "ID of the agent who sent the message (null for incoming messages)", "example": 42 }, "way": { "type": "string", "enum": [ "IN", "OUT" ], "description": "Direction of the message (IN for incoming, OUT for outgoing)", "example": "IN" }, "contact_id": { "type": "integer", "format": "int64", "nullable": true, "description": "ID of the contact who sent the message (null for outgoing messages)", "example": 789 }, "message": { "type": "string", "description": "HTML content of the message body", "example": "

Hello, I need help with my account.

" }, "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/Attachment" }, "description": "Array of file attachments in the message" }, "status": { "type": "string", "enum": [ "DRAFT", "PENDING", "SENT", "RECEIVED", "BOUNCED", "SPAM", "ERROR" ], "description": "Current status of the message", "example": "SENT" }, "delay": { "type": "integer", "format": "int32", "description": "Delay in seconds before the message is sent (for scheduled messages)", "example": 0 }, "source": { "type": "string", "enum": [ "EMAIL", "CHAT" ], "description": "Source channel of the message", "example": "EMAIL" }, "unsubscribe_url": { "type": "string", "nullable": true, "description": "URL for the recipient to unsubscribe, if available", "example": "https://newsletter.hooli.com/unsubscribe?token=xyz789" }, "last_event": { "allOf": [ { "$ref": "#/components/schemas/MessageEvent" } ], "nullable": true, "description": "Most recent delivery event for this message" }, "actions": { "type": "array", "items": { "type": "object" }, "description": "Array of automated actions triggered by this message" }, "language": { "type": "string", "nullable": true, "description": "Detected language code of the message content (e.g., en, fr, es)", "example": "en" }, "is_read": { "type": "boolean", "description": "Whether the message has been read by the recipient (chat messages only)", "example": false }, "is_automated": { "type": "boolean", "description": "Whether this message was sent automatically by the system", "example": false } }, "required": [ "id", "conversation_id", "type", "timestamp", "way", "status", "source" ], "x-computed-hash": "f06a9fad859d70eed1fa800c0c475119662f50b53898da1b3e6443b836ce35be", "x-last-modified": 1773150592 }, "Attachment": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "Unique identifier for the attachment" }, "name": { "type": "string", "maxLength": 250, "description": "Name of the attachment file" }, "url": { "type": "string", "format": "uri", "description": "Download URL for the attachment" }, "type": { "type": "string", "maxLength": 250, "description": "MIME type of the attachment (content_type)" }, "size": { "type": "integer", "format": "int32", "description": "Size of the attachment in bytes" }, "uuid": { "type": "string", "format": "uuid", "description": "Unique UUID for the attachment" } }, "required": [ "id", "name", "url", "type", "size", "uuid" ], "x-computed-hash": "e3f6f020dd720737f6114ca84de8255a075145ec2af171dfba4f88f71cfb4490", "x-last-modified": 1769075324 }, "MessageEvent": { "type": "object", "properties": { "event": { "type": "string", "enum": [ "QUEUED", "CANCELED", "DELIVERED", "RECEIVED", "SOFT_BOUNCE", "HARD_BOUNCE", "REJECTED", "SPAM", "ERROR" ], "description": "Type of delivery event", "example": "DELIVERED" }, "error_code": { "type": "string", "maxLength": 10, "nullable": true, "description": "Error code if the event represents a failure", "example": "550" }, "reason": { "type": "string", "maxLength": 250, "nullable": true, "description": "Human-readable description of the event or error", "example": "Message delivered successfully" }, "received_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was received", "example": "2026-01-21T14:31:00Z" } }, "required": [ "event", "received_at" ], "x-computed-hash": "91b9f7e32e29a071b0d7ea10809ffe841a3ac3f59acecfdf33716d2010e8de35", "x-last-modified": 1769075324 }, "Organization": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 250, "description": "Name of the organization", "example": "PiedPiper Inc." }, "slug": { "type": "string", "maxLength": 250, "description": "URL-friendly slug for the organization", "example": "piedpier" }, "line1": { "type": "string", "maxLength": 250, "nullable": true, "description": "First line of the organization's address", "example": "5230 Newell Road" }, "line2": { "type": "string", "maxLength": 250, "nullable": true, "description": "Second line of the organization's address (suite, building, etc.)" }, "zipcode": { "type": "string", "maxLength": 25, "nullable": true, "description": "Postal/ZIP code", "example": 94303 }, "city": { "type": "string", "maxLength": 250, "nullable": true, "description": "City name", "example": "Palo Alto" }, "state": { "type": "string", "maxLength": 250, "nullable": true, "description": "State or province", "example": "California" }, "country": { "type": "string", "maxLength": 2, "nullable": true, "description": "ISO 3166-1 alpha-2 country code", "example": "US" }, "company_vat": { "type": "string", "maxLength": 250, "nullable": true, "description": "VAT/Tax identification number" }, "billing_email": { "type": "string", "format": "email", "nullable": true, "description": "Email address for billing notifications", "example": "billing@piedpiper.com" }, "notification_email": { "type": "string", "format": "email", "nullable": true, "description": "Email address for system notifications", "example": "notifications@piedpiper.com" }, "from_name": { "type": "string", "maxLength": 100, "description": "Template for the \"From\" name in emails. Supports variables like ${agent_name}, ${organization_name}, ${channel_email}", "example": "${agent_name} from ${organization_name}" }, "trial_ends_at": { "type": "string", "format": "date-time", "description": "Timestamp when the trial period ends (UTC)", "example": "2024-12-31T23:59:59Z" }, "trial_ends_at_ts": { "type": "integer", "format": "int64", "description": "Unix timestamp in milliseconds when the trial period ends", "example": 1735689599000 }, "onboarding": { "type": "object", "nullable": true, "description": "Onboarding progress tracking with steps (email, channel, stripe, invite, snippet, rule, cheatsheet, knowledge) and their states (done, ignored)", "example": { "email": "done", "channel": "done", "stripe": "ignored" } }, "renew_date": { "type": "string", "format": "date-time", "nullable": true, "description": "Next subscription renewal date (UTC)", "example": "2024-12-01T00:00:00Z" }, "renew_date_ts": { "type": "integer", "format": "int64", "nullable": true, "description": "Unix timestamp in milliseconds for next subscription renewal", "example": 1733011200000 }, "cancels_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp when the subscription will be canceled (UTC)", "example": "2024-12-31T23:59:59Z" }, "cancels_at_ts": { "type": "integer", "format": "int64", "nullable": true, "description": "Unix timestamp in milliseconds when the subscription will be canceled", "example": 1735689599000 }, "card_expiry": { "type": "string", "format": "date-time", "nullable": true, "description": "Payment card expiration date (UTC)", "example": "2025-12-01T00:00:00Z" }, "card_expiry_ts": { "type": "integer", "format": "int64", "nullable": true, "description": "Unix timestamp in milliseconds for payment card expiration", "example": 1764547200000 }, "card_brand": { "type": "string", "maxLength": 50, "nullable": true, "description": "Payment card brand (Visa, Mastercard, etc.)", "example": "Visa" }, "last4": { "type": "string", "maxLength": 4, "nullable": true, "description": "Last 4 digits of the payment card", "example": "4242" }, "is_premium": { "type": "boolean", "description": "Whether the organization has an active paid subscription", "example": true }, "integrations": { "type": "array", "items": { "type": "string" }, "description": "List of enabled integrations (e.g., LINEAR, GITHUB, SLACK)", "example": [ "LINEAR", "SLACK" ] }, "hours": { "type": "object", "nullable": true, "description": "Business hours configuration with days and opening/closing times", "example": { "monday": [ { "open": "09:00", "close": "17:00" } ], "tuesday": [ { "open": "09:00", "close": "17:00" } ] } }, "created": { "type": "string", "format": "date-time", "description": "Timestamp when the organization was created (UTC)", "example": "2024-01-01T00:00:00Z" }, "created_ts": { "type": "integer", "format": "int64", "description": "Unix timestamp in milliseconds when the organization was created", "example": 1704067200000 }, "is_custom_data_enabled": { "type": "boolean", "description": "Whether the custom data panel is enabled and properly configured", "example": false }, "is_ai_enabled": { "type": "boolean", "description": "Whether AI features are enabled.", "example": true }, "is_ai_chat_enabled": { "type": "boolean", "description": "Whether AI chat feature is enabled", "example": true }, "is_ai_articles_enabled": { "type": "boolean", "description": "Whether AI articles feature is enabled", "example": false }, "is_ai_messages_enabled": { "type": "boolean", "description": "Whether AI messages feature is enabled", "example": false } }, "required": [ "name", "slug", "from_name", "trial_ends_at", "trial_ends_at_ts", "is_premium", "integrations", "created", "created_ts", "is_custom_data_enabled", "is_ai_enabled", "is_ai_chat_enabled", "is_ai_articles_enabled", "is_ai_messages_enabled" ], "x-computed-hash": "ab16b3acab623ad9e540308c642150465a6397b582d8d8c166c3a40c78509a53", "x-last-modified": 1769075324 }, "Channel": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "Unique identifier for the channel", "example": 12345 }, "name": { "type": "string", "maxLength": 250, "description": "Display name for the channel. Defaults to the local part of the email (before @) if not set.", "example": "Support" }, "email": { "type": "string", "format": "email", "maxLength": 250, "description": "Email address for this channel", "example": "support@piedpiper.com" }, "destination": { "type": "string", "format": "email", "description": "The actual email inbox used by Fernand to receive emails. This is where you point your email redirection to.", "example": "support@piedpiper.fernand-mails.com" }, "is_valid": { "type": "boolean", "description": "Whether the channel's domain has been validated and is ready to send/receive emails", "example": true } }, "required": [ "id", "name", "email", "destination", "is_valid" ], "x-computed-hash": "e1627e7cece0dc3e9993939d033c003c7862607dcd0bce4bcb6ae74daf6031d6", "x-last-modified": 1769075324 }, "VectorStoreFile": { "type": "object", "properties": { "id": { "type": "integer", "format": "int32", "description": "Unique identifier for the vector store file", "example": 42 }, "name": { "type": "string", "description": "Display name for the file (filename if available, URL, or generated name based on source)", "example": "documentation.pdf" }, "uuid": { "type": "string", "maxLength": 40, "description": "Unique identifier for tracking this file", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "url": { "type": "string", "maxLength": 1000, "nullable": true, "description": "Source URL for the file (if it was crawled from a web page)", "example": "https://docs.piedpiper.com/guide" }, "source": { "type": "string", "description": "Type of source for this file", "enum": [ "URL", "TEXT", "QUESTION", "MESSAGE", "ARTICLE" ], "example": "URL" }, "created": { "type": "string", "format": "date-time", "description": "Timestamp when the file was added to the vector store (UTC)", "example": "2024-01-15T10:30:00Z" }, "created_ts": { "type": "integer", "format": "int64", "description": "Unix timestamp in milliseconds when the file was added", "example": 1705315800000 }, "last_updated": { "type": "string", "format": "date-time", "description": "Timestamp when the file content was last modified (UTC)", "example": "2024-01-20T14:45:00Z" }, "last_updated_ts": { "type": "integer", "format": "int64", "description": "Unix timestamp in milliseconds when the file was last updated", "example": 1705759500000 }, "size": { "type": "integer", "format": "int32", "minimum": 0, "description": "Size of the file in bytes", "example": 2048 } }, "required": [ "id", "name", "uuid", "source", "created", "created_ts", "last_updated", "last_updated_ts", "size" ], "x-computed-hash": "1e7271267d91a10e125807540ba588d74f4fb99f69251bda216cd81d7ab822a6", "x-last-modified": 1769075324 }, "Ruleset": { "type": "object", "properties": { "id": { "type": "integer", "format": "int32", "description": "Unique identifier for the ruleset" }, "name": { "type": "string", "maxLength": 250, "description": "Name of the ruleset", "example": "Auto-close spam conversations" }, "description": { "type": "string", "maxLength": 500, "nullable": true, "description": "Optional description of what the ruleset does", "example": "Automatically closes conversations marked as spam" }, "status": { "type": "string", "enum": [ "PAUSED", "LIVE" ], "description": "Current status of the ruleset", "example": "LIVE" }, "priority": { "type": "integer", "format": "int16", "description": "Priority order for rule execution (lower numbers execute first)", "example": 0 }, "stop": { "type": "boolean", "description": "If true, stops processing subsequent rules when this rule matches", "example": false }, "trigger_name": { "type": "string", "maxLength": 50, "description": "Event that triggers this rule. Accepted triggers:\n- messages.new_conversation\n- messages.incoming\n- messages.response\n- messages.delivery_failure\n- messages.spam\n- messages.note\n- messages.disable_ai\n- status.closed\n- status.opened\n- status.snoozed\n- status.unsnoozed\n- teammates.assigned\n- teammate.mentioned\n- time.unanswered_by_client\n- time.unanswered_by_team\n- tickets.ticket_done\n", "example": "messages.incoming" }, "trigger_data": { "type": "string", "maxLength": 250, "nullable": true, "description": "Additional data for the trigger (required for certain triggers):\n- For \"teammates.assigned\" or \"teammate.mentioned\": \"no_one\", \"anyone\", or an Agent ID\n- For \"time.*\" triggers: duration and period in format \"{duration} {period}\" (e.g., \"2 hours\", \"3 days\")\n", "example": "2 hours" }, "filters": { "type": "array", "nullable": true, "description": "Array of filter conditions that must be met for the rule to execute.\nEach filter contains conditions to match against the entity.\n", "items": { "type": "object" }, "example": [ { "field": "conversation.status", "operator": "equals", "value": "OPENED" } ] }, "actions": { "type": "array", "description": "Array of actions to execute when the rule matches.\nEach action has a name and optional data.\n", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the action to execute" }, "data": { "type": "object", "description": "Optional data for the action" } } }, "example": [ { "name": "conversation.close", "data": {} } ] }, "created": { "type": "string", "format": "date-time", "description": "Timestamp when the ruleset was created (UTC)", "example": "2025-01-21T10:30:00Z" }, "last_applied_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp when the rule was last applied (UTC)", "example": "2025-01-21T15:45:30Z" }, "applied_count": { "type": "integer", "format": "int32", "description": "Number of times this rule has been successfully applied", "example": 42 } }, "required": [ "id", "name", "status", "priority", "stop", "trigger_name", "created", "applied_count" ], "x-computed-hash": "825d70624279e89eaa8af56e2d0dde159a1fa02f03c1369b8e6285e19c4c5cd8", "x-last-modified": 1776152542 }, "Snippet": { "type": "object", "properties": { "id": { "type": "integer", "format": "int32", "description": "Unique identifier for the snippet", "example": 42 }, "title": { "type": "string", "maxLength": 250, "description": "Title of the snippet", "example": "Welcome Message" }, "shortcut": { "type": "string", "maxLength": 40, "nullable": true, "pattern": "^[a-z0-9-]*$", "description": "Optional keyboard shortcut to quickly insert the snippet (lowercase, numbers, and dashes only)", "example": "welcome" }, "created": { "type": "string", "format": "date-time", "description": "Timestamp when the snippet was created (UTC)", "example": "2024-01-15T10:30:00Z" }, "last_applied_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp when the snippet was last applied to a conversation (UTC)" }, "applied_count": { "type": "integer", "format": "int32", "description": "Number of times this snippet has been applied", "example": 15 }, "categories": { "type": "array", "items": { "type": "integer" }, "description": "Array of category IDs this snippet belongs to (0 represents root category)", "example": [ 1, 3 ] }, "actions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "format": "int32", "description": "Unique identifier for the action", "example": 1 }, "name": { "type": "string", "description": "Name of the action (status, assign, snooze, reply, note, tag)", "example": "status" }, "data": { "type": "object", "description": "Action-specific data payload", "example": { "status": "closed" } }, "sort": { "type": "integer", "format": "int32", "description": "Sort order for this action", "example": 0 } } }, "description": "Array of actions to be applied when the snippet is used", "example": [ { "id": 1, "name": "status", "data": { "status": "closed" }, "sort": 0 } ] } }, "required": [ "id", "title", "created", "applied_count", "categories", "actions" ], "x-computed-hash": "c38d3a2f7c50e50bbd7b0d94127b2a5ecc651e8a4d8aab93b02f1cd0546f5ec3", "x-last-modified": 1769075324 }, "SnippetCategory": { "type": "object", "properties": { "id": { "type": "integer", "format": "int32", "description": "Unique identifier for the snippet category", "example": 5 }, "name": { "type": "string", "maxLength": 250, "description": "Name of the category", "example": "Customer Support" }, "parent_id": { "type": "integer", "format": "int32", "nullable": true, "description": "ID of the parent category (null for root-level categories)", "example": 2 }, "sort": { "type": "integer", "format": "int32", "description": "Sort order within the parent category (1-based)", "example": 1 } }, "required": [ "id", "name", "sort" ], "x-computed-hash": "1b4d16a9a35a9d103ccbdaccc7316600d08ef27b337e5623ad58f40ccc9f763b", "x-last-modified": 1769075324 }, "Tag": { "type": "object", "properties": { "id": { "type": "integer", "format": "int32", "description": "Unique identifier for the tag", "example": 42 }, "slug": { "type": "string", "maxLength": 50, "description": "URL-friendly slug generated from the tag name", "example": "important-customer" }, "name": { "type": "string", "maxLength": 50, "description": "Display name of the tag", "example": "Important Customer" }, "color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$", "description": "Hex color code for the tag (e.g.,", "example": "#FF5733" }, "count_conversations": { "type": "integer", "format": "int32", "description": "Number of conversations associated with this tag", "example": 15 }, "is_system": { "type": "boolean", "description": "Whether this is a system-defined tag that cannot be modified or deleted", "example": false } }, "required": [ "id", "slug", "name", "color", "count_conversations", "is_system" ], "x-computed-hash": "08655ed7b3fa25ee437748f74114938f897196b9991c09562b57293801571f3d", "x-last-modified": 1769075325 }, "KnowledgeLang": { "type": "object", "description": "Knowledge base settings combined with language-specific content. Inherits all properties from Knowledge model and adds language-specific fields.", "allOf": [ { "$ref": "#/components/schemas/Knowledge" }, { "type": "object", "properties": { "title": { "type": "string", "maxLength": 250, "description": "Main title displayed on the knowledge base homepage.", "example": "Help Center" }, "description": { "type": "string", "maxLength": 1000, "nullable": true, "description": "Description text shown on the knowledge base homepage.", "example": "Welcome to the PiedPiper help center" }, "company_name": { "type": "string", "maxLength": 250, "nullable": true, "description": "Company name displayed in the knowledge base.", "example": "PiedPiper help center" }, "company_url": { "type": "string", "maxLength": 250, "nullable": true, "description": "Company website URL.", "example": "https://piedpiper.com" } } } ], "x-computed-hash": "170caacbd23fea152e48643e0dd9c0fc2ed66d23823382f710368354faa89abb", "x-last-modified": 1769075325 }, "Knowledge": { "type": "object", "properties": { "subdomain": { "type": "string", "maxLength": 50, "nullable": true, "description": "Subdomain for accessing the knowledge base (e.g., 'piedpiper' for piedpiper.fernand.help).", "example": "help" }, "custom_domain": { "type": "string", "maxLength": 250, "nullable": true, "description": "Custom domain configured for the knowledge base.", "example": "help.piedpiper.com" }, "favicon": { "type": "string", "maxLength": 250, "nullable": true, "description": "URL to the favicon image stored in CDN.", "example": "https://cdn.example.com/knowledge/uuid/images/favicon.png" }, "language": { "type": "string", "maxLength": 5, "nullable": true, "description": "Default language code for the knowledge base (null for browser detection).", "example": "en" }, "color_scheme": { "type": "string", "maxLength": 5, "nullable": true, "enum": [ "light", "dark" ], "description": "Preferred color scheme for the knowledge base. Defaults to null, which will use the user system's preferences." }, "light_logo": { "type": "string", "maxLength": 250, "nullable": true, "description": "URL to the logo image for light mode." }, "light_accent_color": { "type": "string", "maxLength": 7, "description": "Hex color code for accent color in light mode.", "example": "#00a0ff" }, "dark_logo": { "type": "string", "maxLength": 250, "nullable": true, "description": "URL to the logo image for dark mode." }, "dark_accent_color": { "type": "string", "maxLength": 7, "description": "Hex color code for accent color in dark mode.", "example": "#00a0ff" }, "custom_css": { "type": "string", "nullable": true, "description": "Custom CSS applied to the knowledge base." }, "custom_js": { "type": "string", "nullable": true, "description": "Custom JavaScript applied to the knowledge base." }, "previous_url": { "type": "string", "maxLength": 250, "nullable": true, "description": "Previous URL if migrated from another help system." }, "valid_custom_domain": { "type": "boolean", "description": "Whether the custom domain DNS is properly configured and verified." }, "last_verified_dns": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp of the last successful DNS verification." }, "indexable": { "type": "boolean", "description": "Whether the knowledge base should be indexed by search engines." } }, "x-computed-hash": "a29a10c4ab4e28400244ce0a61fc8677a0a08639ee8c31eab9ec1ee0534d4fa5", "x-last-modified": 1769075325 }, "Collection": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "Unique identifier for the collection." }, "parent_id": { "type": "integer", "nullable": true, "description": "ID of the parent collection for nested organization (null for root-level collections)." }, "title": { "type": "string", "maxLength": 250, "description": "Display title of the collection shown in navigation and headers.", "example": "Getting Started" }, "slug": { "type": "string", "maxLength": 250, "pattern": "^[a-z0-9_-]+$", "description": "URL-safe slug used in the collection's URL path.", "example": "getting-started" }, "description": { "type": "string", "nullable": true, "description": "Description of the collection content and purpose.", "example": "Essential guides to help you get started with our platform" }, "seo_title": { "type": "string", "maxLength": 250, "description": "SEO-optimized title for search engines and meta tags.", "example": "Getting Started - Complete Guide" }, "seo_description": { "type": "string", "maxLength": 250, "nullable": true, "description": "SEO-optimized description for search engines and social media previews." }, "icon": { "type": "string", "maxLength": 25, "nullable": true, "description": "Emoji icon identifier displayed alongside the collection title for visual distinction.", "example": "\ud83d\ude80" }, "get_icon_color": { "type": "string", "nullable": true, "description": "Computed color code associated with the emoji icon for theming purposes." }, "created": { "type": "string", "format": "date-time", "description": "Timestamp when the collection was created." }, "last_updated": { "type": "string", "format": "date-time", "description": "Timestamp when the collection was last modified." }, "get_articles": { "type": "array", "items": { "type": "integer" }, "description": "Array of article IDs contained directly in this collection (not including nested collections).", "example": [ 12, 45, 67 ] }, "get_collections": { "type": "array", "items": { "type": "integer" }, "description": "Array of sub-collection IDs that are children of this collection.", "example": [ 3, 8, 15 ] }, "sort": { "type": "integer", "description": "Sort order within the parent collection or at root level.", "example": 2 } }, "x-computed-hash": "680b3b52d5771752ebd9584afb952bc5efa4006ed32d920a58071bf37479d4fb", "x-last-modified": 1769075325 }, "Article": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "Unique identifier for the article." }, "title": { "type": "string", "maxLength": 250, "description": "Display title of the article.", "example": "How to get started" }, "seo_title": { "type": "string", "maxLength": 250, "description": "SEO-optimized title for search engines and meta tags.", "example": "Getting Started Guide - Complete Tutorial" }, "slug": { "type": "string", "maxLength": 250, "pattern": "^[a-z0-9_-]+$", "description": "URL-safe slug used in the article's URL path.", "example": "how-to-get-started" }, "previous_url": { "type": "string", "maxLength": 250, "nullable": true, "description": "Previous URL if the article was migrated from another help system, used for redirect tracking." }, "description": { "type": "string", "maxLength": 250, "nullable": true, "description": "Brief description used for SEO meta tags and article previews.", "example": "Learn how to set up your account and start using our platform in minutes." }, "content": { "type": "string", "nullable": true, "description": "Full HTML content of the article including formatted text, images, code blocks, and embedded media.", "example": "

Welcome to our platform! This guide will help you get started...

" }, "created": { "type": "string", "format": "date-time", "description": "Timestamp when the article was originally created." }, "last_updated": { "type": "string", "format": "date-time", "description": "Timestamp when the article was last modified." }, "published": { "type": "boolean", "description": "Whether the article is published and visible to users (unpublished articles are drafts)." }, "get_collections": { "type": "array", "items": { "type": "object", "properties": { "collection_id": { "type": "integer", "nullable": true, "description": "ID of the collection containing this article (null for root level)." }, "sort": { "type": "integer", "description": "Sort position within the collection." } } }, "description": "List of collections this article belongs to with their sort positions.", "example": [ { "collection_id": 1, "sort": 1 }, { "collection_id": 3, "sort": 2 } ] }, "visibility": { "type": "string", "maxLength": 10, "enum": [ "public", "chat", "chat_auth" ], "description": "Visibility setting - public (visible to all), chat (only in chat widget), chat_auth (only in chat for authenticated users).", "example": "public" }, "get_url": { "type": "string", "description": "Full computed URL path to access the article, including collection hierarchy.", "example": "https://help.piedpiper.com/getting-started/introduction" } }, "x-computed-hash": "3a5b7101545f0f84fa1766bc6cf87a28d4f3c86155db9553cd2be296e36ae71a", "x-last-modified": 1769075325 }, "KnowledgeLinkLang": { "type": "object", "description": "Navigation link combined with language-specific content. Inherits all properties from KnowledgeLink model and adds language-specific fields.", "allOf": [ { "$ref": "#/components/schemas/KnowledgeLink" }, { "type": "object", "properties": { "title": { "type": "string", "maxLength": 250, "description": "Display text for the link shown in navigation.", "example": "Contact Us" } } } ], "x-computed-hash": "2b6d21ff36ba971be271b295a5b9e82f064073e6cee1af4f2b803b6ea8fefba5", "x-last-modified": 1769075325 }, "KnowledgeLink": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "Unique identifier for the link." }, "sort": { "type": "integer", "description": "Sort order within the position (HEADER or FOOTER).", "example": 1 }, "url": { "type": "string", "maxLength": 250, "description": "Destination URL for the link.", "example": "https://piedpiper.com/contact" }, "target": { "type": "string", "maxLength": 6, "enum": [ "_blank", "_self" ], "description": "Link target behavior - _blank for new tab, _self for same window.", "example": "_blank" }, "position": { "type": "string", "maxLength": 6, "enum": [ "HEADER", "FOOTER" ], "description": "Where the link is displayed in the knowledge base.", "example": "HEADER" } }, "x-computed-hash": "e887866a88caa67ffffb49193c7a9ed3c1a580f597ac733824d62223eff3abb9", "x-last-modified": 1769075325 }, "MessageDraft": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "Unique identifier for the message draft" }, "title": { "type": "string", "maxLength": 250, "nullable": true, "description": "Optional title for the draft" }, "content": { "type": "object", "description": "JSON object containing the draft content and metadata.\nExample:\n {\n \"content\": \"string\",\n \"attachments\": [\n {\n \"type\": \"application/pdf\",\n \"name\": \"report.pdf\",\n \"content\": \"<... base64 encoded content ...>\"\n }\n ],\n \"inlines\": [\n {\n \"type\": \"image/png\",\n \"name\": \"screenshot.png\",\n \"content\": \"<... base64 encoded content ...>\",\n \"cid\": \"random-cid-12345\"\n }\n ],\n \"actions\": [\n {\n \"name\": \"status.close\",\n \"snippet_id\": 123,\n \"data\": {}\n }\n ]\n }\n" }, "created": { "type": "string", "format": "date-time", "description": "Timestamp when the draft was created (UTC)" }, "last_updated": { "type": "string", "format": "date-time", "description": "Timestamp when the draft was last updated (UTC)" }, "conversation_id": { "type": "integer", "format": "int64", "description": "Conversation ID this draft belongs to" }, "author_id": { "type": "integer", "format": "int64", "nullable": true, "description": "Agent ID who created the draft" }, "target_id": { "type": "integer", "format": "int64", "nullable": true, "description": "Agent ID to whom the draft is targeted (null means everyone)" } }, "required": [ "conversation_id", "created", "last_updated" ], "x-computed-hash": "8c8367becf2ed235e0c256a8de0c4821b45ded56aa5429e19da093b7c10e2094", "x-last-modified": 1769075325 }, "ConversationNote": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the note", "example": "n-123456" }, "agent_id": { "type": "integer", "format": "int64", "nullable": true, "description": "ID of the agent who created the note", "example": 42 }, "conversation_id": { "type": "integer", "format": "int64", "description": "ID of the conversation this note belongs to", "example": 12345 }, "message": { "type": "string", "description": "HTML content of the note", "example": "

Customer mentioned they prefer email communication.

" }, "created": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the note was created", "example": "2026-01-21T14:30:00Z" }, "type": { "type": "string", "enum": [ "NOTE" ], "description": "Type of entry (always NOTE for conversation notes)", "example": "NOTE" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp for sorting entries (same as created)", "example": "2026-01-21T14:30:00Z" }, "actions": { "type": "array", "items": { "type": "object" }, "description": "Array of automated actions triggered by this note" }, "edited_at": { "type": "string", "format": "date-time", "nullable": true, "description": "ISO 8601 timestamp when the note was last edited, or null if never edited", "example": "2026-01-21T15:00:00Z" } }, "required": [ "id", "conversation_id", "message", "created", "type", "timestamp" ], "x-computed-hash": "038dff7ecb709161310e1f432f81b912c8ba9915d38aed5f5fb7cccc5874d7d8", "x-last-modified": 1769075325 }, "ConversationEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the event", "example": "e-123456" }, "conversation_id": { "type": "integer", "format": "int64", "description": "ID of the conversation this event belongs to", "example": 519508 }, "type": { "type": "string", "enum": [ "EVENT" ], "description": "Type of entry (always EVENT for conversation events)", "example": "EVENT" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp for sorting entries", "example": "2026-01-21T17:46:22.877626Z" }, "timestamp_ts": { "type": "integer", "format": "int64", "description": "Unix timestamp in milliseconds corresponding to timestamp", "example": 1769017582877 }, "agent_id": { "type": "integer", "format": "int64", "nullable": true, "description": "ID of the agent who triggered the event", "example": 2478 }, "event": { "type": "string", "description": "Event name", "example": "CLOSED" }, "details": { "type": "object", "nullable": true, "description": "Optional event-specific details" }, "target_id": { "type": "integer", "format": "int64", "nullable": true, "description": "Optional ID of the target affected by the event" } }, "required": [ "id", "conversation_id", "type", "timestamp", "timestamp_ts", "event" ] }, "ArticleInCollection": { "type": "object", "description": "Junction table representing the relationship between articles and collections with sort ordering.", "properties": { "article_id": { "type": "integer", "format": "int64", "description": "ID of the article in this relationship." }, "collection_id": { "type": "integer", "nullable": true, "description": "ID of the collection containing the article (null for root-level placement)." }, "sort": { "type": "integer", "description": "Zero-based sort position of the article within the collection.", "example": 2 } }, "x-computed-hash": "bad32f8f85976911c32c6fdcb5189b1c8cbb1affc89245f0bab5303a3f660bcf", "x-last-modified": 1769075325 } } }, "security": [ { "apiKeyHeader": [] } ], "externalDocs": { "description": "You can access our documentation online by visiting https://api.fernand.help", "url": "https://api.fernand.help" } }