> ## 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.

# Project Management

> Organize and manage groups of related tasks with projects

## Overview

Projects in Xenia group related tasks together for coordinated execution. They're ideal for:

* Multi-step work that spans multiple assignees or locations
* Recurring work programs (daily rounds, weekly audits)
* Asset-based maintenance programs
* Role-based task distribution

<Info>
  Projects require the `PROJECTS` feature to be enabled for your workspace.
</Info>

**Project Types:**

* **User Projects**: Assign tasks to specific users
* **Asset Projects**: Create tasks for each asset
* **Role Projects**: Distribute tasks based on user roles and locations

***

## Create a Project

### User-Based Project

Create a project that assigns tasks to specific users.

<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 Rounds",
      "description": "Complete weekly safety inspection at assigned locations",
      "isProject": true,
      "projectType": "user",
      "assignees": ["user-uuid-1", "user-uuid-2", "user-uuid-3"],
      "recurringTask": true,
      "recurringByEvery": "weekly",
      "intervalWeek": [1],
      "startTime": "08:00",
      "dueTime": "12:00",
      "timezone": "America/New_York",
      "ChecklistId": "safety-checklist-uuid",
      "isChecklistRequired": true,
      "notification": {
        "email": true,
        "push": true
      }
    }'
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "status": "success",
  "code": 200,
  "data": {
    "id": "project-uuid",
    "title": "Weekly Safety Rounds",
    "type": "user",
    "state": "creating",
    "isPaused": false,
    "entityIds": ["user-uuid-1", "user-uuid-2", "user-uuid-3"],
    "isSchedulesProject": true,
    "recurringByEvery": "weekly",
    "CreatedBy": "creator-uuid",
    "createdAt": "2024-12-20T10:00:00Z"
  },
  "message": "We are setting up your project, Please check back shortly"
}
```

<Note>
  Project creation is asynchronous. The `state` will be `creating` initially and transition to `ready` once all schedules are generated.
</Note>

### Asset-Based Project

Create a project that generates tasks for each specified asset.

<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": "Monthly HVAC Maintenance",
      "description": "Perform monthly preventive maintenance on HVAC units",
      "isProject": true,
      "projectType": "asset",
      "assets": ["hvac-uuid-1", "hvac-uuid-2", "hvac-uuid-3"],
      "recurringTask": true,
      "recurringByEvery": "monthly",
      "recurringOnDay": 1,
      "startTime": "08:00",
      "dueTime": "17:00",
      "timezone": "America/New_York",
      "ChecklistId": "hvac-maintenance-checklist-uuid",
      "isChecklistRequired": true
    }'
  ```
</CodeGroup>

### Role-Based Project

Create a project that distributes tasks based on user roles.

<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": "Daily Opening Checklist",
      "description": "Complete opening procedures",
      "isProject": true,
      "projectType": "role",
      "assigneesRoles": {
        "creationType": "CREATE_TASKS_BY_LOCATION",
        "roles": ["shift-supervisor-role-uuid"]
      },
      "recurringTask": true,
      "recurringByEvery": "daily",
      "startTime": "06:00",
      "dueTime": "08:00",
      "timezone": "America/New_York",
      "ChecklistId": "opening-checklist-uuid",
      "isChecklistRequired": true
    }'
  ```
</CodeGroup>

**Role Assignment Types:**

| Type                             | Description                                      |
| -------------------------------- | ------------------------------------------------ |
| `CREATE_SEPARATE_TASK_USER_WISE` | One task per user with the role                  |
| `CREATE_TASKS_BY_LOCATION`       | One task per location with users having the role |

***

## List Projects

### Get All Projects

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

**Query Parameters:**

| Parameter  | Type    | Description                                  |
| ---------- | ------- | -------------------------------------------- |
| `detailed` | boolean | Include analytics and statistics             |
| `all`      | boolean | Include all projects (bypass user filtering) |

### List Projects with Filters

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/projects" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}" \
    -H "Content-Type: application/json" \
    -d '{
      "offset": 0,
      "limit": 20,
      "searchText": "safety",
      "sortField": "createdAt",
      "sortOrder": "DESC",
      "status": "ACTIVE"
    }'
  ```
