Final Milestone API Endpoints

Final Milestone API Endpoints

API Documentation

• Live Swagger / OpenAPI UI: https://socialeventmapper.com/api/docs/
• Source OpenAPI specifications: docs/openapi
• Backend architecture and business-flow documentation: docs/backend
• Route registration source: backend/internal/server/http.go

The live API documentation covers the final release endpoints served under /api. The specifications are split by domain (auth, event, ticket, profile, notification, badge, category, favorite_location, and admin) and are mounted behind Swagger UI in the deployed environment.

Endpoint Coverage Summary

Domain	Endpoint groups covered in the final release
Authentication & sessions	Email OTP registration, availability checks, login, refresh, logout, forgot-password OTP verification, and password reset
Event management	Event discovery, event creation, event detail, host update/cancel/complete, host management context, participants, favorite/unfavorite, comments, review comments, image upload confirmation, and event reports
Participation & access control	Public/protected join, private invitations, protected join requests, participant leave, host approval/rejection, invitation revoke, and event-update reconfirmation
Ticketing & check-in	User ticket list/detail, mobile QR token stream, host mobile ticket scan, ticket state transitions, and reconfirmation-aware ticket reactivation
Social and profile features	User profile, public profile, hosted/upcoming/completed/canceled events, equipment, showcase images, favorite locations, badges, and user search
Notifications	Notification list, unread count, mark-read/delete, push device registration/revocation, and SSE notification stream
Admin moderation	Admin users, events, participations, tickets, notifications, reports, categories, invitations, join requests, comments, ratings, favorites, badges, and push devices

The examples below use sanitized UUIDs and tokens. Long event-detail responses are shortened to the fields relevant to each workflow, while field names, enum values, and lifecycle states match the final OpenAPI contracts and backend handlers.

Sample Usage Scenarios

Scenario 1: Protected Event QR Ticket Check-In

• Endpoint: GET /api/me/tickets/{ticketId}/qr-stream and POST /api/host/events/{eventId}/ticket-scans
• Scenario Description: A participant who has an approved ticket for a protected event opens the mobile ticket screen near the venue. The backend streams short-lived QR tokens only when the participant is eligible and within the configured proximity. The event host scans the latest token from the mobile app and the backend atomically marks the ticket as used.

The Request: participant opens the QR stream

curl -N -X GET "https://socialeventmapper.com/api/me/tickets/8f29d184-6d80-4a3b-9f1f-5b7e0f54e5aa/qr-stream?lat=41.0853&lon=29.0444" \
  -H "Authorization: Bearer <participant_access_token>" \
  -H "X-Client-Surface: MOBILE"

The Response:

event: qr_token
data: {"token":"<signed-short-lived-qr-token>","expires_at":"2026-05-16T16:30:10+03:00","version":42}

The Request: host scans the token

curl -X POST "https://socialeventmapper.com/api/host/events/5f81d6de-8cb4-4639-8f60-7c9f55456121/ticket-scans" \
  -H "Authorization: Bearer <host_access_token>" \
  -H "X-Client-Surface: MOBILE" \
  -H "Content-Type: application/json" \
  -d '{
    "qr_token": "<signed-short-lived-qr-token>"
  }'

The Response:

{
  "result": "ACCEPTED",
  "ticket_id": "8f29d184-6d80-4a3b-9f1f-5b7e0f54e5aa",
  "participation_id": "2b715a91-c610-4fc6-8932-9a4bda391b40",
  "user_id": "7b9ad5e2-6807-4e47-97ec-3d443f4e41b5",
  "ticket_status": "USED"
}

Evidence: Ticketing and QR flow were implemented in PR #513, with stale QR stream cleanup in PR #557.

Scenario 2: Event Update, Versioned Diff, and Participant Reconfirmation

• Endpoint: PATCH /api/events/{id}, GET /api/events/{id}, and POST /api/events/{id}/participation/reconfirm
• Scenario Description: A host changes critical details of an active event. The backend creates a new event version, moves affected approved participations and tickets to PENDING, exposes a viewer-specific diff to each participant, and reactivates the participant's ticket when they reconfirm.

The Request: host updates critical event details

curl -X PATCH "https://socialeventmapper.com/api/events/5f81d6de-8cb4-4639-8f60-7c9f55456121" \
  -H "Authorization: Bearer <host_access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Istanbul Trail Run - Updated Start",
    "start_time": "2026-05-24T09:00:00+03:00",
    "address": "Belgrad Forest North Gate, Istanbul"
  }'

The Response: participant sees what changed

{
  "id": "5f81d6de-8cb4-4639-8f60-7c9f55456121",
  "version_no": 6,
  "title": "Istanbul Trail Run - Updated Start",
  "viewer_context": {
    "participation_status": "PENDING",
    "needs_reconfirmation": true,
    "last_confirmed_event_version": 5,
    "latest_event_version": 6,
    "event_diff": {
      "from_version_no": 5,
      "to_version_no": 6,
      "changed_fields": ["title", "start_time", "location"],
      "changes": [
        {
          "field": "start_time",
          "old_value": "2026-05-24T08:00:00+03:00",
          "new_value": "2026-05-24T09:00:00+03:00"
        }
      ]
    }
  }
}

The Request: participant reconfirms

