Skip to content

Final API Documentation

Jump to bottom
delibas-rojhat edited this page May 15, 2026 · 2 revisions

Final API Documentation with Examples

This document describes the backend API for the final release of the Neighborhood Emergency Preparedness Hub (NEPH). The backend is a Node.js + Express API and exposes JSON endpoints under /api.

API Documentation Link

  • Live API root: https://api.neph.app/api
  • Local API root: http://localhost:3000/api
  • Health check: https://api.neph.app/health
  • This wiki page is the final API documentation for the release.

General Conventions

Content Type

All request bodies are JSON.

Content-Type: application/json

Authentication

Protected endpoints require a JWT access token in the Authorization header.

Authorization: Bearer <accessToken>

The access token is returned by POST /api/auth/login.

Guest Help Request Access

Guest-created help requests return a request-specific guestAccessToken. Guests can use this token to read or update only that help request.

x-help-request-access-token: <guestAccessToken>

The same token may also be passed as a query parameter:

GET /api/help-requests/{requestId}?guestAccessToken=<guestAccessToken>

Standard Error Shape

Most errors use this JSON format:

{
  "code": "VALIDATION_FAILED",
  "message": "Validation failed",
  "details": [
    "`status` must be one of: safe, not_safe, unknown."
  ]
}

Common Status Codes

Status Meaning
200 Successful read or update
201 Resource created
204 Resource deleted with no response body
400 Validation error
401 Missing, invalid, or expired authentication
403 Authenticated but not allowed
404 Resource not found
409 Conflict, such as invalid status transition
429 Too many requests on rate-limited endpoints
500 Unexpected server error
503 External provider unavailable
504 External provider timeout

Endpoint Summary

Method Path Auth Description
GET /health No Backend health check
GET /api No API metadata and enabled modules
GET /api/auth No Auth module metadata
POST /api/auth/signup No Create account
POST /api/auth/login No Login and receive JWT
GET /api/auth/verify-email No Verify email token
POST /api/auth/resend-verification No Resend verification email
POST /api/auth/forgot-password No Send password reset email
POST /api/auth/reset-password No Reset password
POST /api/auth/google No Login/signup with Google token
POST /api/auth/logout Yes Logout confirmation
GET /api/auth/me Yes Current authenticated user
DELETE /api/auth/me Yes Delete own account
GET /api/profiles No Profile module metadata
GET /api/profiles/me Yes Get own profile bundle
PATCH /api/profiles/me Yes Create/update base profile
PATCH /api/profiles/me/physical Yes Update physical information
PATCH /api/profiles/me/health Yes Update health information
PATCH /api/profiles/me/location Yes Update saved location
PATCH /api/profiles/me/privacy Yes Update privacy settings
PATCH /api/profiles/me/profession Yes Update profession
PUT /api/profiles/me/expertise-areas Yes Replace expertise areas
POST /api/help-requests Optional Create help request as user or guest
GET /api/help-requests Yes List own help requests
GET /api/help-requests/active Optional List active visible help requests, optionally filtered
GET /api/help-requests/{requestId} Yes or guest token Get one help request
PATCH /api/help-requests/{requestId} Yes or guest token Update help request details
PATCH /api/help-requests/{requestId}/status Yes or guest token Update request status
GET /api/availability/status Yes Get volunteer availability and active assignment
POST /api/availability/toggle Yes Set volunteer availability
POST /api/availability/sync Yes Sync offline availability records
GET /api/availability/my-assignment Yes Get active assignment
POST /api/availability/assignments/{assignmentId}/cancel Yes Cancel current assignment
POST /api/availability/assignments/resolve Yes Resolve assigned request
GET /api/assignments/{assignmentId}/route Yes Get route information for an assignment
GET /api/location/tree No Get country/city/district/neighborhood hierarchy
GET /api/location/search No Search locations
GET /api/location/reverse No Reverse-geocode coordinates
GET /api/gathering-areas/nearby No Get nearby gathering/safe areas
GET /api/gathering-areas/viewport No Get gathering/safe areas inside map viewport
GET /api/announcements No List public announcements
GET /api/announcements/{announcementId} No Get one public announcement
GET /api/safety-status/me Yes Get own safety status
PATCH /api/safety-status/me Yes Update own safety status
GET /api/safety-status/visible Yes List safety statuses visible to current user
GET /api/operational-location/me Yes Get current operational location
PATCH /api/operational-location/me Yes Update current operational location
GET /api/safety-circles Yes List own safety circles
POST /api/safety-circles Yes Create safety circle
GET /api/safety-circles/invites Yes List received circle invites
POST /api/safety-circles/invites/{inviteId}/respond Yes Accept or reject circle invite
GET /api/safety-circles/{circleId} Yes Get circle details and members
POST /api/safety-circles/{circleId}/invites Yes Invite a user to a circle
PATCH /api/safety-circles/{circleId}/owner Yes Transfer circle ownership
PATCH /api/safety-circles/{circleId}/check-in Yes Check in to a circle with safety status
DELETE /api/safety-circles/{circleId} Yes Delete circle as owner
DELETE /api/safety-circles/{circleId}/members/me Yes Leave circle
POST /api/notifications Admin Create notification
GET /api/notifications Yes List own notifications
PATCH /api/notifications/read-all Yes Mark all notifications as read
PATCH /api/notifications/{notificationId}/read Yes Mark one notification as read
POST /api/notifications/devices/register Yes Register push device
POST /api/notifications/devices/unregister Yes Unregister push device
GET /api/notifications/preferences Yes Get push preferences
PATCH /api/notifications/preferences Yes Update push preferences
GET /api/notifications/preferences/types Yes Get notification type preferences
PATCH /api/notifications/preferences/types Yes Update one notification type preference
GET /api/notifications/unread-count Yes Get unread notification count
GET /api/notifications/admin/stats Admin Get notification delivery statistics
POST /api/notifications/admin/broadcast/emergency Admin Send emergency broadcast by radius
GET /api/admin/users Admin List users
PATCH /api/admin/users/{userId}/ban Admin Ban/suspend user
PATCH /api/admin/users/{userId}/unban Admin Unban user
GET /api/admin/help-requests Admin List help requests
GET /api/admin/stats Admin Basic system statistics
GET /api/admin/emergency-overview Admin Emergency dashboard overview
GET /api/admin/emergency-history Admin Emergency history report
GET /api/admin/emergency-analytics Admin Emergency analytics report
GET /api/admin/deployment-monitoring Admin Deployment monitoring data
GET /api/admin/announcements Admin List announcements
POST /api/admin/announcements Admin Create announcement
PATCH /api/admin/announcements/{announcementId} Admin Update announcement
DELETE /api/admin/announcements/{announcementId} Admin Delete announcement

