API Endpoints

API Endpoints

All API routes live in routes/api.php. The API serves two clients: the Vue 3 SPA (session auth) and a mobile app (Bearer token auth). Current version is v3. All legacy v1/v2 endpoints have been removed (2026-03-01).

Key Files

• routes/api.php — All route definitions (~146 active routes)
• readme/API.md — Comprehensive endpoint documentation with request/response contracts for every endpoint (2080+ lines). READ THIS FIRST before modifying any API endpoint.
• app/Http/Controllers/Auth/AuthTokenController.php — Mobile token login (Sanctum)
• app/Http/Controllers/Auth/LoginController.php — SPA session login
• app/Http/Controllers/Auth/RegisterController.php — User registration (both clients)
• app/Http/Controllers/Uploads/UploadPhotoController.php — v3 upload (web EXIF + mobile explicit coords)
• app/Http/Controllers/API/Tags/PhotoTagsController.php — v3 tag CRUD (POST add, PUT replace)
• app/Http/Controllers/API/Tags/GetTagsController.php — Public tag catalog
• app/Http/Controllers/User/ProfileController.php — Profile (auth + public)
• app/Http/Controllers/User/Photos/UsersUploadsController.php — v3 user photos (paginated, filterable)
• app/Http/Controllers/Leaderboard/LeaderboardController.php — Leaderboard (time-filtered, location-scoped)
• app/Http/Controllers/Points/PointsController.php — Map points GeoJSON
• app/Http/Controllers/Points/PointsStatsController.php — Map viewport stats
• app/Http/Controllers/Clusters/ClusterController.php — Map clusters GeoJSON (ETag cached)
• app/Http/Controllers/Location/LocationController.php — Location hierarchy API
• app/Http/Controllers/Location/TagController.php — Location tag analytics
• app/Http/Controllers/API/TeamsController.php — Team CRUD + membership
• app/Http/Controllers/Teams/TeamPhotosController.php — Team photo management + school approval
• app/Http/Controllers/Teams/TeamsLeaderboardController.php — Teams leaderboard
• app/Http/Controllers/Teams/TeamsClusterController.php — Team map clusters/points
• app/Http/Controllers/API/DeleteAccountController.php — GDPR account deletion
• app/Http/Controllers/UsersController.php — Settings, privacy toggles, details
• app/Http/Controllers/ApiSettingsController.php — Privacy settings (maps/leaderboard/createdby)
• app/Http/Controllers/Achievements/AchievementsController.php — User achievements
• app/Http/Controllers/API/GlobalStatsController.php — World totals (total_tags, total_images, total_users, new_users_*)
• app/Http/Controllers/CommunityController.php — Community stats
• app/Http/Controllers/Cleanups/ — 4 cleanup controllers (create, list, join, leave)
• app/Http/Requests/ — Form request validation classes (one per endpoint that needs validation)

Route Groups

Invariants

1. Dual auth: session + token. All auth:sanctum routes accept both SPA session cookies and mobile Bearer tokens. The SPA uses POST /api/auth/login (session), mobile uses POST /api/auth/token (Sanctum token).
2. Token name is mobile. AuthTokenController creates tokens named mobile and revokes previous mobile tokens on each login (prevents buildup).
3. Registration always sets name = NULL. Ignores any name field in the request. Auto-generates username if omitted (pattern: {adjective}-{noun}-{number}).
4. readme/API.md is the source of truth. Every endpoint's exact request/response contract is documented there. Always consult it before modifying an endpoint.
5. Error responses are inconsistent. Some controllers return { "msg": "..." }, others return { "message": "..." }. This is a known legacy issue — match the existing pattern for each controller. UploadPhotoRequest overrides failedValidation() to return { success, error, message, errors } with a typed error code field (no_exif, no_gps, no_datetime, invalid_coordinates, validation_error). Duplicates are no longer a validation error — the controller returns idempotent 200 success with the existing photo_id. Handler::unauthenticated() returns { message: "Unauthenticated." } without an error code (known inconsistency). PhotoTagsRequest uses Laravel's default failedValidation() (no custom error codes). Admin routes (/api/admin/*) require the admin middleware which already wraps auth:sanctum — do not add a redundant auth:sanctum wrapper.
6. Public endpoints must filter is_public = true. All map/points/global/community endpoints use Photo::public() scope or explicit where('is_public', true).
7. v3 is the current API version. New endpoints go in the v3 group. All legacy v1/v2 endpoints have been removed.
8. Location API uses locations/location_type keys. Not children/children_type. The {type} parameter accepts country, state, or city.
9. Consistent API field naming convention. All list/leaderboard endpoints (teams, locations, global stats) use: total_tags, total_photos, total_members, created_at, updated_at. Never use old names like total_litter, total_images, tags, photos, contributors.
10. Points API returns page (not current_page). Frontend normalizes to current_page in pointsHelper.getPaginationData().
11. Delete account is GDPR-compliant. Photos are preserved as anonymous contributions (user_id set to NULL via DB CASCADE). Redis leaderboards and per-user metrics are cleaned up.

