Skip to main content

​
Endpoint

PATCH /api/v1/tickets/{id}/status

​
Authentication

Requires authentication with ticket:write permission.

​
Path Parameters

ParameterTypeRequiredDescription
idstring (UUID)YesTicket ID to update

​
Request Body

{
  "status": "IN_PROGRESS"
}

​
Body Parameters

ParameterTypeRequiredDescription
statusstringYesNew status for the ticket

​
Valid Status Values

  • PENDING - Newly created ticket awaiting assignment
  • IN_PROGRESS - Ticket assigned and work in progress
  • COMPLETED - Work completed, ticket resolved
  • CANCELLED - Ticket cancelled (no longer needed)

​
Request Example

curl -X PATCH "http://localhost:3001/api/v1/tickets/550e8400-e29b-41d4-a716-446655440000/status" \
  -H "Content-Type: application/json" \
  -H "Cookie: session=your-session-cookie" \
  -d '{
    "status": "IN_PROGRESS"
  }'

​
Response

​
Success Response (200)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "userId": "550e8400-e29b-41d4-a716-446655440001",
  "status": "IN_PROGRESS",
  "category": "MAINTENANCE",
  "title": "Elevator Malfunction",
  "description": "Elevator not working on floor 3",
  "attachments": ["https://example.com/image1.jpg"],
  "assignedTo": "550e8400-e29b-41d4-a716-446655440002",
  "notes": "Technician dispatched and working on issue",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T14:00:00Z"
}

​
Error Response (400)

{
  "success": false,
  "error": {
    "message": "Validation failed",
    "code": "VALIDATION_ERROR",
    "details": {
      "status": "Invalid status value. Must be one of: PENDING, IN_PROGRESS, COMPLETED, CANCELLED"
    }
  }
}

​
Error Response (404)

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

​
Error Response (401)

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

​
Error Response (403)

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

​
Status Workflow

The typical ticket workflow follows this progression:
  1. PENDING → IN_PROGRESS: When a technician starts working on the ticket
  2. IN_PROGRESS → COMPLETED: When the work is finished successfully
  3. IN_PROGRESS → CANCELLED: When the work is no longer needed
  4. PENDING → CANCELLED: When the ticket is cancelled before assignment

​
Notes

  • The updatedAt timestamp is automatically updated
  • Status changes are logged and tracked
  • Consider adding notes when changing status to provide context
  • Use Assign Ticket to assign tickets before changing to IN_PROGRESS
  • Use Update Ticket to add notes when changing status