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/user/{userId}

​
Authentication

Requires authentication with ticket:read permission.

​
Path Parameters

ParameterTypeRequiredDescription
userIdstring (UUID)YesID of the user whose tickets to retrieve

​
Query Parameters

ParameterTypeRequiredDescription
pagenumberNoPage number for pagination (default: 1)
limitnumberNoNumber of tickets per page (default: 10 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 User Tickets (Grouped by Status)

curl -X GET "http://localhost:3001/api/v1/tickets/user/550e8400-e29b-41d4-a716-446655440000?page=1&limit=10" \
  -H "Cookie: session=your-session-cookie"

​
Get User Tickets by Specific Status

# Get only PENDING tickets for a user
curl -X GET "http://localhost:3001/api/v1/tickets/user/550e8400-e29b-41d4-a716-446655440000?status=PENDING&page=1&limit=20" \
  -H "Cookie: session=your-session-cookie"

# Get only IN_PROGRESS tickets for a user
curl -X GET "http://localhost:3001/api/v1/tickets/user/550e8400-e29b-41d4-a716-446655440000?status=IN_PROGRESS" \
  -H "Cookie: session=your-session-cookie"

​
Response

​
Success Response - All Tickets (200)

Returns all tickets for the user 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",
      "technician": null
    }
  ],
  "IN_PROGRESS": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440002",
      "userId": "550e8400-e29b-41d4-a716-446655440001",
      "status": "IN_PROGRESS",
      "category": "WATER",
      "title": "Leaking Pipe",
      "description": "Water leak in kitchen",
      "attachments": [],
      "assignedTo": "550e8400-e29b-41d4-a716-446655440004",
      "notes": "Technician assigned and working on it",
      "createdAt": "2024-01-14T09:00:00Z",
      "updatedAt": "2024-01-15T11:00:00Z",
      "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",
      "technician": null
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440005",
      "userId": "550e8400-e29b-41d4-a716-446655440001",
      "status": "PENDING",
      "category": "CLEANING",
      "title": "Hallway Cleaning",
      "description": "Need cleaning in hallway",
      "attachments": [],
      "assignedTo": null,
      "notes": null,
      "createdAt": "2024-01-15T14:00:00Z",
      "updatedAt": "2024-01-15T14:00:00Z",
      "technician": null
    }
  ],
  "IN_PROGRESS": [],
  "COMPLETED": [],
  "CANCELLED": []
}

​
No Content Response (204)

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

​
Error Response (400)

{
  "success": false,
  "error": {
    "message": "Invalid user ID format",
    "code": "VALIDATION_ERROR"
  }
}

​
Error Response (401)

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

​
Error Response (403)

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

​
Error Response (404)

{
  "success": false,
  "error": {
    "message": "User not found",
    "code": "NOT_FOUND"
  }
}

​
Notes

  • Without Status Filter: Returns up to 10 tickets per page grouped by status
  • With Status Filter: Returns paginated tickets from the specified status only (default: 50 per page)
  • Tickets are automatically grouped by status in the response
  • Each ticket includes assigned technician details (when available)
  • User information is not included since we’re already filtering by user ID
  • Empty arrays are returned for statuses with no tickets
  • Default sorting is by creation date (newest first)
  • The userId parameter must be a valid UUID v4
  • This endpoint is useful for user dashboards and ticket history views