Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.city.atlas.krd/llms.txt

Use this file to discover all available pages before exploring further.

​
Endpoint

GET /api/v1/tickets

​
Authentication

Requires authentication with ticket:read permission.

​
Query Parameters

ParameterTypeRequiredDescription
pagenumberNoPage number for pagination (default: 1)
limitnumberNoNumber of tickets per page (default: 50 for all, 50 for filtered)
sortBystringNoSort field and direction (e.g., “createdAt:desc”)
statusstringNoFilter by status: PENDING, IN_PROGRESS, COMPLETED, or CANCELLED

​
Request Examples

​
Get All Tickets (Grouped by Status)

curl -X GET "http://localhost:3001/api/v1/tickets?page=1&limit=50&sortBy=createdAt:desc" \
  -H "Cookie: session=your-session-cookie"

​
Get Tickets by Specific Status

# Get only PENDING tickets
curl -X GET "http://localhost:3001/api/v1/tickets?status=PENDING&page=1&limit=20&sortBy=createdAt:desc" \
  -H "Cookie: session=your-session-cookie"

# Get only IN_PROGRESS tickets
curl -X GET "http://localhost:3001/api/v1/tickets?status=IN_PROGRESS&page=1&limit=20" \
  -H "Cookie: session=your-session-cookie"

​
Response

​
Success Response - All Tickets (200)

Returns all tickets grouped by status when no status filter is applied: 
{
  "PENDING": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "userId": "550e8400-e29b-41d4-a716-446655440001",
      "status": "PENDING",
      "category": "MAINTENANCE",
      "title": "Elevator Malfunction",
      "description": "Elevator not working on floor 3",
      "attachments": ["https://example.com/image1.jpg"],
      "assignedTo": null,
      "notes": "Reported by resident",
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z",
      "user": {
        "id": "550e8400-e29b-41d4-a716-446655440001",
        "fullname": "John Doe",
        "phoneNumber": "+1234567890",
        "profilePhoto": "https://example.com/profile.jpg"
      },
      "technician": null
    }
  ],
  "IN_PROGRESS": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440002",
      "userId": "550e8400-e29b-41d4-a716-446655440003",
      "status": "IN_PROGRESS",
      "category": "ELECTRICITY",
      "title": "Power Outage",
      "description": "Power outage in building A",
      "attachments": [],
      "assignedTo": "550e8400-e29b-41d4-a716-446655440004",
      "notes": "Technician dispatched and working on electrical panel",
      "createdAt": "2024-01-15T09:00:00Z",
      "updatedAt": "2024-01-15T11:00:00Z",
      "user": {
        "id": "550e8400-e29b-41d4-a716-446655440003",
        "fullname": "Jane Smith",
        "phoneNumber": "+1234567891",
        "profilePhoto": null
      },
      "technician": {
        "id": "550e8400-e29b-41d4-a716-446655440004",
        "fullname": "Mike Johnson",
        "email": "mike@example.com",
        "profilePhoto": "https://example.com/tech.jpg"
      }
    }
  ],
  "COMPLETED": [],
  "CANCELLED": []
}

​
Success Response - Filtered by Status (200)

Returns only tickets from the specified status when status filter is applied: 
{
  "PENDING": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "userId": "550e8400-e29b-41d4-a716-446655440001",
      "status": "PENDING",
      "category": "MAINTENANCE",
      "title": "Elevator Malfunction",
      "description": "Elevator not working on floor 3",
      "attachments": ["https://example.com/image1.jpg"],
      "assignedTo": null,
      "notes": "Reported by resident",
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z",
      "user": {
        "id": "550e8400-e29b-41d4-a716-446655440001",
        "fullname": "John Doe",
        "phoneNumber": "+1234567890",
        "profilePhoto": "https://example.com/profile.jpg"
      },
      "technician": null
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440005",
      "userId": "550e8400-e29b-41d4-a716-446655440006",
      "status": "PENDING",
      "category": "WATER",
      "title": "Leaking Pipe",
      "description": "Water leak in apartment 204",
      "attachments": [],
      "assignedTo": null,
      "notes": null,
      "createdAt": "2024-01-15T11:00:00Z",
      "updatedAt": "2024-01-15T11:00:00Z",
      "user": {
        "id": "550e8400-e29b-41d4-a716-446655440006",
        "fullname": "Alice Brown",
        "phoneNumber": "+1234567892",
        "profilePhoto": null
      },
      "technician": null
    }
  ],
  "IN_PROGRESS": [],
  "COMPLETED": [],
  "CANCELLED": []
}

​
No Content Response (204)

{
  "PENDING": [],
  "IN_PROGRESS": [],
  "COMPLETED": [],
  "CANCELLED": []
}

​
Error Response (401)

{
  "success": false,
  "error": {
    "message": "Unauthorized access",
    "code": "UNAUTHORIZED"
  }
}

​
Error Response (403)

{
  "success": false,
  "error": {
    "message": "Insufficient permissions",
    "code": "FORBIDDEN"
  }
}

​
Notes

  • Without Status Filter: Returns up to 50 most recent tickets grouped by status
  • With Status Filter: Returns paginated tickets from the specified status only
  • Tickets are automatically grouped by status in the response
  • Each ticket includes user information and assigned technician details (when available)
  • Empty arrays are returned for statuses with no tickets
  • Default sorting is by creation date (newest first)
  • The title field has a maximum length of 120 characters
  • The notes field is a single text field (not an array)