---
title: "Події · API Reference: документація AOA API"
description: "Ендпоінти для пошуку подій, деталей, типів квитків і поточної доступності місць."
canonical: "https://aoa.com.ua/docs/api-reference/events"
---

# Події

Ендпоінти для пошуку подій, деталей, типів квитків і поточної доступності місць.

Чотири ендпоінти для читання. Ключ не обовʼязковий, але з ним ліміт вищий. Показуються лише опубліковані публічні події, які ще не завершились.

## Список подій

**GET** `/events`

```bash
curl "https://aoa.com.ua/api/v1/events?city=Київ&category=workshop&limit=20" \
  -H "Authorization: Bearer aoa_live_…"
```

### Параметри

| Параметр | Тип | Опис |
| --- | --- | --- |
| `city` | string | Назва міста. Порівняння точне, без урахування регістру: «Київ» спрацює, «Киев» чи «Ки» — ні. |
| `category` | string | Категорія події. Невідоме значення дає 400 зі списком у повідомленні. |
| `limit` | integer | Скільки подій повернути. За замовчуванням 50, максимум 100. |

Пагінації немає

За один запит можна отримати щонайбільше 100 подій, зсуву чи курсора поки не передбачено. Якщо вам потрібен повний каталог більшого обсягу — напишіть нам.

### Категорії

`dj-set`, `live-music`, `party`, `book-event`, `performance`, `art-exhibition`, `market`, `workshop`, `lecture`, `networking`, `open-space`, `movie-screening`, `other`

### Відповідь

```json
{
  "data": [
    {
      "id": "a1b2c3",
      "url": "https://aoa.com.ua/events/a1b2c3",
      "title": "Джаз-вечір",
      "startAt": "2026-08-15T18:00:00.000Z",
      "endAt": "2026-08-15T22:00:00.000Z",
      "imageUrl": "https://aoa.com.ua/uploads/events/cover.jpg",
      "eventType": "live_music",
      "status": "published",
      "city": "Київ",
      "venue": "Coffee Lab"
    }
  ],
  "meta": { "count": 1, "total": 1, "limit": 20 }
}
```

`meta.total` — скільки подій підійшло під фільтри, `meta.count` — скільки повернули з урахуванням ліміту. Усі поля, крім `id`, `url` і `title`, можуть бути `null`. Події відсортовані за датою початку.

## Деталі події

**GET** `/events/{eventId}`

Замість `eventId` підійде як короткий ідентифікатор із посилання, так і повний внутрішній.

```json
{
  "data": {
    "id": "a1b2c3",
    "url": "https://aoa.com.ua/events/a1b2c3",
    "title": "Джаз-вечір",
    "description": "Живий джаз у затишному просторі",
    "imageUrl": "https://aoa.com.ua/uploads/events/cover.jpg",
    "startAt": "2026-08-15T18:00:00.000Z",
    "endAt": "2026-08-15T22:00:00.000Z",
    "allDay": false,
    "eventType": "live_music",
    "status": "published",
    "attendanceMode": "offline",
    "capacity": 120,
    "location": {
      "name": "Coffee Lab",
      "address": "вул. Хрещатик, 1",
      "city": "Київ"
    },
    "organizer": {
      "name": "Coffee Lab",
      "url": "https://aoa.com.ua/o/coffee-lab"
    },
    "refundPolicy": {
      "refundsEnabled": true,
      "refundDeadlineHours": 24
    },
    "ticketTypes": [ … ]
  }
}
```

Кілька особливостей, які варто врахувати:

- `organizer` присутній завжди. Якщо подію створено не від імені організації, там буде AOA.
- `location` може бути `null` — наприклад, коли адресу ще не вказали.
- `ticketTypes` дублює вміст окремого ендпоінта: якщо потрібні лише квитки, беріть його — відповідь менша.
- Видалена подія дає `410`, а неопублікована — `404`.

## Типи квитків

**GET** `/events/{eventId}/ticket-types`

```json
{
  "data": [
    {
      "id": "clx9ticket001",
      "name": "Standard",
      "priceMinor": 45000,
      "priceDecimal": "450.00",
      "currency": "UAH",
      "isFree": false,
      "capacity": 100,
      "sold": 37,
      "remaining": 63,
      "salesStart": "2026-07-01T00:00:00.000Z",
      "salesEnd": "2026-08-15T17:00:00.000Z",
      "status": "on_sale"
    }
  ],
  "meta": { "count": 1 }
}
```

### Ціни

Рахуйте на `priceMinor` — це копійки цілим числом. `priceDecimal` дано лише для показу. Поле `isFree` істинне і для нульової ціни, і для типу без ціни.

### Наявність

`capacity: null` означає тип без обмеження місць — тоді `remaining` теж `null`, і це не помилка.

| status | Значення |
| --- | --- |
| `on_sale` | Продається зараз |
| `sold_out` | Місць не лишилось |
| `sales_not_started` | Продаж ще не почався |
| `sales_ended` | Продаж завершено |

Типи, приховані організатором на сторінці події, через API не віддаються.

## Поточна доступність

**GET** `/events/{eventId}/availability`

Найсвіжіші залишки. На відміну від `ticket-types`, тут враховані активні резерви й незавершені оплати — тобто число показує, скільки квитків справді можна купити цієї миті.

```json
{
  "data": {
    "eventId": "a1b2c3",
    "ticketTypes": {
      "clx9ticket001": 63,
      "clx9ticket002": 0
    },
    "checkedAt": "2026-07-30T12:34:56.789Z"
  }
}
```

`ticketTypes` — це обʼєкт, де ключ це ідентифікатор типу, а значення — залишок. Типи без обмеження місць у ньому відсутні.

Порожня відповідь неоднозначна

Порожній

`ticketTypes: {}`

означає або що в події немає типів з обмеженням місць, або що сервіс залишків тимчасово недоступний. Розрізнити ці випадки з відповіді не можна, тому не трактуйте порожній обʼєкт як «все розпродано» — звіряйтесь із

`ticket-types`

.

Це найдешевший спосіб оновлювати залишки: одна відповідь покриває всі типи квитків події.