Patterns

Auth flow (Mobile)

POST /api/auth/token  →  { token, user }
// Include on all subsequent requests:
Authorization: Bearer <token>
// Validate token is still valid:
POST /api/validate-token  →  { message: "valid" }

Auth flow (SPA)

GET /sanctum/csrf-cookie        →  Sets XSRF-TOKEN cookie
POST /api/auth/login            →  Sets session cookie, returns { success, user }
GET /api/user/profile/index     →  Returns user + stats + level + rank
POST /api/auth/logout           →  Destroys session

Photo lifecycle endpoints

POST  /api/v3/upload              →  Upload photo (web: EXIF; mobile: explicit lat/lon/date)
                                      Idempotent: a duplicate (user_id+datetime) returns 200
                                      { success, photo_id: <existing>, already_uploaded: true,
                                        tagged: <bool>, xp_awarded: 0 } — NOT a 422.
                                      On validation failure: { success: false, error: <code>, message, errors }
                                      Error codes: no_exif | no_gps | no_datetime |
                                                   invalid_coordinates | validation_error
GET   /api/v3/user/photos         →  List user's photos (paginated, filterable, per_page up to 100)
                                      Response includes `is_public` (boolean) and `school_team` (boolean)
                                      for each photo. Owner sees all photos including private ones.
GET   /api/v3/user/photos/stats   →  Aggregate counts (totalPhotos, totalTags, leftToTag)
POST  /api/v3/tags                →  Add tags to untagged photo (PhotoTagsRequest — default Laravel errors)
PUT   /api/v3/tags                →  Replace all tags on tagged photo (edit mode, accepts empty tags: [])
PATCH /api/v3/photos/{id}/visibility →  Toggle is_public for a single photo (owner only, auth:sanctum).
                                      Returns { is_public: bool }. Blocked for school team photos (403).
                                      PhotoObserver marks dirty tiles on change.
POST  /api/profile/photos/delete  →  Delete single photo { "photoid": 123 } (soft delete)

Leaderboard query parameters

GET /api/leaderboard?timeFilter=all-time&locationType=country&locationId=1&page=1
// timeFilter: all-time | today | yesterday | this-month | last-month | this-year | last-year
// locationType: country | state | city (optional)
// locationId: numeric ID (required if locationType set)
// All time filters use MySQL metrics table. Per page hardcoded to 100.
// Public endpoint (no auth required). Optional auth adds currentUserRank.

Team photo management (school teams)

GET    /api/teams/photos?team_id=X&status=pending   →  List photos (with new_tags CLO format)
GET    /api/teams/photos/{photo}?team_id=X           →  Single photo (with new_tags)
GET    /api/teams/photos/member-stats?team_id=X      →  Per-student stats (leader only, safeguarding)
GET    /api/teams/photos/map?team_id=X               →  Map points (up to 5000)
POST   /api/teams/photos/approve   { photo_ids, team_id }  →  Approve (fires TagsVerifiedByAdmin)
POST   /api/teams/photos/revoke    { photo_ids, team_id }  →  Revoke approval (reverses metrics)
PATCH  /api/teams/photos/{photo}/tags  { tags: [...] }     →  Edit tags (CLO format, leader/school_manager)
DELETE /api/teams/photos/{photo}?team_id=X                  →  Delete (reverses metrics first)

# Participant management (auth:sanctum, team leader only)
GET    /api/teams/{team}/participants                       →  List slots with photo_count
POST   /api/teams/{team}/participants  { count: N }        →  Create slots in bulk
POST   /api/teams/{team}/participants/{id}/deactivate       →  Revoke session
POST   /api/teams/{team}/participants/{id}/activate         →  Re-enable session
POST   /api/teams/{team}/participants/{id}/reset-token      →  Regenerate token (returns new token)
DELETE /api/teams/{team}/participants/{id}                   →  Hard delete slot

# Participant session (public/token auth)
POST   /api/participant/session  { token: "64-char" }      →  Validate token, return session info (public)
POST   /api/participant/upload                              →  Upload photo (X-Participant-Token header)
POST   /api/participant/tags     { photo_id, tags }        →  Tag own photo (X-Participant-Token header)
GET    /api/participant/photos                              →  List own photos (X-Participant-Token header)
DELETE /api/participant/photos/{photo}                       →  Delete own pre-approval photo

Public profile (no auth required)

GET /api/user/profile/{id}
// Returns stats, level, rank, achievements, recent locations
// Respects privacy: returns { public: false } if profile is private
// Respects show_name/show_username flags