{"openapi":"3.1.0","servers":[{"url":"https://api.theymes.com/v2"}],"info":{"title":"Theymes API v2","version":"2.0.0","description":"Theymes API allows you to interact with the Theymes platform.\n\n\nMost endpoints require an API key for authentication. You can generate an API key in the Theymes dashboard.\n\n\nThe API key should be included in the Authorization header (```Authorization: Bearer <YOUR_KEY>```).\n\n\nThe public support link endpoints do not require authentication and are grouped separately below."},"tags":[{"name":"Authenticated endpoints (API key)","description":"Endpoints that require an API key in the Authorization header."},{"name":"Public support links (no authentication)","description":"Endpoints for creating web support sessions and links. These require no authentication and are identified by an app environment token."}],"components":{"schemas":{"StatsMetric":{"type":"object","properties":{"type":{"type":"string","enum":["CSAT","CSAT_TOP_TWO_BOX_RATE","CSAT_RESPONSE_RATE","CREATED_TICKETS","CLOSED_TICKETS","RESOLVED_TICKETS","REJECTED_TICKETS","AUTO_CLOSED_TICKETS","MERGED_TICKETS","ASSIGNED_TICKETS","REPLIED_TICKETS","PUBLIC_ACTIVITY_TICKETS","ANY_ACTIVITY_TICKETS","OPEN_TICKETS","AGENT_MESSAGES","AUTOMATIC_MESSAGES_PER_TICKET","OUTGOING_MESSAGES_PER_TICKET","CUSTOMER_MESSAGES","TIME_TO_FIRST_RESPONSE","TIME_TO_CLOSE","TIME_TO_RESPONSE_FROM_EARLIEST_MSG","TIME_TO_RESPONSE_FROM_LATEST_MSG","BACKLOG_WAIT_TIME","ARTICLE_DEFLECTION_RATE","DEFLECTION_RATE","ARTICLE_VIEWS","ARTICLE_REFERENCED_IN_RAG","ARTICLE_HELPED_YES","ARTICLE_HELPED_NO","ROLLING_RETENTION_1_DAY","ROLLING_RETENTION_3_DAYS","ROLLING_RETENTION_7_DAYS","ROLLING_RETENTION_14_DAYS","ROLLING_RETENTION_30_DAYS","AVAILABLE_AGENTS","UNAVAILABLE_AGENTS","REOPENED_TICKETS","REOPEN_RATE","TIME_TO_RESPONSE_FROM_ASSIGN","PENDING_TIME_FROM_ASSIGN","FCR","FCR_RATE","RESOLUTION_ACCEPTANCE_RATIO","CPH","APH","AGENT_MESSAGES_PER_HOUR","AGENT_ONLINE_TIME"],"description":"Metric to calculate."},"filters":{"type":"array","items":{"$ref":"#/components/schemas/StatsFilter"},"title":"StatsFilter","description":"Filters applied to this metric only, in addition to the shared filters."}},"required":["type"]},"StatsFilter":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["ticketId"]},"op":{"type":"string","enum":["include-all","include-any","exclude-all","exclude-any"]},"value":{"type":"array","items":{"type":"string"}}},"required":["type","op","value"],"title":"ticketId"},{"type":"object","properties":{"type":{"type":"string","enum":["app"]},"op":{"type":"string","enum":["is","is-not"],"description":"`is` matches any listed value. `is-not` matches none of them."},"value":{"type":"array","items":{"type":"string"},"description":"Ids to match."}},"required":["type","op","value"],"title":"app"},{"type":"object","properties":{"type":{"type":"string","enum":["team"]},"op":{"type":"string","enum":["is","is-not"],"description":"`is` matches any listed value. `is-not` matches none of them."},"value":{"type":"array","items":{"type":"string"},"description":"Ids to match."}},"required":["type","op","value"],"title":"team"},{"type":"object","properties":{"type":{"type":"string","enum":["theymesCustomerId"]},"op":{"type":"string","enum":["is","is-not"],"description":"`is` matches any listed value. `is-not` matches none of them."},"value":{"type":"array","items":{"type":"string"},"description":"Ids to match."}},"required":["type","op","value"],"title":"theymesCustomerId"},{"type":"object","properties":{"type":{"type":"string","enum":["status"]},"op":{"type":"string","enum":["is","is-not"],"description":"`is` matches any listed value. `is-not` matches none of them."},"value":{"type":"array","items":{"type":"string","enum":["new","assigned","unassigned","waiting","on_hold","closed"]}}},"required":["type","op","value"],"title":"status"},{"type":"object","properties":{"type":{"type":"string","enum":["category"]},"op":{"type":"string","enum":["is","is-not"],"description":"`is` matches any listed value. `is-not` matches none of them."},"value":{"type":"array","items":{"type":"string"},"description":"Ids to match."}},"required":["type","op","value"],"title":"category"},{"type":"object","properties":{"type":{"type":"string","enum":["subCategory"]},"op":{"type":"string","enum":["is","is-not"],"description":"`is` matches any listed value. `is-not` matches none of them."},"value":{"type":"array","items":{"type":"string"},"description":"Ids to match."}},"required":["type","op","value"],"title":"subCategory"},{"type":"object","properties":{"type":{"type":"string","enum":["article"]},"op":{"type":"string","enum":["is","is-not"],"description":"`is` matches any listed value. `is-not` matches none of them."},"value":{"type":"array","items":{"type":"string"},"description":"Ids to match."}},"required":["type","op","value"],"title":"article"},{"type":"object","properties":{"type":{"type":"string","enum":["assignee"]},"op":{"type":"string","enum":["is","is-not"],"description":"`is` matches any listed value. `is-not` matches none of them."},"value":{"type":"array","items":{"type":"string","format":"uuid"},"description":"User ids."}},"required":["type","op","value"],"title":"assignee"},{"type":"object","properties":{"type":{"type":"string","enum":["latestAssignee"]},"op":{"type":"string","enum":["is","is-not"],"description":"`is` matches any listed value. `is-not` matches none of them."},"value":{"type":"array","items":{"type":"string","format":"uuid"},"description":"User ids."}},"required":["type","op","value"],"title":"latestAssignee"},{"type":"object","properties":{"type":{"type":"string","enum":["language"]},"op":{"type":"string","enum":["is","is-not"],"description":"`is` matches any listed value. `is-not` matches none of them."},"value":{"type":"array","items":{"type":"string","enum":["en","de","es","es-AR","es-MX","fi","fil","fr","id","ja","ko","ms","pt","pt-BR","ru","tr","uk","vi","zh","zh-Hans","zh-Hant","ar","cs","da","nl","el","hu","it","no","nb","pl","ro","sk","sv","th"]}}},"required":["type","op","value"],"title":"language"},{"type":"object","properties":{"type":{"type":"string","enum":["platform"]},"op":{"type":"string","enum":["is","is-not"],"description":"`is` matches any listed value. `is-not` matches none of them."},"value":{"type":"array","items":{"type":"string","enum":["ios","android","win","macos","linux","web","widget","discord","email","messenger","api","started_by_agent","playstation_4","playstation_5","switch","switch_2","xbox_series","xbox_one","not_specified"]}}},"required":["type","op","value"],"title":"platform"},{"type":"object","properties":{"type":{"type":"string","enum":["supportSource"]},"op":{"type":"string","enum":["is","is-not"],"description":"`is` matches any listed value. `is-not` matches none of them."},"value":{"type":"array","items":{"type":"string","enum":["IN_APP","WIDGET","EMAIL","MESSENGER","WEB","API","STARTED_BY_AGENT","TEST_GENERATED","MIGRATED"]}}},"required":["type","op","value"],"title":"supportSource"},{"type":"object","properties":{"type":{"type":"string","enum":["channel"]},"op":{"type":"string","enum":["is","is-not"],"description":"`is` matches any listed value. `is-not` matches none of them."},"value":{"type":"array","items":{"type":"string","enum":["chat","email","messenger"]}}},"required":["type","op","value"],"title":"channel"},{"type":"object","properties":{"type":{"type":"string","enum":["csat"]},"op":{"type":"string","enum":["is","is-not"],"description":"`is` matches any listed value. `is-not` matches none of them."},"value":{"type":"array","items":{"type":"integer","minimum":1,"maximum":5}}},"required":["type","op","value"],"title":"csat"},{"type":"object","properties":{"type":{"type":"string","enum":["csat"]},"op":{"type":"string","enum":["is-set"]},"value":{"type":"null"}},"required":["type","op","value"],"title":"csatIsSet"},{"type":"object","properties":{"type":{"type":"string","enum":["csat"]},"op":{"type":"string","enum":["is-not-set"]},"value":{"type":"null"}},"required":["type","op","value"],"title":"csatIsNotSet"},{"type":"object","properties":{"type":{"type":"string","enum":["similarTicketIssue"]},"op":{"type":"string","enum":["is","is-not"],"description":"`is` matches any listed value. `is-not` matches none of them."},"value":{"type":"array","items":{"type":"string"},"description":"Ids to match."}},"required":["type","op","value"],"title":"similarTicketIssue"},{"type":"object","properties":{"type":{"type":"string","enum":["similarTicketIssue"]},"op":{"type":"string","enum":["is-set"]},"value":{"type":"null"}},"required":["type","op","value"],"title":"similarTicketIssueIsSet"},{"type":"object","properties":{"type":{"type":"string","enum":["similarTicketIssue"]},"op":{"type":"string","enum":["is-not-set"]},"value":{"type":"null"}},"required":["type","op","value"],"title":"similarTicketIssueIsNotSet"},{"type":"object","properties":{"type":{"type":"string","enum":["tag"]},"op":{"type":"string","enum":["include-all","include-any","exclude-all","exclude-any"]},"value":{"type":"array","items":{"type":"string"}}},"required":["type","op","value"],"title":"tag"},{"type":"object","properties":{"type":{"type":"string","enum":["tag"]},"op":{"type":"string","enum":["is-set"]},"value":{"type":"null"}},"required":["type","op","value"],"title":"tagIsSet"},{"type":"object","properties":{"type":{"type":"string","enum":["tag"]},"op":{"type":"string","enum":["is-not-set"]},"value":{"type":"null"}},"required":["type","op","value"],"title":"tagIsNotSet"},{"type":"object","properties":{"type":{"type":"string","enum":["field"]},"fieldType":{"type":"string","enum":["boolean","date","dropdown","number","text"]},"fieldKey":{"type":"string"},"op":{"type":"string","enum":["include-all","include-any","exclude-all","exclude-any","contains","not-contains","before","after","between","greater-than","less-than","is","is-not","is-set","is-not-set"]},"value":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"string"},{"type":"object","properties":{"type":{"type":"string","enum":["date"]},"date":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["1_HOUR_AGO","3_HOUR_AGO","6_HOUR_AGO","12_HOUR_AGO","1_DAY_AGO","2_DAYS_AGO","3_DAYS_AGO","7_DAYS_AGO","14_DAYS_AGO","30_DAYS_AGO","365_DAYS_AGO"]}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["CUSTOM"]},"date":{"type":"string","format":"date"}},"required":["type","date"]}]}},"required":["type","date"]},{"type":"object","properties":{"type":{"type":"string","enum":["date-range"]},"from":{"type":"object","properties":{"type":{"type":"string","enum":["CUSTOM"]},"date":{"type":"string","format":"date"}},"required":["type","date"]},"to":{"type":"object","properties":{"type":{"type":"string","enum":["CUSTOM"]},"date":{"type":"string","format":"date"}},"required":["type","date"]}},"required":["type","from","to"]},{"type":"number"},{"type":"object","properties":{"type":{"type":"string","enum":["number-range"]},"min":{"type":"number"},"max":{"type":"number"}},"required":["type","min","max"]},{"type":"boolean"}]}},"required":["type","fieldType","fieldKey","op","value"],"title":"field"},{"type":"object","properties":{"type":{"type":"string","enum":["customerTier"]},"op":{"type":"string","enum":["is","is-not"],"description":"`is` matches any listed value. `is-not` matches none of them."},"value":{"type":"array","items":{"type":"integer","minimum":0,"maximum":3}}},"required":["type","op","value"],"title":"customerTier"},{"type":"object","properties":{"type":{"type":"string","enum":["reopenStatus"]},"op":{"type":"string","enum":["is","is-not"],"description":"`is` matches any listed value. `is-not` matches none of them."},"value":{"type":"array","items":{"type":"string","enum":["reopened","reopen_follow_up","not_reopened"]}}},"required":["type","op","value"],"title":"reopenStatus"},{"type":"object","properties":{"type":{"type":"string","enum":["resolutionType"]},"op":{"type":"string","enum":["is","is-not"],"description":"`is` matches any listed value. `is-not` matches none of them."},"value":{"type":"array","items":{"type":"string","enum":["resolved","rejected","auto_closed","merged"]}}},"required":["type","op","value"],"title":"resolutionType"},{"type":"object","properties":{"type":{"type":"string","enum":["messageSource"]},"op":{"type":"string","enum":["is","is-not"],"description":"`is` matches any listed value. `is-not` matches none of them."},"value":{"type":"array","items":{"type":"string","enum":["AGENT","AUTOMATIC","CUSTOMER"]}}},"required":["type","op","value"],"title":"messageSource"},{"type":"object","properties":{"type":{"type":"string","enum":["appVersion"]},"op":{"type":"string","enum":["is","is-not"],"description":"`is` matches any listed value. `is-not` matches none of them."},"value":{"type":"array","items":{"type":"string"},"description":"Ids to match."}},"required":["type","op","value"],"title":"appVersion"},{"type":"object","properties":{"type":{"type":"string","enum":["ticketReopened"]},"op":{"type":"string","enum":["is"]},"value":{"type":"boolean"}},"required":["type","op","value"],"title":"ticketReopened"},{"type":"object","properties":{"type":{"type":"string","enum":["hasCsatReview"]},"op":{"type":"string","enum":["is"]},"value":{"type":"boolean"}},"required":["type","op","value"],"title":"hasCsatReview"},{"type":"object","properties":{"type":{"type":"string","enum":["hasBeenAssistedByTheAssistant"]},"op":{"type":"string","enum":["is"]},"value":{"type":"boolean"}},"required":["type","op","value"],"title":"hasBeenAssistedByTheAssistant"},{"type":"object","properties":{"type":{"type":"string","enum":["csatSurveySent"]},"op":{"type":"string","enum":["is"]},"value":{"type":"boolean"}},"required":["type","op","value"],"title":"csatSurveySent"},{"type":"object","properties":{"type":{"type":"string","enum":["assigned"]},"op":{"type":"string","enum":["is"]},"value":{"type":"boolean"}},"required":["type","op","value"],"title":"assigned"},{"type":"object","properties":{"op":{"type":"string","enum":["greater-than","less-than","between"]},"value":{"anyOf":[{"type":"number"},{"type":"object","properties":{"type":{"type":"string","enum":["number-range"]},"min":{"type":"number"},"max":{"type":"number"}},"required":["type","min","max"]}]},"type":{"type":"string","enum":["backlogWaitTime"]}},"required":["op","value","type"],"title":"backlogWaitTime"},{"type":"object","properties":{"op":{"type":"string","enum":["greater-than","less-than","between"]},"value":{"anyOf":[{"type":"number"},{"type":"object","properties":{"type":{"type":"string","enum":["number-range"]},"min":{"type":"number"},"max":{"type":"number"}},"required":["type","min","max"]}]},"type":{"type":"string","enum":["firstResponseTime"]}},"required":["op","value","type"],"title":"firstResponseTime"},{"type":"object","properties":{"op":{"type":"string","enum":["greater-than","less-than","between"]},"value":{"anyOf":[{"type":"number"},{"type":"object","properties":{"type":{"type":"string","enum":["number-range"]},"min":{"type":"number"},"max":{"type":"number"}},"required":["type","min","max"]}]},"type":{"type":"string","enum":["agentMessageCount"]}},"required":["op","value","type"],"title":"agentMessageCount"},{"type":"object","properties":{"op":{"type":"string","enum":["greater-than","less-than","between"]},"value":{"anyOf":[{"type":"number"},{"type":"object","properties":{"type":{"type":"string","enum":["number-range"]},"min":{"type":"number"},"max":{"type":"number"}},"required":["type","min","max"]}]},"type":{"type":"string","enum":["customerMessageCount"]}},"required":["op","value","type"],"title":"customerMessageCount"},{"type":"object","properties":{"type":{"type":"string","enum":["bulkAction"]},"op":{"type":"string","enum":["is"]},"value":{"type":"boolean"}},"required":["type","op","value"],"title":"bulkAction"}],"description":"Limits which tickets count toward the stat.\n\nNote on the `field` filter: it uses operators based on its field type. Dropdowns use `include-any`, `include-all`, `exclude-any`, and `exclude-all`. Text uses `is`, `is-not`, `contains`, and `not-contains`. Numbers use `is`, `is-not`, `greater-than`, `less-than`, and `between`. Dates use `before`, `after`, and `between`. Boolean fields use `is` with `true` or `false`. Every field type also accepts `is-set` and `is-not-set`."},"StatsTimeframe":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["TODAY"]}},"required":["type"],"title":"Today"},{"type":"object","properties":{"type":{"type":"string","enum":["PAST_7_DAYS"]}},"required":["type"],"title":"Past 7 days"},{"type":"object","properties":{"type":{"type":"string","enum":["PAST_30_DAYS"]}},"required":["type"],"title":"Past 30 days"},{"type":"object","properties":{"type":{"type":"string","enum":["PAST_90_DAYS"]}},"required":["type"],"title":"Past 90 days"},{"type":"object","properties":{"type":{"type":"string","enum":["PAST_365_DAYS"]}},"required":["type"],"title":"Past 365 days"},{"type":"object","properties":{"type":{"type":"string","enum":["CUSTOM"]},"from":{"anyOf":[{"type":"string","format":"date"},{"type":"object","properties":{"date":{"type":"string","format":"date"},"hours":{"type":"integer","minimum":0,"maximum":23,"description":"Hour of the day, 0-23."}},"required":["date","hours"]}],"description":"Inclusive start. A date, or a date plus an hour."},"to":{"anyOf":[{"type":"string","format":"date"},{"type":"object","properties":{"date":{"type":"string","format":"date"},"hours":{"type":"integer","minimum":0,"maximum":23,"description":"Hour of the day, 0-23."}},"required":["date","hours"]}],"description":"End. A date, or a date plus an hour."}},"required":["type","from","to"],"title":"Custom"}],"description":"Time range for the query. Preset ranges include the current day."},"StatsBreakdown":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["TICKET_ID","ASSIGNEE","AGENT","ARTICLE","CHANNEL","CSAT","APP","LANGUAGE","PLATFORM","SUPPORT_SOURCE","STATUS","RESOLUTION_TYPE","CUSTOMER_TIER","TIME_TO_FIRST_RESPONSE_BUCKET","BACKLOG_WAIT_TIME_BUCKET","AVERAGE_TIME_TO_RESPONSE_FROM_EARLIEST_MSG_BUCKET","TIME_TO_RESOLUTION_BUCKET","TAG","TEAM","SKILL","TIME_HOUR","TIME_DAY","TIME_WEEK","TIME_WEEKDAY","TIME_MONTH","TIME_YEAR"]}},"required":["type"],"title":"Other dimensions"},{"type":"object","properties":{"type":{"type":"string","enum":["FIELD"]},"fieldKey":{"type":"string","description":"Custom field key."},"fieldType":{"type":"string","enum":["text","date","boolean","dropdown","number"]}},"required":["type","fieldKey","fieldType"],"title":"Field dimension"}],"description":"One breakdown or segment. FIELD also requires fieldKey and fieldType."}},"parameters":{}},"paths":{"/announcements":{"get":{"operationId":"getAnnouncements","summary":"List announcements","tags":["Authenticated endpoints (API key)"],"description":"List explicitly configured shared and app announcements. Shared announcements have appId null. Excludes environment overrides and deleted apps; inherited announcements are not duplicated. Ordered shared first, then by app ID.","parameters":[{"schema":{"type":"string","description":"Bearer token API key"},"required":true,"description":"Bearer token API key","name":"Authorization","in":"header"}],"responses":{"200":{"description":"Configured announcements, or an empty list","content":{"application/json":{"schema":{"type":"object","properties":{"announcements":{"type":"array","items":{"type":"object","properties":{"shortContent":{"type":"object","properties":{"en":{"type":["string","null"]},"de":{"type":["string","null"]},"es":{"type":["string","null"]},"es-AR":{"type":["string","null"]},"es-MX":{"type":["string","null"]},"fi":{"type":["string","null"]},"fil":{"type":["string","null"]},"fr":{"type":["string","null"]},"id":{"type":["string","null"]},"ja":{"type":["string","null"]},"ko":{"type":["string","null"]},"ms":{"type":["string","null"]},"pt":{"type":["string","null"]},"pt-BR":{"type":["string","null"]},"ru":{"type":["string","null"]},"tr":{"type":["string","null"]},"uk":{"type":["string","null"]},"vi":{"type":["string","null"]},"zh":{"type":["string","null"]},"zh-Hans":{"type":["string","null"]},"zh-Hant":{"type":["string","null"]},"ar":{"type":["string","null"]},"cs":{"type":["string","null"]},"da":{"type":["string","null"]},"nl":{"type":["string","null"]},"el":{"type":["string","null"]},"hu":{"type":["string","null"]},"it":{"type":["string","null"]},"no":{"type":["string","null"]},"nb":{"type":["string","null"]},"pl":{"type":["string","null"]},"ro":{"type":["string","null"]},"sk":{"type":["string","null"]},"sv":{"type":["string","null"]},"th":{"type":["string","null"]}}},"longContent":{"type":"object","properties":{"en":{"type":["string","null"]},"de":{"type":["string","null"]},"es":{"type":["string","null"]},"es-AR":{"type":["string","null"]},"es-MX":{"type":["string","null"]},"fi":{"type":["string","null"]},"fil":{"type":["string","null"]},"fr":{"type":["string","null"]},"id":{"type":["string","null"]},"ja":{"type":["string","null"]},"ko":{"type":["string","null"]},"ms":{"type":["string","null"]},"pt":{"type":["string","null"]},"pt-BR":{"type":["string","null"]},"ru":{"type":["string","null"]},"tr":{"type":["string","null"]},"uk":{"type":["string","null"]},"vi":{"type":["string","null"]},"zh":{"type":["string","null"]},"zh-Hans":{"type":["string","null"]},"zh-Hant":{"type":["string","null"]},"ar":{"type":["string","null"]},"cs":{"type":["string","null"]},"da":{"type":["string","null"]},"nl":{"type":["string","null"]},"el":{"type":["string","null"]},"hu":{"type":["string","null"]},"it":{"type":["string","null"]},"no":{"type":["string","null"]},"nb":{"type":["string","null"]},"pl":{"type":["string","null"]},"ro":{"type":["string","null"]},"sk":{"type":["string","null"]},"sv":{"type":["string","null"]},"th":{"type":["string","null"]}}},"appId":{"type":["string","null"],"format":"uuid"}},"required":["shortContent","longContent","appId"]}}},"required":["announcements"]}}}},"403":{"description":"API key authentication required"}}},"put":{"operationId":"setAnnouncement","summary":"Set an announcement","tags":["Authenticated endpoints (API key)"],"description":"Create or fully replace one announcement. appId is required: null selects shared scope, an app UUID selects app scope. shortContent is localized plain text and must be nonblank in the primary language configured in your account. longContent is localized Markdown; null or an empty object clears details and is returned as an empty object. Both localization maps are replaced, removing omitted translations. Changes use the existing announcement display and inheritance behavior.","parameters":[{"schema":{"type":"string","description":"Bearer token API key"},"required":true,"description":"Bearer token API key","name":"Authorization","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"shortContent":{"type":"object","properties":{"en":{"type":["string","null"]},"de":{"type":["string","null"]},"es":{"type":["string","null"]},"es-AR":{"type":["string","null"]},"es-MX":{"type":["string","null"]},"fi":{"type":["string","null"]},"fil":{"type":["string","null"]},"fr":{"type":["string","null"]},"id":{"type":["string","null"]},"ja":{"type":["string","null"]},"ko":{"type":["string","null"]},"ms":{"type":["string","null"]},"pt":{"type":["string","null"]},"pt-BR":{"type":["string","null"]},"ru":{"type":["string","null"]},"tr":{"type":["string","null"]},"uk":{"type":["string","null"]},"vi":{"type":["string","null"]},"zh":{"type":["string","null"]},"zh-Hans":{"type":["string","null"]},"zh-Hant":{"type":["string","null"]},"ar":{"type":["string","null"]},"cs":{"type":["string","null"]},"da":{"type":["string","null"]},"nl":{"type":["string","null"]},"el":{"type":["string","null"]},"hu":{"type":["string","null"]},"it":{"type":["string","null"]},"no":{"type":["string","null"]},"nb":{"type":["string","null"]},"pl":{"type":["string","null"]},"ro":{"type":["string","null"]},"sk":{"type":["string","null"]},"sv":{"type":["string","null"]},"th":{"type":["string","null"]}}},"longContent":{"type":["object","null"],"properties":{"en":{"type":["string","null"]},"de":{"type":["string","null"]},"es":{"type":["string","null"]},"es-AR":{"type":["string","null"]},"es-MX":{"type":["string","null"]},"fi":{"type":["string","null"]},"fil":{"type":["string","null"]},"fr":{"type":["string","null"]},"id":{"type":["string","null"]},"ja":{"type":["string","null"]},"ko":{"type":["string","null"]},"ms":{"type":["string","null"]},"pt":{"type":["string","null"]},"pt-BR":{"type":["string","null"]},"ru":{"type":["string","null"]},"tr":{"type":["string","null"]},"uk":{"type":["string","null"]},"vi":{"type":["string","null"]},"zh":{"type":["string","null"]},"zh-Hans":{"type":["string","null"]},"zh-Hant":{"type":["string","null"]},"ar":{"type":["string","null"]},"cs":{"type":["string","null"]},"da":{"type":["string","null"]},"nl":{"type":["string","null"]},"el":{"type":["string","null"]},"hu":{"type":["string","null"]},"it":{"type":["string","null"]},"no":{"type":["string","null"]},"nb":{"type":["string","null"]},"pl":{"type":["string","null"]},"ro":{"type":["string","null"]},"sk":{"type":["string","null"]},"sv":{"type":["string","null"]},"th":{"type":["string","null"]}}},"appId":{"type":["string","null"],"format":"uuid"}},"required":["shortContent","longContent","appId"]}}}},"responses":{"200":{"description":"The saved announcement","content":{"application/json":{"schema":{"type":"object","properties":{"announcement":{"type":"object","properties":{"shortContent":{"type":"object","properties":{"en":{"type":["string","null"]},"de":{"type":["string","null"]},"es":{"type":["string","null"]},"es-AR":{"type":["string","null"]},"es-MX":{"type":["string","null"]},"fi":{"type":["string","null"]},"fil":{"type":["string","null"]},"fr":{"type":["string","null"]},"id":{"type":["string","null"]},"ja":{"type":["string","null"]},"ko":{"type":["string","null"]},"ms":{"type":["string","null"]},"pt":{"type":["string","null"]},"pt-BR":{"type":["string","null"]},"ru":{"type":["string","null"]},"tr":{"type":["string","null"]},"uk":{"type":["string","null"]},"vi":{"type":["string","null"]},"zh":{"type":["string","null"]},"zh-Hans":{"type":["string","null"]},"zh-Hant":{"type":["string","null"]},"ar":{"type":["string","null"]},"cs":{"type":["string","null"]},"da":{"type":["string","null"]},"nl":{"type":["string","null"]},"el":{"type":["string","null"]},"hu":{"type":["string","null"]},"it":{"type":["string","null"]},"no":{"type":["string","null"]},"nb":{"type":["string","null"]},"pl":{"type":["string","null"]},"ro":{"type":["string","null"]},"sk":{"type":["string","null"]},"sv":{"type":["string","null"]},"th":{"type":["string","null"]}}},"longContent":{"type":"object","properties":{"en":{"type":["string","null"]},"de":{"type":["string","null"]},"es":{"type":["string","null"]},"es-AR":{"type":["string","null"]},"es-MX":{"type":["string","null"]},"fi":{"type":["string","null"]},"fil":{"type":["string","null"]},"fr":{"type":["string","null"]},"id":{"type":["string","null"]},"ja":{"type":["string","null"]},"ko":{"type":["string","null"]},"ms":{"type":["string","null"]},"pt":{"type":["string","null"]},"pt-BR":{"type":["string","null"]},"ru":{"type":["string","null"]},"tr":{"type":["string","null"]},"uk":{"type":["string","null"]},"vi":{"type":["string","null"]},"zh":{"type":["string","null"]},"zh-Hans":{"type":["string","null"]},"zh-Hant":{"type":["string","null"]},"ar":{"type":["string","null"]},"cs":{"type":["string","null"]},"da":{"type":["string","null"]},"nl":{"type":["string","null"]},"el":{"type":["string","null"]},"hu":{"type":["string","null"]},"it":{"type":["string","null"]},"no":{"type":["string","null"]},"nb":{"type":["string","null"]},"pl":{"type":["string","null"]},"ro":{"type":["string","null"]},"sk":{"type":["string","null"]},"sv":{"type":["string","null"]},"th":{"type":["string","null"]}}},"appId":{"type":["string","null"],"format":"uuid"}},"required":["shortContent","longContent","appId"]}},"required":["announcement"]}}}},"400":{"description":"Invalid input or missing primary-language short content"},"403":{"description":"API key authentication required"},"404":{"description":"App not found"}}},"delete":{"operationId":"clearSharedAnnouncement","summary":"Clear the shared announcement","tags":["Authenticated endpoints (API key)"],"description":"Clear the shared announcement. App and environment overrides are preserved. Succeeds even when no shared announcement is configured.","parameters":[{"schema":{"type":"string","description":"Bearer token API key"},"required":true,"description":"Bearer token API key","name":"Authorization","in":"header"}],"responses":{"200":{"description":"Shared announcement cleared","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]}},"required":["success"]}}}},"403":{"description":"API key authentication required"}}}},"/announcements/{appId}":{"delete":{"operationId":"clearAppAnnouncement","summary":"Clear an app announcement","tags":["Authenticated endpoints (API key)"],"description":"Clear the app announcement, restoring the shared fallback. Environment overrides are preserved. Succeeds even when the app has no configured announcement.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"appId","in":"path"},{"schema":{"type":"string","description":"Bearer token API key"},"required":true,"description":"Bearer token API key","name":"Authorization","in":"header"}],"responses":{"200":{"description":"App announcement cleared","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]}},"required":["success"]}}}},"400":{"description":"Invalid app UUID"},"403":{"description":"API key authentication required"},"404":{"description":"App not found"}}}},"/tickets":{"get":{"operationId":"getTickets","summary":"List tickets","tags":["Authenticated endpoints (API key)"],"description":"List tickets for the company associated with the API key. Filter by identity, scope, status, tags, custom fields, or creation date. Results are paginated; use the returned cursor with the same ordering to fetch the next page.","parameters":[{"schema":{"type":"string"},"required":false,"name":"email","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"ticketId","in":"query"},{"schema":{"type":"string","description":"JSON-encoded array of tag names. A ticket must contain every supplied tag. Example: `[\"vip\",\"billing\"]`."},"required":false,"description":"JSON-encoded array of tag names. A ticket must contain every supplied tag. Example: `[\"vip\",\"billing\"]`.","name":"tags","in":"query"},{"schema":{"type":"string","description":"JSON-encoded object of custom field keys and values. A ticket must match every supplied field; dropdown fields must contain all supplied options. Example: `{\"priority\":[\"high\"],\"escalated\":true}`."},"required":false,"description":"JSON-encoded object of custom field keys and values. A ticket must match every supplied field; dropdown fields must contain all supplied options. Example: `{\"priority\":[\"high\"],\"escalated\":true}`.","name":"fields","in":"query"},{"schema":{"type":"string","description":"JSON-encoded array of ticket statuses. A ticket matches when its status is any of the supplied values. Allowed values: `new`, `assigned`, `unassigned`, `waiting`, `on_hold`, `closed`. Example: `[\"new\",\"waiting\"]`."},"required":false,"description":"JSON-encoded array of ticket statuses. A ticket matches when its status is any of the supplied values. Allowed values: `new`, `assigned`, `unassigned`, `waiting`, `on_hold`, `closed`. Example: `[\"new\",\"waiting\"]`.","name":"status","in":"query"},{"schema":{"type":"string","format":"date","description":"Only return tickets created on or after this date"},"required":false,"description":"Only return tickets created on or after this date","name":"createdAfter","in":"query"},{"schema":{"type":"string","format":"date","description":"Only return tickets created on or before this date"},"required":false,"description":"Only return tickets created on or before this date","name":"createdBefore","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"asc","description":"Sort by ticket creation order, oldest first or newest first"},"required":false,"description":"Sort by ticket creation order, oldest first or newest first","name":"order","in":"query"},{"schema":{"type":"string","description":"Pagination cursor returned from a previous response. Must be used with the same `order` direction it was obtained with. Omit when starting a new scan."},"required":false,"description":"Pagination cursor returned from a previous response. Must be used with the same `order` direction it was obtained with. Omit when starting a new scan.","name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":1000,"default":100},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"appId","in":"query"},{"schema":{"type":"string"},"required":false,"name":"customerId","in":"query"},{"schema":{"type":"string","description":"Bearer token API key"},"required":true,"description":"Bearer token API key","name":"Authorization","in":"header"}],"responses":{"200":{"description":"A list of tickets","content":{"application/json":{"schema":{"type":"object","properties":{"tickets":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"runningId":{"type":"integer","description":"Human-readable running ticket number"},"url":{"type":"string","description":"URL to view the conversation in the support application"},"email":{"type":["string","null"],"description":"Customer email associated with the ticket, when available"},"status":{"type":"string","enum":["new","assigned","unassigned","waiting","on_hold","closed"]},"assigneeId":{"type":["string","null"],"format":"uuid","default":null,"description":"ID of the agent currently assigned to the ticket. Null when the ticket is unassigned."},"assigneeName":{"type":["string","null"],"default":null,"description":"Display name of the agent currently assigned to the ticket. Null when the ticket is unassigned."},"supportSource":{"type":["string","null"],"enum":["IN_APP","WIDGET","EMAIL","MESSENGER","WEB","API","STARTED_BY_AGENT","TEST_GENERATED","MIGRATED",null],"description":"Origin through which the ticket was created"},"channels":{"type":"array","items":{"type":"string","enum":["chat","email","messenger"]}},"language":{"type":"string","enum":["en","de","es","es-AR","es-MX","fi","fil","fr","id","ja","ko","ms","pt","pt-BR","ru","tr","uk","vi","zh","zh-Hans","zh-Hant","ar","cs","da","nl","el","hu","it","no","nb","pl","ro","sk","sv","th"]},"resolutionType":{"type":["string","null"],"enum":["resolved","rejected","auto_closed","merged",null]},"csatScore":{"type":["integer","null"],"minimum":1,"maximum":5},"csatReview":{"type":["string","null"]},"issueSummary":{"type":["string","null"]},"issueResolution":{"type":["string","null"]},"followUpTicketId":{"type":["string","null"],"format":"uuid"},"reopenedFromTicketId":{"type":["string","null"],"format":"uuid"},"createdAt":{"type":"string","format":"date-time"},"lastActivityAt":{"type":["string","null"],"format":"date-time"},"tags":{"type":"array","items":{"type":"string"}},"fields":{"type":"object","additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"array","items":{"type":"string"}},{"type":"boolean"}]},"description":"Custom fields associated with the ticket, keyed by the configured field key"},"metadata":{"type":"object","additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"array","items":{"type":"string"}},{"type":"boolean"}]},"description":"Builtin metadata fields associated with the ticket"},"appId":{"type":"string","format":"uuid"},"appEnvironmentId":{"type":"string","format":"uuid"},"theymesCustomerId":{"type":["string","null"],"format":"uuid","description":"Theymes internal customer ID"},"customerId":{"type":["string","null"],"description":"External customer ID provided by the app, null for email/web tickets"},"customerName":{"type":["string","null"],"description":"Customer name associated with the ticket, when available"}},"required":["id","runningId","url","email","status","supportSource","channels","language","resolutionType","csatScore","csatReview","issueSummary","issueResolution","followUpTicketId","reopenedFromTicketId","createdAt","lastActivityAt","tags","fields","metadata","appId","appEnvironmentId","theymesCustomerId","customerId","customerName"]}},"pagination":{"type":"object","properties":{"cursor":{"type":["string","null"],"description":"Cursor for pagination if more results are available else null"}},"required":["cursor"]}},"required":["tickets","pagination"]}}}}}},"post":{"operationId":"createTicket","summary":"Create a ticket","tags":["Authenticated endpoints (API key)"],"description":"Create a new ticket. To include attachments, call POST /v2/attachments to obtain upload URLs, upload the files, and pass the returned attachment IDs in the `attachments` array.","parameters":[{"schema":{"type":"string","description":"Bearer token API key"},"required":true,"description":"Bearer token API key","name":"Authorization","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"attachments":{"type":"array","items":{"type":"string"},"default":[],"description":"List of attachment IDs returned by POST /v2/attachments after the file upload completes."},"skipDuplicateCheck":{"type":"boolean","default":false,"description":"If true, the duplicate ticket check will be skipped."},"language":{"type":"string","enum":["en","de","es","es-AR","es-MX","fi","fil","fr","id","ja","ko","ms","pt","pt-BR","ru","tr","uk","vi","zh","zh-Hans","zh-Hant","ar","cs","da","nl","el","hu","it","no","nb","pl","ro","sk","sv","th"]},"channels":{"type":"array","items":{"type":"string","enum":["email"]},"minItems":1},"platform":{"type":"string","enum":["ios","android","win","macos","linux","web","playstation_4","playstation_5","switch","switch_2","xbox_series","xbox_one","not_specified"],"default":"not_specified"},"metadata":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"string"},"description":"List of tag names to associate with the ticket"},"fields":{"type":"object","additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"array","items":{"type":"string"}},{"type":"boolean"}]},"description":"Custom fields associated with the ticket, key value where key is the field key as configured in Theymes and value type depends on field configuration"},"customer":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"email":{"type":"string","format":"email"},"tier":{"anyOf":[{"type":"number","enum":[1]},{"type":"number","enum":[2]},{"type":"number","enum":[3]}]}},"required":["email"]}},"required":["customer"]},"appId":{"type":"string","format":"uuid"}},"required":["message","language","channels","metadata","appId"]}}}},"responses":{"200":{"description":"The created ticket","content":{"application/json":{"schema":{"type":"object","properties":{"ticketId":{"type":"string","format":"uuid"},"runningId":{"type":"integer","description":"Human-readable running ticket number"}},"required":["ticketId","runningId"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"type":"object","properties":{"details":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["CUSTOMER_BLOCKED"]}},"required":["type"],"title":"CustomerBlocked","description":"The user is blocked from contacting support"},{"type":"object","properties":{"type":{"type":"string","enum":["DUPLICATE_OPEN_TICKET_DETECTED"]},"payload":{"type":"object","properties":{"duplicateConversationId":{"type":"string","format":"uuid","description":"The ID of the existing similar open ticket"}},"required":["duplicateConversationId"]}},"required":["type","payload"],"title":"DuplicateOpenTicketDetected","description":"The user has already requested a similar open ticket"}]}},"required":["details"]}}}}}}},"/attachments":{"post":{"operationId":"prepareAttachmentUpload","summary":"Prepare an attachment upload","tags":["Authenticated endpoints (API key)"],"description":"Generate a pre-signed upload URL for a ticket attachment. Upload the file with an HTTP PUT request to the returned URL, then pass the attachment ID in the POST /v2/tickets request.","parameters":[{"schema":{"type":"string","description":"Bearer token API key"},"required":true,"description":"Bearer token API key","name":"Authorization","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"fileName":{"type":"string","minLength":1},"fileType":{"type":"string","enum":["image/svg+xml","image/png","image/jpeg","image/gif","application/pdf","video/mp4","video/quicktime","text/plain","application/zip","application/vnd.rar"]},"fileSize":{"type":"integer","exclusiveMinimum":0,"maximum":209715200,"description":"Size of the file in bytes. Maximum allowed size is 200 MB."},"appId":{"type":"string","format":"uuid"},"customerId":{"type":["string","null"],"minLength":1,"description":"Optional customer identifier to associate with the uploaded attachment."}},"required":["fileName","fileType","fileSize","appId"]}}}},"responses":{"200":{"description":"Attachment upload instructions","content":{"application/json":{"schema":{"type":"object","properties":{"attachmentId":{"type":"string","description":"Attachment identifier to be used in POST /v2/tickets. Represents the uploaded file key."},"uploadUrl":{"type":"string","format":"uri","description":"Pre-signed URL for uploading the file."},"uploadMethod":{"type":"string","enum":["PUT"],"description":"HTTP method to use for the upload request."},"uploadHeaders":{"type":"object","additionalProperties":{"type":"string"},"description":"Headers that must be included when uploading the file. Provide them exactly as returned to ensure the URL signature matches."},"uploadExpiresInSeconds":{"type":"integer","exclusiveMinimum":0,"description":"Number of seconds the signed upload URL remains valid."}},"required":["attachmentId","uploadUrl","uploadMethod","uploadHeaders","uploadExpiresInSeconds"]}}}}}}},"/attachments/{attachmentId}":{"get":{"operationId":"downloadAttachment","summary":"Download an attachment","tags":["Authenticated endpoints (API key)"],"description":"Redirect to a short-lived signed URL for downloading a previously uploaded ticket attachment.","parameters":[{"schema":{"type":"string","description":"Attachment ID returned by POST /v2/attachments."},"required":true,"description":"Attachment ID returned by POST /v2/attachments.","name":"attachmentId","in":"path"},{"schema":{"type":"string","description":"Bearer token API key"},"required":true,"description":"Bearer token API key","name":"Authorization","in":"header"}],"responses":{"307":{"description":"Temporary redirect to the attachment download URL"}}}},"/tickets/{ticketId}/actions":{"post":{"operationId":"performTicketActions","summary":"Perform ticket actions","tags":["Authenticated endpoints (API key)"],"description":"Perform actions on a ticket such as managing metadata, sending messages, assigning, changing status, and closing","parameters":[{"schema":{"type":"string","format":"uuid","description":"The ID of the ticket to perform actions on"},"required":true,"description":"The ID of the ticket to perform actions on","name":"ticketId","in":"path"},{"schema":{"type":"string","description":"Bearer token API key"},"required":true,"description":"Bearer token API key","name":"Authorization","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"actions":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["addTags"]},"tagNames":{"type":"array","items":{"type":"string"},"minItems":1},"userId":{"type":"string","format":"uuid","description":"The Theymes user to attribute as performing the action. The user must have access to the ticket app."}},"required":["type","tagNames"],"title":"addTags","description":"Action to add tags to the ticket"},{"type":"object","properties":{"type":{"type":"string","enum":["setFields"]},"fields":{"type":"object","additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"array","items":{"type":"string"}},{"type":"boolean"}],"description":"Value of the custom field to add to the ticket, type depends on field configuration in Theymes support app"},"description":"Map of custom field keys to their values to set on the ticket"},"userId":{"type":"string","format":"uuid","description":"The Theymes user to attribute as performing the action. The user must have access to the ticket app."}},"required":["type","fields"],"title":"setFields","description":"Action to add custom fields to the ticket"},{"type":"object","properties":{"type":{"type":"string","enum":["setOnHold"]},"onHold":{"type":"boolean","description":"Whether to set the ticket on hold (true) or remove from on hold (false)"},"userId":{"type":"string","format":"uuid","description":"The Theymes user to attribute as performing the action. The user must have access to the ticket app."}},"required":["type","onHold"],"title":"setOnHold","description":"Action to set the ticket on hold or remove from on hold. Only one ticket status action may be specified"},{"type":"object","properties":{"type":{"type":"string","enum":["setStatus"]},"status":{"type":"string","enum":["waiting","assigned"],"description":"Status to set. Assigned resolves to unassigned when the ticket has no assignee. Use setOnHold, resolveTicket, or rejectTicket for hold and closed states."},"userId":{"type":"string","format":"uuid","description":"The Theymes user to attribute as performing the action. The user must have access to the ticket app."}},"required":["type","status"],"title":"setStatus","description":"Action to set the status of an open ticket. Only one ticket status action may be specified"},{"type":"object","properties":{"type":{"type":"string","enum":["setCustomerInfo"]},"customer":{"type":"object","properties":{"name":{"type":"string","description":"The name of the customer"},"tier":{"anyOf":[{"type":"number","enum":[1]},{"type":"number","enum":[2]},{"type":"number","enum":[3]}],"description":"The tier of the customer"}}}},"required":["type","customer"],"title":"setCustomerInfo","description":"The customer info to set on the ticket"},{"type":"object","properties":{"type":{"type":"string","enum":["sendMessage"]},"message":{"type":"string","minLength":1,"description":"The outbound message content to send to the ticket. The message must be in the language of the ticket."},"userId":{"type":"string","format":"uuid","description":"The Theymes user to attribute as the message sender. The user must have access to the ticket app."}},"required":["type","message"],"title":"sendMessage","description":"Action to send an outbound message to the ticket"},{"type":"object","properties":{"type":{"type":"string","enum":["addPrivateNote"]},"message":{"type":"string","minLength":1,"description":"The private note content to add to the ticket"},"userId":{"type":"string","format":"uuid","description":"The Theymes user to attribute as performing the action. The user must have access to the ticket app."}},"required":["type","message"],"title":"addPrivateNote","description":"Action to add a private note to the ticket"},{"type":"object","properties":{"type":{"type":"string","enum":["resolveTicket"]},"userId":{"type":"string","format":"uuid","description":"The Theymes user to attribute as performing the action. The user must have access to the ticket app."}},"required":["type"],"title":"resolveTicket","description":"Action to resolve the ticket"},{"type":"object","properties":{"type":{"type":"string","enum":["rejectTicket"]},"userId":{"type":"string","format":"uuid","description":"The Theymes user to attribute as performing the action. The user must have access to the ticket app."}},"required":["type"],"title":"rejectTicket","description":"Action to reject the ticket"},{"type":"object","properties":{"type":{"type":"string","enum":["assignTicket"]},"assigneeId":{"type":"string","format":"uuid","description":"The user ID to assign the ticket to"},"userId":{"type":"string","format":"uuid","description":"The Theymes user to attribute as performing the action. The user must have access to the ticket app."}},"required":["type","assigneeId"],"title":"assignTicket","description":"Action to assign the ticket to a user"},{"type":"object","properties":{"type":{"type":"string","enum":["unassignTicket"]},"userId":{"type":"string","format":"uuid","description":"The Theymes user to attribute as performing the action. The user must have access to the ticket app."}},"required":["type"],"title":"unassignTicket","description":"Action to remove the current ticket assignee"},{"type":"object","properties":{"type":{"type":"string","enum":["removeTags"]},"tagNames":{"type":"array","items":{"type":"string"},"minItems":1},"userId":{"type":"string","format":"uuid","description":"The Theymes user to attribute as performing the action. The user must have access to the ticket app."}},"required":["type","tagNames"],"title":"removeTags","description":"Action to remove tags from the ticket"}]},"minItems":1}},"required":["actions"]}}}},"responses":{"200":{"description":"Result of performing the actions","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]}}}}}}},"/tickets/{ticketId}/events":{"get":{"operationId":"getTicketEvents","summary":"List ticket events","tags":["Authenticated endpoints (API key)"],"description":"Get selected ticket events, including message attachments as downloadable attachment IDs.","parameters":[{"schema":{"type":"string","format":"uuid","description":"The ID of the ticket to fetch events for"},"required":true,"description":"The ID of the ticket to fetch events for","name":"ticketId","in":"path"},{"schema":{"type":"string","description":"Bearer token API key"},"required":true,"description":"Bearer token API key","name":"Authorization","in":"header"}],"responses":{"200":{"description":"A list of ticket events","content":{"application/json":{"schema":{"type":"object","properties":{"events":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"createdAt":{"type":"string","format":"date-time"},"message":{"type":"string"},"language":{"type":"string","enum":["en","de","es","es-AR","es-MX","fi","fil","fr","id","ja","ko","ms","pt","pt-BR","ru","tr","uk","vi","zh","zh-Hans","zh-Hant","ar","cs","da","nl","el","hu","it","no","nb","pl","ro","sk","sv","th"]},"attachments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Attachment ID used with GET /v2/attachments/{attachmentId}"}},"required":["id"]}},"type":{"type":"string","enum":["CUSTOMER_MESSAGE"]}},"required":["id","createdAt","message","language","attachments","type"],"title":"customerMessage","description":"Event representing a message from a customer"},{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["AGENT_MESSAGE"]},"createdAt":{"type":"string","format":"date-time"},"userId":{"type":["string","null"],"format":"uuid","default":null,"description":"ID of the agent who sent the message. Null when a system automation added the message."},"displayName":{"type":["string","null"],"default":null,"description":"Display name of the agent who sent the message. Null when a system automation added the message."},"message":{"type":"string","description":"Plain-text body. For rich-text replies, the editor text, with images included as URLs."},"messageHtml":{"type":"string","description":"HTML of a rich-text reply. Omitted for plain-text replies."},"language":{"type":"string","enum":["en","de","es","es-AR","es-MX","fi","fil","fr","id","ja","ko","ms","pt","pt-BR","ru","tr","uk","vi","zh","zh-Hans","zh-Hant","ar","cs","da","nl","el","hu","it","no","nb","pl","ro","sk","sv","th"]},"attachments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Attachment ID used with GET /v2/attachments/{attachmentId}"}},"required":["id"]}}},"required":["id","type","createdAt","message","language","attachments"],"title":"agentMessage","description":"Event representing a message from an agent"},{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["PRIVATE_NOTE"]},"createdAt":{"type":"string","format":"date-time"},"userId":{"type":["string","null"],"format":"uuid","default":null,"description":"ID of the agent who added the note. Null when a system automation added the note."},"displayName":{"type":["string","null"],"default":null,"description":"Display name of the agent who added the note. Null when a system automation added the note."},"message":{"type":"string","description":"Plain-text body. For rich-text notes, the editor text, with images included as URLs."},"messageHtml":{"type":"string","description":"HTML of a rich-text note. Omitted for plain-text notes."},"attachments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Attachment ID used with GET /v2/attachments/{attachmentId}"}},"required":["id"]}}},"required":["id","type","createdAt","message","attachments"],"title":"privateNote","description":"Event representing a private note on the ticket"},{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["CSAT"]},"createdAt":{"type":"string","format":"date-time"},"score":{"type":"integer","minimum":1,"maximum":5},"review":{"type":["string","null"]}},"required":["id","type","createdAt","score","review"],"title":"csat","description":"Event representing a CSAT submission on the ticket"},{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["END"]},"createdAt":{"type":"string","format":"date-time"},"resolutionType":{"type":"string","enum":["resolved","rejected","auto_closed"]}},"required":["id","type","createdAt","resolutionType"],"title":"end","description":"Event representing the end of the conversation"},{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["COLLECTOR_RESULT"]},"createdAt":{"type":"string","format":"date-time"},"collectorId":{"type":"string","format":"uuid"},"resultId":{"type":"string","format":"uuid"},"title":{"type":"string"},"fields":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"key":{"type":["string","null"]},"label":{"type":"string"},"type":{"type":"string","enum":["TEXT"]},"value":{"type":["string","null"]}},"required":["key","label","type","value"]},{"type":"object","properties":{"key":{"type":["string","null"]},"label":{"type":"string"},"type":{"type":"string","enum":["SELECT_GROUP"]},"value":{"type":"array","items":{"type":"string"}}},"required":["key","label","type","value"]},{"type":"object","properties":{"key":{"type":["string","null"]},"label":{"type":"string"},"type":{"type":"string","enum":["DROPDOWN"]},"value":{"type":"array","items":{"type":"string"}}},"required":["key","label","type","value"]},{"type":"object","properties":{"key":{"type":["string","null"]},"label":{"type":"string"},"type":{"type":"string","enum":["DATE"]},"value":{"type":["string","null"]}},"required":["key","label","type","value"]},{"type":"object","properties":{"key":{"type":["string","null"]},"label":{"type":"string"},"type":{"type":"string","enum":["EMAIL"]},"value":{"type":["string","null"]}},"required":["key","label","type","value"]},{"type":"object","properties":{"key":{"type":["string","null"]},"label":{"type":"string"},"type":{"type":"string","enum":["CHECKBOX"]},"value":{"type":["boolean","null"]}},"required":["key","label","type","value"]},{"type":"object","properties":{"key":{"type":["string","null"]},"label":{"type":"string"},"type":{"type":"string","enum":["PLATFORM_SELECTOR"]},"value":{"type":["string","null"]}},"required":["key","label","type","value"]},{"type":"object","properties":{"key":{"type":["string","null"]},"label":{"type":"string"},"type":{"type":"string","enum":["FILE"]},"attachments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Attachment ID used with GET /v2/attachments/{attachmentId}"}},"required":["id"]}}},"required":["key","label","type","attachments"]}]}}},"required":["id","type","createdAt","collectorId","resultId","title","fields"],"title":"collectorResult","description":"Event representing a filled collector form, with the collector results."}]},"description":"List of events in the conversation, ordered by creation time, more event types may be added in the future"}},"required":["events"]}}}}}}},"/tickets/{ticketId}/breadcrumbs":{"get":{"operationId":"getTicketBreadcrumbs","summary":"Get ticket breadcrumbs","tags":["Authenticated endpoints (API key)"],"description":"Get SDK breadcrumbs captured for a ticket.","parameters":[{"schema":{"type":"string","format":"uuid","description":"The ID of the ticket to fetch breadcrumbs for"},"required":true,"description":"The ID of the ticket to fetch breadcrumbs for","name":"ticketId","in":"path"},{"schema":{"type":"string","description":"Bearer token API key"},"required":true,"description":"Bearer token API key","name":"Authorization","in":"header"}],"responses":{"200":{"description":"Ticket breadcrumbs","content":{"application/json":{"schema":{"type":"object","properties":{"breadcrumbs":{"type":"array","items":{"type":"object","properties":{"message":{"type":"string"},"clientOccurredAt":{"type":"string","format":"date-time"}},"required":["message","clientOccurredAt"]}},"clientClockOffsetMs":{"type":["integer","null"]}},"required":["breadcrumbs","clientClockOffsetMs"]}}}}}}},"/apps":{"get":{"operationId":"getApps","summary":"List apps","tags":["Authenticated endpoints (API key)"],"description":"List apps for the company associated with the API key, including their identifiers, names, slugs, and supported languages.","parameters":[{"schema":{"type":"string","description":"Bearer token API key"},"required":true,"description":"Bearer token API key","name":"Authorization","in":"header"}],"responses":{"200":{"description":"A list of apps","content":{"application/json":{"schema":{"type":"object","properties":{"apps":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"languages":{"type":"array","items":{"type":"string","enum":["en","de","es","es-AR","es-MX","fi","fil","fr","id","ja","ko","ms","pt","pt-BR","ru","tr","uk","vi","zh","zh-Hans","zh-Hant","ar","cs","da","nl","el","hu","it","no","nb","pl","ro","sk","sv","th"]}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","name","slug","languages","createdAt","updatedAt"]}}},"required":["apps"]}}}}}}},"/tags":{"get":{"operationId":"getTags","summary":"List tags","tags":["Authenticated endpoints (API key)"],"description":"List tag definitions for the company associated with the API key, including their scope and configuration.","parameters":[{"schema":{"type":"string","description":"Bearer token API key"},"required":true,"description":"Bearer token API key","name":"Authorization","in":"header"}],"responses":{"200":{"description":"A list of tags","content":{"application/json":{"schema":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":["string","null"]},"isAiTag":{"type":"boolean"},"isSkill":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"appId":{"type":["string","null"],"format":"uuid","description":"The ID of the app this tag is associated with, or null if it is a company-wide tag"}},"required":["name","description","isAiTag","isSkill","createdAt","updatedAt","appId"]}}},"required":["tags"]}}}}}}},"/fields":{"get":{"operationId":"getFields","summary":"List custom fields","tags":["Authenticated endpoints (API key)"],"description":"List custom field definitions for the company associated with the API key, including field keys, types, descriptions, and scope.","parameters":[{"schema":{"type":"string","description":"Bearer token API key"},"required":true,"description":"Bearer token API key","name":"Authorization","in":"header"}],"responses":{"200":{"description":"A list of fields","content":{"application/json":{"schema":{"type":"object","properties":{"fields":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":["string","null"]},"type":{"type":"string","enum":["text","number","date","boolean","dropdown"]},"key":{"type":"string"},"isAiField":{"type":"boolean"},"appId":{"type":["string","null"],"format":"uuid","description":"The ID of the app this field is associated with, or null if it is a company-wide field"}},"required":["name","description","type","key","isAiField","appId"]}}},"required":["fields"]}}}}}}},"/customers/schedule-deletion":{"post":{"operationId":"scheduleCustomerDeletion","summary":"Schedule customer deletion","tags":["Authenticated endpoints (API key)"],"description":"Schedule deletion of a customer's data. The customer will be scheduled to be deleted in 24 hours. The scheduled deletion can be cancelled from the Theymes application if necessary.","parameters":[{"schema":{"type":"string","description":"Bearer token API key"},"required":true,"description":"Bearer token API key","name":"Authorization","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"theymesCustomerId":{"type":"string","format":"uuid","description":"The Theymes Customer ID, can be found with the ticket API."}},"required":["theymesCustomerId"]}}}},"responses":{"200":{"description":"Customer deletion scheduled","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]}}}}}}},"/customers":{"delete":{"operationId":"deleteCustomer","summary":"Delete a customer","tags":["Authenticated endpoints (API key)"],"description":"Immediately and permanently delete a customer's data. Unlike schedule-deletion, there is no 24-hour delay and the deletion cannot be cancelled. This endpoint is only available to companies that have been explicitly allowlisted; contact Theymes to request access.","parameters":[{"schema":{"type":"string","description":"Bearer token API key"},"required":true,"description":"Bearer token API key","name":"Authorization","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"theymesCustomerId":{"type":"string","format":"uuid","description":"The Theymes Customer ID, can be found with the ticket API."}},"required":["theymesCustomerId"]}}}},"responses":{"200":{"description":"Customer deletion completed","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]}}}}}}},"/insights/stats":{"post":{"operationId":"queryStats","summary":"Query stats","tags":["Authenticated endpoints (API key)"],"description":"**This endpoint does not create or change any data.** POST is used because the query is a nested JSON body.\n\nQuery insights for the company associated with the API key. Send one or more metrics and one timeframe, and optionally shared filters, one breakdown, and one segment.\n\nSee [Querying stats](/developers/insights/querying-stats) for how to use the endpoint with examples. The body data below lists supported metrics, breakdowns and filters.","parameters":[{"schema":{"type":"string","description":"Bearer token API key"},"required":true,"description":"Bearer token API key","name":"Authorization","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"metrics":{"type":"array","items":{"$ref":"#/components/schemas/StatsMetric"},"minItems":1,"description":"Metrics to calculate. Values in each stats row follow this order."},"filters":{"type":"array","items":{"$ref":"#/components/schemas/StatsFilter"},"title":"StatsFilter","description":"Filters applied to every metric, in addition to each metric's own filters."},"timeframe":{"$ref":"#/components/schemas/StatsTimeframe"},"breakdown":{"allOf":[{"$ref":"#/components/schemas/StatsBreakdown"},{"description":"Split each stats row by one dimension. The row `breakdown` is that dimension's display name."}]},"segment":{"allOf":[{"$ref":"#/components/schemas/StatsBreakdown"},{"description":"Second dimension, returned on each row as `segment`."}]}},"required":["metrics","timeframe"],"additionalProperties":false,"description":"Stats query. This request does not create or change data."}}}},"responses":{"200":{"description":"Calculated stats. This response is a read of existing data.","content":{"application/json":{"schema":{"type":"object","properties":{"metrics":{"type":"array","items":{"$ref":"#/components/schemas/StatsMetric"},"minItems":1},"timeframe":{"$ref":"#/components/schemas/StatsTimeframe"},"breakdown":{"$ref":"#/components/schemas/StatsBreakdown"},"segment":{"$ref":"#/components/schemas/StatsBreakdown"},"stats":{"type":"array","items":{"type":"object","properties":{"timeframe":{"type":"object","properties":{"type":{"type":"string","enum":["TODAY","PAST_7_DAYS","PAST_30_DAYS","PAST_90_DAYS","PAST_365_DAYS","CUSTOM"]},"from":{"anyOf":[{"type":"string","format":"date"},{"type":"object","properties":{"date":{"type":"string","format":"date"},"hours":{"type":"integer","minimum":0,"maximum":23,"description":"Hour of the day, 0-23."}},"required":["date","hours"]}]},"to":{"anyOf":[{"type":"string","format":"date"},{"type":"object","properties":{"date":{"type":"string","format":"date"},"hours":{"type":"integer","minimum":0,"maximum":23,"description":"Hour of the day, 0-23."}},"required":["date","hours"]}]}},"required":["type","from","to"],"description":"Resolved range for this row."},"metrics":{"type":"array","items":{"type":["number","null"]},"description":"One value per requested metric, in request order. Null when the metric has no value for the row."},"breakdown":{"type":["string","null"],"description":"Display name for the requested breakdown, or null when it is empty."},"segment":{"type":["string","null"],"description":"Display name for the requested segment, or null when it is empty."}},"required":["metrics"]}}},"required":["metrics","timeframe","stats"]}}}},"400":{"description":"Invalid stats query"},"403":{"description":"API key authentication required"}}}},"/support/sessions/redirect":{"get":{"operationId":"redirectToSupport","summary":"Redirect to web support","tags":["Public support links (no authentication)"],"description":"Create a web support session from metadata passed in the query string and redirect the customer to the public web support site with the session code attached (`sid`). Requires no authentication; the app is identified by its app environment `token`. Extra `customer.*`, `tags`, and `fields.*` query parameters are accepted as session metadata.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"token","in":"query"},{"schema":{"type":"string"},"required":false,"name":"language","in":"query"},{"schema":{"type":"string","description":"When provided, the user is taken directly to that resource instead of the support home page. Must match a resource key configured in the Theymes application."},"required":false,"description":"When provided, the user is taken directly to that resource instead of the support home page. Must match a resource key configured in the Theymes application.","name":"resource","in":"query"},{"schema":{"type":"string"},"required":false,"name":"signedMetadataToken","in":"query"},{"schema":{"type":"string"},"required":false,"name":"customer.id","in":"query"},{"schema":{"type":"string"},"required":false,"name":"customer.name","in":"query"},{"schema":{"type":"string","format":"email"},"required":false,"name":"customer.email","in":"query"},{"schema":{"type":"number"},"required":false,"name":"customer.tier","in":"query"},{"schema":{"type":"string"},"required":false,"name":"tags","in":"query"}],"responses":{"307":{"description":"Temporary redirect to the public web support URL with the session code attached"}}}},"/support/sessions":{"post":{"operationId":"createSupportSession","summary":"Create a support session","tags":["Public support links (no authentication)"],"description":"Create a web support session from metadata passed in the request body and return the session code together with the full public web support URL that has the session code attached (`sid`). Requires no authentication; the app is identified by its app environment `token`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string","format":"uuid"},"language":{"type":"string"},"resource":{"type":"string","description":"When provided, the user is taken directly to that resource instead of the support home page. Must match a resource key configured in the Theymes application."},"signedMetadataToken":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"fields":{"type":"object","additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"array","items":{"type":"string"}},{"type":"boolean"}]}},"customer":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"email":{"type":"string","format":"email"},"tier":{"anyOf":[{"type":"number","enum":[1]},{"type":"number","enum":[2]},{"type":"number","enum":[3]}]}}}},"required":["token"]}}}},"responses":{"200":{"description":"The created support session code and the public web support URL","content":{"application/json":{"schema":{"type":"object","properties":{"sessionCode":{"type":"string"},"url":{"type":"string"}},"required":["sessionCode","url"]}}}}}}}},"webhooks":{},"x-tagGroups":[{"name":"Authenticated (API key)","tags":["Authenticated endpoints (API key)"]},{"name":"Public (no authentication)","tags":["Public support links (no authentication)"]}]}