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 /operator/reports/assigned: list reports assigned to the current operator.
• GET /operator/reports/open: list open unassigned reports.
• GET /operator/reports/others: list reports assigned to other operators.
• GET /reports/{id}: report detail.
• GET /reports/{id}/intervention-summary: operator-facing report summary with citizen contact data, media and latest messages.
• 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}/messages/{message_id}/flags: flag a message for moderation.
• POST /reports/{id}/assignments: assign a team.
• POST /reports/{id}/feedback: add citizen feedback.
• POST /reports/{id}/flags: flag a report for moderation.
• POST /reports/{id}/media: upload up to five multipart media files. Supported types are JPEG, PNG, WebP, MP4, WebM and QuickTime.

User

• GET /notifications: list authenticated user notifications.
• PATCH /notifications/{id}/read: mark one notification as read.
• GET /me/rewards: return current points and reward event history.

Admin Reference Data

• GET|POST /admin/categories
• GET|POST /admin/areas
• GET|POST /admin/teams
• GET /admin/stats/overview
• GET /admin/moderation: list moderation flags with optional status.
• PATCH /admin/moderation/{id}: resolve or dismiss a moderation flag, optionally rejecting the related report.
• GET /admin/users
• PATCH /admin/users/{id}/roles
• PATCH /admin/users/{id}/ban

Public Data

• GET /open-data/reports: anonymized resolved/closed report export.