{"openapi":"3.1.0","info":{"title":"Ateneo API","version":"1.0.0","description":"Ateneo's public API connects management software (box office, membership, school or event platforms) with an organization's events and bookings. Access uses an API key or an OAuth2 client of the organization (paid plans), and each credential only sees its own organization's data. Amounts are in hundredths of the organization's currency. Webhook deliveries are signed: the X-Ateneo-Signature header carries t=<timestamp>,v1=<HMAC-SHA256 of the secret over \"<timestamp>.<body>\">. Human-readable docs: https://ateneo.app/en/api","contact":{"name":"Oksigenia","url":"https://ateneo.app"}},"servers":[{"url":"https://ateneo.app/api/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"`Authorization: Bearer <credential>`. The credential is an organization API key (`atn_live_…`, admin panel → API) or an OAuth access token obtained from `/oauth/token` (client credentials). Both carry scopes and only see their own organization's data."}},"schemas":{"TokenRequest":{"type":"object","required":["grant_type"],"properties":{"grant_type":{"type":"string","enum":["client_credentials"]},"client_id":{"type":"string","description":"Required unless sent with HTTP Basic auth."},"client_secret":{"type":"string","description":"Required unless sent with HTTP Basic auth."},"scope":{"type":"string","description":"Optional: a subset of the client's scopes, space-separated."}}}},"responses":{"Unauthorized":{"description":"Missing or invalid credential"},"Forbidden":{"description":"The credential lacks the scope this operation needs"},"PlanRequired":{"description":"The organization's plan does not include the API, the organization is suspended for non-payment (read-only), or it has reached its plan's limit of active events"},"NotFound":{"description":"Not found (or not in your organization)"},"RateLimited":{"description":"Too many requests; see the Retry-After header"}}},"paths":{"/oauth/token":{"post":{"summary":"OAuth2 client credentials: get an access token","description":"Exchanges client_id and client_secret for a short-lived (1 hour) Bearer token with the client's scopes. An alternative to a static API key. Credentials go in the body (form or JSON) or in HTTP Basic auth.","security":[],"requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/TokenRequest"}},"application/json":{"schema":{"$ref":"#/components/schemas/TokenRequest"}}}},"responses":{"200":{"description":"Token issued","content":{"application/json":{"schema":{"type":"object","properties":{"access_token":{"type":"string"},"token_type":{"type":"string","example":"Bearer"},"expires_in":{"type":"integer","example":3600},"scope":{"type":"string"}}}}}},"400":{"description":"invalid_request / unsupported_grant_type / invalid_scope"},"401":{"description":"invalid_client"}}}},"/events":{"get":{"summary":"List the organization's events","responses":{"200":{"description":"OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PlanRequired"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"summary":"Create an event on one of the organization's seating charts","description":"Requires the events:write scope. Creates an open event (booking window already open) with a default session on one of your organization's seating charts (`layoutId`). If `managerEmail` is given, that person becomes the event manager. Emits the `event.published` webhook.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["layoutId"],"properties":{"layoutId":{"type":"integer"},"name":{"type":"string"},"managerEmail":{"type":"string","format":"email"}}}}}},"responses":{"201":{"description":"Created: {eventId, passId, managerUserId}"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PlanRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"The seating chart does not exist or is not in your organization"},"422":{"description":"Missing layoutId"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/events/{id}":{"get":{"summary":"Get an event and its sessions","description":"Amounts (each session's price) are in hundredths of the organization's currency, given in event.currency (ISO 4217): 1250 with EUR = €12.50; 1500000 with PYG = ₲15,000.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/events/{id}/availability":{"get":{"summary":"Seating chart capacity and seats taken in each session","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/events/{id}/roster":{"put":{"summary":"Replace the event's guest list (sent by your management software)","description":"Requires the roster:write scope. Fully replaces the event's list with the given entries. `maxSeats` caps each person's seats; entries sharing a `groupKey` (a family, a company) share one cap.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["entries"],"properties":{"entries":{"type":"array","items":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email"},"name":{"type":"string"},"role":{"type":"string","enum":["apuntador","acomodador","usuario"],"description":"Optional staff role for this event: `apuntador` (booking clerk: books on behalf of others), `acomodador` (usher: checks people in at the door) or `usuario` (regular attendee, the default)."},"maxSeats":{"type":"integer","minimum":1},"groupKey":{"type":"string"}}}}}}}}},"responses":{"200":{"description":"OK: {ok, count, withRole}"},"402":{"$ref":"#/components/responses/PlanRequired"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"Invalid body"}}}},"/events/{id}/reservations":{"post":{"summary":"Pre-book seats in someone's name (from your management software)","description":"Requires the reservations:write scope. Books seats in someone's name (by email) without waiting for the public booking window, so the organization can assign seats before opening. `count` takes the first N free seats; or pass explicit `seatIds`. If the event is paid, `tariffIndex` is required and the price is fixed on the server. `passId` is optional when the event has a single session.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email"},"name":{"type":"string"},"passId":{"type":"integer"},"count":{"type":"integer","minimum":1,"maximum":20},"seatIds":{"type":"array","items":{"type":"integer"}},"tariffIndex":{"type":"integer","minimum":0},"groupKey":{"type":"string"},"maxSeats":{"type":"integer","minimum":1}}}}}},"responses":{"201":{"description":"Created: {ok, email, passId, seatIds, reservationIds}"},"402":{"$ref":"#/components/responses/PlanRequired"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"The event is closed, has no free seats, or one of the seats is already booked"},"422":{"description":"Invalid body (email, fare, seats or per-person limit)"}}}},"/reservations":{"get":{"summary":"One person's bookings, by email address","parameters":[{"name":"email","in":"query","required":true,"schema":{"type":"string","format":"email"}}],"responses":{"200":{"description":"OK"},"400":{"description":"Missing email"}}}},"/webhooks":{"get":{"summary":"List the organization's webhooks","description":"Never returns the secret (it is shown only once, when the webhook is created).","responses":{"200":{"description":"OK: {webhooks:[{id, url, events, enabled, failCount, lastStatus, lastAttemptAt, createdAt}]}"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PlanRequired"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"summary":"Register a webhook","description":"Requires the webhooks:write scope. The URL must use https and must not point to internal networks. Returns the `secret` only ONCE (to verify the HMAC signature of deliveries). Unknown events are ignored.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url","events"],"properties":{"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string","enum":["reservation.created","reservation.cancelled","pass.soldout","event.published"]}}}}}}},"responses":{"201":{"description":"Created: {id, url, events, secret}"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PlanRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"description":"Unsafe URL or no valid events"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/webhooks/{id}":{"delete":{"summary":"Delete a webhook","description":"Requires the webhooks:write scope. Idempotent.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK: {ok:true}"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PlanRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"description":"Invalid id"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/webhooks/{id}/test":{"post":{"summary":"Send a test ping to a webhook","description":"Requires the webhooks:write scope. Sends a signed `ping` event to that webhook (no retries) and returns your endpoint's HTTP status.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK: {ok, status} of your endpoint"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PlanRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"Invalid id"},"429":{"$ref":"#/components/responses/RateLimited"}}}}}}