Discovery & Enums
CivicPulse exposes machine-readable endpoints for API discovery, city listings, and category metadata. These are useful for building integrations, populating dropdowns, or writing tests without hardcoding values.
GET /api/
Returns a complete machine-readable index of all API routes, valid enum values, and pagination parameters. No authentication required.
Request:
GET /api/
Response — 200 OK (abbreviated):
{
"success": true,
"data": {
"version": "1.0.0",
"baseUrl": "http://localhost:3001/api",
"enums": {
"cities": ["mumbai", "bangalore", "delhi", "hyderabad", "chennai", "pune", "kolkata", "ahmedabad"],
"categories": ["traffic", "road", "infrastructure", "hygiene", "healthcare", "systemic"],
"statuses": ["open", "in_progress", "resolved"],
"priorities": ["low", "medium", "high"],
"roles": ["citizen", "official", "admin"],
"mediaTypes": ["image", "video", "twitter"],
"reactions": ["👍", "❤️", "😡", "😢", "🙏", "🚨"]
},
"pagination": {
"defaultLimit": 20,
"maxLimit": 100,
"cursorParam": "lastKey",
"nextKeyField": "nextKey"
},
"routes": {
"auth": {
"POST /api/auth/google": { "auth": false, "description": "Google OAuth login" },
"POST /api/auth/refresh": { "auth": false, "description": "Refresh access token" },
"POST /api/auth/logout": { "auth": true, "description": "Logout and revoke refresh token" }
},
"issues": {
"GET /api/issues": { "auth": false, "description": "List issues with filters" },
"POST /api/issues": { "auth": true, "description": "Create issue" },
"GET /api/issues/stats": { "auth": false, "description": "Aggregated stats" },
"GET /api/issues/by-city/:city": { "auth": false, "description": "Issues by city" },
"GET /api/issues/by-category/:category": { "auth": false, "description": "Issues by category" },
"GET /api/issues/:id": { "auth": false, "description": "Get single issue" },
"PATCH /api/issues/:id": { "auth": true, "description": "Update issue" },
"POST /api/issues/:id/upvote": { "auth": true, "description": "Toggle upvote" },
"POST /api/issues/:id/assign": { "auth": true, "role": "official", "description": "Assign to official" },
"POST /api/issues/bulk/status": { "auth": true, "role": "admin", "description": "Bulk status update" }
},
"messages": {
"GET /api/issues/:id/messages": { "auth": false },
"POST /api/issues/:id/messages": { "auth": true },
"DELETE /api/issues/:id/messages/:msgId": { "auth": true },
"POST /api/issues/:id/messages/:msgId/react": { "auth": true }
},
"media": {
"POST /api/issues/:id/media": { "auth": true },
"DELETE /api/issues/:id/media/:mediaId": { "auth": true }
},
"scores": {
"GET /api/scores": { "auth": false },
"GET /api/scores/:userId": { "auth": false }
},
"discovery": {
"GET /api/": { "auth": false },
"GET /api/cities": { "auth": false },
"GET /api/categories": { "auth": false },
"GET /api/health": { "auth": false }
}
}
}
}
GET /api/cities
Returns all supported cities with their display name, region, and current open issue count.
Request:
GET /api/cities
Response — 200 OK:
{
"success": true,
"data": {
"cities": [
{
"slug": "mumbai",
"displayName": "Mumbai",
"state": "Maharashtra",
"openIssues": 482,
"totalIssues": 730,
"resolvedIssues": 248
},
{
"slug": "bangalore",
"displayName": "Bangalore",
"state": "Karnataka",
"openIssues": 371,
"totalIssues": 540,
"resolvedIssues": 169
},
{
"slug": "delhi",
"displayName": "Delhi",
"state": "Delhi NCT",
"openIssues": 314,
"totalIssues": 491,
"resolvedIssues": 177
},
{
"slug": "hyderabad",
"displayName": "Hyderabad",
"state": "Telangana",
"openIssues": 198,
"totalIssues": 310,
"resolvedIssues": 112
},
{
"slug": "chennai",
"displayName": "Chennai",
"state": "Tamil Nadu",
"openIssues": 175,
"totalIssues": 265,
"resolvedIssues": 90
},
{
"slug": "pune",
"displayName": "Pune",
"state": "Maharashtra",
"openIssues": 143,
"totalIssues": 218,
"resolvedIssues": 75
},
{
"slug": "kolkata",
"displayName": "Kolkata",
"state": "West Bengal",
"openIssues": 129,
"totalIssues": 193,
"resolvedIssues": 64
},
{
"slug": "ahmedabad",
"displayName": "Ahmedabad",
"state": "Gujarat",
"openIssues": 107,
"totalIssues": 155,
"resolvedIssues": 48
}
]
}
}
GET /api/categories
Returns all issue categories with their icon, brand colour, description, and live issue count.
Request:
GET /api/categories
Response — 200 OK:
{
"success": true,
"data": {
"categories": [
{
"slug": "road",
"displayName": "Roads",
"icon": "🛣️",
"color": "#f59e0b",
"description": "Potholes, damaged road surfaces, missing road markings, and road safety hazards.",
"openIssues": 523,
"totalIssues": 810
},
{
"slug": "infrastructure",
"displayName": "Infrastructure",
"icon": "🏗️",
"color": "#6366f1",
"description": "Streetlights, public buildings, bridges, footpaths, and civic structures.",
"openIssues": 418,
"totalIssues": 630
},
{
"slug": "hygiene",
"displayName": "Hygiene & Sanitation",
"icon": "🧹",
"color": "#22c55e",
"description": "Garbage dumps, open drains, sanitation facilities, and cleanliness issues.",
"openIssues": 289,
"totalIssues": 445
},
{
"slug": "traffic",
"displayName": "Traffic",
"icon": "🚦",
"color": "#ef4444",
"description": "Signal malfunctions, illegal parking, encroachments, and traffic management issues.",
"openIssues": 267,
"totalIssues": 398
},
{
"slug": "healthcare",
"displayName": "Healthcare",
"icon": "🏥",
"color": "#ec4899",
"description": "Public hospital and clinic issues, medicine shortages, and health facility accessibility.",
"openIssues": 198,
"totalIssues": 290
},
{
"slug": "systemic",
"displayName": "Systemic",
"icon": "⚖️",
"color": "#8b5cf6",
"description": "Policy failures, corruption reports, bureaucratic inefficiencies, and governance issues.",
"openIssues": 147,
"totalIssues": 220
}
]
}
}
Valid Enum Values
Use these exact string values when making API requests:
Cities
mumbai bangalore delhi hyderabad chennai pune kolkata ahmedabad
Categories
traffic road infrastructure hygiene healthcare systemic
Statuses
open in_progress resolved
Priorities
low medium high
Sort options (for GET /api/issues)
createdAt_desc createdAt_asc upvotes_desc