Tasks

NapX PMS includes a task management system for tracking housekeeping and operational work items. Tasks are scoped to a tenant and optionally linked to a property or space.

Endpoints

Method	Path	Description
GET	/v1/tasks	List tasks for the tenant (filterable by property)
POST	/v1/tasks	Create a new task
PATCH	/v1/tasks/:id/status	Update task status (state machine enforced)

Task State Machine

Status transitions are validated by TaskStateMachine. Only the following transitions are allowed:

pending ──→ in_progress ──→ completed
   └──────────────────────→ cancelled

Current status	Allowed next statuses
pending	in_progress, cancelled
in_progress	completed, cancelled
completed	(terminal)
cancelled	(terminal)

Attempting an invalid transition (e.g. pending → completed) returns a 400 Bad Request.

Response Shape

Field	Type	Description
id	uuid	Task ID
tenantId	uuid	Owning tenant
propertyId	uuid	Property the task is linked to
spaceId	uuid | null	Optional space within the property
assignedUserId	uuid | null	User assigned to the task
type	string	Task type (e.g. housekeeping, maintenance)
description	string | null	Task description
priority	string | null	Priority (e.g. low, normal, high)
status	string	Current status
createdAt	ISO 8601 string	Creation timestamp
updatedAt	ISO 8601 string | null	Last update timestamp

Creating a Task

POST /v1/tasks
Authorization: Bearer <session-token>
Content-Type: application/json

{
  "propertyId": "65a8da05-491d-4aa4-a6f6-b4eeb2fcbb22",
  "type": "maintenance",
  "description": "Fix broken window latch in Room 4",
  "priority": "high"
}

Filtering Tasks by Property

GET /v1/tasks?propertyId=65a8da05-491d-4aa4-a6f6-b4eeb2fcbb22
Authorization: Bearer <session-token>

Automatic Housekeeping Tasks

The HousekeepingListenerService automatically creates a housekeeping task when a guest checks out (RESERVATION_CHECKED_OUT event). The task is created with:

• type: 'housekeeping'
• status: 'pending'
• The property from the checked-out reservation

No manual API call is required for post-checkout housekeeping flows.

Security Model

• Every request requires Authorization: Bearer <session-token>.
• Tenant context is derived from validated auth claims; callers only see tasks for their tenant.

Error Handling

• 400 Bad Request when a field fails validation or a status transition is invalid.
• 401 Unauthorized when the bearer token is missing or invalid.
• 404 Not Found when the task ID does not exist for the tenant.

See the API reference for the full request contract and all accepted field values.