REST API

Base URL: /api Content-Type: application/json Auth: Session cookie (pinteach_session, 30-day expiry)

Public Routes (/api/public/:slug) — No Auth

Method	Path	Rate Limit	Description
GET	/:slug	—	Teacher public profile + services
GET	/:slug/services	—	Active services list
GET	/:slug/services/:serviceSlug	—	Service detail
GET	/:slug/service-availability	30/min	Available slots for a service
POST	/:slug/events	60/min	Track analytics events
POST	/:slug/widget-event	120/min	Track widget events
POST	/:slug/trial-session	3/hr	Book a trial session
POST	/:slug/enroll	10/min	Student enrollment
GET	/:slug/reviews	—	Public reviews with stats
POST	/:slug/validate-discount	10/min	Validate a discount code
GET	/:slug/widget-css	—	Custom CSS for widget config (?configId=xxx, returns text/css)

GET /:slug/service-availability

Query params:
  serviceId: string (required)
  timezone: string (IANA)
  start: string (ISO date)
  end: string (ISO date)
  preferredStart: string (HH:mm, optional)
  preferredEnd: string (HH:mm, optional)
  preferredDays: string (comma-separated 1-7, optional)

{
  "slots": [
    {
      "startUtc": "2026-02-12T09:00:00Z",
      "endUtc": "2026-02-12T10:00:00Z",
      "startLocal": "2026-02-12T10:00:00+01:00",
      "endLocal": "2026-02-12T11:00:00+01:00",
      "isPreferred": true
    }
  ]
}

Student Routes (/api/student) — Student Auth

Sessions

Method	Path	Description
POST	/student/sessions	Book a session
GET	/student/sessions	List sessions
GET	/student/sessions/:id	Session detail
POST	/student/sessions/:id/cancel	Cancel (enforces policy)
POST	/student/sessions/:id/reschedule	Reschedule
POST	/student/sessions/:id/mood	Submit mood
GET	/student/sessions/:id/cancellation-preview	Dry-run cancel
GET	/student/sessions/:id/reschedule-preview	Dry-run reschedule

Reviews

Method	Path	Description
POST	/student/sessions/:id/review	Submit review
PATCH	/student/reviews/:id	Update review
DELETE	/student/reviews/:id	Delete review

Waitlist

Method	Path	Description
POST	/student/waitlist	Join waitlist
DELETE	/student/waitlist/:serviceId	Leave waitlist
GET	/student/waitlist/:serviceId	Check position

Privacy (GDPR)

Method	Path	Description
GET	/student/privacy/my-data	View data summary
POST	/student/privacy/export	Download export
POST	/student/privacy/erasure-request	Request erasure

Teacher Routes (/api/teacher) — Teacher Auth

Services

Method	Path	Description
GET	/teacher/services	List services
POST	/teacher/services	Create service
PATCH	/teacher/services/:id	Update service
DELETE	/teacher/services/:id	Soft-delete
POST	/teacher/services/:id/publish	Publish
POST	/teacher/services/:id/pause	Pause
POST	/teacher/services/:id/archive	Archive

Sessions

Method	Path	Description
GET	/teacher/sessions	List sessions
POST	/teacher/sessions	Create session
POST	/teacher/sessions/:id/cancel	Cancel
POST	/teacher/sessions/:id/complete	Complete
POST	/teacher/sessions/:id/no-show/:studentId	No-show
PATCH	/teacher/sessions/:id/content	Update content
POST	/teacher/sessions/:id/templates	Link templates
POST	/teacher/sessions/:id/resources	Link resources

Students

Method	Path	Description
GET	/teacher/students	List students
POST	/teacher/students	Create student
PATCH	/teacher/students/:id	Update student
DELETE	/teacher/students/:id	Soft-delete
POST	/teacher/students/:id/impersonate	Impersonate

Dashboard & Calendar

Method	Path	Description
GET	/teacher/dashboard/summary	KPIs + pending trials
GET	/teacher/dashboard/smart-actions	Suggested actions
GET	/teacher/calendar/week	Week view data
GET	/teacher/calendar/agenda	Agenda list

Payments

Method	Path	Description
GET	/teacher/payments	Payment history
GET	/teacher/payments/kpis	Revenue KPIs
POST	/teacher/payments/csv-export	CSV export
POST	/teacher/payments/refund	Initiate refund

Materials & Resources

Method	Path	Description
GET/POST	/teacher/lesson-templates	Template CRUD
GET	/teacher/lesson-templates/tree	Full tree
GET	/teacher/materials/:folderId/contents	Folder contents
GET	/teacher/materials/search	Search materials
POST	/teacher/materials/move	Move items
GET/POST	/teacher/resources	Resource CRUD
POST	/teacher/resources/:id/favorite	Toggle favorite

Reviews

Method	Path	Description
GET	/teacher/reviews	List reviews
GET	/teacher/reviews/stats	Review stats
POST	/teacher/reviews/:id/respond	Add response
POST	/teacher/reviews/import	Import external
POST	/teacher/reviews/requests/send	Send request

Widgets & Availability

Method	Path	Description
CRUD	/teacher/widget-configs	Widget management
CRUD	/teacher/availability-schedules	Schedules
CRUD	/teacher/availability-overrides	Overrides
CRUD	/teacher/cancellation-policies	Policies

Audit & Privacy

Method	Path	Description
GET	/teacher/audit-log	Paginated audit logs
GET	/teacher/privacy/export	Teacher data export
POST	/teacher/privacy/erase-student	Erase student data
GET	/teacher/privacy/erasure-requests	List erasure requests

Discount Codes

Method	Path	Description
GET	/teacher/discount-codes	List discount codes
GET	/teacher/discount-codes/:id	Get discount code detail
GET	/teacher/discount-codes/:id/stats	Usage stats for a code
POST	/teacher/discount-codes	Create discount code
PATCH	/teacher/discount-codes/:id	Update discount code
DELETE	/teacher/discount-codes/:id	Soft-delete discount code

Scheduled Messages

Method	Path	Description
GET	/teacher/scheduled-messages	List scheduled messages
POST	/teacher/scheduled-messages	Create scheduled message (enqueues BullMQ delayed job)
DELETE	/teacher/scheduled-messages/:id	Cancel a pending message (removes BullMQ job)

Webhook Routes

POST /api/webhooks/stripe

Signature verified via stripe-signature header. Idempotent via webhook_events.stripeEventId.

Events handled:

• checkout.session.completed — Confirm enrollment / activate payment
• invoice.paid — Auto-renew subscription enrollments
• customer.subscription.deleted — Cancel enrollment
• charge.refunded — Apply refund
• charge.dispute.created — Record dispute

Rate Limits

Endpoint Pattern	Limit
POST /auth/magic-link	5/hr per IP
POST /public/*/trial-session	3/hr per IP
GET /public/*/service-availability	30/min per IP
POST /public/*/events	60/min per IP
POST /public/*/validate-discount	10/min per IP
All authenticated	100/min per session