## List tickets

`GET /v1/feedback`

Returns a list of tickets with filters and pagination. A regular key sees only its own tickets (submitted with the same key), a key with the `vibe:feedback` scope — all tickets of its Bitrix24 account.

## Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|:--------:|---------|-------------|
| `status` (query) | string | no | — | `NEW`, `REVIEWING`, `AWAITING_USER`, `NEEDS_REVIEW`, `RESOLVED`, `ARCHIVED`, `WITHDRAWN`. Case-insensitive |
| `category` (query) | string | no | — | `BUG`, `SUGGESTION`, `DOCS`, `CHAT`, `BOTS`, `OTHER`. Case-insensitive |
| `offset` (query) | number | no | `0` | How many records to skip |
| `page` (query) | number | no | `1` | Page-based pagination. Used when `offset` is not set |
| `limit` (query) | number | no | `20` | Page size, from 1 to 100 |

To page through results, use `offset` — for example `offset=100&limit=50`. The `offset` field in the response echoes the applied offset. If `offset` is not passed, `page` is used.

The `status` and `category` filters are case-insensitive (`status=new` is equivalent to `status=NEW`). An unknown value returns `400 INVALID_FILTER_VALUE` — a typo in a filter is rejected explicitly rather than returning the whole list.

## Examples

### curl — personal key

```bash
curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://vibecode.bitrix24.com/v1/feedback?status=NEW&category=BUG&limit=20"
```

### curl — OAuth application

```bash
curl -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  "https://vibecode.bitrix24.com/v1/feedback?status=NEW&category=BUG&limit=20"
```

### JavaScript — personal key

```javascript
const res = await fetch(
  'https://vibecode.bitrix24.com/v1/feedback?status=NEW&category=BUG&limit=20',
  { headers: { 'X-Api-Key': 'YOUR_API_KEY' } },
)
const { data, total } = await res.json()
```

### JavaScript — OAuth application

```javascript
const res = await fetch(
  'https://vibecode.bitrix24.com/v1/feedback?status=NEW&category=BUG&limit=20',
  { headers: { 'X-Api-Key': 'YOUR_APP_KEY', 'Authorization': 'Bearer USER_SESSION_TOKEN' } },
)
const { data, total } = await res.json()
```

## Response fields

| Field | Type | Description |
|-------|------|-------------|
| `success` | boolean | Always `true` on success |
| `data` | array | Array of tickets |
| `data[].id` | string | Ticket UUID |
| `data[].category` | string | Category |
| `data[].title` | string | Title |
| `data[].body` | string | Description |
| `data[].status` | string | Current status |
| `data[].source` | string | `api` or `ui` |
| `data[].resolution` | string · null | Resolution text, if the ticket is closed |
| `data[].attachmentCount` | number | Number of attachments |
| `data[].createdAt` | string | Creation date (ISO 8601) |
| `data[].resolvedAt` | string · null | Closing date, if any |
| `total` | number | Total records matching the filter |
| `page` | number | Current page |
| `limit` | number | Page size |
| `offset` | number | Applied offset |

A key with the `vibe:feedback` scope additionally receives the `portalDomain`, `userName`, `userId`, `apiKeyId` fields in each record — who submitted the ticket and with which key.

## Response example

```json
{
  "success": true,
  "data": [
    {
      "id": "a1b2c3d4-1111-2222-3333-444455556666",
      "category": "BUG",
      "title": "POST /v1/deals/search returns 500 on empty filter",
      "body": "Calling POST /v1/deals/search with body {\"filter\":{}} gives a 500.",
      "status": "NEW",
      "source": "api",
      "resolution": null,
      "attachmentCount": 0,
      "createdAt": "2026-04-19T10:30:00.000Z",
      "resolvedAt": null
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20,
  "offset": 0
}
```

## Error response example

400 — unknown filter value:

```json
{
  "success": false,
  "error": {
    "code": "INVALID_FILTER_VALUE",
    "message": "Invalid status 'BOGUS'. Allowed values: NEW, REVIEWING, AWAITING_USER, NEEDS_REVIEW, RESOLVED, ARCHIVED, WITHDRAWN."
  }
}
```

## Errors

| HTTP | Code | Description |
|------|------|-------------|
| 400 | `INVALID_FILTER_VALUE` | An unknown `status` or `category` value was passed |
| 401 | `MISSING_API_KEY` | The `X-Api-Key` header was not passed |

For the full list of common API errors, see [Errors](/docs/errors).

## See also

- [Get a ticket](/docs/feedback/get)
- [Submit a ticket](/docs/feedback/submit)
- [Feedback](/docs/feedback)
- [Errors](/docs/errors)