Nümi API Reference
Base path for API requests: /api. All authenticated endpoints require a valid Clerk session (cookie or Bearer token) unless noted.
Authentication
- Authenticated routes: Use
AuthMiddleware; user ID is taken from the request context (userID). - Unauthenticated:
/api/contact,/api/test-emails,/api/auth/logout,/api/webhooks/clerk.
Settings
| Method | Path | Auth | Description |
|---|---|---|---|
| GET | /api/settings |
Yes | Get current user’s settings. User ID from context. |
| POST | /api/settings |
Yes | Create settings for the current user. Body: Settings JSON. |
| PUT | /api/settings |
Yes | Update current user’s settings. Body: Settings JSON. |
Settings body fields (for POST/PUT): unitSystem, height, age, sex, defaultCheckinDay, weekStartDay, notificationsEnabled, timeZone, email, firstName. Valid defaultCheckinDay / weekStartDay: Monday–Sunday. ID is set from the authenticated user.
Responses: 200/201 with settings object; 400 validation error; 401 unauthorized; 404 (GET when no settings).
Journeys
| Method | Path | Auth | Description |
|---|---|---|---|
| GET | /api/journeys |
Yes | List all journeys for the current user. |
| POST | /api/journeys |
Yes | Create a journey. Body: Journey (e.g. title, targetWeight). |
| GET | /api/journeys/{id} |
Yes | Get one journey. Must belong to current user. |
| PUT | /api/journeys/{id} |
Yes | Update journey. Must belong to current user. |
| DELETE | /api/journeys/{id} |
Yes | Delete journey. Must belong to current user. |
| PATCH | /api/journeys/{id}/levels/{levelNumber} |
Yes | Update a level (e.g. endWeight, check-in). Body: level fields. |
| POST | /api/journeys/{id}/email-report |
Yes | Request email report for journey. |
| GET | /api/journeys/active/ |
Yes | Get the current user’s active journey. |
| GET | /api/journeys/random-title |
Yes | Get a random journey title suggestion. |
Responses: 200/201 with journey or list; 400 bad request; 401 unauthorized; 403 forbidden; 404 not found.
Auth
| Method | Path | Auth | Description |
|---|---|---|---|
| GET | /api/auth/superadmin-status |
Yes | Returns { "isSuperadmin": boolean }. |
| POST | /api/auth/logout |
No | Clears session/cookies (e.g. Clerk). |
Contact
| Method | Path | Auth | Description |
|---|---|---|---|
| POST | /api/contact |
No | Submit contact form. Body: { "name", "email", "subject", "message" }. Sends email async. |
Response: 200 with { "success": true } or { "success": false, "error": "..." }.
Test emails
| Method | Path | Auth | Description |
|---|---|---|---|
| POST | /api/test-emails |
No | Send test email(s) to the given address. Body: { "email": "..." }. Used to preview templates (welcome, badge, check-in reminder, etc.). |
Webhooks
| Method | Path | Auth | Description |
|---|---|---|---|
| POST | /api/webhooks/clerk |
Clerk signature | Clerk webhook (user created/updated/deleted). Creates/updates settings. |
Errors
JSON error responses use the shape: { "error": "message" }. Typical status codes: 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 405 Method Not Allowed, 500 Internal Server Error.