{"openapi":"3.2.0","info":{"title":"Answell Public API","version":"1.0.0","description":"REST API pro externí integrace (live-chat widget, Discord bot, Slack). Autentizace pomocí API klíče.","contact":{"name":"Answell Support","url":"https://answell.app"}},"servers":[{"url":"https://app.answell.app/api/v1","description":"Production"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"API key from Answell Settings → API Keys. Available scopes: tickets:read, tickets:write, tickets:delete, messages:read, messages:write, contacts:read, contacts:write, kb:read, kb:write"}},"schemas":{"Conversation":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"integer"},"subject":{"type":"string"},"status":{"type":"string","enum":["OPEN","PENDING","RESOLVED","CLOSED"]},"priority":{"type":"string","enum":["LOW","MEDIUM","HIGH","URGENT"]},"inboxId":{"type":"string"},"contactId":{"type":"string"},"assignedToId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"Message":{"type":"object","properties":{"id":{"type":"string"},"conversationId":{"type":"string"},"content":{"type":"string"},"contentType":{"type":"string","enum":["TEXT","HTML","MARKDOWN"]},"authorAgentId":{"type":["string","null"],"description":"ID of human agent author. null = customer or AI message."},"authorAiAgentId":{"type":["string","null"],"description":"ID of AI agent author. null = customer or human agent message. Signals this message was posted by the AI resolution engine."},"isInternal":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"}}},"Contact":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"email":{"type":"string","format":"email"},"avatarUrl":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"}}},"PaginatedMeta":{"type":"object","properties":{"total":{"type":"integer"},"page":{"type":"integer"},"limit":{"type":"integer"},"totalPages":{"type":"integer"}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"details":{"type":"object"}}},"KnowledgeBaseArticle":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"content":{"type":"string","description":"Serialized MDX/markdown content"},"slug":{"type":["string","null"]},"parentId":{"type":["string","null"]},"isPublished":{"type":"boolean"},"sourceType":{"type":"string","enum":["MANUAL","GENERATED","IMPORTED","OPENAPI"]},"order":{"type":"integer"},"knowledgeBaseId":{"type":"string"},"authorName":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}},"paths":{"/{orgId}/conversations":{"parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"},"description":"Organization ID"}],"get":{"operationId":"listConversations","summary":"List tickets","tags":["Conversations"],"security":[{"bearerAuth":["tickets:read"]}],"parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["OPEN","PENDING","RESOLVED","CLOSED"]}},{"name":"priority","in":"query","schema":{"type":"string","enum":["LOW","MEDIUM","HIGH","URGENT"]}},{"name":"inboxId","in":"query","schema":{"type":"string"}},{"name":"contactId","in":"query","schema":{"type":"string"}},{"name":"search","in":"query","schema":{"type":"string"}},{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":100}}],"responses":{"200":{"description":"List of tickets","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Ticket"}},"meta":{"$ref":"#/components/schemas/PaginatedMeta"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createConversation","summary":"Create a ticket","tags":["Conversations"],"security":[{"bearerAuth":["tickets:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["subject","inboxId","contactEmail"],"properties":{"subject":{"type":"string","maxLength":500},"inboxId":{"type":"string"},"contactEmail":{"type":"string","format":"email","description":"Contact is auto-created if not found"},"contactName":{"type":"string","description":"Used only when creating a new contact"},"contactMetadata":{"type":"object","description":"Optional metadata stored on the contact (up to 10 KB)"},"priority":{"type":"string","enum":["LOW","MEDIUM","HIGH","URGENT"]},"assignedToId":{"type":"string"}}}}}},"responses":{"201":{"description":"Conversation created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Ticket"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — inboxId belongs to a different organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Inbox not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/{orgId}/conversations/{conversationId}":{"parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"},"description":"Organization ID"}],"get":{"operationId":"getConversation","summary":"Get ticket detail","tags":["Conversations"],"security":[{"bearerAuth":["tickets:read"]}],"parameters":[{"name":"conversationId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Conversation","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Ticket"}}}}}},"404":{"description":"Not found"}}},"patch":{"operationId":"updateConversation","summary":"Update ticket","tags":["Conversations"],"security":[{"bearerAuth":["tickets:write"]}],"parameters":[{"name":"conversationId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"subject":{"type":"string"},"priority":{"type":"string","enum":["LOW","MEDIUM","HIGH","URGENT"]},"status":{"type":"string","enum":["OPEN","PENDING","RESOLVED","CLOSED"]},"inboxId":{"type":"string"},"assignedToId":{"type":["string","null"]}}}}}},"responses":{"200":{"description":"Updated ticket"},"404":{"description":"Not found"},"422":{"description":"Validation error"}}},"delete":{"operationId":"deleteConversation","summary":"Delete ticket","tags":["Conversations"],"security":[{"bearerAuth":["tickets:delete"]}],"parameters":[{"name":"conversationId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Deleted"},"404":{"description":"Not found"},"422":{"description":"Cannot delete — wrong status"}}}},"/{orgId}/conversations/{conversationId}/messages":{"parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"},"description":"Organization ID"}],"get":{"operationId":"listMessages","summary":"List ticket messages","tags":["Messages"],"security":[{"bearerAuth":["messages:read"]}],"parameters":[{"name":"conversationId","in":"path","required":true,"schema":{"type":"string"}},{"name":"includeInternal","in":"query","schema":{"type":"boolean","default":false}},{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":100}}],"responses":{"200":{"description":"Messages","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Message"}},"meta":{"$ref":"#/components/schemas/PaginatedMeta"}}}}}}}},"post":{"operationId":"createMessage","summary":"Add a message to ticket","tags":["Messages"],"security":[{"bearerAuth":["messages:write"]}],"parameters":[{"name":"conversationId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["content"],"properties":{"content":{"type":"string"},"contentType":{"type":"string","enum":["TEXT","HTML","MARKDOWN"],"default":"TEXT"},"authorRole":{"type":"string","enum":["customer","agent"],"default":"customer","description":"'customer' = from end-user, 'agent' = from support agent"},"authorAgentId":{"type":"string","description":"Required when authorRole is 'agent'"}}}}}},"responses":{"201":{"description":"Message created"},"404":{"description":"Conversation not found"},"422":{"description":"Validation error"}}}},"/{orgId}/contacts":{"parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"},"description":"Organization ID"}],"get":{"operationId":"listContacts","summary":"List contacts","tags":["Contacts"],"security":[{"bearerAuth":["contacts:read"]}],"parameters":[{"name":"search","in":"query","schema":{"type":"string"}},{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":100}}],"responses":{"200":{"description":"Contacts","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Contact"}},"meta":{"$ref":"#/components/schemas/PaginatedMeta"}}}}}}}},"post":{"operationId":"createContact","summary":"Create a contact","tags":["Contacts"],"security":[{"bearerAuth":["contacts:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","email"],"properties":{"name":{"type":"string","maxLength":200},"email":{"type":"string","format":"email"},"avatarUrl":{"type":"string","format":"uri"},"metadata":{"type":"object"}}}}}},"responses":{"201":{"description":"Contact created"},"409":{"description":"Email already exists"},"422":{"description":"Validation error"}}}},"/{orgId}/contacts/{contactId}":{"parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"},"description":"Organization ID"}],"get":{"operationId":"getContact","summary":"Get contact detail","tags":["Contacts"],"security":[{"bearerAuth":["contacts:read"]}],"parameters":[{"name":"contactId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Contact"},"404":{"description":"Not found"}}},"patch":{"operationId":"updateContact","summary":"Update contact","tags":["Contacts"],"security":[{"bearerAuth":["contacts:write"]}],"parameters":[{"name":"contactId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"email":{"type":"string","format":"email"},"avatarUrl":{"type":["string","null"]},"metadata":{"type":["object","null"]}}}}}},"responses":{"200":{"description":"Updated contact"},"404":{"description":"Not found"},"409":{"description":"Email conflict"}}}},"/{orgId}/kb/articles":{"parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"},"description":"Organization ID"}],"get":{"operationId":"listKbArticles","summary":"List knowledge base articles","tags":["Knowledge Base"],"security":[{"bearerAuth":["kb:read"]}],"parameters":[{"name":"search","in":"query","schema":{"type":"string"},"description":"Full-text search in title and content"},{"name":"isPublished","in":"query","schema":{"type":"boolean"},"description":"Filter by published state"},{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":100}}],"responses":{"200":{"description":"List of KB articles","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/KnowledgeBaseArticle"}},"meta":{"$ref":"#/components/schemas/PaginatedMeta"}}}}}},"400":{"description":"Invalid query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — org mismatch","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createKbArticle","summary":"Create a knowledge base article","tags":["Knowledge Base"],"security":[{"bearerAuth":["kb:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["title","content"],"properties":{"title":{"type":"string","maxLength":500},"content":{"type":"string","maxLength":200000,"description":"Markdown content. Converted to Plate.js nodes — article will be editable in the Answell UI editor."},"slug":{"type":"string","maxLength":200,"description":"URL slug (auto-generated if omitted)"},"parentId":{"type":"string","description":"ID of parent article in this organization"},"isPublished":{"type":"boolean","default":false}}}}}},"responses":{"201":{"description":"Article created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/KnowledgeBaseArticle"}}}}}},"400":{"description":"Invalid JSON body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Plan article limit reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — org mismatch","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error (including invalid parentId)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/{orgId}/kb/articles/{articleId}":{"parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"},"description":"Organization ID"}],"get":{"operationId":"getKbArticle","summary":"Get knowledge base article detail","tags":["Knowledge Base"],"security":[{"bearerAuth":["kb:read"]}],"parameters":[{"name":"articleId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"KB article","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/KnowledgeBaseArticle"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — org mismatch","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Article not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateKbArticle","summary":"Update a knowledge base article","tags":["Knowledge Base"],"security":[{"bearerAuth":["kb:write"]}],"parameters":[{"name":"articleId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","minProperties":1,"properties":{"title":{"type":"string","maxLength":500},"content":{"type":"string","maxLength":200000,"description":"Markdown content. Converted to Plate.js nodes on save."},"slug":{"type":["string","null"],"maxLength":200},"parentId":{"type":["string","null"],"description":"ID of parent article in this organization. Pass null to remove parent."},"isPublished":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Updated article","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/KnowledgeBaseArticle"}}}}}},"400":{"description":"Invalid JSON body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — org mismatch","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Article not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error — including invalid parentId, self-reference, or cycle","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteKbArticle","summary":"Delete a knowledge base article","tags":["Knowledge Base"],"security":[{"bearerAuth":["kb:write"]}],"parameters":[{"name":"articleId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Deleted"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — org mismatch","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Article not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}