{"openapi":"3.1.0","info":{"title":"Tirver API","version":"1.0.0","description":"Read your workspace and act on it with a secret API key. Create a key under Settings, API keys. Each key has explicit scopes and may make 120 requests a minute."},"servers":[{"url":"https://app.tirver.com/api/v1"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Workspace"},{"name":"Conversations"},{"name":"Customers"},{"name":"Help center"},{"name":"Feedback"},{"name":"Changelog"},{"name":"Knowledge"},{"name":"AI"},{"name":"Credits"}],"paths":{"/workspace":{"get":{"operationId":"getWorkspace","summary":"Get the workspace","description":"Returns the workspace the API key belongs to and the key’s own scopes. Needs no scope; a quick way to check a key.","tags":["Workspace"],"parameters":[],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Workspace"}}}},"401":{"$ref":"#/components/responses/Error401"},"429":{"$ref":"#/components/responses/Error429"}},"security":[{"bearerAuth":[]}]}},"/conversations":{"get":{"operationId":"listConversations","summary":"List conversations","description":"Newest first by creation time. Filter by status, assignee, who handled it, tag or customer.","tags":["Conversations"],"parameters":[{"name":"status","in":"query","required":false,"description":"One of `open`, `snoozed` or `closed`.","schema":{"type":"string","enum":["open","snoozed","closed"]}},{"name":"assignee_id","in":"query","required":false,"description":"Only conversations assigned to this team member.","schema":{"type":"string","maxLength":128}},{"name":"handled_by","in":"query","required":false,"description":"`ai` for conversations the AI agent is handling, `team` for the rest.","schema":{"type":"string","enum":["ai","team"]}},{"name":"tag","in":"query","required":false,"description":"A tag name or id.","schema":{"type":"string","maxLength":128}},{"name":"customer_id","in":"query","required":false,"description":"Only this customer’s conversations.","schema":{"type":"string","maxLength":128}},{"name":"limit","in":"query","required":false,"description":"Page size, 1 to 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"cursor","in":"query","required":false,"description":"The `next_cursor` from the previous page.","schema":{"type":"string","maxLength":400}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationList"}}}},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"}},"x-required-scope":"conversations:read","security":[{"bearerAuth":[]}]}},"/conversations/{id}":{"get":{"operationId":"getConversation","summary":"Get a conversation","description":"One conversation with its customer, a short extract of the thread and up to the first 500 messages (internal notes included).","tags":["Conversations"],"parameters":[{"name":"id","in":"path","required":true,"description":"Conversation id.","schema":{"type":"string","minLength":1,"maxLength":128}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationDetail"}}}},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"429":{"$ref":"#/components/responses/Error429"}},"x-required-scope":"conversations:read","security":[{"bearerAuth":[]}]}},"/conversations/{id}/messages":{"get":{"operationId":"listMessages","summary":"List messages in a conversation","description":"Oldest first. Internal notes are included and have `type` set to `note`.","tags":["Conversations"],"parameters":[{"name":"id","in":"path","required":true,"description":"Conversation id.","schema":{"type":"string","minLength":1,"maxLength":128}},{"name":"limit","in":"query","required":false,"description":"Page size, 1 to 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"cursor","in":"query","required":false,"description":"The `next_cursor` from the previous page.","schema":{"type":"string","maxLength":400}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageList"}}}},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"}},"x-required-scope":"conversations:read","security":[{"bearerAuth":[]}]},"post":{"operationId":"createMessage","summary":"Reply to a conversation or add a note","description":"A `reply` is sent to the customer and takes the conversation off the AI agent. A `note` stays with your team. The message is from `author_id`, a team member; it defaults to the person who created the key.","tags":["Conversations"],"parameters":[{"name":"id","in":"path","required":true,"description":"Conversation id.","schema":{"type":"string","minLength":1,"maxLength":128}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string","description":"The message text, up to 4,000 characters.","minLength":1,"maxLength":4000},"type":{"type":"string","description":"`reply` reaches the customer. `note` stays with your team.","enum":["reply","note"]},"author_id":{"type":"string","description":"The team member the message is from.","maxLength":128}},"required":["body","type"],"additionalProperties":false}}}},"responses":{"201":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Message"}}}},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"}},"x-required-scope":"conversations:write","security":[{"bearerAuth":[]}]}},"/conversations/{id}/close":{"post":{"operationId":"closeConversation","summary":"Close a conversation","description":"Sets `status` to `closed`. Sends no message to the customer.","tags":["Conversations"],"parameters":[{"name":"id","in":"path","required":true,"description":"Conversation id.","schema":{"type":"string","minLength":1,"maxLength":128}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Conversation"}}}},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"429":{"$ref":"#/components/responses/Error429"}},"x-required-scope":"conversations:write","security":[{"bearerAuth":[]}]}},"/customers":{"get":{"operationId":"listCustomers","summary":"List customers","description":"Newest first. Search by name or email with `q`, or look one up by exact `email` or `external_id`.","tags":["Customers"],"parameters":[{"name":"q","in":"query","required":false,"description":"Search name and email.","schema":{"type":"string","maxLength":100}},{"name":"email","in":"query","required":false,"description":"Exact email address.","schema":{"type":"string","maxLength":320}},{"name":"external_id","in":"query","required":false,"description":"The id you gave the customer when you identified them.","schema":{"type":"string","maxLength":200}},{"name":"limit","in":"query","required":false,"description":"Page size, 1 to 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"cursor","in":"query","required":false,"description":"The `next_cursor` from the previous page.","schema":{"type":"string","maxLength":400}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerList"}}}},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"}},"x-required-scope":"customers:read","security":[{"bearerAuth":[]}]}},"/customers/{id}":{"get":{"operationId":"getCustomer","summary":"Get a customer","description":"One customer with how many conversations they have had.","tags":["Customers"],"parameters":[{"name":"id","in":"path","required":true,"description":"Customer id.","schema":{"type":"string","minLength":1,"maxLength":128}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerDetail"}}}},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"429":{"$ref":"#/components/responses/Error429"}},"x-required-scope":"customers:read","security":[{"bearerAuth":[]}]}},"/help-center/collections":{"get":{"operationId":"listCollections","summary":"List help center collections","description":"All collections with article counts.","tags":["Help center"],"parameters":[],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionList"}}}},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"429":{"$ref":"#/components/responses/Error429"}},"x-required-scope":"help-center:read","security":[{"bearerAuth":[]}]}},"/help-center/articles":{"get":{"operationId":"listArticles","summary":"List help center articles","description":"Most recently updated first, drafts included unless you filter by `status`. The list leaves out the body; fetch one article for it.","tags":["Help center"],"parameters":[{"name":"status","in":"query","required":false,"description":"`draft` or `published`.","schema":{"type":"string","enum":["draft","published"]}},{"name":"collection_id","in":"query","required":false,"description":"Only articles in this collection.","schema":{"type":"string","maxLength":128}},{"name":"q","in":"query","required":false,"description":"Search title and body.","schema":{"type":"string","maxLength":100}},{"name":"limit","in":"query","required":false,"description":"Page size, 1 to 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"cursor","in":"query","required":false,"description":"The `next_cursor` from the previous page.","schema":{"type":"string","maxLength":400}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArticleList"}}}},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"}},"x-required-scope":"help-center:read","security":[{"bearerAuth":[]}]},"post":{"operationId":"createArticle","summary":"Create an article draft","description":"Creates a draft. It is never published: a person publishes it in Tirver.","tags":["Help center"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","description":"Title, up to 160 characters.","minLength":1,"maxLength":160},"body":{"type":"string","description":"Markdown body.","maxLength":100000},"collection_id":{"type":["string","null"],"description":"Collection to file it under.","maxLength":128},"slug":{"type":"string","description":"Address; made from the title when left out. Lowercase letters, numbers and dashes.","maxLength":80},"description":{"type":"string","description":"SEO description, up to 320 characters.","maxLength":320}},"required":["title"],"additionalProperties":false}}}},"responses":{"201":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArticleDetail"}}}},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"}},"x-required-scope":"help-center:write","security":[{"bearerAuth":[]}]}},"/help-center/articles/{id}":{"get":{"operationId":"getArticle","summary":"Get a help center article","description":"One article with its Markdown body. Accepts the article id or its slug.","tags":["Help center"],"parameters":[{"name":"id","in":"path","required":true,"description":"Article id or slug.","schema":{"type":"string","minLength":1,"maxLength":128}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArticleDetail"}}}},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"429":{"$ref":"#/components/responses/Error429"}},"x-required-scope":"help-center:read","security":[{"bearerAuth":[]}]}},"/search":{"get":{"operationId":"searchArticles","summary":"Search published articles","description":"Keyword search over the title and body of published articles; titles rank first. It matches the words you give, not their meaning: for a natural language answer use Ask.","tags":["Help center"],"parameters":[{"name":"q","in":"query","required":true,"description":"What to look for.","schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"limit","in":"query","required":false,"description":"How many results, 1 to 50.","schema":{"type":"integer","minimum":1,"maximum":50,"default":10}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArticleList"}}}},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"}},"x-required-scope":"help-center:read","security":[{"bearerAuth":[]}]}},"/feedback/boards":{"get":{"operationId":"listBoards","summary":"List feedback boards","description":"All boards.","tags":["Feedback"],"parameters":[],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoardList"}}}},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"429":{"$ref":"#/components/responses/Error429"}},"x-required-scope":"feedback:read","security":[{"bearerAuth":[]}]}},"/feedback/posts":{"get":{"operationId":"listFeedbackPosts","summary":"List feedback posts","description":"Newest first. Posts merged into another post are left out.","tags":["Feedback"],"parameters":[{"name":"status","in":"query","required":false,"description":"Roadmap status.","schema":{"type":"string","enum":["open","planned","in_progress","shipped","declined"]}},{"name":"board_id","in":"query","required":false,"description":"Only posts on this board.","schema":{"type":"string","maxLength":128}},{"name":"q","in":"query","required":false,"description":"Search title and details.","schema":{"type":"string","maxLength":100}},{"name":"limit","in":"query","required":false,"description":"Page size, 1 to 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"cursor","in":"query","required":false,"description":"The `next_cursor` from the previous page.","schema":{"type":"string","maxLength":400}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackPostList"}}}},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"}},"x-required-scope":"feedback:read","security":[{"bearerAuth":[]}]},"post":{"operationId":"createFeedbackPost","summary":"Create a feedback post","description":"Files a post on the team’s behalf. With `conversation_id` the post is linked to that conversation and its customer, who gets the first vote. A conversation can have one post.","tags":["Feedback"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","description":"Title, up to 160 characters.","minLength":1,"maxLength":160},"body":{"type":"string","description":"Details, up to 8,000 characters.","maxLength":8000},"board_id":{"type":["string","null"],"description":"Board to file it on.","maxLength":128},"conversation_id":{"type":"string","description":"Link the post to this conversation.","maxLength":128}},"required":["title"],"additionalProperties":false}}}},"responses":{"201":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackPost"}}}},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"}},"x-required-scope":"feedback:write","security":[{"bearerAuth":[]}]}},"/feedback/posts/{id}":{"get":{"operationId":"getFeedbackPost","summary":"Get a feedback post","description":"One post with its comments.","tags":["Feedback"],"parameters":[{"name":"id","in":"path","required":true,"description":"Post id.","schema":{"type":"string","minLength":1,"maxLength":128}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackPostDetail"}}}},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"429":{"$ref":"#/components/responses/Error429"}},"x-required-scope":"feedback:read","security":[{"bearerAuth":[]}]}},"/changelog":{"get":{"operationId":"listChangelog","summary":"List changelog entries","description":"Newest first. Only published entries unless you pass `status`.","tags":["Changelog"],"parameters":[{"name":"status","in":"query","required":false,"description":"`published` (default), `draft` or `all`.","schema":{"type":"string","enum":["published","draft","all"]}},{"name":"limit","in":"query","required":false,"description":"Page size, 1 to 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"cursor","in":"query","required":false,"description":"The `next_cursor` from the previous page.","schema":{"type":"string","maxLength":400}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangelogEntryList"}}}},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"}},"x-required-scope":"changelog:read","security":[{"bearerAuth":[]}]}},"/changelog/{id}":{"get":{"operationId":"getChangelogEntry","summary":"Get a changelog entry","description":"One entry with its Markdown body. Accepts the entry id or its slug.","tags":["Changelog"],"parameters":[{"name":"id","in":"path","required":true,"description":"Entry id or slug.","schema":{"type":"string","minLength":1,"maxLength":128}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangelogEntryDetail"}}}},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"429":{"$ref":"#/components/responses/Error429"}},"x-required-scope":"changelog:read","security":[{"bearerAuth":[]}]}},"/knowledge/sources":{"get":{"operationId":"listKnowledgeSources","summary":"List knowledge sources","description":"The files, pages and sitemaps the AI agent learns from, with their indexing state. Read only.","tags":["Knowledge"],"parameters":[],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeSourceList"}}}},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"429":{"$ref":"#/components/responses/Error429"}},"x-required-scope":"knowledge:read","security":[{"bearerAuth":[]}]}},"/knowledge/sources/{id}":{"get":{"operationId":"getKnowledgeSource","summary":"Get a knowledge source","description":"One source with page counts and a few pages that failed or were skipped.","tags":["Knowledge"],"parameters":[{"name":"id","in":"path","required":true,"description":"Source id.","schema":{"type":"string","minLength":1,"maxLength":128}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeSourceDetail"}}}},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"429":{"$ref":"#/components/responses/Error429"}},"x-required-scope":"knowledge:read","security":[{"bearerAuth":[]}]}},"/ask":{"post":{"operationId":"ask","summary":"Ask the AI agent","description":"Answers a question from the workspace’s knowledge, with citations, using the same AI agent and settings as the “Test the agent” box. Nothing is stored and no credits are used. Limited to 10 questions a minute per key. Questions are up to 2000 characters.","tags":["AI"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"question":{"type":"string","description":"The question, up to 2000 characters.","minLength":1,"maxLength":2000},"history":{"type":"array","description":"Earlier turns, oldest first, up to 19.","maxItems":19,"items":{"type":"object","properties":{"role":{"type":"string","description":"`user` or `assistant`.","enum":["user","assistant"]},"text":{"type":"string","description":"What was said.","minLength":1,"maxLength":2000}},"required":["role","text"],"additionalProperties":false}}},"required":["question"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Answer"}}}},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"}},"x-required-scope":"ai:ask","security":[{"bearerAuth":[]}]}},"/credits":{"get":{"operationId":"getCredits","summary":"Get the credit balance","description":"AI credits left, granted and spent.","tags":["Credits"],"parameters":[],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Credits"}}}},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"429":{"$ref":"#/components/responses/Error429"}},"x-required-scope":"credits:read","security":[{"bearerAuth":[]}]}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Send \"Authorization: Bearer trv_live_...\" . Scopes: conversations:read, customers:read, help-center:read, feedback:read, changelog:read, knowledge:read, credits:read, ai:ask, conversations:write, help-center:write, feedback:write."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"A stable machine readable code."},"message":{"type":"string","description":"What went wrong, in words."},"fields":{"type":"object","description":"Field name to message, for validation errors.","properties":{},"additionalProperties":true},"request_id":{"type":"string","description":"Quote this if you contact support."}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"Workspace":{"type":"object","properties":{"id":{"type":"string","description":"Workspace id."},"name":{"type":"string","description":"Workspace name."},"slug":{"type":"string","description":"Workspace slug."},"api_key":{"type":"object","properties":{"id":{"type":"string","description":"Key id."},"name":{"type":"string","description":"Key name."},"prefix":{"type":"string","description":"First characters of the key."},"scopes":{"type":"array","items":{"type":"string","description":"Scope."}}},"required":["id","name","prefix","scopes"]}},"required":["id","name","slug","api_key"]},"Conversation":{"type":"object","properties":{"id":{"type":"string","description":"Conversation id."},"status":{"type":"string","description":"open, snoozed or closed.","enum":["open","snoozed","closed"]},"customer_id":{"type":"string","description":"The customer in the conversation."},"assignee_id":{"type":["string","null"],"description":"Team member the conversation is assigned to, or null."},"handled_by":{"type":"string","description":"ai when the AI agent is handling it, otherwise team.","enum":["ai","team"]},"channel":{"type":"string","description":"Where it started.","enum":["widget","email","api"]},"subject":{"type":["string","null"],"description":"Subject line, when there is one."},"tags":{"type":"array","items":{"type":"string","description":"Tag name."}},"snoozed_until":{"type":["string","null"],"description":"When a snoozed conversation returns to open."},"last_message_at":{"type":["string","null"],"description":"Time of the latest message."},"created_at":{"type":["string","null"],"description":"ISO 8601 time."},"updated_at":{"type":["string","null"],"description":"ISO 8601 time."}},"required":["id","status","customer_id","assignee_id","handled_by","channel","subject","tags","snoozed_until","last_message_at","created_at","updated_at"]},"ConversationDetail":{"type":"object","properties":{"id":{"type":"string","description":"Conversation id."},"status":{"type":"string","description":"open, snoozed or closed.","enum":["open","snoozed","closed"]},"customer_id":{"type":"string","description":"The customer in the conversation."},"assignee_id":{"type":["string","null"],"description":"Team member the conversation is assigned to, or null."},"handled_by":{"type":"string","description":"ai when the AI agent is handling it, otherwise team.","enum":["ai","team"]},"channel":{"type":"string","description":"Where it started.","enum":["widget","email","api"]},"subject":{"type":["string","null"],"description":"Subject line, when there is one."},"tags":{"type":"array","items":{"type":"string","description":"Tag name."}},"snoozed_until":{"type":["string","null"],"description":"When a snoozed conversation returns to open."},"last_message_at":{"type":["string","null"],"description":"Time of the latest message."},"created_at":{"type":["string","null"],"description":"ISO 8601 time."},"updated_at":{"type":["string","null"],"description":"ISO 8601 time."},"customer":{"type":["object","null"],"properties":{"id":{"type":"string","description":"Customer id."},"name":{"type":["string","null"],"description":"Name."},"email":{"type":["string","null"],"description":"Email address."}},"required":["id","name","email"]},"summary":{"type":"string","description":"A short plain extract of the thread (not a model summary)."},"messages":{"type":"array","description":"Up to the first 500 messages, oldest first, notes included.","items":{"type":"object","properties":{"id":{"type":"string","description":"Message id."},"conversation_id":{"type":"string","description":"Conversation id."},"type":{"type":"string","description":"reply is visible to the customer, note is internal.","enum":["reply","note"]},"sender":{"type":"string","description":"Who wrote it.","enum":["customer","agent","ai"]},"author_id":{"type":["string","null"],"description":"Team member or customer id; null for the AI agent."},"body":{"type":"string","description":"Message text."},"citations":{"type":"array","description":"Sources the AI agent used.","items":{"type":"object","properties":{"title":{"type":["string","null"],"description":"Source title."},"url":{"type":["string","null"],"description":"Source address."}},"required":["title","url"]}},"created_at":{"type":["string","null"],"description":"ISO 8601 time."}},"required":["id","conversation_id","type","sender","author_id","body","citations","created_at"]}}},"required":["id","status","customer_id","assignee_id","handled_by","channel","subject","tags","snoozed_until","last_message_at","created_at","updated_at","customer","summary","messages"]},"Message":{"type":"object","properties":{"id":{"type":"string","description":"Message id."},"conversation_id":{"type":"string","description":"Conversation id."},"type":{"type":"string","description":"reply is visible to the customer, note is internal.","enum":["reply","note"]},"sender":{"type":"string","description":"Who wrote it.","enum":["customer","agent","ai"]},"author_id":{"type":["string","null"],"description":"Team member or customer id; null for the AI agent."},"body":{"type":"string","description":"Message text."},"citations":{"type":"array","description":"Sources the AI agent used.","items":{"type":"object","properties":{"title":{"type":["string","null"],"description":"Source title."},"url":{"type":["string","null"],"description":"Source address."}},"required":["title","url"]}},"created_at":{"type":["string","null"],"description":"ISO 8601 time."}},"required":["id","conversation_id","type","sender","author_id","body","citations","created_at"]},"Customer":{"type":"object","properties":{"id":{"type":"string","description":"Customer id."},"external_id":{"type":["string","null"],"description":"Your own id for the customer, when identified."},"email":{"type":["string","null"],"description":"Email address."},"name":{"type":["string","null"],"description":"Name."},"attributes":{"type":"object","description":"Custom attributes.","properties":{},"additionalProperties":true},"last_seen_at":{"type":["string","null"],"description":"ISO 8601 time."},"created_at":{"type":["string","null"],"description":"ISO 8601 time."}},"required":["id","external_id","email","name","attributes","last_seen_at","created_at"]},"CustomerDetail":{"type":"object","properties":{"id":{"type":"string","description":"Customer id."},"external_id":{"type":["string","null"],"description":"Your own id for the customer, when identified."},"email":{"type":["string","null"],"description":"Email address."},"name":{"type":["string","null"],"description":"Name."},"attributes":{"type":"object","description":"Custom attributes.","properties":{},"additionalProperties":true},"last_seen_at":{"type":["string","null"],"description":"ISO 8601 time."},"created_at":{"type":["string","null"],"description":"ISO 8601 time."},"conversation_count":{"type":"integer","description":"Conversations this customer has had."}},"required":["id","external_id","email","name","attributes","last_seen_at","created_at","conversation_count"]},"Collection":{"type":"object","properties":{"id":{"type":"string","description":"Collection id."},"slug":{"type":"string","description":"Slug."},"name":{"type":"string","description":"Name."},"article_count":{"type":"integer","description":"All articles."},"published_article_count":{"type":"integer","description":"Published articles."}},"required":["id","slug","name","article_count","published_article_count"]},"Article":{"type":"object","properties":{"id":{"type":"string","description":"Article id."},"slug":{"type":"string","description":"Address slug."},"title":{"type":"string","description":"Title."},"status":{"type":"string","description":"draft or published.","enum":["draft","published"]},"collection":{"type":["object","null"],"properties":{"id":{"type":"string","description":"Collection id."},"slug":{"type":"string","description":"Collection slug."},"name":{"type":"string","description":"Collection name."}},"required":["id","slug","name"]},"description":{"type":"string","description":"SEO description, or the start of the body."},"helpful_count":{"type":"integer","description":"Readers who rated it helpful."},"not_helpful_count":{"type":"integer","description":"Readers who rated it not helpful."},"published_at":{"type":["string","null"],"description":"ISO 8601 time."},"created_at":{"type":["string","null"],"description":"ISO 8601 time."},"updated_at":{"type":["string","null"],"description":"ISO 8601 time."}},"required":["id","slug","title","status","collection","description","helpful_count","not_helpful_count","published_at","created_at","updated_at"]},"ArticleDetail":{"type":"object","properties":{"id":{"type":"string","description":"Article id."},"slug":{"type":"string","description":"Address slug."},"title":{"type":"string","description":"Title."},"status":{"type":"string","description":"draft or published.","enum":["draft","published"]},"collection":{"type":["object","null"],"properties":{"id":{"type":"string","description":"Collection id."},"slug":{"type":"string","description":"Collection slug."},"name":{"type":"string","description":"Collection name."}},"required":["id","slug","name"]},"description":{"type":"string","description":"SEO description, or the start of the body."},"helpful_count":{"type":"integer","description":"Readers who rated it helpful."},"not_helpful_count":{"type":"integer","description":"Readers who rated it not helpful."},"published_at":{"type":["string","null"],"description":"ISO 8601 time."},"created_at":{"type":["string","null"],"description":"ISO 8601 time."},"updated_at":{"type":["string","null"],"description":"ISO 8601 time."},"body":{"type":"string","description":"Markdown body."}},"required":["id","slug","title","status","collection","description","helpful_count","not_helpful_count","published_at","created_at","updated_at","body"]},"Board":{"type":"object","properties":{"id":{"type":"string","description":"Board id."},"slug":{"type":"string","description":"Slug."},"name":{"type":"string","description":"Name."}},"required":["id","slug","name"]},"FeedbackPost":{"type":"object","properties":{"id":{"type":"string","description":"Post id."},"title":{"type":"string","description":"Title."},"body":{"type":"string","description":"Details."},"status":{"type":"string","description":"Roadmap status.","enum":["open","planned","in_progress","shipped","declined"]},"board_id":{"type":["string","null"],"description":"Board id."},"customer_id":{"type":["string","null"],"description":"Author, when the post came from a customer."},"vote_count":{"type":"integer","description":"Votes."},"source_conversation_id":{"type":["string","null"],"description":"Conversation the post was created from."},"changelog_entry_id":{"type":["string","null"],"description":"Changelog entry that announced it."},"created_at":{"type":["string","null"],"description":"ISO 8601 time."},"updated_at":{"type":["string","null"],"description":"ISO 8601 time."}},"required":["id","title","body","status","board_id","customer_id","vote_count","source_conversation_id","changelog_entry_id","created_at","updated_at"]},"FeedbackPostDetail":{"type":"object","properties":{"id":{"type":"string","description":"Post id."},"title":{"type":"string","description":"Title."},"body":{"type":"string","description":"Details."},"status":{"type":"string","description":"Roadmap status.","enum":["open","planned","in_progress","shipped","declined"]},"board_id":{"type":["string","null"],"description":"Board id."},"customer_id":{"type":["string","null"],"description":"Author, when the post came from a customer."},"vote_count":{"type":"integer","description":"Votes."},"source_conversation_id":{"type":["string","null"],"description":"Conversation the post was created from."},"changelog_entry_id":{"type":["string","null"],"description":"Changelog entry that announced it."},"created_at":{"type":["string","null"],"description":"ISO 8601 time."},"updated_at":{"type":["string","null"],"description":"ISO 8601 time."},"comments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Comment id."},"author_kind":{"type":"string","description":"team or customer.","enum":["team","customer"]},"author_id":{"type":["string","null"],"description":"Team member or customer id."},"body":{"type":"string","description":"Text."},"created_at":{"type":["string","null"],"description":"ISO 8601 time."}},"required":["id","author_kind","author_id","body","created_at"]}}},"required":["id","title","body","status","board_id","customer_id","vote_count","source_conversation_id","changelog_entry_id","created_at","updated_at","comments"]},"ChangelogEntry":{"type":"object","properties":{"id":{"type":"string","description":"Entry id."},"slug":{"type":"string","description":"Address slug."},"title":{"type":"string","description":"Title."},"status":{"type":"string","description":"draft or published.","enum":["draft","published"]},"labels":{"type":"array","items":{"type":"string","description":"Label."}},"published_at":{"type":["string","null"],"description":"ISO 8601 time."},"created_at":{"type":["string","null"],"description":"ISO 8601 time."},"updated_at":{"type":["string","null"],"description":"ISO 8601 time."},"description":{"type":"string","description":"The start of the body."}},"required":["id","slug","title","status","labels","published_at","created_at","updated_at","description"]},"ChangelogEntryDetail":{"type":"object","properties":{"id":{"type":"string","description":"Entry id."},"slug":{"type":"string","description":"Address slug."},"title":{"type":"string","description":"Title."},"status":{"type":"string","description":"draft or published.","enum":["draft","published"]},"labels":{"type":"array","items":{"type":"string","description":"Label."}},"published_at":{"type":["string","null"],"description":"ISO 8601 time."},"created_at":{"type":["string","null"],"description":"ISO 8601 time."},"updated_at":{"type":["string","null"],"description":"ISO 8601 time."},"body":{"type":"string","description":"Markdown body."}},"required":["id","slug","title","status","labels","published_at","created_at","updated_at","body"]},"KnowledgeSource":{"type":"object","properties":{"id":{"type":"string","description":"Source id."},"kind":{"type":"string","description":"upload, url or sitemap.","enum":["upload","url","sitemap"]},"name":{"type":"string","description":"Display name."},"location":{"type":"string","description":"Address or original file name."},"status":{"type":"string","description":"Indexing state.","enum":["pending","indexing","indexed","failed","skipped"]},"error":{"type":["string","null"],"description":"Why it failed, when it did."},"page_count":{"type":"integer","description":"Pages indexed from a site or sitemap."},"size_bytes":{"type":["integer","null"],"description":"File size, for uploads."},"last_synced_at":{"type":["string","null"],"description":"ISO 8601 time."},"created_at":{"type":["string","null"],"description":"ISO 8601 time."}},"required":["id","kind","name","location","status","error","page_count","size_bytes","last_synced_at","created_at"]},"KnowledgeSourceDetail":{"type":"object","properties":{"id":{"type":"string","description":"Source id."},"kind":{"type":"string","description":"upload, url or sitemap.","enum":["upload","url","sitemap"]},"name":{"type":"string","description":"Display name."},"location":{"type":"string","description":"Address or original file name."},"status":{"type":"string","description":"Indexing state.","enum":["pending","indexing","indexed","failed","skipped"]},"error":{"type":["string","null"],"description":"Why it failed, when it did."},"page_count":{"type":"integer","description":"Pages indexed from a site or sitemap."},"size_bytes":{"type":["integer","null"],"description":"File size, for uploads."},"last_synced_at":{"type":["string","null"],"description":"ISO 8601 time."},"created_at":{"type":["string","null"],"description":"ISO 8601 time."},"counts":{"type":"object","description":"Pages of a site by state.","properties":{"pending":{"type":"integer","description":"Pages pending."},"indexing":{"type":"integer","description":"Pages indexing."},"indexed":{"type":"integer","description":"Pages indexed."},"failed":{"type":"integer","description":"Pages failed."},"skipped":{"type":"integer","description":"Pages skipped."}},"required":["pending","indexing","indexed","failed","skipped"]},"issues":{"type":"array","description":"A few pages that failed or were skipped.","items":{"type":"object","properties":{"url":{"type":"string","description":"Page address."},"status":{"type":"string","description":"failed or skipped."},"error":{"type":["string","null"],"description":"Reason."}},"required":["url","status","error"]}}},"required":["id","kind","name","location","status","error","page_count","size_bytes","last_synced_at","created_at","counts","issues"]},"Answer":{"type":"object","properties":{"answer":{"type":"string","description":"The answer, without citation markers."},"citations":{"type":"array","items":{"type":"object","properties":{"title":{"type":["string","null"],"description":"Source title."},"url":{"type":["string","null"],"description":"Source address."},"source_id":{"type":["string","null"],"description":"Knowledge source id."}},"required":["title","url","source_id"]}}},"required":["answer","citations"]},"Credits":{"type":"object","properties":{"balance":{"type":"integer","description":"Credits left."},"granted":{"type":"integer","description":"Credits ever granted."},"spent":{"type":"integer","description":"Credits used."}},"required":["balance","granted","spent"]},"ConversationList":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Conversation id."},"status":{"type":"string","description":"open, snoozed or closed.","enum":["open","snoozed","closed"]},"customer_id":{"type":"string","description":"The customer in the conversation."},"assignee_id":{"type":["string","null"],"description":"Team member the conversation is assigned to, or null."},"handled_by":{"type":"string","description":"ai when the AI agent is handling it, otherwise team.","enum":["ai","team"]},"channel":{"type":"string","description":"Where it started.","enum":["widget","email","api"]},"subject":{"type":["string","null"],"description":"Subject line, when there is one."},"tags":{"type":"array","items":{"type":"string","description":"Tag name."}},"snoozed_until":{"type":["string","null"],"description":"When a snoozed conversation returns to open."},"last_message_at":{"type":["string","null"],"description":"Time of the latest message."},"created_at":{"type":["string","null"],"description":"ISO 8601 time."},"updated_at":{"type":["string","null"],"description":"ISO 8601 time."}},"required":["id","status","customer_id","assignee_id","handled_by","channel","subject","tags","snoozed_until","last_message_at","created_at","updated_at"]}},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page, or null on the last page."},"has_more":{"type":"boolean","description":"True when another page exists."}},"required":["data","next_cursor","has_more"]},"MessageList":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Message id."},"conversation_id":{"type":"string","description":"Conversation id."},"type":{"type":"string","description":"reply is visible to the customer, note is internal.","enum":["reply","note"]},"sender":{"type":"string","description":"Who wrote it.","enum":["customer","agent","ai"]},"author_id":{"type":["string","null"],"description":"Team member or customer id; null for the AI agent."},"body":{"type":"string","description":"Message text."},"citations":{"type":"array","description":"Sources the AI agent used.","items":{"type":"object","properties":{"title":{"type":["string","null"],"description":"Source title."},"url":{"type":["string","null"],"description":"Source address."}},"required":["title","url"]}},"created_at":{"type":["string","null"],"description":"ISO 8601 time."}},"required":["id","conversation_id","type","sender","author_id","body","citations","created_at"]}},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page, or null on the last page."},"has_more":{"type":"boolean","description":"True when another page exists."}},"required":["data","next_cursor","has_more"]},"CustomerList":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Customer id."},"external_id":{"type":["string","null"],"description":"Your own id for the customer, when identified."},"email":{"type":["string","null"],"description":"Email address."},"name":{"type":["string","null"],"description":"Name."},"attributes":{"type":"object","description":"Custom attributes.","properties":{},"additionalProperties":true},"last_seen_at":{"type":["string","null"],"description":"ISO 8601 time."},"created_at":{"type":["string","null"],"description":"ISO 8601 time."}},"required":["id","external_id","email","name","attributes","last_seen_at","created_at"]}},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page, or null on the last page."},"has_more":{"type":"boolean","description":"True when another page exists."}},"required":["data","next_cursor","has_more"]},"CollectionList":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Collection id."},"slug":{"type":"string","description":"Slug."},"name":{"type":"string","description":"Name."},"article_count":{"type":"integer","description":"All articles."},"published_article_count":{"type":"integer","description":"Published articles."}},"required":["id","slug","name","article_count","published_article_count"]}},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page, or null on the last page."},"has_more":{"type":"boolean","description":"True when another page exists."}},"required":["data","next_cursor","has_more"]},"ArticleList":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Article id."},"slug":{"type":"string","description":"Address slug."},"title":{"type":"string","description":"Title."},"status":{"type":"string","description":"draft or published.","enum":["draft","published"]},"collection":{"type":["object","null"],"properties":{"id":{"type":"string","description":"Collection id."},"slug":{"type":"string","description":"Collection slug."},"name":{"type":"string","description":"Collection name."}},"required":["id","slug","name"]},"description":{"type":"string","description":"SEO description, or the start of the body."},"helpful_count":{"type":"integer","description":"Readers who rated it helpful."},"not_helpful_count":{"type":"integer","description":"Readers who rated it not helpful."},"published_at":{"type":["string","null"],"description":"ISO 8601 time."},"created_at":{"type":["string","null"],"description":"ISO 8601 time."},"updated_at":{"type":["string","null"],"description":"ISO 8601 time."}},"required":["id","slug","title","status","collection","description","helpful_count","not_helpful_count","published_at","created_at","updated_at"]}},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page, or null on the last page."},"has_more":{"type":"boolean","description":"True when another page exists."}},"required":["data","next_cursor","has_more"]},"BoardList":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Board id."},"slug":{"type":"string","description":"Slug."},"name":{"type":"string","description":"Name."}},"required":["id","slug","name"]}},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page, or null on the last page."},"has_more":{"type":"boolean","description":"True when another page exists."}},"required":["data","next_cursor","has_more"]},"FeedbackPostList":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Post id."},"title":{"type":"string","description":"Title."},"body":{"type":"string","description":"Details."},"status":{"type":"string","description":"Roadmap status.","enum":["open","planned","in_progress","shipped","declined"]},"board_id":{"type":["string","null"],"description":"Board id."},"customer_id":{"type":["string","null"],"description":"Author, when the post came from a customer."},"vote_count":{"type":"integer","description":"Votes."},"source_conversation_id":{"type":["string","null"],"description":"Conversation the post was created from."},"changelog_entry_id":{"type":["string","null"],"description":"Changelog entry that announced it."},"created_at":{"type":["string","null"],"description":"ISO 8601 time."},"updated_at":{"type":["string","null"],"description":"ISO 8601 time."}},"required":["id","title","body","status","board_id","customer_id","vote_count","source_conversation_id","changelog_entry_id","created_at","updated_at"]}},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page, or null on the last page."},"has_more":{"type":"boolean","description":"True when another page exists."}},"required":["data","next_cursor","has_more"]},"ChangelogEntryList":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Entry id."},"slug":{"type":"string","description":"Address slug."},"title":{"type":"string","description":"Title."},"status":{"type":"string","description":"draft or published.","enum":["draft","published"]},"labels":{"type":"array","items":{"type":"string","description":"Label."}},"published_at":{"type":["string","null"],"description":"ISO 8601 time."},"created_at":{"type":["string","null"],"description":"ISO 8601 time."},"updated_at":{"type":["string","null"],"description":"ISO 8601 time."},"description":{"type":"string","description":"The start of the body."}},"required":["id","slug","title","status","labels","published_at","created_at","updated_at","description"]}},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page, or null on the last page."},"has_more":{"type":"boolean","description":"True when another page exists."}},"required":["data","next_cursor","has_more"]},"KnowledgeSourceList":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Source id."},"kind":{"type":"string","description":"upload, url or sitemap.","enum":["upload","url","sitemap"]},"name":{"type":"string","description":"Display name."},"location":{"type":"string","description":"Address or original file name."},"status":{"type":"string","description":"Indexing state.","enum":["pending","indexing","indexed","failed","skipped"]},"error":{"type":["string","null"],"description":"Why it failed, when it did."},"page_count":{"type":"integer","description":"Pages indexed from a site or sitemap."},"size_bytes":{"type":["integer","null"],"description":"File size, for uploads."},"last_synced_at":{"type":["string","null"],"description":"ISO 8601 time."},"created_at":{"type":["string","null"],"description":"ISO 8601 time."}},"required":["id","kind","name","location","status","error","page_count","size_bytes","last_synced_at","created_at"]}},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page, or null on the last page."},"has_more":{"type":"boolean","description":"True when another page exists."}},"required":["data","next_cursor","has_more"]}},"responses":{"Error401":{"description":"The API key is missing, invalid, revoked or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Error403":{"description":"The key lacks the scope this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Error404":{"description":"Not found, or the part of the workspace is switched off.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Error422":{"description":"The request failed validation. `error.fields` names the fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Error429":{"description":"Too many requests. Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}