{"openapi":"3.1.0","info":{"title":"Theymes API","version":"1.0.0","description":"Theymes API allows you to interact with the Theymes platform.\n\n\nAll 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>```)."},"components":{"schemas":{},"parameters":{}},"paths":{"/tickets":{"get":{"operationId":"getTickets","description":"Get tickets","parameters":[{"schema":{"type":"string"},"required":false,"name":"playerId","in":"query"},{"schema":{"type":"string"},"required":false,"name":"email","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"gameId","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"ticketId","in":"query"},{"schema":{"type":"string","format":"date","description":"Only return tickets created on or after this date"},"required":false,"name":"createdAfter","in":"query"},{"schema":{"type":"string","format":"date","description":"Only return tickets created on or before this date"},"required":false,"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,"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,"name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":1000,"default":100},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Bearer token API key"},"required":true,"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"},"url":{"type":"string","description":"URL to view the conversation in the support application"},"gameId":{"type":"string","format":"uuid"},"gameEnvironmentId":{"type":"string","format":"uuid"},"theymesPlayerId":{"type":"string","nullable":true,"format":"uuid","description":"Theymes internal player ID"},"playerId":{"type":"string","nullable":true,"description":"External player ID provided by the game, null for email/web tickets"},"status":{"type":"string","enum":["new","assigned","unassigned","waiting","on_hold","closed"]},"channels":{"type":"array","items":{"type":"string","enum":["chat","email"]}},"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","nullable":true,"enum":["resolved","rejected","auto_closed"]},"csatScore":{"type":"integer","nullable":true,"minimum":1,"maximum":5},"csatReview":{"type":"string","nullable":true},"issueSummary":{"type":"string","nullable":true},"issueResolution":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"lastActivityAt":{"type":"string","nullable":true,"format":"date-time"}},"required":["id","url","gameId","gameEnvironmentId","theymesPlayerId","playerId","status","channels","language","resolutionType","csatScore","csatReview","issueSummary","issueResolution","createdAt","lastActivityAt"]}},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true,"description":"Cursor for pagination if more results are available else null"}},"required":["cursor"]}},"required":["tickets","pagination"]}}}}}},"post":{"operationId":"createTicket","description":"Create a new ticket. To include attachments, call POST /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,"name":"Authorization","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"gameId":{"type":"string","format":"uuid"},"message":{"type":"string"},"attachments":{"type":"array","items":{"type":"string"},"default":[],"description":"List of attachment IDs returned by POST /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},"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"},"player":{"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":["player"]}},"required":["gameId","message","language","channels","metadata"]}}}},"responses":{"200":{"description":"The created ticket ID","content":{"application/json":{"schema":{"type":"object","properties":{"ticketId":{"type":"string","format":"uuid"}},"required":["ticketId"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"type":"object","properties":{"details":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["PLAYER_BLOCKED"]}},"required":["type"],"description":"The user is blocked from contacting support","title":"PlayerBlocked"},{"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"],"description":"The user has already requested a similar open ticket","title":"DuplicateOpenTicketDetected"}]}},"required":["details"]}}}}}}},"/attachments":{"post":{"operationId":"prepareAttachmentUpload","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 /tickets request.","parameters":[{"schema":{"type":"string","description":"Bearer token API key"},"required":true,"name":"Authorization","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"gameId":{"type":"string","format":"uuid"},"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","minimum":0,"exclusiveMinimum":true,"maximum":209715200,"description":"Size of the file in bytes. Maximum allowed size is 200 MB."},"playerId":{"type":"string","nullable":true,"minLength":1,"description":"Optional player identifier to associate with the uploaded attachment."}},"required":["gameId","fileName","fileType","fileSize"]}}}},"responses":{"200":{"description":"Attachment upload instructions","content":{"application/json":{"schema":{"type":"object","properties":{"attachmentId":{"type":"string","description":"Attachment identifier to be used in POST /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","minimum":0,"exclusiveMinimum":true,"description":"Number of seconds the signed upload URL remains valid."}},"required":["attachmentId","uploadUrl","uploadMethod","uploadHeaders","uploadExpiresInSeconds"]}}}}}}},"/attachments/{attachmentId}":{"get":{"operationId":"downloadAttachment","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 /attachments."},"required":true,"name":"attachmentId","in":"path"},{"schema":{"type":"string","description":"Bearer token API key"},"required":true,"name":"Authorization","in":"header"}],"responses":{"307":{"description":"Temporary redirect to the attachment download URL"}}}},"/tickets/{ticketId}/actions":{"post":{"operationId":"performTicketActions","description":"Perform actions on a ticket such as managing metadata, sending messages, assigning, and closing","parameters":[{"schema":{"type":"string","format":"uuid","description":"The ID of the ticket to perform actions on"},"required":true,"name":"ticketId","in":"path"},{"schema":{"type":"string","description":"Bearer token API key"},"required":true,"name":"Authorization","in":"header"}],"requestBody":{"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}},"required":["type","tagNames"],"description":"Action to add tags to the ticket","title":"addTags"},{"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"}},"required":["type","fields"],"description":"Action to add custom fields to the ticket","title":"setFields"},{"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)"}},"required":["type","onHold"],"description":"Action to set the ticket on hold or remove from on hold. Only one action of this type may be specified","title":"setOnHold"},{"type":"object","properties":{"type":{"type":"string","enum":["setPlayerInfo"]},"player":{"type":"object","properties":{"name":{"type":"string","description":"The name of the player"},"tier":{"anyOf":[{"type":"number","enum":[1]},{"type":"number","enum":[2]},{"type":"number","enum":[3]}],"description":"The tier of the player"}}}},"required":["type","player"],"description":"The player info to set on the ticket","title":"setPlayerInfo"},{"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."}},"required":["type","message"],"description":"Action to send an outbound message to the ticket","title":"sendMessage"},{"type":"object","properties":{"type":{"type":"string","enum":["addPrivateNote"]},"message":{"type":"string","minLength":1,"description":"The private note content to add to the ticket"}},"required":["type","message"],"description":"Action to add a private note to the ticket","title":"addPrivateNote"},{"type":"object","properties":{"type":{"type":"string","enum":["resolveTicket"]}},"required":["type"],"description":"Action to resolve the ticket","title":"resolveTicket"},{"type":"object","properties":{"type":{"type":"string","enum":["rejectTicket"]}},"required":["type"],"description":"Action to reject the ticket","title":"rejectTicket"},{"type":"object","properties":{"type":{"type":"string","enum":["assignTicket"]},"assigneeId":{"type":"string","format":"uuid","description":"The user ID to assign the ticket to"}},"required":["type","assigneeId"],"description":"Action to assign the ticket to a user","title":"assignTicket"},{"type":"object","properties":{"type":{"type":"string","enum":["unassignTicket"]}},"required":["type"],"description":"Action to remove the current ticket assignee","title":"unassignTicket"},{"type":"object","properties":{"type":{"type":"string","enum":["removeTags"]},"tagNames":{"type":"array","items":{"type":"string"},"minItems":1}},"required":["type","tagNames"],"description":"Action to remove tags from the ticket","title":"removeTags"}]},"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","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,"name":"ticketId","in":"path"},{"schema":{"type":"string","description":"Bearer token API key"},"required":true,"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"},"type":{"type":"string","enum":["PLAYER_MESSAGE"]},"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 /attachments/{attachmentId}"}},"required":["id"]}}},"required":["id","type","createdAt","message","language","attachments"],"description":"Event representing a message from a player","title":"playerMessage"},{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["AGENT_MESSAGE"]},"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 /attachments/{attachmentId}"}},"required":["id"]}}},"required":["id","type","createdAt","message","language","attachments"],"description":"Event representing a message from an agent","title":"agentMessage"},{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["PRIVATE_NOTE"]},"createdAt":{"type":"string","format":"date-time"},"message":{"type":"string"},"attachments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Attachment ID used with GET /attachments/{attachmentId}"}},"required":["id"]}}},"required":["id","type","createdAt","message","attachments"],"description":"Event representing a private note on the ticket","title":"privateNote"},{"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","nullable":true}},"required":["id","type","createdAt","score","review"],"description":"Event representing a CSAT submission on the ticket","title":"csat"},{"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"],"description":"Event representing the end of the conversation","title":"end"},{"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","nullable":true},"label":{"type":"string"},"type":{"type":"string","enum":["TEXT"]},"value":{"type":"string","nullable":true}},"required":["key","label","type","value"]},{"type":"object","properties":{"key":{"type":"string","nullable":true},"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","nullable":true},"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","nullable":true},"label":{"type":"string"},"type":{"type":"string","enum":["DATE"]},"value":{"type":"string","nullable":true}},"required":["key","label","type","value"]},{"type":"object","properties":{"key":{"type":"string","nullable":true},"label":{"type":"string"},"type":{"type":"string","enum":["EMAIL"]},"value":{"type":"string","nullable":true}},"required":["key","label","type","value"]},{"type":"object","properties":{"key":{"type":"string","nullable":true},"label":{"type":"string"},"type":{"type":"string","enum":["CHECKBOX"]},"value":{"type":"boolean","nullable":true}},"required":["key","label","type","value"]},{"type":"object","properties":{"key":{"type":"string","nullable":true},"label":{"type":"string"},"type":{"type":"string","enum":["FILE"]},"attachments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Attachment ID used with GET /attachments/{attachmentId}"}},"required":["id"]}}},"required":["key","label","type","attachments"]}]}}},"required":["id","type","createdAt","collectorId","resultId","title","fields"],"description":"Event representing a filled collector form, with the collector results.","title":"collectorResult"}]},"description":"List of events in the conversation, ordered by creation time, more event types may be added in the future"}},"required":["events"]}}}}}}},"/games":{"get":{"operationId":"getGames","description":"Get games for the company associated with the API key","parameters":[{"schema":{"type":"string","description":"Bearer token API key"},"required":true,"name":"Authorization","in":"header"}],"responses":{"200":{"description":"A list of games","content":{"application/json":{"schema":{"type":"object","properties":{"games":{"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":["games"]}}}}}}},"/tags":{"get":{"operationId":"getTags","description":"Get tags for the company associated with the API key","parameters":[{"schema":{"type":"string","description":"Bearer token API key"},"required":true,"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":{"gameId":{"type":"string","nullable":true,"format":"uuid","description":"The ID of the game this tag is associated with, or null if it is a company-wide tag"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"isAiTag":{"type":"boolean"},"isSkill":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["gameId","name","description","isAiTag","isSkill","createdAt","updatedAt"]}}},"required":["tags"]}}}}}}},"/fields":{"get":{"operationId":"getFields","description":"Get fields for the company associated with the API key","parameters":[{"schema":{"type":"string","description":"Bearer token API key"},"required":true,"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":{"gameId":{"type":"string","nullable":true,"format":"uuid","description":"The ID of the game this field is associated with, or null if it is a company-wide field"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"type":{"type":"string","enum":["text","number","date","boolean","dropdown"]},"key":{"type":"string"},"isAiField":{"type":"boolean"}},"required":["gameId","name","description","type","key","isAiField"]}}},"required":["fields"]}}}}}}},"/player/schedule-deletion":{"post":{"operationId":"schedulePlayerDeletion","description":"Schedule deletion of a player's data","parameters":[{"schema":{"type":"string","description":"Bearer token API key"},"required":true,"name":"Authorization","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"theymesPlayerId":{"type":"string","format":"uuid","description":"The Theymes Player ID, can be found with the ticket API."}},"required":["theymesPlayerId"]}}}},"responses":{"200":{"description":"Player deletion scheduled","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]}}}}}}}}}