API Documentation

Tutor is a Next.js 16 (App Router) application. There is no separate API server — every endpoint is a route handler living under src/app/api/. They run on the same host as the storefront and admin panel, so the base URL is simply your site origin. It is a lesson booking API: search lessons, read tutor availability, price a quote, and create a booking. All money is in minor units (cents).

Base URL (local): http://localhost:3000 Base URL (production): https://your-domain.com

There are several families of endpoints, each authenticated differently:

The public/mobile API is the non-admin surface under /api/v1. Admin endpoints are for the back office only and are excluded from the mobile API reference.

Authentication

Tutor uses cookie-based JWT sessions for every first-party surface. Each cookie is also accepted as an Authorization: Bearer <jwt> header for mobile clients (bearer is checked before the cookie). There are four sessions:

Admin session (admin_token)

Admins sign in at POST /api/v1/admin/auth/login. On success the server sets an HTTP-only admin_token cookie holding a signed JWT. Every /api/v1/admin/* route reads that cookie, and most write routes additionally enforce a permission (RBAC) via requirePermission(...) — there is no global middleware, the check is per-route.

POST /api/v1/admin/auth/login
Content-Type: application/json

{ "email": "admin@example.com", "password": "••••••••" }

Customer / host session (member_session)

Customers register and verify via email OTP, then receive a member_session cookie (JWT). A host is simply a signed-in customer who also owns an active hosts row, so hosts use the same cookie. /api/v1/portal/auth/* handles the account lifecycle:

Interactive API reference (OpenAPI)

Tutor ships an auto-generated OpenAPI 3 document rendered with Scalar. The spec is generated from the route handlers themselves (scripts/gen-openapi.ts, run via npm run gen:openapi), so a mobile-app developer always has an accurate, current API surface.

Both are admin-gated: without a valid admin_token session the reference page redirects to /admin/login and the spec returns 401, so the spec can't be scraped publicly. Both send noindex, nofollow.

The generator scans every src/app/api/**/route.ts, derives each path ([id] → {id}, route groups dropped), the exported HTTP methods, and the auth requirement (from which helper the file calls — getSession→Admin, getCustomerId→Customer, getHostId→Host, getInfluencerId→Influencer). It groups endpoints into mobile-app surfaces — Auth · Home & content · Listings & search · Bookings & checkout · Reviews · Forms · Customer app · Host app · Influencer app — and excludes internal areas (admin, install, license, plugins, ext, cron, and the chat/analytics routes) so the reference stays focused on the mobile/public surface.

# Regenerate after adding/renaming routes
npm run gen:openapi

Endpoint reference

The tables below list real route handlers under src/app/api/v1/. List endpoints accept query params; :slug / :id are path params. Paginated lists return { data, meta }; detail endpoints return { data } (or the resource directly); money is always in cents.

Listings & search (lessons)

GET /api/v1/listings supports page, per_page (≤ 50, default 12), sort (recommended · price_asc · price_desc · rating · reviews), q, city, category, amenities, guests (seats needed), min_rating, instant, price_min, price_max, lang. It returns:

{ "data": [ /* lesson cards */ ],
  "meta": { "total": 42, "page": 1, "per_page": 12, "total_pages": 4, "sort": "recommended" } }

Quote prices a single lesson time server-side (the client never sends an amount):

POST /api/v1/listings/quote
Content-Type: application/json

{ "session_id": 128, "seats": 2, "booking_mode": "per_person" }

booking_mode is per_person (charge per seat) or private (a private buyout of the lesson time). The response includes availability, seat count, subtotal, extras, and totals — all in cents.

Bookings & checkout

A booking is keyed on a session_id + seats + booking_mode plus guest details. Seats are claimed atomically on creation (seats_total - seats_booked >= seats), so overselling is impossible; a race returns 409.

POST /api/v1/bookings/checkout
Content-Type: application/json

{
  "session_id": 128,
  "seats": 2,
  "booking_mode": "per_person",
  "guest_name": "Sofia Rossi",
  "guest_email": "sofia@example.com",
  "guest_phone": "+39 …",
  "guest_country": "IT",
  "extras": [ { "id": 4, "qty": 2 } ],
  "coupon_code": "WELCOME10",
  "special_requests": "Focus on algebra basics",
  "pay_option": "deposit",
  "provider": "paypal"
}

{ "reference": "Tutor-8FQ2", "public_id": "bkg_…",
  "total": 12000, "deposit": 4000, "currency": "EUR", "amount": 4000, "outcome": { /* gateway */ } }

pay_option is deposit or full; the server charges the deposit only when the guest chose it and a deposit exists (0 < deposit < total), otherwise the full amount. All figures are cents.

Reviews & forms

Content & reference data (public)

Portal endpoints (customer / host / influencer)

Each signed-in portal has its own resource tree, scoped to the current user:

License

Admin (excluded from the mobile API)

Admin resources (/api/v1/admin/*) manage listings, bookings, hosts, customers, extras, coupons, refunds (the approval queue), reviews, blogs, FAQs, gallery, hero slider, pages, menus, theme builder, master-data, partners, testimonials, issues, leads, settings, and license. They require an admin_token session plus the relevant RBAC permission and are not part of the mobile API reference.

Error responses

Routes return JSON { "error": "..." } with the appropriate HTTP status (via err() / serverErr()):

{ "error": "Those seats have just been taken." }

© CreativeCape Solutions · creative-cape.com · support@creative-cape.com