{"openapi":"3.1.0","info":{"title":"Frosvo REST API","version":"1.0.0","description":"Read and answer conversations, keep contacts in sync, publish knowledge base articles, read reports and manage webhooks. Authenticate with an API key from Settings → API: `Authorization: Bearer frv_…`. Supported handler responses carry a server-generated X-Request-Id. Valid-key quota responses carry X-RateLimit-Limit/-Remaining/-Reset; past the limit you get 429 with Retry-After. Database unavailability returns 503 with Retry-After; unexpected failures return 500 with a generic error and request_id."},"servers":[{"url":"https://frosvo.com/api/v1"}],"components":{"headers":{"RequestId":{"description":"Server-generated request correlation ID. Include this ID when reporting a failed request.","schema":{"type":"string","format":"uuid"}}},"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"API key (frv_…). Scopes: conversations:read, conversations:write, contacts:read, contacts:write, knowledge:read, knowledge:write, reports:read, webhooks:manage, audit:read."}},"responses":{"E400":{"description":"The request isn't valid.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"E401":{"description":"No key, or a revoked or expired one (invalid_token).","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"E403":{"description":"The key lacks the scope (insufficient_scope), or the plan lacks the feature (plan_required, plan_limit).","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"E404":{"description":"Not found — or not in this key's workspace.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"E409":{"description":"The channel refused the reply (for example, outside WhatsApp's 24-hour window).","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"E429":{"description":"Over the per-minute quota (rate_limited). Wait Retry-After seconds.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"E500":{"description":"Unexpected server failure (server_error). Include request_id when reporting the failure; do not blindly retry writes.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"E503":{"description":"Database availability or pool timeout (temporarily_unavailable). Wait Retry-After seconds; verify ambiguous write outcomes before retrying.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Seconds before another attempt."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string","format":"uuid","description":"Present on unexpected failures; matches X-Request-Id."}}}}},"Conversation":{"type":"object","properties":{"id":{"type":"string"},"site_id":{"type":"string"},"contact_id":{"type":"string"},"status":{"type":"string","enum":["open","active","closed"]},"channel":{"type":"string","enum":["web","telegram","whatsapp","messenger","instagram","email"]},"assignee_id":{"type":["string","null"]},"assistant_handling":{"type":"boolean","description":"The AI assistant is still answering it."},"spam":{"type":"boolean"},"tags":{"type":"array","items":{"type":"string"}},"data":{"type":"object","additionalProperties":{"type":"string"}},"subject":{"type":["string","null"]},"rating":{"type":["integer","null"],"minimum":1,"maximum":5},"rating_comment":{"type":["string","null"]},"last_message_at":{"type":"string","format":"date-time"},"resolved_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"}}},"ConversationDetail":{"allOf":[{"$ref":"#/components/schemas/Conversation"},{"type":"object","required":["reply_version","contact","messages"],"properties":{"reply_version":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Full-history public agent reply count, including removed replies. Pass the reviewed value as expected_reply_version when replying."},"contact":{"$ref":"#/components/schemas/Contact"},"messages":{"type":"array","items":{"$ref":"#/components/schemas/Message"},"maxItems":200}}}]},"Message":{"type":"object","properties":{"id":{"type":"string"},"from":{"type":"string","enum":["visitor","agent","bot","system"]},"sender_name":{"type":["string","null"]},"agent_id":{"type":["string","null"]},"text":{"type":"string"},"private":{"type":"boolean","description":"A team note the visitor never sees."},"files":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string"},"size":{"type":"integer"},"type":{"type":"string"}}}},"created_at":{"type":"string","format":"date-time"}}},"Contact":{"type":"object","properties":{"id":{"type":"string"},"site_id":{"type":"string"},"name":{"type":["string","null"]},"email":{"type":["string","null"]},"phone":{"type":["string","null"]},"company":{"type":["string","null"]},"notes":{"type":["string","null"]},"tags":{"type":"array","items":{"type":"string"}},"fields":{"type":"object","description":"Custom contact fields, by key."},"marketing_consent":{"type":"boolean"},"consent_at":{"type":["string","null"],"format":"date-time"},"consent_source":{"type":["string","null"]},"country":{"type":["string","null"]},"city":{"type":["string","null"]},"first_seen_at":{"type":"string","format":"date-time"},"last_seen_at":{"type":"string","format":"date-time"}}},"ContactInput":{"type":"object","properties":{"name":{"type":"string"},"email":{"type":"string","format":"email"},"phone":{"type":"string"},"company":{"type":"string"},"notes":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"fields":{"type":"object"},"marketing_consent":{"type":"boolean","description":"Only if the person agreed. Recorded with source \"api\"."}}},"Article":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"slug":{"type":"string"},"body":{"type":"string","description":"Markdown."},"category":{"type":["string","null"]},"published":{"type":"boolean"},"url":{"type":"string","description":"Its page in the public help centre."},"views":{"type":"integer"},"helpful":{"type":"integer"},"not_helpful":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"ReportSummary":{"type":"object","properties":{"range":{"type":"object","properties":{"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"},"tz":{"type":"string"}}},"conversations":{"type":"integer"},"resolved":{"type":"integer"},"first_response_seconds":{"type":"object","properties":{"median":{"type":["integer","null"]},"p90":{"type":["integer","null"]}}},"resolution_seconds":{"type":"object","properties":{"median":{"type":["integer","null"]},"p90":{"type":["integer","null"]}}},"satisfaction":{"type":"object","properties":{"average":{"type":["number","null"]},"ratings":{"type":"integer"},"satisfied_percent":{"type":["integer","null"]},"distribution":{"type":"array","items":{"type":"integer"}}}},"sla":{"type":"object","properties":{"met":{"type":"integer"},"breached":{"type":"integer"},"met_percent":{"type":["integer","null"]}}},"assistant":{"type":"object","properties":{"conversations":{"type":"integer"},"resolved_alone":{"type":"integer"},"handed_over":{"type":"integer"}}},"per_day":{"type":"array","items":{"type":"object","properties":{"day":{"type":"string"},"conversations":{"type":"integer"}}}}}},"WebhookEndpoint":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"description":{"type":["string","null"]},"events":{"type":"array","items":{"type":"string","enum":["*","conversation.created","conversation.resolved","conversation.reopened","conversation.assigned","conversation.handed_over","message.created","contact.created","contact.updated","rating.created","sla.breached"]}},"enabled":{"type":"boolean"},"disabled_reason":{"type":["string","null"]},"failure_streak":{"type":"integer"},"created_at":{"type":"string","format":"date-time"}}},"WebhookDelivery":{"type":"object","properties":{"id":{"type":"string"},"event_id":{"type":"string"},"event_type":{"type":"string"},"status":{"type":"string","enum":["pending","sending","succeeded","failed","dead"]},"attempts":{"type":"integer"},"next_attempt_at":{"type":["string","null"],"format":"date-time"},"response_status":{"type":["integer","null"]},"response_body":{"type":["string","null"]},"error":{"type":["string","null"]},"duration_ms":{"type":["integer","null"]},"replay":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"}}},"Event":{"type":"object","description":"What every webhook request body is, and what /events lists.","properties":{"id":{"type":"string","description":"evt_… — dedupe on it."},"type":{"type":"string","enum":["conversation.created","conversation.resolved","conversation.reopened","conversation.assigned","conversation.handed_over","message.created","contact.created","contact.updated","rating.created","sla.breached","webhook.test"]},"created_at":{"type":"string","format":"date-time"},"workspace_id":{"type":"string"},"data":{"type":"object"}}}}},"paths":{"/me":{"get":{"summary":"The key: its workspace, scopes and quota","security":[{"bearer":[]}],"responses":{"200":{"description":"The key."},"401":{"$ref":"#/components/responses/E401"},"500":{"$ref":"#/components/responses/E500"},"503":{"$ref":"#/components/responses/E503"}}}},"/stream":{"get":{"summary":"Live events (Server-Sent Events): message.created, conversation.updated, typing, conversation.read, message.removed, message.delivery","x-scope":"conversations:read","security":[{"bearer":["conversations:read"]}],"x-sse":true,"description":"A long-lived text/event-stream. The first frame is a `ready` event; each frame has an `id`. Reconnect with the Last-Event-ID header to receive what was missed (up to a day). The WebSocket gateway relays the same events.","parameters":[{"name":"Last-Event-ID","in":"header","schema":{"type":"string"},"description":"The id of the last frame received."}],"responses":{"200":{"description":"The event stream.","content":{"text/event-stream":{"schema":{"type":"string"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"},"500":{"$ref":"#/components/responses/E500"},"503":{"$ref":"#/components/responses/E503"}}}},"/conversations":{"get":{"summary":"List conversations, most recently active first","x-scope":"conversations:read","security":[{"bearer":["conversations:read"]}],"parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["open","active","closed"]}},{"name":"site_id","in":"query","schema":{"type":"string"}},{"name":"updated_since","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"next_cursor from the previous page."}],"responses":{"200":{"description":"A page of conversations.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Conversation"}},"next_cursor":{"type":["string","null"],"description":"Pass as ?cursor= for the next page; null on the last."}}}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"},"500":{"$ref":"#/components/responses/E500"},"503":{"$ref":"#/components/responses/E503"}}}},"/conversations/{id}":{"get":{"summary":"A conversation with its contact and latest 200 messages","x-scope":"conversations:read","security":[{"bearer":["conversations:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The conversation's id."}],"responses":{"200":{"description":"The conversation and its reply version in one snapshot.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ConversationDetail"}}}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"429":{"$ref":"#/components/responses/E429"},"500":{"$ref":"#/components/responses/E500"},"503":{"$ref":"#/components/responses/E503"}}}},"/conversations/{id}/messages":{"get":{"summary":"Messages, oldest first","x-scope":"conversations:read","security":[{"bearer":["conversations:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The conversation's id."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"next_cursor from the previous page."}],"responses":{"200":{"description":"A page of messages.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Message"}},"next_cursor":{"type":["string","null"],"description":"Pass as ?cursor= for the next page; null on the last."}}}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"429":{"$ref":"#/components/responses/E429"},"500":{"$ref":"#/components/responses/E500"},"503":{"$ref":"#/components/responses/E503"}}},"post":{"summary":"Reply to the visitor, or add a private team note","x-scope":"conversations:write","security":[{"bearer":["conversations:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The conversation's id."}],"requestBody":{"required":true,"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","required":["text"],"properties":{"text":{"type":"string","maxLength":8000},"private":{"type":"boolean","default":false},"sender_name":{"type":"string","description":"Shown to the visitor; defaults to the key's name."},"expected_reply_version":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Optional reviewed reply_version from GET conversation. Public sends return 409 reply_collision if another public reply arrived. Private notes do not advance the version; omitted guards preserve legacy behavior."}}}}}},"responses":{"201":{"description":"The message, sent like a reply from the desk (translated, delivered on the conversation's channel, counted for SLAs).","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Message"}}}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"409":{"$ref":"#/components/responses/E409"},"429":{"$ref":"#/components/responses/E429"},"500":{"$ref":"#/components/responses/E500"},"503":{"$ref":"#/components/responses/E503"}}}},"/conversations/{id}/actions":{"post":{"summary":"Resolve, reopen, assign, tag or mark as spam","x-scope":"conversations:write","security":[{"bearer":["conversations:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The conversation's id."}],"requestBody":{"required":true,"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","required":["action"],"properties":{"action":{"type":"string","enum":["close","reopen","assign","release","tag","untag","data","spam","unspam"]},"agent_id":{"type":["string","null"],"description":"assign: someone on the team, or null to unassign."},"tag":{"type":"string","description":"tag / untag."},"key":{"type":"string","description":"data: the key."},"value":{"type":"string","description":"data: the value; empty removes the key."}}}}}},"responses":{"200":{"description":"The conversation after the action.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Conversation"}}}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"429":{"$ref":"#/components/responses/E429"},"500":{"$ref":"#/components/responses/E500"},"503":{"$ref":"#/components/responses/E503"}}}},"/contacts":{"get":{"summary":"List or find contacts","x-scope":"contacts:read","security":[{"bearer":["contacts:read"]}],"parameters":[{"name":"email","in":"query","schema":{"type":"string"}},{"name":"q","in":"query","schema":{"type":"string"},"description":"Name, email, phone or company contains."},{"name":"site_id","in":"query","schema":{"type":"string"}},{"name":"tag","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"next_cursor from the previous page."}],"responses":{"200":{"description":"A page of contacts.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Contact"}},"next_cursor":{"type":["string","null"],"description":"Pass as ?cursor= for the next page; null on the last."}}}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"},"500":{"$ref":"#/components/responses/E500"},"503":{"$ref":"#/components/responses/E503"}}},"post":{"summary":"Create a contact, or update the one with this email on this website","x-scope":"contacts:write","security":[{"bearer":["contacts:write"]}],"requestBody":{"required":true,"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"allOf":[{"type":"object","required":["site_id"],"properties":{"site_id":{"type":"string"}}},{"$ref":"#/components/schemas/ContactInput"}]}}}},"responses":{"200":{"description":"Updated (created: false).","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Contact"},"created":{"type":"boolean"}}}}}},"201":{"description":"Created (created: true).","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Contact"},"created":{"type":"boolean"}}}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"},"500":{"$ref":"#/components/responses/E500"},"503":{"$ref":"#/components/responses/E503"}}}},"/contacts/{id}":{"get":{"summary":"A contact","x-scope":"contacts:read","security":[{"bearer":["contacts:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The contact's id."}],"responses":{"200":{"description":"The contact.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Contact"}}}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"429":{"$ref":"#/components/responses/E429"},"500":{"$ref":"#/components/responses/E500"},"503":{"$ref":"#/components/responses/E503"}}},"patch":{"summary":"Change a contact","x-scope":"contacts:write","security":[{"bearer":["contacts:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The contact's id."}],"requestBody":{"required":true,"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactInput"}}}},"responses":{"200":{"description":"The contact.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Contact"}}}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"429":{"$ref":"#/components/responses/E429"},"500":{"$ref":"#/components/responses/E500"},"503":{"$ref":"#/components/responses/E503"}}}},"/articles":{"get":{"summary":"List knowledge base articles","x-scope":"knowledge:read","security":[{"bearer":["knowledge:read"]}],"parameters":[{"name":"published","in":"query","schema":{"type":"boolean"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"next_cursor from the previous page."}],"responses":{"200":{"description":"A page of articles.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Article"}},"next_cursor":{"type":["string","null"],"description":"Pass as ?cursor= for the next page; null on the last."}}}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"},"500":{"$ref":"#/components/responses/E500"},"503":{"$ref":"#/components/responses/E503"}}},"post":{"summary":"Publish an article (the assistant learns it)","x-scope":"knowledge:write","security":[{"bearer":["knowledge:write"]}],"requestBody":{"required":true,"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","required":["title","body"],"properties":{"title":{"type":"string"},"body":{"type":"string"},"category":{"type":"string"},"published":{"type":"boolean","default":true}}}}}},"responses":{"201":{"description":"The article.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Article"}}}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"},"500":{"$ref":"#/components/responses/E500"},"503":{"$ref":"#/components/responses/E503"}}}},"/articles/{id}":{"get":{"summary":"An article","x-scope":"knowledge:read","security":[{"bearer":["knowledge:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The article's id."}],"responses":{"200":{"description":"The article.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Article"}}}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"429":{"$ref":"#/components/responses/E429"},"500":{"$ref":"#/components/responses/E500"},"503":{"$ref":"#/components/responses/E503"}}},"patch":{"summary":"Change an article","x-scope":"knowledge:write","security":[{"bearer":["knowledge:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The article's id."}],"requestBody":{"required":true,"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"body":{"type":"string"},"category":{"type":["string","null"]},"published":{"type":"boolean"}}}}}},"responses":{"200":{"description":"The article.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Article"}}}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"429":{"$ref":"#/components/responses/E429"},"500":{"$ref":"#/components/responses/E500"},"503":{"$ref":"#/components/responses/E503"}}}},"/reports/summary":{"get":{"summary":"Report numbers for a date range","x-scope":"reports:read","security":[{"bearer":["reports:read"]}],"parameters":[{"name":"from","in":"query","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","schema":{"type":"string","format":"date"}},{"name":"tz","in":"query","schema":{"type":"string","default":"UTC"},"description":"IANA zone; days are counted in it."},{"name":"site_id","in":"query","schema":{"type":"string"}},{"name":"channel","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"The numbers.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ReportSummary"}}}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"},"500":{"$ref":"#/components/responses/E500"},"503":{"$ref":"#/components/responses/E503"}}}},"/audit":{"get":{"summary":"The audit log, newest first, a page at a time","x-scope":"audit:read","security":[{"bearer":["audit:read"]}],"parameters":[{"name":"action","in":"query","schema":{"type":"string"},"description":"One action (auth.sign_in) or a group ending in a dot (auth.)."},{"name":"since","in":"query","schema":{"type":"string","format":"date-time"},"description":"Only events after this moment."},{"name":"limit","in":"query","schema":{"type":"integer","maximum":200,"default":100}},{"name":"cursor","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Events and next_cursor."},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"},"500":{"$ref":"#/components/responses/E500"},"503":{"$ref":"#/components/responses/E503"}}}},"/webhooks":{"get":{"summary":"List webhook endpoints","x-scope":"webhooks:manage","security":[{"bearer":["webhooks:manage"]}],"responses":{"200":{"description":"Endpoints.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEndpoint"}}}}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"},"500":{"$ref":"#/components/responses/E500"},"503":{"$ref":"#/components/responses/E503"}}},"post":{"summary":"Add an endpoint (its signing secret is in this answer)","x-scope":"webhooks:manage","security":[{"bearer":["webhooks:manage"]}],"requestBody":{"required":true,"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","required":["url","events"],"properties":{"url":{"type":"string","format":"uri"},"description":{"type":"string"},"events":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"201":{"description":"The endpoint, with secret.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"$ref":"#/components/schemas/WebhookEndpoint"},{"type":"object","properties":{"secret":{"type":"string"}}}]}}}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"},"500":{"$ref":"#/components/responses/E500"},"503":{"$ref":"#/components/responses/E503"}}}},"/webhooks/{id}":{"get":{"summary":"An endpoint","x-scope":"webhooks:manage","security":[{"bearer":["webhooks:manage"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The endpoint's id."}],"responses":{"200":{"description":"The endpoint.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WebhookEndpoint"}}}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"429":{"$ref":"#/components/responses/E429"},"500":{"$ref":"#/components/responses/E500"},"503":{"$ref":"#/components/responses/E503"}}},"patch":{"summary":"Change an endpoint, or switch it on/off","x-scope":"webhooks:manage","security":[{"bearer":["webhooks:manage"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The endpoint's id."}],"requestBody":{"required":true,"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"},"description":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"enabled":{"type":"boolean"}}}}}},"responses":{"200":{"description":"The endpoint.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WebhookEndpoint"}}}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"429":{"$ref":"#/components/responses/E429"},"500":{"$ref":"#/components/responses/E500"},"503":{"$ref":"#/components/responses/E503"}}},"delete":{"summary":"Delete an endpoint and its delivery history","x-scope":"webhooks:manage","security":[{"bearer":["webhooks:manage"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The endpoint's id."}],"responses":{"200":{"description":"Deleted."},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"429":{"$ref":"#/components/responses/E429"},"500":{"$ref":"#/components/responses/E500"},"503":{"$ref":"#/components/responses/E503"}}}},"/webhooks/{id}/deliveries":{"get":{"summary":"Deliveries to an endpoint, newest first","x-scope":"webhooks:manage","security":[{"bearer":["webhooks:manage"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The endpoint's id."},{"name":"status","in":"query","schema":{"type":"string","enum":["pending","sending","succeeded","failed","dead"]}},{"name":"before","in":"query","schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"Deliveries.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookDelivery"}},"next_before":{"type":["string","null"]}}}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"429":{"$ref":"#/components/responses/E429"},"500":{"$ref":"#/components/responses/E500"},"503":{"$ref":"#/components/responses/E503"}}}},"/webhooks/{id}/replay":{"post":{"summary":"Send an event to this endpoint again","x-scope":"webhooks:manage","security":[{"bearer":["webhooks:manage"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The endpoint's id."}],"requestBody":{"required":true,"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","required":["event_id"],"properties":{"event_id":{"type":"string"}}}}}},"responses":{"202":{"description":"Queued.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"delivery_id":{"type":"string"}}}}}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"429":{"$ref":"#/components/responses/E429"},"500":{"$ref":"#/components/responses/E500"},"503":{"$ref":"#/components/responses/E503"}}}},"/events":{"get":{"summary":"Events sent to this workspace's webhooks, newest first","x-scope":"webhooks:manage","security":[{"bearer":["webhooks:manage"]}],"parameters":[{"name":"type","in":"query","schema":{"type":"string"}},{"name":"before","in":"query","schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"Events, each with its deliveries.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Event"}},"next_before":{"type":["string","null"]}}}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"},"500":{"$ref":"#/components/responses/E500"},"503":{"$ref":"#/components/responses/E503"}}}}},"x-webhooks":{"events":{"conversation.created":"A new conversation starts (its first message)","conversation.resolved":"A conversation is resolved","conversation.reopened":"A resolved conversation is reopened","conversation.assigned":"A conversation is assigned, reassigned or released","conversation.handed_over":"The assistant hands a conversation to the team","message.created":"A message from the visitor, the assistant or the team (not private notes)","contact.created":"A contact is created","contact.updated":"A contact is changed","rating.created":"A visitor rates a conversation","sla.breached":"A first-response or resolution deadline is missed"},"signature":"Frosvo-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\" with the endpoint's secret>. Compare in constant time and reject timestamps older than 5 minutes. Retries: 1, 5, 30, 120, 360, 720, 1440 minutes, then given up."}}