API Reference¶

FreezerMan exposes a RESTful JSON API for managing household freezer inventories. All endpoints are prefixed with /api/v1/.

Base URL¶

https://<your-domain>/api/v1/

In local development the default is http://localhost:3000/api/v1/.

Authentication¶

The API uses JWT Bearer tokens. Obtain a token pair by calling POST /auth/login or POST /auth/register, then include the access token in every subsequent request:

Authorization: Bearer <accessToken>

Token lifecycle¶

When you call POST /auth/refresh, the server issues a new access token and a new refresh token. The old refresh token is revoked immediately (rotation). Clients must store and use the new refresh token for subsequent refreshes.

Error format¶

All error responses follow a consistent shape:

{
  "statusCode": 401,
  "message": "Invalid credentials",
  "error": "Unauthorized"
}

Pagination¶

Endpoints that return collections use a PaginatedResponse<T> envelope:

{
  "data": [
    { "id": "abc123", "name": "Chicken breast", "quantity": 4 }
  ],
  "total": 42,
  "page": 1,
  "limit": 20
}

Control pagination with the page and limit query parameters.

Rate limiting¶

The API enforces per-IP rate limits to prevent abuse.

Exceeding the limit returns 429 Too Many Requests.

IDs¶

All resource identifiers use the CUID2 format (e.g., clh2v3x0k0000qw08z1y9d3rk).

Dates¶

All date/time values are serialized as ISO-8601 strings in UTC (e.g., 2025-01-15T08:30:00.000Z).

Swagger UI¶

In development mode only, interactive API documentation is available at:

http://localhost:3000/api/docs

This Swagger UI is disabled in production builds.

Endpoint overview¶