{ "components": { "schemas": { "dto.APIError": { "properties": { "data": { "description": "Data carries optional structured context for the error." }, "fields": { "additionalProperties": { "type": "string" }, "description": "Fields maps a request field to a validation message, when applicable.", "type": "object" }, "msg": { "description": "Msg is a human-readable description of what went wrong.", "example": "seat is no longer available", "type": "string" }, "timestamp": { "description": "Timestamp is when the error was produced (RFC 3339).", "example": "2026-06-20T18:00:00Z", "type": "string", "format": "date-time" }, "traceId": { "description": "TraceID identifies this request in our logs; include it in support asks.", "example": "01JABCDoftraceZ", "type": "string" }, "type": { "$ref": "#/components/schemas/dto.ErrorCode" } }, "type": "object" }, "dto.ErrorCode": { "description": "Type is the stable, machine-readable error code.", "enum": [ "INVALID_PAYLOAD", "VALIDATION_FAILED", "NOT_FOUND", "CONFLICT", "FORBIDDEN", "VERIFICATION_REQUIRED", "INTERNAL_ERROR", "INVALID_PAYLOAD", "VALIDATION_FAILED", "NOT_FOUND", "CONFLICT", "FORBIDDEN", "VERIFICATION_REQUIRED", "INTERNAL_ERROR" ], "example": "CONFLICT", "type": "string", "x-enum-varnames": [ "ErrInvalidPayload", "ErrValidationFailed", "ErrNotFound", "ErrConflict", "ErrForbidden", "ErrVerificationRequired", "ErrInternal" ] }, "dto.PublicAvailability": { "properties": { "gaRemaining": { "additionalProperties": { "type": "integer" }, "description": "GARemaining maps a standing area id to its remaining capacity.", "type": "object" }, "lowStockThreshold": { "description": "LowStockThreshold is where \"low stock\" begins for this event — clients\nshow the low-stock line when remaining ≤ threshold. 0 = signal off.", "example": 10, "type": "integer" }, "recentOrders": { "description": "RecentOrders counts orders placed in the last 30 minutes — a live\nactivity signal for urgency UI. Always 0 when the event disabled the\nsocial-proof signal; clients choose their display threshold.", "example": 4, "type": "integer" }, "reservedSeats": { "description": "ReservedSeats marks which unavailable seats are merely reserved and may\nfree up again — present only when the event shares reserved status.", "example": [ "1810000000000000502" ], "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "showReserved": { "description": "ShowReserved mirrors the event's \"share reserved status\" setting, so\nclients can hide the reserved legend/state entirely when it is off.", "example": true, "type": "boolean" }, "ticketTypeRemaining": { "additionalProperties": { "type": "integer" }, "description": "TicketTypeRemaining maps a ticket type id to its remaining capacity.", "type": "object" }, "unavailableSeats": { "description": "UnavailableSeats lists the ids of seats that cannot currently be bought.", "example": [ "1810000000000000501", "1810000000000000502" ], "items": { "type": "string" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "dto.PublicCheckoutTheme": { "description": "CheckoutTheme customises the hosted checkout; null = Bookitive defaults.", "properties": { "buttonLabel": { "description": "ButtonLabel overrides the submit button text.", "example": "Objednat", "type": "string" }, "fontFamily": { "description": "FontFamily is an allowlisted font key (self-hosted by Bookitive).", "example": "inter", "type": "string" }, "mode": { "description": "Mode is the colour scheme: \"light\" or \"dark\".", "enum": [ "light", "dark" ], "example": "light", "type": "string" }, "radius": { "description": "Radius is the corner radius for fields and buttons.", "example": "12px", "type": "string" } }, "type": "object" }, "dto.PublicDiscount": { "properties": { "code": { "description": "Code is the normalized (uppercase) promo code.", "example": "EARLYBIRD", "type": "string" }, "kind": { "description": "Kind is how the discount applies: \"percent\" of the items subtotal, or a\n\"fixed\" amount in the event currency's minor units.", "enum": [ "percent", "fixed" ], "example": "percent", "type": "string" }, "value": { "description": "Value is 1-100 for percent, minor units for fixed.", "example": 10, "type": "integer" } }, "type": "object" }, "dto.PublicEvent": { "properties": { "event": { "$ref": "#/components/schemas/dto.PublicEventInfo" }, "floors": { "description": "Floors lets a host page render its floor tabs without loading the full\nseating payload; ids match the seating endpoint's floors.", "items": { "$ref": "#/components/schemas/dto.PublicFloorInfo" }, "type": "array", "uniqueItems": false }, "org": { "$ref": "#/components/schemas/dto.PublicOrg" }, "protection": { "$ref": "#/components/schemas/dto.PublicProtection" }, "ticketTypes": { "description": "TicketTypes are the sellable ticket categories with prices and limits.", "items": { "$ref": "#/components/schemas/dto.PublicTicketType" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "dto.PublicEventInfo": { "description": "Event is the event's public identity: name, times, venue, currency.", "properties": { "currency": { "description": "Currency is the ISO 4217 code all prices are quoted in.", "example": "CZK", "type": "string" }, "endTime": { "description": "EndTime is when the event ends (RFC 3339), when known.", "example": "2026-06-20T23:00:00Z", "type": "string", "format": "date-time" }, "holdTtlSeconds": { "description": "HoldTTLSeconds is how long a checkout holds selected seats before expiry.", "example": 900, "type": "integer" }, "language": { "description": "Language ('cs' | 'en') is the event's language. The widget renders seat\nlabels in it (\"Table A4 · Seat 2\" vs \"Stůl A4 · Místo 2\"), so the live\nhover label matches the printed ticket.", "enum": [ "cs", "en" ], "example": "cs", "type": "string" }, "locationName": { "description": "LocationName is the venue's display name, when set.", "example": "Výstaviště Praha", "type": "string" }, "marketingOptinEnabled": { "description": "MarketingOptinEnabled: the organizer collects a marketing opt-in at\ncheckout — the UI renders the consent checkbox (M1).", "type": "boolean" }, "name": { "description": "Name is the event's public display name.", "example": "Rockfest 2026", "type": "string" }, "salesPaused": { "description": "SalesPaused: the organizer temporarily stopped all sales — the page\nshould say so instead of offering a checkout.", "type": "boolean" }, "salesPausedMessage": { "description": "SalesPausedMessage is the organizer's buyer-facing announcement to show\nwhile paused (e.g. \"Sales open Monday 12. 10.\"). Present only when paused\nAND a message is set; otherwise absent (the page shows its generic notice).", "type": "string" }, "slug": { "description": "Slug is the event's URL identifier (the {eventSlug} path parameter).", "example": "rockfest-2026", "type": "string" }, "startTime": { "description": "StartTime is when doors/the event begins (RFC 3339).", "example": "2026-06-20T18:00:00Z", "type": "string", "format": "date-time" }, "timezone": { "description": "Timezone is the event's IANA zone. StartTime (and every other schedule\ntimestamp here) is an absolute instant; this is the wall clock it means\nat the venue, and what a buyer should be shown wherever they are.", "example": "Europe/Prague", "type": "string" }, "waitlistEnabled": { "description": "WaitlistEnabled: sold-out ticket types accept waitlist signups (RFC 0008).", "type": "boolean" } }, "type": "object" }, "dto.PublicFloor": { "properties": { "cons": { "description": "Cons are short caveats for this floor, shown alongside the pros.", "example": [ "Standing only" ], "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "description": { "description": "Description is optional customer-facing copy shown on the floor's tab.", "example": "Standing area in front of the main stage", "type": "string" }, "id": { "description": "ID is the floor's stable id; it matches PublicFloorInfo.id.", "example": "1810000000000000101", "type": "string" }, "mode": { "description": "Mode is \"single\" (one open space) or \"sections\" (subdivided blocks).", "enum": [ "single", "sections" ], "example": "sections", "type": "string" }, "name": { "description": "Name is the floor's display label.", "example": "Ground floor", "type": "string" }, "position": { "description": "Position is the 1-based tab order among the event's floors.", "example": 1, "type": "integer" }, "pros": { "description": "Pros are short selling points for this floor, shown as a checklist.", "example": [ "Closest to the stage", "Great atmosphere" ], "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "sections": { "description": "Sections are the floor's blocks; a single-mode floor has exactly one.", "items": { "$ref": "#/components/schemas/dto.PublicSection" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "dto.PublicFloorInfo": { "properties": { "cons": { "description": "Cons are short caveats for this floor, shown alongside the pros.", "example": [ "Standing only" ], "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "description": { "description": "Description is optional customer-facing copy shown on the floor's tab.", "example": "Standing area in front of the main stage", "type": "string" }, "id": { "description": "ID is the floor's stable id; it matches a floor in the seating endpoint.", "example": "1810000000000000101", "type": "string" }, "mode": { "description": "Mode is \"single\" (one open space) or \"sections\" (subdivided blocks).", "enum": [ "single", "sections" ], "example": "sections", "type": "string" }, "name": { "description": "Name is the floor's display label.", "example": "Ground floor", "type": "string" }, "position": { "description": "Position is the 1-based tab order among the event's floors.", "example": 1, "type": "integer" }, "pros": { "description": "Pros are short selling points for this floor, shown as a checklist.", "example": [ "Closest to the stage", "Great atmosphere" ], "items": { "type": "string" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "dto.PublicGAArea": { "properties": { "capacity": { "description": "Capacity is the total number of standing tickets this area can sell.", "example": 500, "type": "integer" }, "h": { "description": "H is the area's height on the floor canvas.", "example": 200, "type": "number" }, "id": { "description": "ID is the standing area's stable id, referenced by availability/orders.", "example": "1810000000000000601", "type": "string" }, "label": { "description": "Label is the standing area's display name.", "example": "Pit", "type": "string" }, "rotation": { "description": "Rotation is the area's rotation in degrees.", "example": 0, "type": "number" }, "ticketTypeId": { "description": "TicketTypeID is the standing ticket type mapped to this area, when priced.", "example": "1810000000000000201", "type": "string" }, "w": { "description": "W is the area's width on the floor canvas.", "example": 600, "type": "number" }, "x": { "description": "X is the area's left offset on the floor canvas.", "example": 100, "type": "number" }, "y": { "description": "Y is the area's top offset on the floor canvas.", "example": 400, "type": "number" } }, "type": "object" }, "dto.PublicOrder": { "properties": { "currency": { "description": "Currency is the ISO 4217 code the total is quoted in.", "example": "CZK", "type": "string" }, "discountCents": { "description": "DiscountCents is what the redeemed promo code took off the total.", "example": 14900, "type": "integer" }, "expiresAt": { "description": "ExpiresAt is when the held seats and this order expire (RFC 3339).", "example": "2026-06-20T18:15:00Z", "type": "string", "format": "date-time" }, "payment": { "$ref": "#/components/schemas/dto.PublicPaymentDetail" }, "reference": { "description": "Reference is the order's human-facing reference (also the payment symbol).", "example": "RF26-000142", "type": "string" }, "status": { "description": "Status is the order lifecycle state at creation time. pending_review means\nthe order is held for organizer approval (RFC 0004 risk \"hold\" action).", "enum": [ "pending", "pending_review", "paid", "cancelled", "expired" ], "example": "pending", "type": "string" }, "totalCents": { "description": "TotalCents is the amount due in the event currency's minor units.", "example": 149000, "type": "integer" } }, "type": "object" }, "dto.PublicOrderCustomer": { "description": "Customer is the buyer's contact details.", "properties": { "email": { "description": "Email is where the payment instructions and tickets are sent.", "example": "jana@example.com", "type": "string" }, "name": { "description": "Name is the buyer's full name.", "example": "Jana Nováková", "maxLength": 200, "type": "string" }, "phone": { "description": "Phone is an optional contact number.", "example": "+420123456789", "maxLength": 50, "type": "string" } }, "required": [ "email", "name" ], "type": "object" }, "dto.PublicOrderItem": { "properties": { "attendees": { "description": "Attendees carries one full name per admitted person when the event\nrequires named tickets — exactly Quantity names, in ticket order.", "example": [ "Jana Nováková" ], "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "gaAreaId": { "description": "GAAreaID is the standing area's id for standing ticket types.", "example": "1810000000000000601", "type": "string" }, "quantity": { "description": "Quantity is how many to buy — always 1 for a seat, 1+ for standing.", "example": 1, "minimum": 1, "type": "integer" }, "seatId": { "description": "SeatID is the chosen seat's id for seated ticket types.", "example": "1810000000000000501", "type": "string" }, "ticketTypeId": { "description": "TicketTypeID is the ticket type being bought (from the event endpoint).", "example": "1810000000000000201", "type": "string" } }, "required": [ "quantity", "ticketTypeId" ], "type": "object" }, "dto.PublicOrderRequest": { "properties": { "captchaToken": { "description": "CaptchaToken is the client-side captcha solution, verified server-side.", "example": "03AGdBq26…", "type": "string" }, "customer": { "$ref": "#/components/schemas/dto.PublicOrderCustomer" }, "discountCode": { "description": "DiscountCode redeems a promo code (case-insensitive); the discount is\napplied to the items subtotal and enforced against the code's limits.", "example": "EARLYBIRD", "maxLength": 40, "minLength": 2, "type": "string" }, "fingerprint": { "description": "Fingerprint is a stable hash of the buyer's browser, computed client-side\nand forwarded for device-velocity risk scoring (RFC 0004); optional.", "example": "a1b2c3d4e5f6", "maxLength": 128, "type": "string" }, "items": { "description": "Items are the order lines; at least one is required.", "items": { "$ref": "#/components/schemas/dto.PublicOrderItem" }, "minItems": 1, "type": "array", "uniqueItems": false }, "marketingConsent": { "description": "MarketingConsent mirrors the checkout's marketing opt-in checkbox. Only\nsend true when the buyer explicitly ticked a consent box you showed\nthem — the value is stored as consent evidence and honoured only when\nthe organizer's opt-in setting is enabled.", "example": true, "type": "boolean" }, "verificationToken": { "description": "VerificationToken is the single-use token from the verify/check endpoint,\nrequired when the event demands a verified phone number.", "example": "3q2p8Zk1…", "type": "string" }, "waitlistClaimToken": { "description": "WaitlistClaimToken authorizes buying an offered quantity of a sold-out\ntype (RFC 0008); single-use, consumed with the order.", "type": "string" } }, "required": [ "customer", "items" ], "type": "object" }, "dto.PublicOrg": { "description": "Org is the organizer's public branding (name, logo, accent colour).", "properties": { "accentColor": { "description": "AccentColor is the organizer's brand colour as a hex string, if set.", "example": "#E5482F", "type": "string" }, "checkoutTheme": { "$ref": "#/components/schemas/dto.PublicCheckoutTheme" }, "logoUrl": { "description": "LogoURL is an absolute URL to the organizer's logo, if set.", "example": "https://cdn.bookitive.com/orgs/rockfest/logo.png", "type": "string" }, "name": { "description": "Name is the organizer's public display name.", "example": "Rockfest Productions", "type": "string" }, "privacyUrl": { "description": "PrivacyURL is the organizer's own privacy policy.", "example": "https://rockfest.cz/ochrana-osobnich-udaju", "type": "string" }, "slug": { "description": "Slug is the organizer's URL identifier (the {orgSlug} path parameter).", "example": "rockfest", "type": "string" }, "termsUrl": { "description": "TermsURL is the organizer's own terms of sale — the organizer is the\nseller, so the checkout links these next to Bookitive's buyer notice.", "example": "https://rockfest.cz/obchodni-podminky", "type": "string" } }, "type": "object" }, "dto.PublicPaymentDetail": { "description": "Payment carries the bank-transfer instructions for pending orders.", "properties": { "bankAccount": { "description": "BankAccount is the organizer's free-form payment destination.", "example": "123456789/0100", "type": "string" }, "variableSymbol": { "description": "VariableSymbol identifies the payment — it equals the order reference.", "example": "26000142", "type": "string" } }, "type": "object" }, "dto.PublicProtection": { "description": "Protection describes the anti-scalping requirements a buyer must satisfy\nat checkout (verified phone, named tickets). All-false when unprotected.", "properties": { "phonePrefixes": { "description": "PhonePrefixes is the allowlist of accepted international dialling codes\n(e.g. \"+420\"). Only meaningful when RequireVerifiedPhone is set.", "example": [ "+420", "+421" ], "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "requireAttendeeNames": { "description": "RequireAttendeeNames demands one attendee name per admitted person.", "example": false, "type": "boolean" }, "requireVerifiedPhone": { "description": "RequireVerifiedPhone gates checkout behind SMS phone verification.", "example": true, "type": "boolean" } }, "type": "object" }, "dto.PublicSeat": { "properties": { "code": { "description": "Code is the human-facing seat label (section prefix + table + seat).", "example": "L12-3", "type": "string" }, "geom": { "description": "Geom is editor-owned free-form chair geometry (polygon/oval); opaque,\nabsent = default circle.", "type": "object" }, "id": { "description": "ID is the seat's stable id; availability and orders reference it.", "example": "1810000000000000501", "type": "string" }, "tableId": { "description": "TableID is the owning table's id, when the seat belongs to a table.", "example": "1810000000000000401", "type": "string" }, "ticketTypeId": { "description": "TicketTypeID is the ticket type mapped to this seat, when priced.", "example": "1810000000000000201", "type": "string" }, "x": { "description": "X is the seat centre's x on the floor canvas.", "example": 245, "type": "number" }, "y": { "description": "Y is the seat centre's y on the floor canvas.", "example": 158, "type": "number" } }, "type": "object" }, "dto.PublicSeating": { "properties": { "floors": { "description": "Floors are the chart's floors in tab order, each with its geometry.", "items": { "$ref": "#/components/schemas/dto.PublicFloor" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "dto.PublicSection": { "properties": { "decorations": { "description": "Decorations is opaque visual scenery (stage, walls, doors) — never sold.", "type": "object" }, "gaAreas": { "description": "GAAreas are the standing areas (sold by quantity) in this section.", "items": { "$ref": "#/components/schemas/dto.PublicGAArea" }, "type": "array", "uniqueItems": false }, "h": { "description": "H is the section's height on the floor canvas, if sized.", "example": 300, "type": "number" }, "id": { "description": "ID is the section's stable id.", "example": "1810000000000000301", "type": "string" }, "name": { "description": "Name is the section's display label.", "example": "Left block", "type": "string" }, "polygon": { "description": "Polygon is the section's outline as an array of {x,y} points, if shaped.", "type": "object" }, "prefix": { "description": "Prefix is prepended to seat codes in this section (e.g. \"L\" → \"L12-3\").", "example": "L", "type": "string" }, "seats": { "description": "Seats are the individually sellable seats in this section.", "items": { "$ref": "#/components/schemas/dto.PublicSeat" }, "type": "array", "uniqueItems": false }, "settings": { "description": "Settings is opaque render config (chair gap/size, label typography).", "type": "object" }, "tables": { "description": "Tables are the seated tables in this section.", "items": { "$ref": "#/components/schemas/dto.PublicTable" }, "type": "array", "uniqueItems": false }, "w": { "description": "W is the section's width on the floor canvas, if sized.", "example": 400, "type": "number" }, "x": { "description": "X is the section's left offset on the floor canvas, if positioned.", "example": 120, "type": "number" }, "y": { "description": "Y is the section's top offset on the floor canvas, if positioned.", "example": 80, "type": "number" } }, "type": "object" }, "dto.PublicTable": { "properties": { "bodies": { "description": "Bodies is editor-owned free-form geometry (polygon/oval table bodies; an\narray → composite tables). Opaque; absent for primitive tables.", "type": "object" }, "cornerRadius": { "description": "CornerRadius is the corner rounding of a rect table body, in canvas units.", "example": 5, "type": "number" }, "curve": { "description": "Curve is the arc for row tables, in degrees (0 = straight row).", "example": 0, "type": "number" }, "h": { "description": "H is the height for rect tables, in canvas units.", "example": 60, "type": "number" }, "id": { "description": "ID is the table's stable id, referenced by PublicSeat.tableId.", "example": "1810000000000000401", "type": "string" }, "number": { "description": "Number is the table's display number within its section.", "example": 12, "type": "integer" }, "radius": { "description": "Radius is the radius for round tables, in canvas units.", "example": 45, "type": "number" }, "rotation": { "description": "Rotation is the table's rotation in degrees.", "example": 0, "type": "number" }, "shape": { "description": "Shape is the table outline: \"round\", \"rect\", \"row\", \"poly\", or \"oval\".", "enum": [ "round", "rect", "row", "poly", "oval" ], "example": "round", "type": "string" }, "sides": { "description": "Sides is the seat count per edge for rect tables [top,right,bottom,left].", "items": { "type": "integer" }, "type": "array", "uniqueItems": false }, "spacing": { "description": "Spacing is the gap between seats on a row table, in canvas units.", "example": 24, "type": "number" }, "w": { "description": "W is the width for rect tables, in canvas units.", "example": 120, "type": "number" }, "x": { "description": "X is the table centre's x on the floor canvas.", "example": 240.5, "type": "number" }, "y": { "description": "Y is the table centre's y on the floor canvas.", "example": 160, "type": "number" } }, "type": "object" }, "dto.PublicTicketType": { "properties": { "basePriceCents": { "description": "BasePriceCents is the regular price, present only when a scheduled phase is\ncurrently active and differs from it — so the widget can show \"was €X\".", "example": 179000, "type": "integer" }, "color": { "description": "Color is the swatch used to tint seats/areas of this type, as hex.", "example": "#E5482F", "type": "string" }, "cons": { "description": "Cons are short caveats for this ticket type, shown alongside the pros.", "example": [ "No seating" ], "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "description": { "description": "Description is optional customer-facing copy for this ticket type.", "example": "Front-stage standing with a dedicated bar", "type": "string" }, "id": { "description": "ID is the ticket type's stable id, referenced by order items and seats.", "example": "1810000000000000201", "type": "string" }, "kind": { "description": "Kind is \"seated\" (maps to a seat) or \"standing\" (sold by quantity).", "enum": [ "seated", "standing" ], "example": "standing", "type": "string" }, "lowStockExempt": { "description": "LowStockExempt: this type opts out of the low-stock line — clients must\nnot render \"last N tickets\" for it.", "type": "boolean" }, "maxPerCustomer": { "description": "MaxPerCustomer caps how many of this type one verified buyer may hold\nacross orders (anti-scalping); absent when unlimited.", "example": 4, "type": "integer" }, "maxPerOrder": { "description": "MaxPerOrder caps how many of this type a single order may contain.", "example": 6, "type": "integer" }, "minPerOrder": { "description": "MinPerOrder appears only when it is a real constraint (> 1) — the\nlimit applies to orders that include this type at all.", "example": 1, "type": "integer" }, "name": { "description": "Name is the ticket type's display label.", "example": "VIP", "type": "string" }, "priceCents": { "description": "PriceCents is the EFFECTIVE unit price right now, in the event currency's\nminor units — the base price, or an active scheduled phase's price (RFC\n0005). This is what the buyer pays.", "example": 149000, "type": "integer" }, "priceChangesAt": { "description": "PriceChangesAt is the next scheduled price boundary (RFC 3339) — the widget\ncan count down \"early bird ends in …\"; absent when the price won't change.", "example": "2026-06-01T00:00:00Z", "type": "string", "format": "date-time" }, "pricePhaseDescription": { "description": "PricePhaseDescription is the active phase's optional organizer-authored\ncopy, shown in the widget's phase info popover.", "example": "Launch price for the first hundred fans.", "type": "string" }, "pricePhaseName": { "description": "PricePhaseName is the active phase's label (e.g. \"Early bird\"), if any.", "example": "Early bird", "type": "string" }, "pricePhaseRemaining": { "description": "PricePhaseRemaining is how many tickets are left at the active phase's\nprice before its quantity cap (RFC 0005) — the \"12 left at early bird\"\nurgency; absent when the active phase has no quantity cap.", "example": 12, "type": "integer" }, "pros": { "description": "Pros are short selling points for this ticket type, shown as a checklist.", "example": [ "Best view", "Dedicated bar", "Fast-track entry" ], "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "saleEndTime": { "description": "SaleEndTime is when this type stops selling (RFC 3339), if scheduled.", "example": "2026-06-20T16:00:00Z", "type": "string", "format": "date-time" }, "salePaused": { "description": "SalePaused: the organizer temporarily paused sales of this type.", "type": "boolean" }, "saleStartTime": { "description": "SaleStartTime is when this type goes on sale (RFC 3339), if scheduled.", "example": "2026-01-15T10:00:00Z", "type": "string", "format": "date-time" } }, "type": "object" }, "dto.PublicVerification": { "properties": { "expiresAt": { "description": "ExpiresAt is when the token stops being accepted (RFC 3339).", "example": "2026-06-20T18:30:00Z", "type": "string", "format": "date-time" }, "phone": { "description": "Phone is the normalized number the token certifies.", "example": "+420777123456", "type": "string" }, "verificationToken": { "description": "VerificationToken is consumed by exactly one order for this event.", "example": "5Yx…", "type": "string" } }, "type": "object" }, "dto.PublicVerifyCheckRequest": { "properties": { "code": { "description": "Code is the OTP from the SMS.", "example": "123456", "maxLength": 10, "minLength": 4, "type": "string" }, "phone": { "example": "+420777123456", "maxLength": 20, "minLength": 8, "type": "string" } }, "required": [ "code", "phone" ], "type": "object" }, "dto.PublicVerifyStartRequest": { "properties": { "captchaToken": { "description": "CaptchaToken is the client-side captcha solution, verified server-side.", "example": "03AGdBq26…", "type": "string" }, "phone": { "description": "Phone in international E.164 format.", "example": "+420777123456", "maxLength": 20, "minLength": 8, "type": "string" } }, "required": [ "phone" ], "type": "object" }, "dto.PublicWaitlistClaim": { "properties": { "email": { "example": "anna@example.com", "type": "string" }, "name": { "example": "Anna Nováková", "type": "string" }, "offerExpiresAt": { "type": "string" }, "quantity": { "example": 2, "type": "integer" }, "ticketTypeId": { "example": "734559411483578369", "type": "string" } }, "type": "object" }, "dto.PublicWaitlistEntry": { "properties": { "claimToken": { "description": "ClaimToken completes the purchase while the offer is active.", "type": "string" }, "eventName": { "type": "string" }, "eventSlug": { "type": "string" }, "offerExpiresAt": { "type": "string" }, "offeredQuantity": { "description": "OfferedQuantity and OfferExpiresAt are present while an offer is active.", "type": "integer" }, "offeredTicketTypeName": { "description": "OfferedTicketTypeName labels the offer (\"2× VIP\").", "type": "string" }, "orgSlug": { "description": "Event identity for the manage page's back link.", "type": "string" }, "quantity": { "description": "Quantity still wanted.", "example": 2, "type": "integer" }, "status": { "description": "Status: waiting | offered | claimed | left | expired.", "example": "waiting", "type": "string" }, "ticketTypeNames": { "description": "TicketTypeNames the entry waits for; empty = any type.", "items": { "type": "string" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "publichandler.payloadWaitlistJoin": { "properties": { "email": { "maxLength": 200, "type": "string" }, "fullOnly": { "description": "FullOnly: only offer the complete quantity; partial releases go to the\nnext person in line.", "type": "boolean" }, "name": { "maxLength": 100, "minLength": 2, "type": "string" }, "quantity": { "maximum": 10, "minimum": 1, "type": "integer" }, "ticketTypeIds": { "description": "TicketTypeIds: the set to wait for; empty/omitted = any type.", "items": { "type": "string" }, "maxItems": 20, "type": "array", "uniqueItems": false } }, "required": [ "email", "quantity" ], "type": "object" }, "response.APIError": { "properties": { "data": {}, "fields": { "additionalProperties": { "type": "string" }, "type": "object" }, "msg": { "example": "see fields", "type": "string" }, "timestamp": { "example": "2026-09-13T18:45:12Z", "type": "string", "format": "date-time" }, "traceId": { "example": "2b9c1f0e-6d4a-4a1b-9e0f-3c5d7a8b9c0d", "type": "string" }, "type": { "$ref": "#/components/schemas/response.Type" } }, "required": [ "msg", "type" ], "type": "object" }, "response.APIResponseEmpty": { "type": "object" }, "response.Type": { "enum": [ "INVALID_PAYLOAD", "VALIDATION_FAILED", "NOT_FOUND", "NOT_IMPLEMENTED", "CONFLICT", "INTERNAL_ERROR", "UNAUTHORIZED", "FORBIDDEN", "VERIFICATION_REQUIRED", "MISSING_ORGANIZATION_ID", "MISSING_USER_ID", "PER_ORDER_LIMITS", "PER_CUSTOMER_LIMIT", "SOLD_OUT", "SEATS_TAKEN", "CAPACITY_FULL", "SALE_WINDOW", "SALES_PAUSED", "TICKET_TYPE_PAUSED", "NOT_ON_SALE", "DISCOUNT_INVALID", "DISCOUNT_EXHAUSTED", "VERIFICATION_INVALID", "ATTENDEES_REQUIRED", "TRANSFER_LOCKED", "TRANSFER_CODE_REQUIRED", "TRANSFER_CODE_INVALID", "TOO_MANY_REQUESTS" ], "example": "VALIDATION_FAILED", "type": "string", "x-enum-varnames": [ "ErrInvalidPayload", "ErrValidationFailed", "ErrNotFound", "ErrNotImplemented", "ErrConflict", "ErrInternal", "ErrUnauthorized", "ErrForbidden", "ErrVerificationRequired", "ErrMissingOrganizationID", "ErrMissingUserID", "ErrPerOrderLimits", "ErrPerCustomerLimit", "ErrSoldOut", "ErrSeatsTaken", "ErrCapacityFull", "ErrSaleWindow", "ErrSalesPaused", "ErrTicketTypePaused", "ErrNotOnSale", "ErrDiscountInvalid", "ErrDiscountExhausted", "ErrVerificationInvalid", "ErrAttendeesRequired", "ErrTransferLocked", "ErrTransferCodeRequired", "ErrTransferCodeInvalid", "ErrTooManyRequests" ] } } }, "info": { "description": "The **Bookitive Public API** powers ticket sales for on-sale events: read an event's details, its seating chart and live availability, and place orders — from a browser or a server, with no account required. It's the same API that our own hosted checkout pages and the embeddable widget use.\n\n## Base URL\n\n```\nhttps://api.bookitive.com/public/v1\n```\n\nEvery path is scoped to an organizer and an event by slug, e.g. `GET /orgs/{orgSlug}/events/{eventSlug}`.\n\n## Authentication — none, by design\n\nThese endpoints are **public**: no API keys, tokens, or cookies. A request only needs the org and event slugs in the URL. Reads are CORS-open so any web page can call them directly, and the order endpoint is protected by a **captcha + per-IP rate limits** rather than credentials.\n\n> **\"Is it safe that there's no key?\"** Yes. There's nothing secret to protect here — only on-sale, public information and an order flow that a customer would perform anyway. Because no secret is involved, it's safe to call these endpoints straight from browser JavaScript. You will never need to put a Bookitive secret in the browser, because there isn't one.\n>\n> Organizer-private data (sales figures, direct server-to-server order creation) lives behind a **separate, authenticated API** that uses secret keys. A browser-safe *publishable* key for attribution and origin-locking of the widget is planned but optional — it is **not** required to use anything documented here.\n\n## Client libraries\n\n- **JavaScript / TypeScript** — [`@bookitive/js`](https://www.npmjs.com/package/@bookitive/js), a fully-typed client generated from this exact spec.\n- **Drop-in widget** — [`@bookitive/widget-js`](https://www.npmjs.com/package/@bookitive/widget-js) mounts a seat picker and checkout onto any page in a few lines.\n- **Anything else** — generate a client in your language from the [OpenAPI document](openapi.json).\n\n## Conventions\n\n- **IDs** are strings (64-bit snowflakes) — always treat them as opaque.\n- **Money** is an integer count of minor units (`priceCents`) in the event's `currency` (ISO 4217). `149000` with currency `CZK` means 1 490.00 Kč.\n- **Times** are RFC 3339 / ISO 8601 in UTC.\n- **Errors** share one envelope: a stable `type` code to branch on plus a human-readable `msg`. On checkout, `409 CONFLICT` means a seat was taken between selection and payment — refresh availability and let the customer re-pick.\n\n## Real-time availability\n\n`GET …/availability` is a plain snapshot you can poll. For live updates without polling, `…/live` is a **WebSocket**: it sends the full availability state on connect, then per-seat deltas as seats are taken or freed.", "title": "Bookitive Public API", "version": "", "x-logo": { "url": "logo.png", "altText": "Bookitive" } }, "paths": { "/orgs/{orgSlug}/events/{eventSlug}": { "get": { "description": "Event identity, ticket types with prices and per-order limits, and the org's public branding. Only on-sale events resolve.", "parameters": [ { "description": "Organization slug", "example": "rockfest", "in": "path", "name": "orgSlug", "required": true, "schema": { "type": "string" } }, { "description": "Event slug", "example": "rockfest-2026", "in": "path", "name": "eventSlug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dto.PublicEvent" } } }, "description": "OK" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dto.APIError" } } }, "description": "Not Found" } }, "summary": "Public event info", "tags": [ "Public" ] } }, "/orgs/{orgSlug}/events/{eventSlug}/availability": { "get": { "description": "Unavailable seat ids plus remaining capacity for capped standing areas and ticket types. Poll it to keep a seat picker live.", "parameters": [ { "description": "Organization slug", "example": "rockfest", "in": "path", "name": "orgSlug", "required": true, "schema": { "type": "string" } }, { "description": "Event slug", "example": "rockfest-2026", "in": "path", "name": "eventSlug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dto.PublicAvailability" } } }, "description": "OK" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dto.APIError" } } }, "description": "Not Found" } }, "summary": "Public availability", "tags": [ "Public" ] } }, "/orgs/{orgSlug}/events/{eventSlug}/discount": { "get": { "description": "Checks whether a promo code is currently redeemable and returns what it does. The order endpoint re-validates on submit — a valid preview does not reserve the code.", "parameters": [ { "description": "Organization slug", "example": "rockfest", "in": "path", "name": "orgSlug", "required": true, "schema": { "type": "string" } }, { "description": "Event slug", "example": "rockfest-2026", "in": "path", "name": "eventSlug", "required": true, "schema": { "type": "string" } }, { "description": "Promo code (case-insensitive)", "example": "EARLYBIRD", "in": "query", "name": "code", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dto.PublicDiscount" } } }, "description": "OK" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dto.APIError" } } }, "description": "unknown, paused, or out-of-window code" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dto.APIError" } } }, "description": "code fully redeemed" } }, "summary": "Validate a promo code", "tags": [ "Public" ] } }, "/orgs/{orgSlug}/events/{eventSlug}/live": { "get": { "description": "Websocket: sends {\"event\":\"startstate\",\"data\":} on connect, then {\"event\":\"seat\",\"data\":{\"seatId\",\"taken\",\"status\"}} deltas. Status is \"free\"/\"taken\", plus \"reserved\" when the event shares reserved state (a reserved seat may free up again).", "parameters": [ { "description": "Organization slug", "example": "rockfest", "in": "path", "name": "orgSlug", "required": true, "schema": { "type": "string" } }, { "description": "Event slug", "example": "rockfest-2026", "in": "path", "name": "eventSlug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } }, "summary": "Public live availability (websocket)", "tags": [ "Public" ] } }, "/orgs/{orgSlug}/events/{eventSlug}/orders": { "post": { "description": "Creates a pending bank-transfer order: seats are held atomically for the event's hold TTL and payment instructions are emailed. Conflicting seats return 409 — refresh availability and reselect.", "parameters": [ { "description": "Organization slug", "example": "rockfest", "in": "path", "name": "orgSlug", "required": true, "schema": { "type": "string" } }, { "description": "Event slug", "example": "rockfest-2026", "in": "path", "name": "eventSlug", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dto.PublicOrderRequest" } } }, "description": "Order", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dto.PublicOrder" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dto.APIError" } } }, "description": "Bad Request" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dto.APIError" } } }, "description": "captcha rejected" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dto.APIError" } } }, "description": "seats no longer available" } }, "summary": "Public checkout", "tags": [ "Public" ] } }, "/orgs/{orgSlug}/events/{eventSlug}/seating": { "get": { "description": "Floors → sections → tables, seats, and standing areas — geometry only. Live state comes from the availability endpoint.", "parameters": [ { "description": "Organization slug", "example": "rockfest", "in": "path", "name": "orgSlug", "required": true, "schema": { "type": "string" } }, { "description": "Event slug", "example": "rockfest-2026", "in": "path", "name": "eventSlug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dto.PublicSeating" } } }, "description": "OK" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dto.APIError" } } }, "description": "Not Found" } }, "summary": "Public seating chart", "tags": [ "Public" ] } }, "/orgs/{orgSlug}/events/{eventSlug}/verify/check": { "post": { "description": "Validates the one-time code and returns a single-use verificationToken (30-minute validity) to pass with the order.", "parameters": [ { "description": "Organization slug", "example": "rockfest", "in": "path", "name": "orgSlug", "required": true, "schema": { "type": "string" } }, { "description": "Event slug", "example": "rockfest-2026", "in": "path", "name": "eventSlug", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dto.PublicVerifyCheckRequest" } } }, "description": "Phone + code", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dto.PublicVerification" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dto.APIError" } } }, "description": "wrong code" }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dto.APIError" } } }, "description": "code expired — request a new one" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dto.APIError" } } }, "description": "too many attempts" } }, "summary": "Check phone verification code", "tags": [ "Public" ] } }, "/orgs/{orgSlug}/events/{eventSlug}/verify/start": { "post": { "description": "Sends a one-time code by SMS when the event requires verified buyers. Only phones matching the event's prefix allowlist are accepted; sends are captcha-gated, rate-limited per phone and IP, and a resend within the active window delivers a fresh code.", "parameters": [ { "description": "Organization slug", "example": "rockfest", "in": "path", "name": "orgSlug", "required": true, "schema": { "type": "string" } }, { "description": "Event slug", "example": "rockfest-2026", "in": "path", "name": "eventSlug", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dto.PublicVerifyStartRequest" } } }, "description": "Phone + captcha", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/response.APIResponseEmpty" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dto.APIError" } } }, "description": "invalid phone or disallowed prefix" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dto.APIError" } } }, "description": "captcha rejected or number refused" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dto.APIError" } } }, "description": "cooldown or rate limit" } }, "summary": "Start phone verification", "tags": [ "Public" ] } }, "/orgs/{orgSlug}/events/{eventSlug}/waitlist": { "post": { "description": "Only accepted while the wanted quantity is not openly buyable. One entry per email and ticket type.", "parameters": [ { "description": "Organization slug", "in": "path", "name": "orgSlug", "required": true, "schema": { "type": "string" } }, { "description": "Event slug", "in": "path", "name": "eventSlug", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/publichandler.payloadWaitlistJoin" } } }, "description": "Waitlist signup", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dto.PublicWaitlistEntry" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/response.APIError" } } }, "description": "Bad Request" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/response.APIError" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/response.APIError" } } }, "description": "Conflict" } }, "summary": "Join the event waitlist", "tags": [ "Public" ] } }, "/public/unsubscribe/{token}": { "get": { "parameters": [ { "description": "Unsubscribe token", "in": "path", "name": "token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "text/plain": { "schema": { "type": "string" } } }, "description": "confirmation" } }, "summary": "Sponsor unsubscribe", "tags": [ "Public" ] } }, "/waitlist/claim/{token}": { "get": { "parameters": [ { "description": "Claim token", "in": "path", "name": "token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dto.PublicWaitlistClaim" } } }, "description": "OK" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/response.APIError" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/response.APIError" } } }, "description": "Conflict" } }, "summary": "Get the active waitlist offer behind a claim token", "tags": [ "Public" ] } }, "/waitlist/{token}": { "delete": { "parameters": [ { "description": "Manage token", "in": "path", "name": "token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "OK" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/response.APIError" } } }, "description": "Not Found" } }, "summary": "Leave the waitlist", "tags": [ "Public" ] }, "get": { "parameters": [ { "description": "Manage token", "in": "path", "name": "token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dto.PublicWaitlistEntry" } } }, "description": "OK" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/response.APIError" } } }, "description": "Not Found" } }, "summary": "Get a waitlist entry by manage token", "tags": [ "Public" ] } }, "/waitlist/{token}/decline": { "post": { "parameters": [ { "description": "Manage token", "in": "path", "name": "token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dto.PublicWaitlistEntry" } } }, "description": "OK" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/response.APIError" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/response.APIError" } } }, "description": "Conflict" } }, "summary": "Decline a waitlist offer", "tags": [ "Public" ] } } }, "openapi": "3.1.0", "servers": [ { "url": "https://api.bookitive.com/public/v1", "description": "Production" } ] }