API — Overview

The Neemias API is served by a Cloudflare Worker and organized by resource. All routes use the /api/v1 prefix and follow a declarative middleware pipeline that applies authentication, role-based authorization, rate limiting, and schema validation consistently.

Authentication and Headers

Every authenticated request must include three required headers:

Header	Value	Required for
Authorization	Bearer <accessToken> (JWT HS256)	All authenticated routes
X-Device-Id	UUID v4 identifying the device	All authenticated routes
Idempotency-Key	UUID v4	All mutations (POST, PATCH)

The Idempotency-Key ensures that operations retried due to timeout or network failure are not processed twice — essential for the offline-first architecture with asynchronous sync. See the Idempotency guide for ledger details.

Endpoint Summary (30+ routes)

Health & Meta

Method	Route	Roles	Description
GET	/api/v1/health	Public	Health check
GET	/.well-known/security.txt	Public	RFC 9116

Authentication

Method	Route	Roles	Description
POST	/api/v1/auth/login	Public	Login — rate limit: 5/min
POST	/api/v1/auth/refresh	Public	Renew token — rate limit: 10/min
POST	/api/v1/auth/revoke	Authenticated	Revoke session
POST	/api/v1/session/validate	Authenticated	Validate active session

Students

Method	Route	Roles	Description
GET	/api/v1/students	Authenticated	List students (paginated, search)
POST	/api/v1/students	ADMIN, CADASTRO	Create student
PATCH	/api/v1/students/:studentId	ADMIN, CADASTRO	Update student
POST	/api/v1/students/:studentId/delete	ADMIN	Soft-delete with justification

Attendance

Method	Route	Roles	Description
POST	/api/v1/attendance/events	CHAMADOR, ADMIN	Mark attendance

Classes

Method	Route	Roles	Description
GET	/api/v1/classes	Authenticated	List classes
POST	/api/v1/classes	ADMIN	Create class
PATCH	/api/v1/classes/:classId	ADMIN	Update class
POST	/api/v1/classes/:classId/delete	ADMIN	Soft-delete class

Nuclei

Method	Route	Roles	Description
GET	/api/v1/nuclei	Authenticated	List nuclei
POST	/api/v1/nuclei	ADMIN	Create nucleus
PATCH	/api/v1/nuclei/:nucleusId	ADMIN	Update nucleus
POST	/api/v1/nuclei/:nucleusId/delete	ADMIN	Soft-delete nucleus

Users

Method	Route	Roles	Description
GET	/api/v1/users	ADMIN	List users
POST	/api/v1/users	ADMIN	Create user
PATCH	/api/v1/users/:userId	ADMIN	Update user
POST	/api/v1/users/:userId/reset-password	ADMIN	Reset password
POST	/api/v1/users/:userId/deactivate	ADMIN	Deactivate user

Roles

Method	Route	Roles	Description
GET	/api/v1/roles	ADMIN	List roles
POST	/api/v1/roles	ADMIN	Create custom role
PATCH	/api/v1/roles/:roleName	ADMIN	Update role
DELETE	/api/v1/roles/:roleName	ADMIN	Delete non-system role

Sync

Method	Route	Roles	Description
POST	/api/v1/sync/events	CHAMADOR, ADMIN, CADASTRO	Batch wrapper — multiple events
POST	/api/v1/sync/event	Authenticated	Single atomic event via D1.batch()

Dev

Method	Route	Roles	Description
POST	/_seed	—	Demo data seed (dev only)

Middleware Pipeline

The route() helper (workers/src/middleware/pipeline.ts) builds each endpoint as a declarative middleware chain that executes in sequence. The typical flow is:

Request → rateLimit? → requireAuth (JWT) → requireRole → Zod validation → Handler → Response

Security headers (CORS, CSP, HSTS) are applied uniformly by the router. Errors follow the { error, message, details } envelope with canonical HTTP codes (401 UNAUTHORIZED, 403 FORBIDDEN_ROLE, 409 IDEMPOTENCY_KEY_REUSED_WITH_DIFFERENT_PAYLOAD, etc.).

See the API Guide for the complete workflow for implementing new routes and the OpenAPI specification for the detailed contract of each endpoint.

⚠️ Section under expansion.

---

Source: workers/src/router.ts + workers/CONTEXT.md