API Reference

Події

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

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

Список подій

GET /events

cURL

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.

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