API Reference
The NestFleet API is a REST API served by the Hono server. All endpoints are prefixed with/api/v1 and return JSON. A full OpenAPI specification is coming soon — this page covers the main endpoint groups and authentication flow.
Base URL: https://your-domain/api/v1 for self-hosted, or https://api.nestfleet.dev/v1 for SaaS. All requests must use HTTPS in production.
Authentication
The API uses JWT Bearer token authentication. Obtain a token by calling the login endpoint, then include it in the Authorization header of every subsequent request:
Authorization: Bearer <your-jwt-token>
Access tokens are short-lived (default: 15 minutes). Use the refresh endpoint to obtain a new access token using the refresh token (returned in an httpOnly cookie on login). Token expiry is returned in the login response as expiresIn (seconds).
Login + list cases example
A complete example using curl — authenticate, capture the token, then list open cases:
# Step 1: Login and capture the access token
TOKEN=$(curl -s -X POST https://your-domain/api/v1/auth/login \
-H "Content-Type: application/json" \
-d '{"email":"[email protected]","password":"your-password"}' \
| jq -r '.accessToken')
# Step 2: List open cases for product ID 1
curl -s https://your-domain/api/v1/cases?productId=1&status=open \
-H "Authorization: Bearer $TOKEN" \
| jq .Endpoint groups
Auth
| Endpoint | Description |
|---|---|
| POST /auth/login | Authenticate with email and password. Returns accessToken and sets refresh cookie. |
| POST /auth/register | Create a new account (only when REGISTRATION_ENABLED=true). |
| POST /auth/refresh | Exchange a refresh token cookie for a new access token. |
| POST /auth/logout | Invalidate the refresh token and clear the cookie. |
| POST /auth/reset-password/request | Send a password reset email. |
| POST /auth/reset-password/confirm | Set a new password using the reset token from the email. |
Cases
| Endpoint | Description |
|---|---|
| GET /cases | List cases. Filter by productId, status, severity, type, assigneeId, channel. Paginated. |
| GET /cases/:id | Get a single case with full detail: triage result, notes, linked issues, reply history. |
| PATCH /cases/:id/status | Update case status. Body: { status, note? } |
| PATCH /cases/:id/assign | Assign the case to a user. Body: { userId } |
| PATCH /cases/:id/severity | Override the AI-assigned severity. Body: { severity: 'P0'|'P1'|...'P4' } |
| POST /cases/:id/notes | Add an internal note to the case. Body: { content } |
| POST /cases/:id/escalate | Escalate to a lead. Body: { targetUserId, note? } |
| POST /cases/:id/change-request | Create a change request from this case. |
Products
| Endpoint | Description |
|---|---|
| GET /products | List all products the authenticated user has access to. |
| POST /products | Create a new product. Admin only. |
| GET /products/:id | Get product details including channel configuration. |
| PATCH /products/:id | Update product settings. Admin only. |
| DELETE /products/:id | Archive a product. Admin only. |
Users
| Endpoint | Description |
|---|---|
| GET /users | List team members. Admin only. |
| POST /users/invite | Invite a new user by email. Admin only. |
| GET /users/:id | Get user profile and roles. |
| PATCH /users/:id | Update user details or roles. Admin only. |
| PATCH /users/:id/deactivate | Deactivate a user account. Admin only. |
| POST /users/:id/reset-password | Send a password reset email. Admin only. |
Knowledge Base
| Endpoint | Description |
|---|---|
| GET /knowledge/articles | List articles for a product. Filter by type, tags. |
| POST /knowledge/articles | Create a new article. Knowledge Lead or Admin only. |
| PATCH /knowledge/articles/:id | Update an article. Triggers re-embedding job. |
| DELETE /knowledge/articles/:id | Delete an article. Knowledge Lead or Admin only. |
| GET /knowledge/known-issues | List known issues for a product. |
| POST /knowledge/known-issues | Create a new known issue. |
| PATCH /knowledge/known-issues/:id | Update a known issue status, workaround, or fix version. |
Change Requests
| Endpoint | Description |
|---|---|
| GET /change-requests | List change requests. Filter by productId, status. |
| GET /change-requests/:id | Get CR detail with PR draft, risk assessment, and audit trail. |
| POST /change-requests/:id/approve | Approve a CR. Change Lead role required. Body: { rationale? } |
| POST /change-requests/:id/reject | Reject a CR. Change Lead role required. Body: { rationale } |
| POST /change-requests/:id/push-github | Push the approved PR draft to GitHub. Opens a PR in the product repo. |
Audit & Health
| Endpoint | Description |
|---|---|
| GET /audit | List audit events. Filter by entityType, entityId, actorId. Admin only. Paginated. |
| GET /health | Health check. Returns {status, db, version}. No auth required. |
Error responses
All error responses follow a consistent shape:
{
"error": "Unauthorised",
"message": "JWT token expired",
"statusCode": 401
}Validation errors (400) include a details array with per-field error messages from Zod.
A full OpenAPI 3.1 specification (Swagger UI) is coming in a future release. Until then, the Hono route files in src/api/routes/ are the authoritative source of truth for request and response shapes — each route validates its inputs with Zod schemas that double as the type contract.