Final API Documentation

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.

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.