� API Reference - CleanStreet
Complete API documentation for the CleanStreet civic engagement platform.
Base URL: [Link]
Table of Contents
• Authentication
• Issues
• Comments
• Admin - Issues
• Admin - Reports
• Admin - Users
• Utilities
Authentication
All protected endpoints require a Bearer token in the Authorization header:
Authorization: Bearer <your_jwt_token>
Register New User
Creates a new user account.
POST /api/auth/register
Request Body:
{
"name": "John Doe",
"username": "johndoe",
"email": "john@[Link]",
"password": "SecurePass123",
"location": "Mumbai",
"postalCode": "400001",
"phone": "9876543210"
}
Response:
Status Description
201 Registration successful
1
Status Description
400 Validation error
409 User already exists
Login User
Authenticates a user and returns JWT token.
POST /api/auth/login
Request Body:
{
"email": "john@[Link]",
"password": "SecurePass123"
}
Success Response:
{
"success": true,
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"user": {
"id": "64abc123...",
"name": "John Doe",
"email": "john@[Link]",
"role": "user",
"location": "Mumbai",
"postalCode": "400001"
}
}
Send OTP
Sends a one-time password to the user’s email.
POST /api/auth/send-otp
Request Body:
{
"email": "john@[Link]"
}
Response:
2
Status Description
200 OTP sent successfully
404 User not found
500 Email sending failed
Verify OTP
Verifies the OTP sent to user’s email.
POST /api/auth/verify-otp
Request Body:
{
"email": "john@[Link]",
"otp": "123456"
}
Verify OTP Only
Verifies OTP without performing password reset (for 2-step verification).
POST /api/auth/verify-otp-only
Request Body:
{
"email": "john@[Link]",
"otp": "123456"
}
Reset Password with OTP
Resets user password after OTP verification.
POST /api/auth/reset-password
Request Body:
{
"email": "john@[Link]",
"otp": "123456",
"newPassword": "NewSecurePass123"
}
3
Get Dashboard Data
Retrieves user’s dashboard data including their issues.
GET /api/auth/dashboard
� Requires Authentication
Response:
{
"success": true,
"user": {
"name": "John Doe",
"email": "john@[Link]"
},
"stats": {
"totalIssues": 5,
"resolvedIssues": 2,
"pendingIssues": 3
}
}
Update User Profile
Updates the authenticated user’s profile information.
PUT /api/auth/profile
� Requires Authentication
Request Body:
{
"name": "John Updated",
"phone": "9876543211",
"location": "Delhi"
}
Change Password
Changes the authenticated user’s password.
PUT /api/auth/change-password
� Requires Authentication
Request Body:
4
{
"currentPassword": "OldPassword123",
"newPassword": "NewPassword123"
}
Get All Users
Retrieves list of all users (for admin dropdown selections).
GET /api/auth/allusers
Get Users Count (Public)
Returns total number of registered users.
GET /api/auth/public/users-count
Response:
{
"count": 150
}
Get Postal Codes (Public)
Returns list of unique postal codes from registered users.
GET /api/auth/public/postal-codes
Response:
{
"postalCodes": ["400001", "400002", "400003"]
}
Issues
Report New Issue
Creates a new civic issue report.
POST /api/issues
� Requires Authentication
Request Type: multipart/form-data
5
Form Fields:
Field Type Required Description
title string Yes Issue title
issueType string Yes Category of issue
priority string No low, medium, high (default: medium)
address string Yes Location address
latitude number No GPS latitude
longitude number No GPS longitude
postalCode string No 6-digit postal code
landmark string No Nearby landmark
description string Yes Detailed description
images file[] No Up to 3 images (max 5MB each)
Example:
curl -X POST [Link] \
-H "Authorization: Bearer <token>" \
-F "title=Pothole on Main Road" \
-F "issueType=Pothole" \
-F "priority=high" \
-F "address=123 Main Road, Mumbai" \
-F "description=Large pothole causing accidents" \
-F "images=@[Link]" \
-F "images=@[Link]"
Get All Issues
Retrieves all issues (protected, returns based on user’s postal code).
GET /api/issues
� Requires Authentication
Get Public Issues
Retrieves issues for public display (no sensitive data).
GET /api/issues/public
6
Vote on Issue
Toggle upvote or downvote on an issue.
POST /api/issues/:id/vote/:type
� Requires Authentication
URL Parameters:
Parameter Description
id Issue ID
type upvote or downvote
Response:
{
"success": true,
"upvotes": 15,
"downvotes": 2
}
Update Issue Status (Admin)
Updates the status of an issue.
PATCH /api/issues/admin/issues/:issueId/status
� Requires Admin Authentication
Request Body:
{
"status": "in progress"
}
Valid Statuses: reported, in progress, resolved, rejected
Delete Issue (Admin)
Permanently deletes an issue.
DELETE /api/issues/admin/issues/:issueId
� Requires Admin Authentication
7
Comments
Get Comments for Issue
Retrieves all comments for a specific issue.
GET /api/issues/:issueId/comments
� Requires Authentication
Response:
{
"success": true,
"comments": [
{
"_id": "comment-id",
"text": "This needs urgent attention!",
"user": {
"name": "Jane Doe",
"username": "janedoe"
},
"createdAt": "2024-01-15T10:30:00Z"
}
]
}
Add Comment to Issue
Adds a new comment to an issue.
POST /api/issues/:issueId/comments
� Requires Authentication
Request Body:
{
"text": "I've noticed this issue too, very dangerous!"
}
Delete Comment
Deletes a comment (only by comment author or admin).
DELETE /api/issues/:issueId/comments/:commentId
� Requires Authentication
8
Admin - Issues
Get All Issues (Admin)
Retrieves all issues for admin management.
GET /api/admin/issues
� Requires Admin Authentication
Admin - Reports
Get Analytics Reports
Retrieves comprehensive analytics data.
GET /api/admin/reports
� Requires Admin Authentication
Query Parameters:
Parameter Type Description
range string Time range: week, month, quarter, year
Response:
{
"success": true,
"totalUsers": 150,
"newUsersThisRange": 25,
"userGrowth": [
{ "month": "Jan", "users": 10 },
{ "month": "Feb", "users": 15 }
],
"totalComplaints": 85,
"resolvedComplaints": 60,
"pendingComplaints": 25,
"complaintResolutionRate": "70.59",
"complaintTrends": [
{ "category": "Pothole", "count": 30 },
{ "category": "Garbage", "count": 25 }
],
"issueStatusCounts": {
"reported": 15,
"in progress": 10,
"resolved": 60
9
},
"priorityCounts": {
"high": 20,
"medium": 45,
"low": 20
},
"systemMetrics": {
"avgResponseTime": "24.50h",
"userSatisfaction": "4.2/5",
"systemUptime": "99.99%",
"activeSessions": 12
}
}
Admin - Users
Get All Users
Retrieves all registered users for admin management.
GET /api/admin/users
� Requires Admin Authentication
Update User
Updates a user’s role or status.
PUT /api/admin/users/:userId
� Requires Admin Authentication
Request Body:
{
"role": "admin",
"status": "ACTIVE"
}
Valid Roles: user, admin, globaladmin Valid Statuses: ACTIVE, BLOCKED
Delete User
Deletes a user account.
DELETE /api/admin/users/:userId
10
� Requires Admin Authentication
Utilities
Get Issue Types
Returns available issue type categories.
GET /api/utils/issue-types
Response:
{
"issueTypes": [
"Pothole",
"Garbage Dump",
"Water Leakage",
"Broken Streetlight",
"Sewage Problem",
"Road Damage",
"Other"
]
}
Error Codes Reference
Code Status Description
200 OK Request successful
201 Created Resource created successfully
400 Bad Request Invalid input or validation error
401 Unauthorized Authentication required or token invalid
403 Forbidden Insufficient permissions
404 Not Found Resource not found
409 Conflict Resource already exists
500 Internal Server Error Server error
Rate Limiting
Currently, no rate limiting is implemented. Future versions may include rate
limiting to prevent abuse.
11
Pagination
For endpoints returning large datasets, pagination can be implemented using
query parameters:
GET /api/issues?page=1&limit=10
Back to Main Documentation
12