API Reference

Base URL

http://localhost:8000 (Local)

Authentication

Most endpoints require a Firebase ID Token. Header: Authorization: Bearer <firebase_id_token>

---

1. Users

Method	Endpoint	Description	Auth Required
POST	/users/register	Register or update user profile.	Yes
GET	/users/me	Get current user's profile.	Yes
GET	/users/me/availability	Get volunteer availability.	Yes
PATCH	/users/me/availability	Set volunteer availability.	Yes
PATCH	/users/me/location	Update user location.	Yes
GET	/users/{uid}/display_name	Get a user's display name.	No

2. Requests (Help Requests)

Method	Endpoint	Description
GET	/requests	List all requests (Admin/Responder).
POST	/requests	Create a new help request.
GET	/requests/me	List requests created by current user.
GET	/requests/{req_id}	Get request details.
PATCH	/requests/{req_id}/status	Update request status (e.g., fulfilled).
GET	/requests/disaster/{disaster_id}	List requests for a specific disaster.

3. Tasks

Method	Endpoint	Description
GET	/tasks	List all tasks (Admin).
POST	/tasks	Create a new task.
GET	/tasks/me	List tasks assigned to current user.
GET	/tasks/{task_id}	Get task details.
PATCH	/tasks/{task_id}/status	Update task status (e.g., on_route, completed).
PATCH	/tasks/{task_id}/assign	Assign a task to a user.
PATCH	/tasks/{task_id}/authorize	Authorize a task (Admin).

4. Resources

Method	Endpoint	Description
GET	/resources	List all resources.
POST	/resources	Add a new resource.
GET	/resources/available	List available resources.
GET	/resources/locations	Get locations of all resources (for maps).
GET	/resources/{rid}	Get resource details.
PATCH	/resources/{rid}	Update resource properties (e.g., usage).
PUT	/resources/{rid}/status	Change resource status (available/not_available).
POST	/resources/suggest/{disaster_id}	Trigger AI allocation suggestion.

5. Disasters

Method	Endpoint	Description	Permissions
GET	/disasters	List all confirmed disasters.	Public
POST	/disasters	Create a new disaster.	Admin
GET	/disasters/{id}	Get disaster details.	Public
POST	/disasters/{id}/join	Join a disaster event.	Auth
DELETE	/disasters/{id}/leave	Leave a disaster event.	Auth
GET	/disasters/{id}/joined	Check if joined.	Auth
GET	/disasters/{id}/volunteers	List volunteers in disaster.	Admin
GET	/disasters/agent-suggested	List unapproved AI suggestions.	Admin
POST	/disasters/{id}/approve	Approve a suggested disaster.	Admin
DELETE	/disasters/{id}/discard	Discard a suggested disaster.	Admin

6. Chat & Observations

Method	Endpoint	Description
GET	/disasters/{id}/chat/messages	Get chat messages for a disaster.
POST	/disasters/{id}/chat/messages	Send a message to the disaster chat.
GET	/observations	List community observations.
POST	/observations	Report a new observation (e.g., damage).
GET	/observations/{obs_id}	Get observation details.
DELETE	/observations/{obs_id}	Delete an observation.

7. Workflow Outputs

Method	Endpoint	Description
GET	/workflow-outputs	List all workflow outputs.
POST	/workflow-outputs	Create or update a workflow output.
GET	/workflow-outputs/{request_id}	Get workflow output for a specific request.
DELETE	/workflow-outputs/{request_id}	Delete a workflow output.

8. Workflow Tasks

Method	Endpoint	Description
GET	/workflow-outputs/{request_id}/tasks	List tasks in a workflow.
POST	/workflow-outputs/{request_id}/tasks	Add a new task to the workflow.
PATCH	/workflow-outputs/{request_id}/tasks/{task_id}	Update a workflow task.
DELETE	/workflow-outputs/{request_id}/tasks/{task_id}	Remove a task from the workflow.

9. Workflow Resources

Method	Endpoint	Description
GET	/workflow-outputs/{request_id}/resources	List resources in a workflow.
POST	/workflow-outputs/{request_id}/resources	Add a new resource suggestion.
PATCH	/workflow-outputs/{request_id}/resources/{res_id}	Update a resource suggestion.
DELETE	/workflow-outputs/{request_id}/resources/{res_id}	Remove a resource suggestion.

10. Chatbot

Method	Endpoint	Description
POST	/chatbot/ask	Send a message to the AI chatbot.

11. Examples

Create Request Payload

{
  "disaster_id": "disaster_123",
  "type_of_need": "medical",
  "description": "Need insulin",
  "location": {
    "lat": 6.9271,
    "lng": 79.8612
  }
}

Create Task Payload

{
  "disaster_id": "disaster_123",
  "priority": 1,
  "instructions": "Deliver supplies to shelter A",
  "role_required": "volunteer"
}