> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xenia.team/llms.txt
> Use this file to discover all available pages before exploring further.

# Task Management

> Create, update, assign, and manage tasks through the API

## Overview

Tasks are the core work units in Xenia. This guide covers creating tasks, updating their status, managing assignments, and tracking task activity.

**Key Concepts:**

* **One-off Tasks**: Single tasks with a specific due date
* **Recurring Tasks**: Tasks that repeat on a schedule (see [Task Scheduling](/guides/workflows/task-scheduling))
* **Work Orders**: Facility requests from requesters (see [Work Orders](/guides/workflows/work-orders))

***

## Create a Task

Create a new one-off task with assignees and optional checklist attachment.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/tasks" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}" \
    -H "Content-Type: application/json" \
    -d '{
      "title": "Weekly Safety Inspection",
      "description": "Complete the standard safety inspection checklist",
      "startDate": "2024-12-20T09:00:00Z",
      "dueDate": "2024-12-20T17:00:00Z",
      "priority": "High",
      "assignees": ["user-uuid-1", "user-uuid-2"],
      "locationIds": ["location-uuid"],
      "AssetId": "asset-uuid",
      "ChecklistId": "checklist-template-uuid",
      "isChecklistRequired": true,
      "notification": {
        "email": true,
        "push": true
      }
    }'
  ```
</CodeGroup>

**Request Body:**

| Field                   | Type      | Required | Description                                         |
| ----------------------- | --------- | -------- | --------------------------------------------------- |
| `title`                 | string    | Yes      | Task title                                          |
| `description`           | string    | No       | Task description                                    |
| `additionalDescription` | string    | No       | Extended description/notes                          |
| `startDate`             | datetime  | Yes      | When the task becomes active                        |
| `dueDate`               | datetime  | No       | When the task is due                                |
| `startTime`             | string    | No       | Specific start time (HH:MM format)                  |
| `dueTime`               | string    | No       | Specific due time (HH:MM format)                    |
| `priority`              | string    | No       | `None`, `Low`, `Medium`, `High`                     |
| `assignees`             | string\[] | No       | Array of user IDs to assign                         |
| `locationIds`           | string\[] | No       | Array of location IDs                               |
| `AssetId`               | string    | No       | Related asset ID                                    |
| `ChecklistId`           | string    | No       | Template to attach for completion                   |
| `isChecklistRequired`   | boolean   | No       | Require checklist completion before task completion |
| `isTimeBound`           | boolean   | No       | Whether task has strict time boundaries             |
| `notification`          | object    | No       | Notification preferences                            |
| `attachment`            | string\[] | No       | Array of attachment file paths                      |
| `ServiceTypeId`         | string    | No       | Task category/service type ID                       |

**Response:**

```json theme={null}
{
  "status": "success",
  "code": 200,
  "data": {
    "id": "task-uuid",
    "title": "Weekly Safety Inspection",
    "description": "Complete the standard safety inspection checklist",
    "taskStatus": "Open",
    "priority": "High",
    "startDate": "2024-12-20T09:00:00Z",
    "dueDate": "2024-12-20T17:00:00Z",
    "taskNumber": "T-2024-001234",
    "Assignees": [
      {
        "id": "user-uuid-1",
        "fullName": "John Smith"
      }
    ],
    "Location": {
      "id": "location-uuid",
      "name": "Building A"
    },
    "createdAt": "2024-12-19T10:00:00Z"
  }
}
```

### Create Multiple Tasks (One Per Assignee)

Set `isMultiTasks: true` to create separate tasks for each assignee.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/tasks" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}" \
    -H "Content-Type: application/json" \
    -d '{
      "title": "Complete Training Module",
      "startDate": "2024-12-20T09:00:00Z",
      "dueDate": "2024-12-27T17:00:00Z",
      "assignees": ["user-uuid-1", "user-uuid-2", "user-uuid-3"],
      "isMultiTasks": true
    }'
  ```
</CodeGroup>

This creates 3 separate tasks, one for each assignee.

***

## Get Tasks

