backend/docs/API_SPEC.md

Visione API Spec

Base path: /api/v1.

Technical

• GET /health: process health.
• GET /ready: MySQL readiness.
• GET /openapi.json: generated OpenAPI 3.0 JSON.
• GET /docs: Swagger UI page backed by the generated spec.

Auth

• POST /auth/register: create a citizen account.
• POST /auth/otp/request: send an OTP email through MailHog.
• POST /auth/otp/verify: verify OTP and create an API token.
• POST /auth/login/password: password login fallback.
• POST /auth/change-password: change the authenticated user's password.
• GET /me: return the authenticated user.

Protected endpoints use:

Authorization: Bearer <token>

Reports

• POST /reports: create a report.
• GET /reports: list reports with optional status, category_id, area_id.
• GET /reports/{id}: report detail.
• PATCH /reports/{id}/status: update status.
• POST /reports/{id}/take: operator/admin takes an open report.
• POST /reports/{id}/messages: write a report message.
• GET /reports/{id}/messages: list report messages.
• POST /reports/{id}/assignments: assign a team.
• POST /reports/{id}/feedback: add citizen feedback.
• POST /reports/{id}/media: upload up to five multipart media files. Supported types are JPEG, PNG, WebP, MP4, WebM and QuickTime. The legacy /reports/{id}/photos path is kept as a compatibility alias.

Admin Reference Data

• GET|POST /admin/categories
• GET|POST /admin/areas
• GET|POST /admin/teams
• GET /admin/stats/overview
• GET /admin/users
• PATCH /admin/users/{id}/roles
• PATCH /admin/users/{id}/ban