API reference
The AOA public API for finding venues and events, booking tables and selling tickets: base URL and response format.
The AOA API gives you access to published venues and events, and lets you book tables and sell tickets from your own app, bot or AI agent. Search and availability are open without a key: you only need one for actions that change state.
Base URL: https://aoa.com.ua/api/v1
Upcoming events in Kyiv. No key needed:
curl "https://aoa.com.ua/api/v1/events?city=Київ&limit=10"You can try bookings, ticket payments and webhooks without creating anything for real in the sandbox: the same endpoints on test data, with a test key you make up yourself.
Every response has the same shape. A success returns an object with a data field, and lists add meta:
{
"data": [ … ],
"meta": { "count": 10, "total": 42, "limit": 10 }
}An error always comes in the error field with a stable code:
{
"error": {
"code": "not_found",
"message": "Event not found"
}
}Check for error rather than the HTTP status, so your handling stays the same if a status is ever refined. The list of codes is on the Errors page.
| Action | Endpoint | Key required |
|---|---|---|
| Find venues | GET/locations | No |
| Check free time slots | GET/locations/{locationId}/availability | No |
| Book a table after confirmation | POST/table-reservations | Yes |
| Find events | GET/events | No |
| Event details | GET/events/{eventId} | No |
| Ticket types and prices | GET/events/{eventId}/ticket-types | No |
| Seats left | GET/events/{eventId}/availability | No |
| Hold tickets for 15 minutes | POST/reservations | Yes |
| Create a payment | POST/checkout | Yes |
| Order status | GET/orders/{paymentId} | Yes |
/events and show the buyer prices from ticket-types./reservations. This step is optional, but without it popular tickets can sell out in the meantime./checkout and send the buyer to paymentUrl./orders/{paymentId} every 5–10 seconds until the status becomes SUCCESS.We send the ticket to the buyer: after a successful payment, an email with the ticket goes to the address they gave, automatically.
This is a server-to-server API
The endpoints don’t return CORS headers, so you can’t call them directly from a browser page. The key must not be exposed on the client anyway: keep the calls on your server.2026-08-15T18:00:00.000Z).priceMinor. The priceDecimal field is there for display; always do the math in kopiyky.id in responses is a short public identifier, the same one as in the event page link.A machine-readable description is available at https://aoa.com.ua/api/v1/openapi.json. You can feed it to a client generator or connect it to an AI agent. This documentation describes the behavior more precisely than the specification, so where they differ, go by the documentation.
Official SDKs for TypeScript, Python and Go, skills for AI agents and configs for coding assistants (AGENTS.md, plugin.json) live in the open repository github.com/aoa-ua/aoa-agent-kit. The SDKs are generated from this specification and updated along with it.
Versioning: the version is part of the path (/api/v1). Breaking changes ship only in a new version. Every API response carries a Link header with rel="deprecation" and rel="sunset" pointing to this policy page. A deprecated endpoint is also marked with the Deprecation and Sunset headers (RFC 9745, RFC 8594) at least 90 days before it is switched off, and the shutdown date is repeated in the documentation.