> ## Documentation Index
> Fetch the complete documentation index at: https://docs.routera.io/llms.txt
> Use this file to discover all available pages before exploring further.

# List tickets

> GET /tickets — paginated list with optional property filter

## Endpoint

```http theme={null}
GET https://api.routera.io/tickets
```

**Route:** `/tickets`\
**Authentication:** Bearer JWT

## Query parameters

| Parameter    | Type    | Default            | Description                                                                                                                                                                                                                                         |
| ------------ | ------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `properties` | string  | *(defaults below)* | Comma-separated list of **additional** property names to include alongside the default set for this object type (e.g. `?properties=phone`). Names already in the default set are not duplicated. Invalid or disallowed property names return `400`. |
| `archived`   | boolean | `false`            | Set to `true` to include archived objects                                                                                                                                                                                                           |
| `limit`      | integer | `10`               | Maximum number of results (10–100)                                                                                                                                                                                                                  |
| `offset`     | integer | `0`                | Pagination offset                                                                                                                                                                                                                                   |

## Default response fields

When `properties` is omitted, each item in `data` includes:

| Property       | Description                                      |
| -------------- | ------------------------------------------------ |
| `id`           | Internal object ID                               |
| `ticket_name`  | Custom or system field (flat on the object)      |
| `pipeline`     | Custom or system field (flat on the object)      |
| `ticket_owner` | Assigned owner email                             |
| `external_id`  | External identifier (nullable)                   |
| `archived`     | `false` when active; ISO timestamp when archived |

<Note>
  `created_at` and `updated_at` are always included in every response (ISO 8601 UTC), even when not listed above. When an object is **archived**, `archived_by` is also included automatically.
</Note>

## Response

**200** — Paginated list

```json theme={null}
{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "external_id": "ext-001",
      "created_at": "2026-05-01T10:00:00.000Z",
      "updated_at": "2026-05-28T12:00:00.000Z",
      "archived": false,
      "ticket_name": "Support request",
      "pipeline": "default",
      "ticket_stage": "new",
      "ticket_owner": "jane@example.com"
    }
  ],
  "pagination": {
    "limit": 10,
    "offset": 0,
    "count": 1
  }
}
```

## Errors

| Status | When                                                             |
| ------ | ---------------------------------------------------------------- |
| `400`  | Invalid `properties` query (empty list or invalid property name) |
| `401`  | Missing or invalid account context in JWT                        |
| `500`  | Internal server error                                            |

```json theme={null}
{ "message": "Invalid property name: example", "error": true }
```


## OpenAPI

````yaml GET /tickets
openapi: 3.0.1
info:
  title: Routera API
  description: >-
    Routera v2 REST API. Objects CRUD for contacts, companies, deals, and
    tickets, routers read API, plus router dispatch.
  version: 1.0.0
servers:
  - url: https://api.routera.io
    description: >-
      API Gateway base URL (override with ROUTERA_API_BASE_URL when generating
      docs)
security: []
tags:
  - name: Authentication
    description: Access token issuance
  - name: Contacts
    description: Contact records
  - name: Companies
    description: Company records
  - name: Deals
    description: Deal records
  - name: Tickets
    description: Ticket records
  - name: Routers
    description: Router configuration
  - name: Dispatch
    description: Router assignment
paths:
  /tickets:
    get:
      tags:
        - Tickets
      summary: List tickets
      operationId: listTickets
      parameters:
        - name: properties
          in: query
          description: >-
            Comma-separated additional property names to include alongside
            defaults (e.g. phone). Invalid or disallowed names return 400.
          schema:
            type: string
        - name: archived
          in: query
          description: Include archived objects when true
          schema:
            type: boolean
        - name: limit
          in: query
          description: Maximum results (default 10, max 100)
          schema:
            type: integer
            default: 10
            minimum: 1
            maximum: 100
        - name: offset
          in: query
          description: Pagination offset (default 0)
          schema:
            type: integer
            default: 0
            minimum: 0
      responses:
        '200':
          description: Paginated list
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ListResponse'
                  - properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/Ticket'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      security:
        - bearerAuth: []
components:
  schemas:
    ListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
        pagination:
          $ref: '#/components/schemas/Pagination'
    Ticket:
      type: object
      properties:
        id:
          type: string
        external_id:
          type: string
          nullable: true
        ticket_name:
          type: string
          nullable: true
        pipeline:
          type: string
          nullable: true
        ticket_owner:
          type: string
          nullable: true
          description: Assigned owner email
          example: jane@example.com
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        archived:
          description: false when active, or ISO timestamp when archived
          oneOf:
            - type: boolean
            - type: string
              format: date-time
        archived_by:
          type: string
    ApiError:
      type: object
      required:
        - message
        - error
      properties:
        message:
          type: string
        error:
          type: boolean
          enum:
            - true
        field:
          type: string
          description: Field that caused a conflict (409 duplicate responses)
    Pagination:
      type: object
      properties:
        limit:
          type: integer
        offset:
          type: integer
        count:
          type: integer
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Bearer JWT with valid account context.

````