Deprecated Compatibility Aliases

The backend still exposes legacy admin aliases under /api/auth/admin/* for backward compatibility. New clients should use /api/admin/*.

Method Deprecated Path Replacement
GET /api/auth/admin/users GET /api/admin/users
PATCH /api/auth/admin/users/{userId}/ban PATCH /api/admin/users/{userId}/ban
PATCH /api/auth/admin/users/{userId}/unban PATCH /api/admin/users/{userId}/unban
GET /api/auth/admin/help-requests GET /api/admin/help-requests
GET /api/auth/admin/stats GET /api/admin/stats
GET /api/auth/admin/emergency-overview GET /api/admin/emergency-overview
GET /api/auth/admin/emergency-history GET /api/admin/emergency-history
GET /api/auth/admin/emergency-analytics GET /api/admin/emergency-analytics
GET /api/auth/admin/deployment-monitoring GET /api/admin/deployment-monitoring
GET /api/auth/admin/announcements GET /api/admin/announcements
POST /api/auth/admin/announcements POST /api/admin/announcements
PATCH /api/auth/admin/announcements/{announcementId} PATCH /api/admin/announcements/{announcementId}
DELETE /api/auth/admin/announcements/{announcementId} DELETE /api/admin/announcements/{announcementId}

Module Details

Auth API

Auth endpoints are available under /api/auth.

Important request bodies:

{
  "email": "user@example.com",
  "password": "password123",
  "acceptedTerms": true
}
{
  "email": "user@example.com",
  "password": "password123"
}

POST /api/auth/google accepts a Google identity token and returns the same login response shape as normal login.

Profiles API

Profile endpoints are available under /api/profiles. All /me endpoints require authentication.

Profile updates are split into base profile, physical information, health information, saved location, privacy settings, profession, and expertise areas.

Privacy fields:

{
  "profileVisibility": "PUBLIC",
  "healthInfoVisibility": "PRIVATE",
  "locationVisibility": "PUBLIC",
  "locationSharingEnabled": true
}

Allowed visibility values:

PUBLIC
EMERGENCY_ONLY
PRIVATE

Help Requests API

Help request endpoints are available under /api/help-requests.

Allowed help types:

first_aid
food_water
shelter
search_rescue

Example create request:

{
  "helpTypes": ["first_aid"],
  "affectedPeopleCount": 2,
  "riskFlags": ["injury"],
  "vulnerableGroups": ["elderly"],
  "description": "Two people need first aid near the building entrance.",
  "shareProfileHealthInfoWithVolunteer": true,
  "location": {
    "country": "Turkiye",
    "city": "Istanbul",
    "district": "Besiktas",
    "neighborhood": "Levazim",
    "extraAddress": "Near Akatlar Culture Center",
    "latitude": 41.0842,
    "longitude": 29.0211
  },
  "contact": {
    "fullName": "Demo Requester",
    "phone": 5051234567
  },
  "consentGiven": true
}

Public-facing status values include:

PENDING_SYNC
SYNCED
MATCHED
RESOLVED
CANCELLED

Availability and Assignment API

Availability endpoints are available under /api/availability. All endpoints require authentication.

When setting availability to true, latitude and longitude are required:

{
  "isAvailable": true,
  "latitude": 41.0842,
  "longitude": 29.0211,
  "accuracyMeters": 20,
  "source": "gps"
}

Offline availability sync accepts timestamped records:

{
  "records": [
    {
      "isAvailable": false,
      "timestamp": "2026-05-15T10:00:00.000Z"
    },
    {
      "isAvailable": true,
      "timestamp": "2026-05-15T10:03:00.000Z",
      "latitude": 41.0842,
      "longitude": 29.0211,
      "capturedAt": "2026-05-15T10:03:00.000Z"
    }
  ]
}

Safety Status API

Safety status endpoints are available under /api/safety-status.

Allowed safety status values:

safe
not_safe
unknown

Example patch request:

{
  "status": "safe",
  "shareLocationConsent": true,
  "note": "I am safe at the gathering area.",
  "location": {
    "latitude": 41.0842,
    "longitude": 29.0211,
    "accuracyMeters": 15,
    "source": "gps",
    "capturedAt": "2026-05-15T10:05:00.000Z"
  }
}

Visible safety status filtering supports nearby residential-area matching and current-location matching:

GET /api/safety-status/visible?nearby=true
GET /api/safety-status/visible?nearby=true&context=current-location&latitude=41.0842&longitude=29.0211

Safety Circles API

Safety circle endpoints are available under /api/safety-circles. All endpoints require authentication.

Important request bodies:

{
  "name": "Family Circle"
}
{
  "inviteeEmail": "sibling@example.com"
}
{
  "decision": "accept"
}
{
  "nextOwnerUserId": "user_123"
}

Notifications API

Notification endpoints are available under /api/notifications. All endpoints require authentication; admin-only endpoints additionally require admin privileges.

Allowed notification types:

TASK_ASSIGNED
TASK_UPDATED
HELP_REQUEST_CREATED
HELP_REQUEST_UPDATED
HELP_REQUEST_STATUS_CHANGED
SAFETY_CIRCLE_INVITE_RECEIVED
SAFETY_CIRCLE_INVITE_RESPONDED
SAFETY_CIRCLE_STATUS_UPDATED
SAFETY_CIRCLE_UPDATED
ANNOUNCEMENT_PUBLISHED
ANNOUNCEMENT_UPDATED
VOLUNTEER_AVAILABILITY_EXPIRING
VOLUNTEER_AVAILABILITY_PAUSED
SYSTEM

Emergency broadcast request:

{
  "title": "Aftershock warning",
  "body": "Please move away from damaged buildings and follow official instructions.",
  "location": {
    "latitude": 41.0842,
    "longitude": 29.0211,
    "radiusKm": 3
  },
  "maxRecipients": 5000
}

Announcements API

Public announcements are available under /api/announcements. Admin announcement management is available under /api/admin/announcements.

Create announcement request:

{
  "title": "Water distribution point updated",
  "content": "The temporary water distribution point has moved to Akatlar Culture Center."
}

Location and Gathering Areas API

Location endpoints provide address hierarchy, search, and reverse lookup:

GET /api/location/tree
GET /api/location/search?q=levazim
GET /api/location/reverse?lat=41.0842&lon=29.0211

Gathering area endpoints return nearby or viewport-based map data:

GET /api/gathering-areas/nearby?lat=41.0842&lon=29.0211&radius=2000&limit=20
GET /api/gathering-areas/viewport?bbox=29.0000,41.0700,29.0400,41.1000&limit=20

Admin API

Admin endpoints are available under /api/admin. They require a valid JWT for an admin user.

The final release includes user moderation, help request monitoring, announcements, basic statistics, emergency overview, emergency history, emergency analytics, and deployment monitoring.

Sample Usage Scenarios

The following scenarios demonstrate complex workflows in the final release. At least three of them cover functionality added after the MVP milestone.

Scenario 1: User Checks In to a Safety Circle

Endpoint: PATCH /api/safety-circles/{circleId}/check-in

Scenario Description: A user marks themselves as safe, shares their location, and the circle detail is returned with updated member safety information.

Request

curl -X PATCH "https://api.neph.app/api/safety-circles/demo_scenario2_circle_alper_family/check-in" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "safe",
    "shareLocationConsent": true,
    "note": "I am safe near the gathering area.",
    "location": {
      "latitude": 41.0842,
      "longitude": 29.0211,
      "accuracyMeters": 18,
      "source": "gps",
      "capturedAt": "2026-05-15T10:05:00.000Z"
    }
  }'

Response

{
  "safetyStatus": {
    "userId": "demo_scenario2_alper",
    "status": "safe",
    "shareLocationConsent": true,
    "note": "I am safe near the gathering area.",
    "latitude": 41.0842,
    "longitude": 29.0211,
    "updatedAt": "2026-05-15T10:05:02.000Z"
  },
  "circle": {
    "circleId": "demo_scenario2_circle_alper_family",
    "name": "Alper Family",
    "ownerUserId": "demo_scenario2_alper"
  },
  "members": [
    {
      "userId": "demo_scenario2_alper",
      "role": "owner",
      "status": "safe"
    },
    {
      "userId": "demo_scenario2_sibling",
      "role": "member",
      "status": "not_safe"
    }
  ]
}

Scenario 2: Nearby Visible Users for Emergency Awareness

Endpoint: GET /api/safety-status/visible?nearby=true

Scenario Description: A user views nearby people whose privacy settings and safety status make them visible in the same residential area.

Request

curl "https://api.neph.app/api/safety-status/visible?nearby=true" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Response

{
  "safetyStatuses": [
    {
      "userId": "demo_scenario2_rojhat",
      "firstName": "Rojhat",
      "lastName": "Demo",
      "status": "safe",
      "note": "I am safe and nearby.",
      "profileVisibility": "PUBLIC",
      "locationVisibility": "PUBLIC",
      "city": "Istanbul",
      "district": "Besiktas",
      "neighborhood": "Levazim",
      "updatedAt": "2026-05-15T10:06:00.000Z"
    }
  ]
}

Scenario 3: Admin Publishes an Emergency Announcement

Endpoint: POST /api/admin/announcements

Scenario Description: An admin creates a public announcement that can be shown on the web and mobile clients.

Request

curl -X POST "https://api.neph.app/api/admin/announcements" \
  -H "Authorization: Bearer <ADMIN_ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Water distribution point updated",
    "content": "The temporary water distribution point has moved to Akatlar Culture Center."
  }'

Response

{
  "announcement": {
    "announcementId": "ann_2c8f1b",
    "title": "Water distribution point updated",
    "content": "The temporary water distribution point has moved to Akatlar Culture Center.",
    "createdByUserId": "admin_001",
    "createdAt": "2026-05-15T10:10:00.000Z",
    "updatedAt": "2026-05-15T10:10:00.000Z"
  }
}

Scenario 4: Admin Sends a Location-Based Emergency Broadcast

Endpoint: POST /api/notifications/admin/broadcast/emergency

Scenario Description: An admin sends an emergency broadcast notification to users within a radius of an incident location.

Request

curl -X POST "https://api.neph.app/api/notifications/admin/broadcast/emergency" \
  -H "Authorization: Bearer <ADMIN_ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Aftershock warning",
    "body": "Please move away from damaged buildings and follow official instructions.",
    "location": {
      "latitude": 41.0842,
      "longitude": 29.0211,
      "radiusKm": 3
    },
    "maxRecipients": 5000
  }'

Response

{
  "broadcastId": "broadcast_8df1e0d1-9db2-40d7-b66d-4a6f9c7f6b1",
  "recipientCount": 12,
  "deliveredCount": 12
}

Notes for Final Milestone Report

  • The API is modularized into auth, admin, profiles, help requests, availability, assignments, location, gathering areas, notifications, announcements, safety status, operational location, and safety circles.
  • Authentication uses JWT bearer tokens.
  • Help request creation supports both authenticated users and guests.
  • Guest help requests use request-specific access tokens.
  • Volunteer availability supports online updates and offline synchronization.
  • Safety circles and safety statuses support family/group awareness during emergencies.
  • Nearby visible users are filtered according to privacy settings and safety visibility rules.
  • Announcements and notifications support admin-driven emergency communication.
  • Gathering area and location APIs support map-based emergency navigation.

🏠 Home

🎓 Team Members

📄 Templates

📅 Weekly Meetings

🧪 Lab Reports

🎬 Scenarios and Mock-ups

🧩 Use Case Diagrams

🏗️ Class Diagram

🔁 Sequence Diagrams

🛠️ Implementation Plan

📦 Deliverables

MVP Deliverables
Final Milestone Deliverables

📚 Project

✅ Acceptance Tests

🚀 Releases

Clone this wiki locally