curl -X POST "https://socialeventmapper.com/api/events/5f81d6de-8cb4-4639-8f60-7c9f55456121/participation/reconfirm" \
  -H "Authorization: Bearer <participant_access_token>"

The Response:

{
  "participation_id": "2b715a91-c610-4fc6-8932-9a4bda391b40",
  "event_id": "5f81d6de-8cb4-4639-8f60-7c9f55456121",
  "status": "APPROVED",
  "reconfirmed_at": "2026-05-16T16:31:42+03:00",
  "updated_at": "2026-05-16T16:31:42+03:00",
  "last_confirmed_event_version": 6,
  "latest_event_version": 6,
  "ticket_status": "ACTIVE"
}

Evidence: Reconfirmation state transitions were implemented in PR #583, versioned event diffs in PR #584, and pending-ticket reactivation in PR #603.

Scenario 3: Private Event Invitation and Acceptance

• Endpoint: POST /api/events/{id}/invitations and POST /api/me/invitations/{invitation_id}/accept
• Scenario Description: A host creates a private event and invites users by exact username. The invitation API supports partial success, creates notifications, and lets invited users accept the invitation to become approved participants.

The Request: host invites users

curl -X POST "https://socialeventmapper.com/api/events/3ad7ed94-d6fe-4f39-8bd3-bf15c7d605f0/invitations" \
  -H "Authorization: Bearer <host_access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "usernames": ["participant_user", "unknown_user"],
    "message": "Join our private photography walk this weekend."
  }'

The Response:

{
  "success_count": 1,
  "invalid_username_count": 1,
  "failed_count": 0,
  "successful_invitations": [
    {
      "invitation_id": "a19c6fef-5fcb-4fb5-90bb-970d359b58cc",
      "event_id": "3ad7ed94-d6fe-4f39-8bd3-bf15c7d605f0",
      "invited_user_id": "7b9ad5e2-6807-4e47-97ec-3d443f4e41b5",
      "username": "participant_user",
      "status": "PENDING",
      "created_at": "2026-05-16T16:32:10+03:00"
    }
  ],
  "invalid_usernames": ["unknown_user"],
  "failed": []
}

The Request: invited user accepts

curl -X POST "https://socialeventmapper.com/api/me/invitations/a19c6fef-5fcb-4fb5-90bb-970d359b58cc/accept" \
  -H "Authorization: Bearer <participant_access_token>"

The Response:

{
  "invitation_id": "a19c6fef-5fcb-4fb5-90bb-970d359b58cc",
  "event_id": "3ad7ed94-d6fe-4f39-8bd3-bf15c7d605f0",
  "invitation_status": "ACCEPTED",
  "participation_id": "7805707b-2a8e-4020-b442-0fbf942bb99b",
  "participation_status": "APPROVED",
  "updated_at": "2026-05-16T16:33:10+03:00"
}

Evidence: Private invitation creation, listing, acceptance, decline, notifications, and ticket integration were implemented in PR #534.

Scenario 4: Event Report and Admin Moderation

• Endpoint: POST /api/events/{id}/reports, GET /api/admin/event-reports, and PATCH /api/admin/event-reports/{report_id}/status
• Scenario Description: A user reports an event with a moderation category and explanation. An admin lists pending reports in the backoffice and marks the report as reviewed after taking the required moderation action.

The Request: user reports an event

curl -X POST "https://socialeventmapper.com/api/events/5f81d6de-8cb4-4639-8f60-7c9f55456121/reports" \
  -H "Authorization: Bearer <user_access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "report_category": "SAFETY",
    "message": "The venue entrance was unsafe and needs moderator review."
  }'

The Response:

{
  "id": "9dd8c962-6a13-4b50-8c06-31be5da6a8b5",
  "event_id": "5f81d6de-8cb4-4639-8f60-7c9f55456121",
  "reporter_user_id": "7b9ad5e2-6807-4e47-97ec-3d443f4e41b5",
  "report_category": "SAFETY",
  "message": "The venue entrance was unsafe and needs moderator review.",
  "image_url": null,
  "status": "PENDING",
  "created_at": "2026-05-16T16:35:00+03:00"
}

The Request: admin resolves the report

curl -X PATCH "https://socialeventmapper.com/api/admin/event-reports/9dd8c962-6a13-4b50-8c06-31be5da6a8b5/status" \
  -H "Authorization: Bearer <admin_access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "REVIEWED",
    "reason": "Reviewed by admin and handled from the backoffice."
  }'

The Response:

{
  "id": "9dd8c962-6a13-4b50-8c06-31be5da6a8b5",
  "event_id": "5f81d6de-8cb4-4639-8f60-7c9f55456121",
  "event_title": "Istanbul Trail Run - Updated Start",
  "reporter_user_id": "7b9ad5e2-6807-4e47-97ec-3d443f4e41b5",
  "report_category": "SAFETY",
  "message": "The venue entrance was unsafe and needs moderator review.",
  "status": "REVIEWED",
  "created_at": "2026-05-16T16:35:00+03:00",
  "updated_at": "2026-05-16T16:36:15+03:00"
}

Evidence: Event reports were added in PR #556, admin moderation APIs and backoffice actions in PR #606, and admin role authorization/read APIs in PR #528.