</CodeGroup>

**Request Body:**

| Field            | Type   | Description                             |
| ---------------- | ------ | --------------------------------------- |
| `offset`         | number | Pagination offset (default: 0)          |
| `limit`          | number | Items per page (default: 10)            |
| `searchText`     | string | Search in title/description             |
| `sortField`      | string | Field to sort by (default: `createdAt`) |
| `sortOrder`      | string | `ASC` or `DESC` (default: `DESC`)       |
| `status`         | string | `ALL`, `ACTIVE`, `PAUSED`, `EXPIRED`    |
| `advanceFilters` | object | Additional filter criteria              |

**Response:**

```json theme={null}
{
  "status": "success",
  "code": 200,
  "data": {
    "projects": [
      {
        "id": "project-uuid",
        "title": "Weekly Safety Rounds",
        "type": "user",
        "state": "ready",
        "isPaused": false,
        "recurringByEvery": "weekly",
        "entityIds": ["user-uuid-1", "user-uuid-2"],
        "statistics": {
          "totalSchedules": 3,
          "activeSchedules": 3,
          "completedTasks": 45,
          "overdueCount": 2,
          "completionRate": 95.7
        },
        "nextInstanceDate": "2024-12-23T08:00:00Z",
        "createdAt": "2024-12-01T10:00:00Z"
      }
    ],
    "meta": {
      "total": 8,
      "offset": 0,
      "limit": 20
    }
  }
}
```

***

## Get Project Details

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/projects/{projectId}" \
    -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": "project-uuid",
    "title": "Weekly Safety Rounds",
    "description": "Complete weekly safety inspection at assigned locations",
    "type": "user",
    "state": "ready",
    "isPaused": false,
    "entityIds": ["user-uuid-1", "user-uuid-2", "user-uuid-3"],
    "recurringTask": true,
    "recurringByEvery": "weekly",
    "intervalWeek": [1],
    "startTime": "08:00",
    "dueTime": "12:00",
    "timezone": "America/New_York",
    "Checklist": {
      "id": "checklist-uuid",
      "title": "Safety Inspection Checklist"
    },
    "isChecklistRequired": true,
    "isEditable": true,
    "NextTask": {
      "id": "next-task-uuid",
      "startDate": "2024-12-23T08:00:00Z"
    },
    "ActiveTask": null,
    "statistics": {
      "totalSchedules": 3,
      "activeSchedules": 3,
      "totalTasks": 48,
      "completedTasks": 45,
      "missedTasks": 3,
      "completionRate": 93.75
    },
    "CreatedBy": {
      "id": "creator-uuid",
      "fullName": "Admin User"
    },
    "createdAt": "2024-12-01T10:00:00Z",
    "updatedAt": "2024-12-20T15:00:00Z"
  }
}
```

***

## Get Active Tasks

Get currently active tasks for a project.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/projects/{projectId}/active/tasks" \
    -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": {
    "project": {
      "id": "project-uuid",
      "title": "Weekly Safety Rounds"
    },
    "activeTasks": [
      {
        "id": "task-uuid-1",
        "taskNumber": "T-2024-001250",
        "taskStatus": "In Progress",
        "Assignee": {
          "id": "user-uuid-1",
          "fullName": "John Smith"
        },
        "startDate": "2024-12-20T08:00:00Z",
        "dueDate": "2024-12-20T12:00:00Z"
      },
      {
        "id": "task-uuid-2",
        "taskNumber": "T-2024-001251",
        "taskStatus": "Open",
        "Assignee": {
          "id": "user-uuid-2",
          "fullName": "Jane Doe"
        },
        "startDate": "2024-12-20T08:00:00Z",
        "dueDate": "2024-12-20T12:00:00Z"
      }
    ]
  }
}
```

***

## Edit Project

