API reference

Base URL and response format

Every route is served under the /api prefix. Locally the base URL is http://localhost:8000/api. On a server it is your API's address followed by /api, the same value both frontends read from NEXT_PUBLIC_API_BASE_URL (Environment variables). Pictures are served outside the prefix, at /media/….

The website's routes are public or take an attendee's token; the dashboard's need a staff member's bearer token, and most also a permission. Request bodies are JSON, except file uploads. Every answer comes in the same envelope:

{
  "success": true,
  "data": { },
  "message": ""
}

data holds the result. message is a short sentence some writes fill in, in the request's language, and empty otherwise. Money is a whole number of minor units with its currency (price_minor: 2000 is 20.00), and every date is an ISO string in UTC; each event also carries its time_zone.

The health check needs no token:

curl http://localhost:8000/api/health

{"success":true,"data":{"status":"ok","database":"up"},"message":""}

When the database cannot be read it still answers 200, with "status":"degraded" and "database":"down". The Docker image's health check reads that field.

Errors

A failure keeps the envelope, with success: false and the HTTP status:

{
  "success": false,
  "data": null,
  "message": "…",
  "errors": { "email": ["…"] },
  "code": "SEAT_UNAVAILABLE",
  "details": { "seats": ["A12"] }
}

• message is a sentence in the request's language.
• errors appears on a validation failure, with the problems per field, keyed by the path the client sent (such as title.en or attendee.email).
• An unknown field in a body is refused with 400, and errors names it. Sign-up, for one, takes only the fields listed below.
• code and details appear where a screen reacts to one refusal in particular: SEAT_UNAVAILABLE with the seats taken, HOLD_EXPIRED, SOLD_OUT, ALREADY_ADMITTED with the first admission, VERSION_CONFLICT, NOT_READY with what is missing, COOLDOWN with retry_after in seconds.
• A guarded route with no token, or an expired one, answers 401; a token without the permission answers 403.
• A request over a limit answers 429.

Headers

Event, venue and ticket type texts carry both languages as { "en": "…", "ar": "…" } whatever Accept-Language says, and the client picks one, falling back to English when the Arabic is empty.

Lists and paging

{ "data": [ ], "page": 1, "limit": 10, "total": 36, "totalPages": 4 }

• Most lists page with page and limit, at most 100 a page: 9 events a page on the website, 10 events, venues and attendees and 8 orders in the dashboard by default. Several also return counts per tab or status.
• The team, roles and site settings lists page with page and page_count, and the inquiries with page and page_size (10 by default, at most 50).
• The dashboard's lists come newest-updated first, with the id as a tiebreaker, so paging is stable. The website's catalogue comes soonest first.
• The team list's filters (email, name, phone) combine: a row must match every one given. name matches the first name, the last name, the username or the full name.

Signing in

1. 01

   Sign in as a staff member

   TerminalCopy

   curl -X POST http://localhost:8000/api/auth/login \
     -H "Content-Type: application/json" \
     -d '{"email":"YOUR_EMAIL","password":"YOUR_PASSWORD"}'

   Use one of the dashboard accounts from Installation, or your own. data.access_token is the token, with token_type Bearer and the staff member with their roles and permissions. The token lasts JWT_EXPIRATION, 7d by default, and expires_in reports that value as written. GET /api/auth/me returns the signed-in staff member with their roles and permissions.
2. 02

   Call a protected route

   TerminalCopy

   curl http://localhost:8000/api/admin/orders \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "X-Workspace-Id: 1"

• An unknown email and a wrong password both answer 401 with the same message.
• Ten failed sign-ins from one address within 15 minutes answer 429 until the oldest failure is 15 minutes old (RATE_LIMIT_LOGIN). Successful sign-ins are not counted. Staff and attendee sign-ins are counted apart.
• Staff accounts come from the seed or from the Team page; there is no staff sign-up. A client signs out by forgetting its token.
• GET /api/admin/workspace/memberships lists the workspaces the member belongs to, their own first. Send the chosen one's id as X-Workspace-Id.

Permissions

Staff routes check a permission named <area>.<action>. A member holds every permission of every role they have, and the role is the same in every workspace they belong to. The 29 permissions and the four seeded roles (Owner, Manager, Finance, Check-in) are listed in Team, roles and workspaces.

Events, venues and organisers on the website

The organiser's takings are never part of a public answer.

Attendee accounts

Sign-up is limited to 10 per address in 10 minutes, and password reset requests to 5. While no mail key is set, codes and links are written to the API's log, and mail_simulated says so.

Holds and checkout

A purchase is two calls: hold the seats or places, then check out from the hold. Both work for a guest and for a signed-in attendee, whose token is read when sent.

• A hold lasts the workspace's hold time (hold_seconds, ten minutes as seeded), counted on the server's clock. After it, the hold answers 410 with HOLD_EXPIRED and the seats are free again.
• A seat someone else holds or bought answers 409 with SEAT_UNAVAILABLE and the seats in details.seats; a full ticket type answers SOLD_OUT; more than the per-order limit answers TOO_MANY.
• Send the browser to redirect_url: Stripe's or PayPal's own page, or the website's simulator page. Card details are never sent to this API.
• A hold whose total is 0 needs no provider: the order is confirmed at once with provider free and status paid, and redirect_url is its confirmation page.

Orders, ticket files and payments

• The download links are signed with exp and sig and work for 30 minutes from the receipt that made them; a stale one answers 404, and reading the receipt again makes fresh ones. They are built from PUBLIC_API_URL.
• Tickets are issued once the provider confirms the payment, by its webhook, by PayPal's return, or by the simulator. Stripe sends checkout.session.completed, checkout.session.async_payment_succeeded, checkout.session.async_payment_failed and refund.updated; PayPal PAYMENT.CAPTURE.COMPLETED, PAYMENT.CAPTURE.DENIED and PAYMENT.CAPTURE.REFUNDED.
• The simulator is offered while no live Stripe or PayPal key is set; PAYMENTS_SIMULATOR=on or off overrides that.

• Going live

The contact form

• A repeated client_token returns the first submission's receipt instead of storing a second one.
• A filled company field is treated as a bot: the answer looks the same, and nothing is stored.
• Each address may send five in ten minutes; the next answers 429.

Events

Venues and seat layouts

Orders, tickets and refunds

Its tickets are suspended (refund_pending) as soon as the refund is asked for, so the door refuses them. The refund settles when the provider confirms it, a few seconds later for the simulator: the tickets are then voided and their seats go back on sale. A failed refund keeps them suspended until it is retried, or restored, which makes them valid again. Read the order again to see where it stands.

Check-in at the door

Members who can edit or publish events reach every session; the others only the sessions they are assigned to, and another answers 403. Each member may make 120 checks a minute.

Overview, reports and exports

CSV files are written to EXPORT_DIR in the background, and the download link is built from PUBLIC_API_URL.

Workspace, payments and site settings

Team and roles

Inquiries, notifications and uploads

Notifications cover paid orders, refund requests, door alerts, new inquiries and finished venue concepts, and are kept for 30 days. An upload has no permission of its own: what the file becomes is checked by the route that saves it. Files go to the R2 bucket when its five variables are set, and to MEDIA_UPLOAD_DIR otherwise.

Limits per address

A request over a limit answers 429. The counts live in the API's memory, so a restart clears them. Behind a reverse proxy, set TRUST_PROXY so each visitor is counted on their own address.

AI event assistant and its conversations

Venue studio

MCP server

Live updates over WebSocket

Demo mode routes