Tickiti

List responses API

This article and the rest of the API documentation in this section are written for a technical audience — integrators and developers connecting external systems to Tickiti. Familiarity with HTTP, REST, JSON and bearer-token authentication is assumed.

The responses endpoint returns just the conversation on a ticket — the same responses array Show ticket returns, without the ticket header, participants or links. Use it when you already know the ticket and only need its replies: to read the thread including internal staff notes, or to enumerate a response’s attachments before downloading one.

Endpoint

POST /api/v1/tickets/responses

Headers

  1. Authorization: Bearer YOUR_TOKEN — required. Token must have the tickets:read ability. A tickets:write token also works (write implies read).
  2. Content-Type: application/json — required. No Idempotency-Key is needed (this is a read).

Body

Required fields:

  1. ticket_number — the 6-digit number of the ticket whose responses to list, as a string. Alternatively send ticket_id, the ticket’s internal id. Send exactly one of the two. The ticket must exist and be visible to the acting user.

Optional fields:

  1. fields — an array choosing which of the heavy response fields to return: any of html, plain_text, attachments. Defaults to all three. The metadata fields (id, flags, author, dates, audit, body_chars) are always returned.
  2. max_body_chars — a whole number. Cuts each response’s html and plain_text to this many characters; a field that was cut gains html_truncated: true or plain_text_truncated: true.

Example

curl -X POST https://support.sole-provider.example/api/v1/tickets/responses \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ticket_number": "220009",
    "fields": ["plain_text"],
    "max_body_chars": 4000
  }'

Successful response

An ordered responses array (pinned first, then oldest to newest), identical in shape to the array Show ticket returns — see Show ticket API for what each field means, including plain_text, body_chars, audit and is_audit_only. Includes internal staff notes (is_internal: true), which is the value over the summary-only List tickets endpoint.

{
  "ok": true,
  "data": {
    "ticket_number": 220009,
    "responses": [
      {
        "id": "41",
        "is_internal": true,
        "is_pinned": false,
        "staff_response": true,
        "created_by_email": "[email protected]",
        "created_at": "2026-05-02T10:05:11+00:00",
        "updated_at": "2026-05-02T10:05:11+00:00",
        "is_email_sourced": false,
        "audit": null,
        "is_audit_only": false,
        "body_chars": 38,
        "html": "<p>Internal note: replacement authorised.</p>",
        "plain_text": "Internal note: replacement authorised.",
        "attachments": []
      }
    ]
  }
}

Error responses

  1. 422 validation_failed — neither or both of ticket_number and ticket_id, or an invalid fields value or max_body_chars.
  2. 404 not_found — no ticket has that number or id.
  3. 401 unauthenticated — bad or missing token.
  4. 403 forbidden — token lacks the tickets:read (or tickets:write) ability, the user it acts as lacks access to the ticket, or the token owner is not a staff account.

What happens server-side

  1. Tickiti locates the ticket by ticket_number or ticket_id and applies the same access check as the staff interface.
  2. It returns every non-deleted response on the ticket — public and internal — each with its attachment metadata, projected per fields and max_body_chars.

To search responses across many tickets at once, use the Cross-ticket responses API; to read one response by id, move responses between tickets or edit and delete them, see the Ticket operations API.