### List Tasks with Filters

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/tasks/list" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}" \
    -H "Content-Type: application/json" \
    -d '{
      "page": 1,
      "pageSize": 20,
      "sort": {
        "field": "dueDate",
        "direction": "ASC"
      },
      "searchText": "safety",
      "filters": {
        "taskStatus": ["Open", "In Progress"],
        "priority": ["High", "Medium"],
        "assigneeIds": ["user-uuid"],
        "locationIds": ["location-uuid"],
        "dateFrom": "2024-12-01",
        "dateTo": "2024-12-31"
      }
    }'
  ```
</CodeGroup>

**Request Body:**

| Field            | Type   | Required | Description                 |
| ---------------- | ------ | -------- | --------------------------- |
| `page`           | number | Yes      | Page number (1-indexed)     |
| `pageSize`       | number | Yes      | Items per page (max 100)    |
| `sort`           | object | Yes      | Sort configuration          |
| `sort.field`     | string | Yes      | Field to sort by            |
| `sort.direction` | string | Yes      | `ASC` or `DESC`             |
| `searchText`     | string | No       | Search in title/description |
| `filters`        | object | No       | Filter criteria             |

**Filter Options:**

| Filter        | Type      | Description                 |
| ------------- | --------- | --------------------------- |
| `taskStatus`  | string\[] | Filter by status(es)        |
| `priority`    | string\[] | Filter by priority level(s) |
| `assigneeIds` | string\[] | Filter by assignee(s)       |
| `locationIds` | string\[] | Filter by location(s)       |
| `assetIds`    | string\[] | Filter by asset(s)          |
| `dateFrom`    | string    | Start date (YYYY-MM-DD)     |
| `dateTo`      | string    | End date (YYYY-MM-DD)       |
| `isOverdue`   | boolean   | Only overdue tasks          |

**Response:**

```json theme={null}
{
  "status": "success",
  "code": 200,
  "data": {
    "tasks": [
      {
        "id": "task-uuid-1",
        "title": "Weekly Safety Inspection",
        "taskStatus": "Open",
        "priority": "High",
        "dueDate": "2024-12-20T17:00:00Z",
        "taskNumber": "T-2024-001234",
        "Assignees": [...],
        "Location": {...}
      }
    ],
    "meta": {
      "total": 45,
      "page": 1,
      "pageSize": 20,
      "totalPages": 3
    }
  }
}
```

### Get Task Details

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/tasks/{taskId}/details" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}"
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "status": "success",
  "code": 200,
  "data": {
    "id": "task-uuid",
    "title": "Weekly Safety Inspection",
    "description": "Complete the standard safety inspection checklist",
    "taskStatus": "In Progress",
    "priority": "High",
    "startDate": "2024-12-20T09:00:00Z",
    "dueDate": "2024-12-20T17:00:00Z",
    "taskNumber": "T-2024-001234",
    "Assignees": [
      {
        "id": "user-uuid",
        "fullName": "John Smith",
        "email": "john@example.com"
      }
    ],
    "Location": {
      "id": "location-uuid",
      "name": "Building A"
    },
    "Asset": {
      "id": "asset-uuid",
      "name": "Fire Extinguisher #42"
    },
    "Checklist": {
      "id": "checklist-uuid",
      "title": "Safety Checklist"
    },
    "ChecklistLog": {
      "id": "submission-uuid",
      "status": "in_progress"
    },
    "Creator": {
      "id": "creator-uuid",
      "fullName": "Jane Doe"
    },
    "attachments": [
      {
        "url": "https://storage.example.com/attachment.pdf",
        "name": "instructions.pdf"
      }
    ],
    "canEdit": true,
    "canChangeStatus": true,
    "canDelete": true,
    "createdAt": "2024-12-19T10:00:00Z",
    "updatedAt": "2024-12-20T11:30:00Z"
  }
}
```

### Get Task Count Summary

Get counts of tasks by status.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/tasks/count-summary" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}"
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "status": "success",
  "code": 200,
  "data": {
    "Open": 25,
    "In Progress": 12,
    "On Hold": 3,
    "Completed": 156,
    "Missed": 8,
    "total": 204
  }
}
```

***

## Update Task Status

### Set Task Status

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PATCH "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/tasks/{taskId}/status" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}" \
    -H "Content-Type: application/json" \
    -d '{
      "taskStatus": "In Progress"
    }'
  ```
