API Reference

Conventions

• Base URL in local development: http://localhost:3001
• All application routes live under /api/v1
• Responses use { data } envelopes for success and { error } for failures
• Most routes require Supabase bearer auth

Health

Method	Path	Notes
GET	/health	unauthenticated service health

Tickets

Method	Path	Purpose
GET	/api/v1/tickets	list tickets with role-aware scoping and filters
POST	/api/v1/tickets	create a new Arabic ticket
POST	/api/v1/tickets/bulk	bulk ticket operations for agents/admins
GET	/api/v1/tickets/by-number/:ticketNumber	resolve display number to UUID
GET	/api/v1/tickets/:id	fetch single ticket
PATCH	/api/v1/tickets/:id	update status, priority, assignee, department
PATCH	/api/v1/tickets/:id/routing	override routing fields
POST	/api/v1/tickets/:id/reclassify	rerun classifier
GET	/api/v1/tickets/:id/audit-log	fetch audit entries

Ticket filters

GET /api/v1/tickets supports:

• status
• priority
• department_id
• assigned_agent_id
• routing_mode
• q
• created_after
• created_before
• page
• page_size
• sort_by
• sort_dir

Comments

Method	Path	Purpose
GET	/api/v1/tickets/:id/comments	list comments for a ticket
POST	/api/v1/tickets/:id/comments	add a comment

Classifier preview

Method	Path	Purpose
POST	/api/v1/classify	preview classifier output without creating a ticket

Departments

Method	Path	Purpose
GET	/api/v1/departments	list departments

Notifications

Method	Path	Purpose
GET	/api/v1/notifications	paginated user notifications
PATCH	/api/v1/notifications/read	mark selected or all notifications as read

Quick actions

Method	Path	Purpose
GET	/api/v1/quick-actions	role-authenticated taxonomy-aware quick actions
GET	/api/v1/quick-actions/all	admin list of all quick actions
POST	/api/v1/quick-actions	admin create
PATCH	/api/v1/quick-actions/:id	admin update
DELETE	/api/v1/quick-actions/:id	admin delete

Stats

Method	Path	Purpose
GET	/api/v1/stats/routing	auto/review/manual counts and percentages
GET	/api/v1/stats/confidence	10-bin confidence histogram
GET	/api/v1/stats/taxonomy	L1 and L2 classification counts
GET	/api/v1/stats/departments	department totals and override rates
GET	/api/v1/stats/workload	per-agent open ticket counts

Admin-only stats utilities

Method	Path	Purpose
GET	/api/v1/stats/admin/dev-config	expose local classifier and demo config
DELETE	/api/v1/stats/admin/tickets	delete all tickets
POST	/api/v1/stats/admin/tickets/reseed	generate demo tickets
DELETE	/api/v1/stats/admin/notifications	delete all notifications
POST	/api/v1/stats/admin/quick-actions/reseed	reseed quick action templates

Users

Method	Path	Purpose
GET	/api/v1/users	agent/admin user listing
GET	/api/v1/users/me	current profile
PATCH	/api/v1/users/me	update own profile
POST	/api/v1/users/invite	admin invite flow
GET	/api/v1/users/:id	admin or self lookup
PATCH	/api/v1/users/:id/role	admin role change
DELETE	/api/v1/users/:id	admin deactivation

Auth behavior

The API does not manage sessions itself. It expects a Supabase access token in the Authorization header and derives app authorization from Supabase user metadata.