# 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.

Protected endpoints use:

```http
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.