Update project configuration. Changes apply to future task instances.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PATCH "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/projects/{projectId}/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 Weekly Safety Rounds",
      "description": "Updated description",
      "dueTime": "14:00",
      "priority": "High",
      "notification": {
        "email": true,
        "push": true,
        "sms": false
      }
    }'
  ```
</CodeGroup>

**Editable Fields:**

* `title`, `description`, `additionalDescription`
* `startTime`, `dueTime`
* `priority`
* `notification`
* `assignees` (for user projects)
* `ChecklistId`, `isChecklistRequired`
* `endDate`

<Warning>
  You cannot change the recurrence pattern (`recurringByEvery`, `intervalWeek`) or project type after creation.
</Warning>

***

## Manage Project State

### Pause Project

Temporarily stop generating new task instances.

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

**Response (Paused):**

```json theme={null}
{
  "status": "success",
  "code": 200,
  "data": {
    "id": "project-uuid",
    "isPaused": true
  },
  "message": "Project has been paused"
}
```

### Resume Project

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

**Response (Resumed):**

```json theme={null}
{
  "status": "success",
  "code": 200,
  "data": {
    "id": "project-uuid",
    "isPaused": false
  },
  "message": "Project has been resumed"
}
```

<Note>
  This endpoint toggles the pause state. Call once to pause, call again to resume.
</Note>

### End Project

Permanently stop the project. No new tasks will be generated.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PUT "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/projects/{projectId}/end" \
    -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": null
}
```

<Warning>
  Ending a project is permanent. All schedules are ended and no new tasks will be created. Existing tasks remain.
</Warning>

***

## Add Schedule to Project

Add a new entity (user, asset, or location) to an existing project.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/projects/{projectId}/add-schedule" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}" \
    -H "Content-Type: application/json" \
    -d '{
      "entityId": "new-user-uuid"
    }'
  ```
</CodeGroup>

**Request Body:**

| Field      | Type   | Description                                                                                    |
| ---------- | ------ | ---------------------------------------------------------------------------------------------- |
| `entityId` | string | User ID (for user projects), Asset ID (for asset projects), or Location ID (for role projects) |

**Response:**

```json theme={null}
{
  "status": "success",
  "code": 200,
  "data": {},
  "message": "Project is updating, Check back shortly"
}
```

***

## Project Access Control

Manage who can view and manage a project.

### Set Project Access

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

**Request Body:**

| Field    | Type      | Description                                      |
| -------- | --------- | ------------------------------------------------ |
| `access` | string\[] | Array of user, role, or team IDs to grant access |

<Note>
  This replaces the entire access list. Include all entities that should have access.
</Note>

***

## Project Analytics

### Get Task Analytics

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

**Response:**

```json theme={null}
{
  "status": "success",
  "code": 200,
  "data": {
    "totalTasks": 96,
    "completedTasks": 90,
    "missedTasks": 4,
    "inProgressTasks": 2,
    "completionRate": 93.75,
    "averageCompletionTime": "2.5 hours",
    "byAssignee": [
      {
        "assignee": "John Smith",
        "completed": 30,
        "missed": 2,
        "completionRate": 93.75
      },
      {
        "assignee": "Jane Doe",
        "completed": 32,
        "missed": 0,
        "completionRate": 100
      }
    ]
  }
}
```

### Get Schedule Analytics

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/projects/{projectId}/schedules/analytics" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}" \
    -H "Content-Type: application/json" \
    -d '{}'
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "status": "success",
  "code": 200,
  "data": {
    "totalSchedules": 3,
    "activeSchedules": 3,
    "pausedSchedules": 0,
    "endedSchedules": 0,
    "schedules": [
      {
        "id": "schedule-uuid-1",
        "assignee": "John Smith",
        "status": "active",
        "instancesGenerated": 16,
        "nextInstance": "2024-12-23T08:00:00Z"
      },
      {
        "id": "schedule-uuid-2",
        "assignee": "Jane Doe",
        "status": "active",
        "instancesGenerated": 16,
        "nextInstance": "2024-12-23T08:00:00Z"
      }
    ]
  }
}
```

***

## Delete Project

<CodeGroup>
  ```bash cURL theme={null}
  curl -X DELETE "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/projects/{projectId}" \
    -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,
  "message": "Project has been deleted"
}
```

<Warning>
  Deleting a project removes all associated schedules and tasks. This cannot be undone.
