> ## Documentation Index > Fetch the complete documentation index at: https://www.text.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # List rules ## OpenAPI ````yaml /api/ticketing/openapi.json get /v1/rules openapi: 3.0.3 info: title: Ticketing API version: 1.0.0 description: > # Introduction This document describes the public API of the Ticketing API # Authentication The Ticketing API shares an authentication and authorization system with [Text](https://www.text.com). More details can be found in [Authorization Documentation](https://developers.text.com/docs/authorization). Endpoints require `Authorization` HTTP header. Authorization methods include: - Personal Access Tokens (good for testing and development purposes). PATs can be created in the Text app under **Settings → API access → Personal access tokens**. Use the `accounts--my:ro` scope when generating the token. After generating a token, use Basic authentication scheme with your **account_id** as the user name and the token as a password. [Detailed instructions](/authentication/personal-access-tokens). - OAuth 2 Authorization Code Grant flow (recommended for production deployment) - details of implementation are described in [Authorization code grant](https://developers.text.com/docs/authorization/authorizing-api-calls/#authorization-code-grant) documentation. - Other possible options are described in the [Use cases](https://developers.text.com/docs/authorization/authorizing-api-calls/#use-cases) documentation section. # Common notions ## Relative dates and date/time ranges All date/time ranges are half-open, i.e. `[from, to)` In addition to absolute timestamps/dates, it is possible to specify relative dates in the format: - `[-+][number][hHdDM]`. `Sign (+ or -)` denotes relation to the current timestamp - `number` denotes the number of units - `unit` represent minutes (`n`), hours (`h`), days (`d`) and months (`m`). Lowercase units are relative to the current timestamp and uppercase units are relative to the start of current truncated period. Examples: | Relative date | Description | |-|-| | `-2d` | 48 hours before now | | `+1m` | 1 month from now in the future | | `-0M` | start of current month | | `-1M` | start of last month | | `-0D` | last midnight | | `-10n` | 10 minutes before now | ## Ticket silos (folders) Tickets are stored in the following silos: - `tickets`: recent tickets with read/write access - `archive`: archived tickets with read-only access - `spam`: spam tickets with read-only access (purged after 60 days since the last update) - `trash`: deleted tickets with read-only access (purged after 30 days since the last update) Important notes about silos: - When listing tickets, it is required to specify the silo name if the listing should contain tickets stored in a silo other than `tickets`. - To move a ticket to another silo, use [PUT /tickets/{ticket_id}/silo](#operation/ticketUpdateChangeSilo) endpoint. # Gotchas ## User-Agent header We advise always including `User-Agent` header in API requests. Requests missing it might be blocked by intermediary services. servers: - url: https://api.helpdesk.com security: - PersonalAccessToken: [] - BearerAuth: [] tags: - name: Tickets description: > ## Fetch tickets in batches The `/v1/tickets` endpoint provides **cursor-based pagination** for efficient navigation through large or frequently updated datasets. This method avoids common pitfalls of offset-based pagination, offering greater stability and performance. ### How Cursor Pagination Works Cursor pagination uses a composite key of: - `value` - a timestamp (e.g., `createdAt`, `updatedAt`, `lastMessageAt`) - `ID` - a unique ticket ID (`UUID`) to guarantee stable sorting, even for duplicate timestamps These fields are used to determine **where to continue pagination** when requesting the next or previous page. You may provide **either** a `next` cursor (to fetch forward) or a `prev` cursor (to fetch backward) — **not both**. ### Query Parameters | Parameter | Type | Description | |----------------|----------|-----------------------------------------------------------------------------| | `pageSize` | number | Number of results per page (default = 20, max = 100) | | `order` | string | Sorting direction: `asc` or `desc` (default = `desc`) | | `sortBy` | string | Field to sort by: `createdAt`, `updatedAt`, `lastMessageAt` (default = `createdAt`) | | `next.value` | string | ISO 8601 timestamp for the last item on the current page | | `next.ID` | UUID | ID of the last item on the current page | | `prev.value` | string | ISO 8601 timestamp for the first item on the current page | | `prev.ID` | UUID | ID of the first item on the current page | ## Example: Step-by-Step Cursor Navigation Assume 7 tickets exist, sorted by `createdAt desc`: | ID (UUID) | Created At | |----------------------------------------|--------------------------| | `fa1355ae-7e4f-4aa2-83df-20e6bc503a4b` | 2026-06-17T10:00:00.000Z | | `7c2037c2-0624-4a56-94e1-86e25b6c3727` | 2026-06-16T10:00:00.000Z | | `cb7a8b56-bc41-4e2a-b88a-6615a2ef45d9` | 2026-06-15T10:00:00.000Z | | `d3ea733f-7b0e-4075-8a64-8f994f2b76d2` | 2026-06-14T10:00:00.000Z | | `bd9a3d9c-12a3-4ba3-b438-1a3d8e3e6dc1` | 2026-06-13T10:00:00.000Z | | `ea0d7356-34dc-4899-a4de-2cbbdf71fcf0` | 2026-06-12T10:00:00.000Z | | `12c3d688-7a14-4dfb-9f82-74e2bc155fe9` | 2026-06-11T10:00:00.000Z | ### Step 1: Initial Request ```http GET /v1/tickets?pageSize=3&order=desc&sortBy=createdAt ``` **Response:** ```json [ { "ID": "fa1355ae-7e4f-4aa2-83df-20e6bc503a4b", "createdAt": "2026-06-17T10:00:00.000Z", ... }, { "ID": "7c2037c2-0624-4a56-94e1-86e25b6c3727", "createdAt": "2026-06-16T10:00:00.000Z", ... }, { "ID": "cb7a8b56-bc41-4e2a-b88a-6615a2ef45d9", "createdAt": "2026-06-15T10:00:00.000Z", ... } ] ``` ### Step 2: Next Page ```http GET /v1/tickets?pageSize=3&order=desc&sortBy=createdAt&next.value=2026-06-15T10:00:00Z&next.ID=cb7a8b56-bc41-4e2a-b88a-6615a2ef45d9 ``` **Response:** ```json [ { "ID": "d3ea733f-7b0e-4075-8a64-8f994f2b76d2", "createdAt": "2026-06-14T10:00:00.000Z", ... }, { "ID": "bd9a3d9c-12a3-4ba3-b438-1a3d8e3e6dc1", "createdAt": "2026-06-13T10:00:00.000Z", ... }, { "ID": "ea0d7356-34dc-4899-a4de-2cbbdf71fcf0", "createdAt": "2026-06-12T10:00:00.000Z", ... } ] ``` ### Step 3: Final Page ```http GET /v1/tickets?pageSize=3&order=desc&sortBy=createdAt&next.value=2026-06-12T10:00:00Z&next.ID=ea0d7356-34dc-4899-a4de-2cbbdf71fcf0 ``` **Response:** ```json [ { "ID": "12c3d688-7a14-4dfb-9f82-74e2bc155fe9", "createdAt": "2026-06-11T10:00:00.000Z", ... } ] ``` ### Best Practices - Use the `next` or `prev` cursor values returned by your last result set to paginate forward or backward. - Keep `sortBy` and `order` consistent across requests for predictable behavior. - Use `eventsScope=none` if you don't need events in the response. - name: Licenses description: | The license describes a customer account. Contains: - [Subscription](#tag/Subscriptions) information (selected plan, number of agent slots) - Global license settings - Default team designation. The default team is selected among all teams and serves as a default/fallback mechanism, every place team can't be determined or hasn't been specified - Default template. The default template is served if the team hasn't got its own template set - name: Agents description: | Agent represent single agent account on a license. Contains: - teams agent belongs to - agent individual settings like notification preferences, avatars etc. - agent role (`owner`, `normal`, `viewer`) - name: Custom fields description: > Custom fields are customer defined fields in ticket. Tickets are created in license scope, visibility is set per team(s). There are four types of custom fields (single line, multi line, url and date). Every custom field has edit permission level: - normal, value editable by any agent in tickets view - owner, value editable by admins only in tickets view - read only, value not editable on interface, only via API Every custom field can be deactivated (hidden in interface). Amount of active custom fields is limited per license in license settings by `maxCustomFieldsActive` value. Only custom field that is not used in any ticket can be deleted. - name: Transactions description: > Transactions represent volatile sets of uploaded attachments used while modifying various elements in Text such as ticket messages, agent signatures etc. ## Basic flow Transactions are volatile. Transaction exists only until it is used in another `POST` or `PATCH` method. Unused transactions are purged after 24 hours along with uploaded attachments with exception of "external" attachments i.e. attachments copied from another entities like agent signatures etc. Transactions have types. Currently `ticket`, `agent`, `templateLogo` and `cannedResponse`. The type determines path of uploaded attachment and the entity in which it can be used. Upon creation, transaction needs entity ID and can only be used in this entity afterwards - this allows to keep consistent naming in S3 paths. The exception to this rule is creating transaction for a ticket, template or canned response that don't exist yet. In this case entity ID should not be provided - it will be generated automatically and will determine final ID of created ticket, template or canned response. ### Create transaction ``` POST /v1/transactions { // only one field allowed: "ticketID": "UUID", // do not add when ticket does not exist yet "agentID": "UUID", // use when uploading attachments for agent signature "templateID": "UUID", // do not add when template does not exist yet "cannedResponseID": "UUID", // do not add when canned resposne does not exist yet } ``` This yields: ``` { "ID": "9a1e8a52-e7f2-4f59-8b45-a1643d28c460", "type": "ticket", "createdAt": "2026-06-24T13:58:12.288Z", "attachments": [] } ``` ### Upload file ``` POST /v1/transactions/9a1e8a52-e7f2-4f59-8b45-a1643d28c460/attachments ``` Use multipart with `attachments` as key. Multiple files are allowed. Result: ``` [ { "ID": "af367f6b-5b8b-4468-a2ef-4990114d968a", "cid": "af367f6b-5b8b-4468-a2ef-4990114d968a", "url": "https://cdn-labs.livechat-static.com/api/file/helpdesk/att/1338/9a1e8a52-e7f2-4f59-8b45-a1643d28c460/9ce3d7c1ada659d0cf2da321ef41a4628192875aa7e0c80627b4243140ab02ae/earl.png", "name": "earl.png", "type": "image/png", "size": 25670 } ] ``` ### Remove uploaded file from transaction ``` DELETE /v1/transactions/9a1e8a52-e7f2-4f59-8b45-a1643d28c460/attachments/af367f6b-5b8b-4468-a2ef-4990114d968a ``` Result: ``` "OK" ``` ### Add attachments from agent signature ``` POST /v1/transactions/6456b4e5-1e8f-4029-86f7-1e534d020225/attachments { "agentID": "GUID" // copy attachments from this agent's signature } ``` Result: ``` [ { "ID": "44b004b7-2efd-4f73-b9f5-ac927816f18b", "cid": "44b004b7-2efd-4f73-b9f5-ac927816f18b", "url": "https://cdn-labs.livechat-static.com/api/file/helpdesk/att/1338/agent/ff623067-ba81-4613-bfa8-1c558e3a58f0/9ce3d7c1ada659d0cf2da321ef41a4628192875aa7e0c80627b4243140ab02ae/earl.png", "name": "earl.png", "type": "image/png", "size": 25670 }, { "ID": "a1fbb278-0bca-4eba-baa8-48cc9d1f1abc", "cid": "a1fbb278-0bca-4eba-baa8-48cc9d1f1abc", "url": "https://cdn-labs.livechat-static.com/api/file/helpdesk/att/1338/agent/ff623067-ba81-4613-bfa8-1c558e3a58f0/9ce3d7c1ada659d0cf2da321ef41a4628192875aa7e0c80627b4243140ab02ae/earl.png", "name": "earl.png", "type": "image/png", "size": 25670 } ] ``` ## Common tasks ### Change attachments in agent signature 1. Create transaction of type `agent` ``` POST /v1/transactions HTTP/1.1 agentID=ff623067-ba81-4613-bfa8-1c558e3a58f0 ``` 2. Upload attachments 3. Update signature using `transactionID` ``` PATCH /v1/agents/ff623067-ba81-4613-bfa8-1c558e3a58f0 HTTP/1.1 signature.text=test transactionID=6efd3115-cf6e-4b2c-83d1-03fa5470c625 ``` - name: Email domains description: >- Email domain represent a domain with records authorizing Text to send emails on behalf of email owner. This allows for using original license owner domain for ticket communication. To achieve seamless end-user experience, additional setup of mailboxes (inboxes) and reply addresses is required. - name: Teams description: > Teams group agents. Every ticket is always assigned to specific team. At any given time one of the teams has to be designated as a default (fallback) team. - name: Templates description: > Teamplate describes HTML (or Visual) and plaintext version of every email sent to end-user. Templates can be used to customize these messages. - name: Audit log description: | Audit log contains all changes made in the system. - name: Mailboxes (inboxes) description: > Mailboxes (inboxes) are virtual email addresses provided by Text as an entry point for all email communcation. All messages that create tickets should be forwarded to one of the mailboxes. Each mailbox can be set to route incomming tickets to specific teams and optionally agents. Mailbox can also have a reply address customized allowing reply to be sent from different `From` address for each mailbox. Default mailbox is built in and can't be removed. It also won't be listed in `GET` responses. - name: Reply addresses description: >- Reply addresses are created automatically when configuring a mailbox with custom reply address. When this happens, an automatic verification message is being sent to verify, that reply address correctly forwards messages back to one of the mailboxes. This is to ensure that end-user will always be able to reply to agent's message. - name: Spam management description: >- Trusting and blocking emails/domains can be used to force message from specific sender to spam (block) or ignore spam filters (trust). In case of conflicting entries, more specific entry has precedence over more general (email is more important than domain). Adding an address or a domain to one list automatically removes it from the other. - name: Canned responses description: >- Canned responses represent short templates of replies fragments that can be used during message composition in the app. - name: Rules description: >- Rules allow automated processing of tickets. Rules are executed for every ticket during creation or any change that modifies the ticket. A rule consists of conditions (triggers) and actions. When every (or any - depending on quantifier) trigger is fulfilled, all action in the rule are being performed. - name: Macros description: >- Macros enable batch processing of tickets. A macro consists of several actions. When a user triggers a macro, all the actions within it are executed on the ticket. The number of macros is limited to 20 shared macros per license and 20 private macros per user. - name: Views description: >- Views are materialized ticket filters. Every ticket filter set can be saved as a view. Views are created per agent. - name: Webhooks description: > Webhooks represent HTTP addresses that are being requested every time an event occurs. Webhook payload for `tickets.*` webhooks (`POST` request with `application/json` payload): ``` { eventType: , createdAt: , payload: { } } ``` Webhook payload for `tickets.events.*` webhooks (`POST` request with `application/json` payload): ``` { eventType: , createdAt: , payload: { ticket: event: } } ``` Supported events: | Event type | Description | |-|-| | `tickets.create` | New ticket was created | | `tickets.update` | Ticket was modified | | `tickets.statusChange` | Ticket's status changed (deprecated - please use `tickets.events.status` instead) | | `tickets.events.status` | Ticket's status changed | | `tickets.events.priority` | Ticket's priority changed | | `tickets.events.message` | New message in ticket | | `tickets.events.tags` | Ticket's tags changed | | `tickets.events.followers` | Ticket's followers changed | | `tickets.events.assignment` | Ticket's assignment changed | The request will be retried for about 24 hours with increasing interval in case endpoint responds with HTTP code different than `200`. paths: /v1/rules: get: tags: - Rules summary: List rules operationId: rulesList responses: '200': description: Successful response. content: application/json: schema: type: array items: $ref: '#/components/schemas/RuleResult' example: - ID: 42e113f9-9353-4e89-9f68-69b92f423b0c licenseID: 13381337 createdAt: '2026-06-30T22:02:08.901Z' createdBy: f56caf69-3f05-4386-9567-fdc909d7ad77 createdByType: agent updatedAt: '2026-06-30T22:02:08.901Z' updatedBy: f56caf69-3f05-4386-9567-fdc909d7ad77 name: Pending to closed description: Set ticket to closed after 3 days when pending type: tickets ordering: 100 active: true quantifier: all triggers: [] actions: [] useCounter: 153 components: schemas: RuleResult: allOf: - $ref: '#/components/schemas/ObjectBase' - $ref: '#/components/schemas/RuleBase' ObjectBase: type: object properties: ID: type: string description: Unique object identifier. format: uuid licenseID: type: integer description: Unique account identifier. createdAt: type: string description: The time of creation. format: date-time createdBy: type: string description: The creator identifier. format: uuid createdByType: type: string enum: - agent - client - system description: The creator type. updatedAt: type: string description: The time of last modification. format: date-time updatedBy: type: string description: The modification author identifier. format: uuid RuleBase: type: object properties: name: type: string description: The rule name. description: type: string description: The rule description. type: type: string enum: - tickets description: The rules domain. ordering: type: integer description: The rule execution order. active: type: boolean description: Is rule active. quantifier: type: string enum: - all - any description: | | Quantifier | Description | |-|-| | `all` | all triggers are required to invoke actions (AND) | | `any` | any trigger suffice to invoke actions (OR) | triggers: type: array items: $ref: '#/components/schemas/RuleTrigger' actions: type: array items: $ref: '#/components/schemas/RuleAction' useCounter: type: number description: The rule use counter. RuleTrigger: type: object RuleAction: oneOf: - $ref: '#/components/schemas/RuleAssignAction' - $ref: '#/components/schemas/RuleSendRatingRequestAction' - $ref: '#/components/schemas/RuleSendFollowUpAction' - $ref: '#/components/schemas/RuleMessageAction' - $ref: '#/components/schemas/RuleStatusAction' - $ref: '#/components/schemas/RulePriorityAction' - $ref: '#/components/schemas/RuleSpamAction' - $ref: '#/components/schemas/RuleAddTagsAction' - $ref: '#/components/schemas/RuleRemoveTagsAction' - $ref: '#/components/schemas/RuleAddFollowersAction' - $ref: '#/components/schemas/RuleRemoveFollowersAction' RuleAssignAction: type: object properties: type: enum: - assign teamID: type: string description: The team ID. nullable: true randomAgent: type: boolean description: Assign to random agent. roundRobin: type: boolean description: Assign in round robin. agentID: type: string description: The agent ID. nullable: true required: - type - teamID RuleSendRatingRequestAction: type: object properties: type: enum: - sendRatingRequest template: type: object properties: text: type: string description: Must be a mustache template. cannedResponseID: type: string description: The canned response ID. required: - type RuleSendFollowUpAction: type: object properties: type: enum: - sendFollowUp template: type: object properties: text: type: string description: Must be a mustache template. cannedResponseID: type: string description: The canned response ID. skipPitL: type: boolean description: >- Skip sending this system message to people in the loop (ticket CC recipients). required: - type RuleMessageAction: type: object properties: type: enum: - message template: type: object properties: text: type: string description: Must be a mustache template. cannedResponseID: type: string description: The canned response ID. isPrivate: type: boolean description: Is message private. skipPitL: type: boolean description: >- Skip sending this system message to people in the loop (ticket CC recipients). required: - type RuleStatusAction: type: object properties: type: enum: - status status: type: string enum: - open - pending - onhold - solved - closed required: - type - status RulePriorityAction: type: object properties: type: enum: - priority priority: type: number enum: - -10 - 0 - 10 - 20 required: - type - priority RuleSpamAction: type: object properties: type: enum: - spam spam: type: boolean required: - type - spam RuleAddTagsAction: type: object properties: type: enum: - addTags tagIDs: type: array items: type: string example: 5f4b1f3b-4b7b-4b7b-8b7b-4b7b4b7b4b7b uniqueItems: true minItems: 0 maxItems: 200 description: An array of tags IDs. required: - type - tagIDs RuleRemoveTagsAction: type: object properties: type: enum: - removeTags tagIDs: type: array items: type: string example: 5f4b1f3b-4b7b-4b7b-8b7b-4b7b4b7b4b7b uniqueItems: true minItems: 0 maxItems: 200 description: An array of tags IDs. required: - type - tagIDs RuleAddFollowersAction: type: object properties: type: enum: - addFollowers followers: type: array items: type: string example: 5f4b1f3b-4b7b-4b7b-8b7b-4b7b4b7b4b7b uniqueItems: true minItems: 0 maxItems: 200 description: An array of follower IDs. required: - type - followers RuleRemoveFollowersAction: type: object properties: type: enum: - removeFollowers followers: type: array items: type: string example: 5f4b1f3b-4b7b-4b7b-8b7b-4b7b4b7b4b7b uniqueItems: true minItems: 0 maxItems: 200 description: An array of follower IDs. required: - type - followers securitySchemes: PersonalAccessToken: type: http scheme: basic description: >- Use your `account ID` as the username and your personal access token (PAT) as the password, or pass a Base64-encoded value directly in the Authorization header. For more information, see the personal access tokens guide. BearerAuth: type: http scheme: bearer description: Authenticate using an OAuth 2.0 Bearer token. x-example: us-south1:MQraNrGCsoJvtxD7KNJQB1kM3d5 ````