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 Mailpit.
• 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.
• PATCH /me: edit user informations.

Protected endpoints use:

Authorization: Bearer <token>

Reports

• POST /reports: create a report.
• GET /reports: list reports with optional status, category_id, area_id.
• GET /report-categories: list active report categories for authenticated users.
• GET /operator/teams: list active intervention teams for operators/admins.
• 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.
• GET /reports/{id}/team-suggestions: suggest compatible teams by area/category.
• POST /reports/{id}/intervention-link: create or rotate public team link.
• DELETE /reports/{id}/intervention-link: revoke public team link.
• PATCH /reports/{id}/status: update status.
• POST /reports/{id}/take: assigned-queue operator 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: assigned operator flags a report message for moderation.
• POST /reports/{id}/assignments: assign a team.
• POST /reports/{id}/feedback: add citizen feedback.
• POST /reports/{id}/flags: assigned operator flags 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.
• PATCH /notifications/read-all: mark all authenticated user notifications as read.
• GET /me/rewards: return current points and reward event history.

Admin Reference Data

• POST /admin/categories
• PATCH /admin/categories/{id}
• POST /admin/areas
• PATCH /admin/areas/{id}
• POST /admin/teams
• PATCH /admin/teams/{id}
• 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 /areas: list active municipal areas.
• GET /interventions/{token}: public intervention summary for external teams.
• GET /open-data/reports: anonymized resolved/closed report export.