{"info":{"_postman_id":"803cc603-b0fe-4e91-a102-4b09680c11a9","name":"HabitatLedger API","description":"

HabitatLedger API is a REST API for tracking tenant housing issues — including construction defects, maintenance negligence, and structural hazards.

Base URL: https://habitatledger-api.onrender.com/api

Endpoints overview:

GET /issues — List all issues (filterable by status, category, keyword)
GET /issues/stats — Aggregate stats for dashboard (by status, category, severity)
GET /issues/:id — Full details of a single issue including timeline and media
POST /issues — Create a new issue
PATCH /issues/:id/status — Update issue lifecycle status
PATCH /issues/:id/close — Close an issue with resolution proof
POST /upload — Upload evidence files (images, videos, PDFs)

Data formats: JSON for all issue endpoints. multipart/form-data for file uploads.

Status values: open → in_progress → closed

\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[],"owner":"50839360","collectionId":"803cc603-b0fe-4e91-a102-4b09680c11a9","publishedId":"2sBXqKofTh","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"},"publishDate":"2026-05-02T18:27:22.000Z"},"item":[{"name":"Issues","item":[{"name":"Get All Issues","id":"b9bcaaa3-ed10-4de9-908f-bf3aabfacfaa","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://habitatledger-api.onrender.com/api/issues","description":"

Retrieves a list of all housing issues logged in the system. Supports filtering and search to narrow down results by status, category, or keyword.

Query Parameters (optional):

status – Filter by issue status (open, in_progress, closed)
category – Filter by issue category (e.g., water, electrical, structural)
search – Keyword search across issue title and description

Response: Returns an array of issue objects, each containing id, title, description, category, severity, status, timestamps, and associated media.

\n","urlObject":{"path":["api","issues"],"host":["https://habitatledger-api.onrender.com"],"query":[],"variable":[]}},"response":[],"_postman_id":"b9bcaaa3-ed10-4de9-908f-bf3aabfacfaa"},{"name":"Get Issue Stats","id":"0731a298-d2c2-45fd-9304-a26e3d2700ae","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://habitatledger-api.onrender.com/api/issues/stats","description":"

Returns aggregate statistics and insights about all logged housing issues. Useful for populating dashboard charts and summary cards.

Response includes:

Total issue count
Breakdown by status (open, in_progress, closed)
Breakdown by category
Breakdown by severity level

\n","urlObject":{"path":["api","issues","stats"],"host":["https://habitatledger-api.onrender.com"],"query":[],"variable":[]}},"response":[],"_postman_id":"0731a298-d2c2-45fd-9304-a26e3d2700ae"},{"name":"Get Single Issue","id":"76bbf8b1-5382-4b0d-85d5-e9a04cf427e0","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://habitatledger-api.onrender.com/api/issues/:id","description":"

Retrieves the full details of a single housing issue by its unique ID, including its complete event timeline and all attached media files.

Path Parameters:

id – The unique MongoDB ObjectId of the issue

Response: Returns the full issue object including title, description, category, severity, status, timeline history, media attachments, and closure notes (if closed).

\n","urlObject":{"path":["api","issues",":id"],"host":["https://habitatledger-api.onrender.com"],"query":[],"variable":[{"id":"97a706e9-3101-4349-b60c-710208bcb70b","type":"any","value":"replace_with_id","key":"id"}]}},"response":[],"_postman_id":"76bbf8b1-5382-4b0d-85d5-e9a04cf427e0"},{"name":"Create Issue","id":"d3a27363-037c-4737-a466-295363bf7223","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"title\": \"Leaking Pipe\",\n \"description\": \"Water dripping from the kitchen sink.\",\n \"category\": \"water\",\n \"severity\": \"Medium\"\n}"},"url":"https://habitatledger-api.onrender.com/api/issues","description":"

Creates a new housing issue entry in the ledger. Use this endpoint to log a new complaint or defect with all relevant details.

Request Body (JSON):

{\n  \"title\": \"Leaking pipe under kitchen sink\",\n  \"description\": \"Water has been dripping consistently for 3 days causing cabinet damage.\",\n  \"category\": \"plumbing\",\n  \"severity\": \"high\",\n  \"location\": \"Kitchen\"\n}\n

Fields:

title (required) – Short summary of the issue
description (required) – Detailed description of the problem
category (required) – Issue category (e.g., plumbing, electrical, structural, pest, hvac)
severity (required) – Severity level (low, medium, high, critical)
location (optional) – Area of the unit affected

Response: Returns the newly created issue object with its assigned _id and initial status of open.

\n","urlObject":{"path":["api","issues"],"host":["https://habitatledger-api.onrender.com"],"query":[],"variable":[]}},"response":[],"_postman_id":"d3a27363-037c-4737-a466-295363bf7223"},{"name":"Update Issue Status","id":"0cf1a6ef-8eda-4a4b-89e7-8c35ad364f50","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"PATCH","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"status\": \"In Progress\"\n}"},"url":"https://habitatledger-api.onrender.com/api/issues/:id/status","description":"

Updates the status of an existing issue to reflect its current lifecycle stage. Each status change is recorded as a timestamped event in the issue's timeline.

Path Parameters:

id – The unique MongoDB ObjectId of the issue

Request Body (JSON):

{\n  \"status\": \"in_progress\"\n}\n

Valid status values:

open – Issue has been reported but not yet acted upon
in_progress – Issue is actively being addressed
closed – Issue has been resolved (use the Close Issue endpoint for proper closure with proof)

Response: Returns the updated issue object with the new status and an appended timeline entry.

\n","urlObject":{"path":["api","issues",":id","status"],"host":["https://habitatledger-api.onrender.com"],"query":[],"variable":[{"id":"a2dd7593-43f3-490a-a668-b11543600408","type":"any","value":"replace_with_id","key":"id"}]}},"response":[],"_postman_id":"0cf1a6ef-8eda-4a4b-89e7-8c35ad364f50"},{"name":"Close Issue","id":"3573ec38-432b-4b95-9c5d-c609f3df7940","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"PATCH","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"resolutionNote\": \"Fixed the pipe with sealant.\"\n}"},"url":"https://habitatledger-api.onrender.com/api/issues/:id/close","description":"

Marks an issue as officially closed. Requires the submitter to provide closing notes and proof of resolution (uploaded file URLs) before the issue can be closed. This enforces accountability and creates an auditable record.

Path Parameters:

id – The unique MongoDB ObjectId of the issue

Request Body (JSON):

{\n  \"closingNotes\": \"Landlord replaced the pipe on May 1st. Issue fully resolved.\",\n  \"resolutionProof\": [\"uploads/proof-image-1.jpg\"]\n}\n

Fields:

closingNotes (required) – Description of how the issue was resolved
resolutionProof (required) – Array of file paths/URLs serving as proof of resolution

Response: Returns the updated issue with status set to closed, closing notes, resolution proof, and a final timeline entry.

\n","urlObject":{"path":["api","issues",":id","close"],"host":["https://habitatledger-api.onrender.com"],"query":[],"variable":[{"id":"337180cb-cd76-45a9-8c1a-15bfc03b3ff0","type":"any","value":"replace_with_id","key":"id"}]}},"response":[],"_postman_id":"3573ec38-432b-4b95-9c5d-c609f3df7940"}],"id":"2274b86b-1ec3-47da-92cc-48e7efd32147","_postman_id":"2274b86b-1ec3-47da-92cc-48e7efd32147","description":""},{"name":"Upload","item":[{"name":"Upload Files","id":"6916b46d-a565-408e-8cff-1cf439edb84c","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"formdata","formdata":[{"key":"files","type":"file","value":""}]},"url":"https://habitatledger-api.onrender.com/api/upload?category=water","description":"

Uploads one or more media files (images, videos, or documents) to the server to be attached as evidence to a housing issue. Files are stored locally in the server/uploads/ directory, organized by category.

Query Parameters:

category – The issue category used to organize uploaded files (e.g., water, electrical, structural)

Request Body: multipart/form-data

files – One or more files to upload (supported types: images, videos, PDFs, documents)

Response: Returns an array of uploaded file metadata including stored file paths, which can then be referenced when creating or closing an issue.

\n
Note: This endpoint uses Multer middleware for file handling. Ensure the request is sent with Content-Type: multipart/form-data.
\n

\n","urlObject":{"path":["api","upload"],"host":["https://habitatledger-api.onrender.com"],"query":[{"key":"category","value":"water"}],"variable":[]}},"response":[],"_postman_id":"6916b46d-a565-408e-8cff-1cf439edb84c"}],"id":"a070dfb9-dd1d-469f-adc5-9b0783d852b4","_postman_id":"a070dfb9-dd1d-469f-adc5-9b0783d852b4","description":""}],"variable":[{"key":"base_url","value":"https://habitatledger-api.onrender.com"}]}