</CodeGroup>

**Task Status Values:**

| Status        | Description                        |
| ------------- | ---------------------------------- |
| `Open`        | Task is created but not started    |
| `In Progress` | Task is being worked on            |
| `On Hold`     | Task is paused                     |
| `Completed`   | Task is finished                   |
| `Missed`      | Task was not completed by due date |

**Response:**

```json theme={null}
{
  "status": "success",
  "code": 200,
  "data": {
    "id": "task-uuid",
    "taskStatus": "In Progress",
    "updatedAt": "2024-12-20T11:30:00Z"
  }
}
```

<Note>
  If a task has `isChecklistRequired: true`, the attached checklist must be submitted before the task can be marked as `Completed`.
</Note>

### Reopen a Completed Task

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PATCH "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/tasks/{taskId}/reopen" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}"
  ```
</CodeGroup>

### Archive a Task

Soft-delete a task (can be recovered).

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PATCH "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/tasks/{taskId}/archive" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}"
  ```
</CodeGroup>

***

## Edit Task

Update task details.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/tasks/{taskId}/edit" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}" \
    -H "Content-Type: application/json" \
    -d '{
      "title": "Updated Task Title",
      "description": "Updated description",
      "dueDate": "2024-12-25T17:00:00Z",
      "priority": "Medium"
    }'
  ```
</CodeGroup>

**Editable Fields:**

* `title`, `description`, `additionalDescription`
* `startDate`, `dueDate`, `startTime`, `dueTime`
* `priority`
* `locationIds`, `AssetId`
* `ChecklistId`, `isChecklistRequired`
* `notification`
* `attachment`
* `ServiceTypeId`

***

## Manage Assignees

### Add Assignee to Task

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/tasks/{taskId}/assignees/{userId}" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}"
  ```
</CodeGroup>

### Remove Assignee from Task

<CodeGroup>
  ```bash cURL theme={null}
  curl -X DELETE "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/tasks/{taskId}/assignees/{userId}" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}"
  ```
</CodeGroup>

### Replace All Assignees

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PATCH "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/tasks/{taskId}/assignees" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}" \
    -H "Content-Type: application/json" \
    -d '{
      "assignees": ["user-uuid-1", "user-uuid-2"]
    }'
  ```
</CodeGroup>

### Claim Task

User claims an unassigned or pool task.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PATCH "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/tasks/{taskId}/claim" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}"
  ```
</CodeGroup>

### Return Task

Return a claimed task back to the pool.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PATCH "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/tasks/{taskId}/return" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}"
  ```
</CodeGroup>

***

## Bulk Operations

### Bulk Update Tasks

Update multiple tasks at once.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PATCH "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/tasks/bulk-update" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}" \
    -H "Content-Type: application/json" \
    -d '{
      "taskIds": ["task-uuid-1", "task-uuid-2", "task-uuid-3"],
      "updates": {
        "priority": "High",
        "assignees": ["user-uuid"]
      }
    }'
  ```
</CodeGroup>

***

## Task Activity

### Get Task Activity Log

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/tasks/{taskId}/activity" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}"
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "status": "success",
  "code": 200,
  "data": [
    {
      "id": "activity-uuid-1",
      "action": "status_changed",
      "details": {
        "from": "Open",
        "to": "In Progress"
      },
      "User": {
        "id": "user-uuid",
        "fullName": "John Smith"
      },
      "createdAt": "2024-12-20T11:30:00Z"
    },
    {
      "id": "activity-uuid-2",
      "action": "assignee_added",
      "details": {
        "assignee": "Jane Doe"
      },
      "User": {
        "id": "user-uuid",
        "fullName": "John Smith"
      },
      "createdAt": "2024-12-19T10:00:00Z"
    }
  ]
}
```

***

## Delete Task

Permanently delete a task.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X DELETE "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/tasks/{taskId}" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}"
  ```
