FridgeRadar exposes a versioned JSON REST API built with FastAPI. Every feature of the application — registering users, managing household pantries, tracking expiry dates, and surfacing recipe suggestions — is accessible through this API. The server runs on port 8000 by default, and all resource endpoints share theDocumentation Index
Fetch the complete documentation index at: https://mintlify.com/EstefanoARG/FridgeRadar/llms.txt
Use this file to discover all available pages before exploring further.
/api/v1 prefix. Interactive documentation is generated automatically and always reflects the live schema.
Base URL
All API endpoints are rooted at:http://localhost:8000 with your hosted domain. The /api/v1 prefix is always required — requests to the bare root path are not routed to any resource handler.
Versioning
The current API version is v1. The version segment is embedded in every route path (/api/v1/...) rather than in a request header. Future breaking changes will be introduced under a new version prefix (e.g. /api/v2) while v1 remains available during a transition period.
Interactive Docs
FastAPI generates two interactive documentation UIs from the OpenAPI schema at server start-up — no additional tooling required.| UI | URL | Description |
|---|---|---|
| Swagger UI | GET /docs | Try out requests directly in the browser |
| Redoc | GET /redoc | Clean, readable reference layout |
Health Check
A lightweight liveness endpoint is available outside the versioned prefix and requires no authentication:Authentication
Most endpoints require a valid JWT Bearer token issued by the/api/v1/auth/login endpoint. Include the token in every authenticated request via the Authorization header:
Response Format
All responses are JSON. The table below summarises the HTTP status codes used across the API:| Status | Meaning |
|---|---|
200 OK | Successful retrieval or update |
201 Created | Resource created successfully |
204 No Content | Resource deleted; body is empty |
400 Bad Request | Malformed request or invalid credentials |
401 Unauthorized | Missing, invalid, or expired JWT token |
403 Forbidden | Authenticated but not permitted to access the resource |
404 Not Found | Requested resource does not exist |
409 Conflict | Request conflicts with current resource state |
422 Unprocessable Entity | Validation error or business rule violation |
Error Body
Errors follow FastAPI’s standardHTTPException envelope with a detail field:
detail array where each element identifies the failing field and the error message.
Resource Groups
FridgeRadar’s API is organised into 13 resource groups. All routes are prefixed with/api/v1.
Auth
Register new accounts and log in to obtain JWT access tokens. The login endpoint accepts OAuth2 password form encoding.
Usuarios
Read and update the authenticated user’s profile, including name, email address, and account status.
Hogares
Create and manage households. Invite or remove members, and administer household-level settings.
Zonas & Estantes
Define named zones within a household and manage shelves nested inside each zone. Shelves are the finest-grained physical storage unit tracked by FridgeRadar.
Inventario
Add, update, and remove pantry items assigned to a shelf. Each item carries a quantity, unit, and optional expiry date for freshness tracking.
Productos
Browse and maintain the shared product catalogue. Products are reusable definitions referenced by inventory items and recipes.
Recetas
Create and retrieve recipes. Each recipe lists required ingredients that can be matched against current pantry stock.
Alertas
Retrieve expiry notifications generated automatically when pantry items approach or pass their expiry date.
Listas de Compra
Manage household shopping lists. Add products with desired quantities and mark items as purchased.
Desperdicio
Log discarded items and query waste metrics over time to identify patterns and reduce food waste.
Semáforo
Query and update the freshness state of inventory items. States use a traffic-light model: green (fresh), amber (≤7 days), red (≤2 days).
Tengo Hambre
Get recipe suggestions ranked by how well they consume items that are close to expiry, minimising waste.
The Semáforo thresholds are configurable via the
SEMAFORO_AMARILLO_DIAS (default 7) and SEMAFORO_ROJO_DIAS (default 2) environment variables in your server configuration.