</Warning>

***

## Project States

| State      | Description                                   |
| ---------- | --------------------------------------------- |
| `creating` | Project is being set up, schedules generating |
| `ready`    | Project is active and operational             |
| `updating` | Project is being modified                     |
| `expired`  | Project has ended                             |

***

## Common Workflows

### Multi-Location Inspection Program

```mermaid theme={null}
sequenceDiagram
    participant Client as Your System
    participant API as Xenia API
    participant Workers as Field Workers

    Client->>API: 1. POST /tasks (isProject: true)
    Note right of Client: projectType: "role"<br/>roles: ["inspector"]

    API->>API: 2. Generate schedules
    Note right of API: One per location<br/>with inspector role

    API-->>Client: Project created (state: ready)

    loop Weekly
        API->>Workers: 3. Tasks become active
        Workers->>API: 4. Complete inspections
        Client->>API: 5. GET /projects/{id}/tasks/analytics
        API-->>Client: Completion rates
    end
```

### Asset Maintenance Program

```bash theme={null}
#!/bin/bash
# Create asset maintenance project

WORKSPACE_ID="your-workspace-uuid"

# Get all HVAC assets
ASSETS=$(curl -s -X POST "https://api.xenia.team/api/v1/mgt/workspaces/${WORKSPACE_ID}/assets" \
  -H "x-client-key: YOUR_KEY" \
  -H "x-client-secret: YOUR_SECRET" \
  -H "workspace-id: ${WORKSPACE_ID}" \
  -H "Content-Type: application/json" \
  -d '{"type": "hvac"}' | jq -r '[.data[].id]')

# Create maintenance project for all HVAC units
curl -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\": \"Quarterly HVAC Maintenance\",
    \"description\": \"Preventive maintenance for HVAC units\",
    \"isProject\": true,
    \"projectType\": \"asset\",
    \"assets\": ${ASSETS},
    \"recurringTask\": true,
    \"recurringByEvery\": \"quarterly\",
    \"recurringOnDay\": 1,
    \"timezone\": \"America/New_York\",
    \"ChecklistId\": \"hvac-checklist-uuid\",
    \"isChecklistRequired\": true
  }"
```

***

## Best Practices

<AccordionGroup>
  <Accordion title="Choose the right project type">
    * **User projects**: When you know specific individuals who should do the work
    * **Asset projects**: For equipment-based maintenance programs
    * **Role projects**: For location-based work where any user with the role can complete it
  </Accordion>

  <Accordion title="Attach checklists for consistency">
    Require checklist completion (`isChecklistRequired: true`) to ensure standardized data collection across all project tasks.
  </Accordion>

  <Accordion title="Monitor completion rates">
    Regularly check project analytics. Low completion rates may indicate staffing issues, unrealistic schedules, or training needs.
  </Accordion>

  <Accordion title="Use pause for temporary stops">
    If a project needs to be temporarily halted (holiday season, construction period), use pause instead of ending it.
  </Accordion>

  <Accordion title="Add schedules incrementally">
    When new users, assets, or locations need to be included, use the add-schedule endpoint rather than recreating the project.
  </Accordion>

  <Accordion title="Set appropriate access">
    Configure project access so only relevant managers and supervisors can view and manage the project.
  </Accordion>
</AccordionGroup>

***

## Permissions

| Action         | Required Permission        |
| -------------- | -------------------------- |
| Create project | `CAN_MANAGE_TASKS`         |
| View projects  | — (access controlled)      |
| Edit project   | `CAN_EDIT_PROJECT`         |
| Pause/Resume   | `CAN_PAUSE_RESUME_PROJECT` |
| Delete project | `CAN_DELETE_PROJECT`       |
| Manage access  | `CAN_EDIT_PROJECT`         |

***

## Related Guides

* [Task Management](/guides/workflows/task-management) - Individual task operations
* [Task Scheduling](/guides/workflows/task-scheduling) - Recurring task configuration
* [Template Management](/guides/workflows/template-management) - Create checklists for projects
* [Asset Management](/guides/workflows/asset-management) - Manage assets for asset projects