</CodeGroup>

<Warning>
  This permanently deletes the task and cannot be undone. Use archive for soft deletion.
</Warning>

***

## Export Tasks

### Export to CSV

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/tasks/csv" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}" \
    -H "Content-Type: application/json" \
    -d '{
      "filters": {
        "dateFrom": "2024-12-01",
        "dateTo": "2024-12-31"
      }
    }'
  ```
</CodeGroup>

**Response:** CSV file content

***

## Common Workflows

### Task with Required Checklist

```mermaid theme={null}
sequenceDiagram
    participant Client as Your System
    participant API as Xenia API
    participant User as Assignee

    Client->>API: 1. POST /tasks (with ChecklistId)
    Note right of Client: isChecklistRequired: true
    API-->>Client: Task created

    User->>API: 2. PATCH /tasks/{id}/status
    Note right of User: Set to "In Progress"

    User->>API: 3. POST /checklists/{id}/logs
    Note right of User: Start submission

    User->>API: 4. Complete checklist items

    User->>API: 5. POST /logs/{id}/submit
    Note right of User: Submit checklist

    User->>API: 6. PATCH /tasks/{id}/status
    Note right of User: Set to "Completed"
    API-->>Client: Task completed
```

### Assign and Track Task

```bash theme={null}
#!/bin/bash
# Create task, assign, and monitor

WORKSPACE_ID="your-workspace-uuid"

# 1. Create task
TASK=$(curl -s -X POST "https://api.xenia.team/api/v1/ops/workspaces/${WORKSPACE_ID}/tasks" \
  -H "x-client-key: YOUR_KEY" \
  -H "x-client-secret: YOUR_SECRET" \
  -H "workspace-id: ${WORKSPACE_ID}" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Equipment Maintenance",
    "startDate": "2024-12-20T09:00:00Z",
    "dueDate": "2024-12-20T17:00:00Z",
    "priority": "High"
  }')

TASK_ID=$(echo $TASK | jq -r '.data.id')

# 2. Add assignee
curl -X POST "https://api.xenia.team/api/v1/ops/workspaces/${WORKSPACE_ID}/tasks/${TASK_ID}/assignees/user-uuid" \
  -H "x-client-key: YOUR_KEY" \
  -H "x-client-secret: YOUR_SECRET" \
  -H "workspace-id: ${WORKSPACE_ID}"

# 3. Check task status
curl -X GET "https://api.xenia.team/api/v1/ops/workspaces/${WORKSPACE_ID}/tasks/${TASK_ID}/details" \
  -H "x-client-key: YOUR_KEY" \
  -H "x-client-secret: YOUR_SECRET" \
  -H "workspace-id: ${WORKSPACE_ID}"
```

***

## Best Practices

<AccordionGroup>
  <Accordion title="Use appropriate task status transitions">
    Follow the natural flow: Open → In Progress → Completed. Avoid skipping statuses for accurate reporting.
  </Accordion>

  <Accordion title="Attach checklists for standardized work">
    When tasks require specific steps or inspections, attach a checklist template. Set `isChecklistRequired: true` to enforce completion.
  </Accordion>

  <Accordion title="Use locations and assets for context">
    Always associate tasks with locations and assets when applicable. This improves filtering, reporting, and mobile worker routing.
  </Accordion>

  <Accordion title="Set realistic due dates">
    Consider timezone differences when setting due dates. Use `startTime` and `dueTime` for time-sensitive tasks.
  </Accordion>

  <Accordion title="Use bulk operations for efficiency">
    When updating multiple tasks (e.g., reassigning), use the bulk update endpoint instead of individual calls.
  </Accordion>
</AccordionGroup>

***

## Related Guides

* [Task Scheduling](/guides/workflows/task-scheduling) - Recurring tasks and schedules
* [Work Orders](/guides/workflows/work-orders) - Facility request management
* [Corrective Actions](/guides/workflows/corrective-actions) - Tasks from flagged items
* [Project Management](/guides/workflows/project-management) - Organize related tasks
* [Template Management](/guides/workflows/template-management) - Create checklists for tasks