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

# Asset Management

> Create, organize, and maintain assets with hierarchical structures and service tracking

## Overview

Xenia's asset management system allows you to track equipment, machinery, and other physical assets across your locations. Key features include:

* **Hierarchical assets**: Create parent-child relationships (e.g., HVAC System → Compressor → Filter)
* **Location binding**: Associate assets with specific locations
* **Service tracking**: Schedule and record maintenance activities
* **QR codes**: Enable quick asset identification via QR scanning
* **Task integration**: Link tasks to specific assets for maintenance workflows

***

## Asset CRUD Operations

### List All Assets

Retrieve assets with optional filtering and pagination.

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

  ```bash cURL (With Pagination) theme={null}
  curl -X GET "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/assets?page=1&perPage=50" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}"
  ```

  ```bash cURL (With Search) theme={null}
  curl -X GET "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/assets?searchText=HVAC" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}"
  ```
</CodeGroup>

**Query Parameters:**

| Parameter    | Type   | Description                              |
| ------------ | ------ | ---------------------------------------- |
| `page`       | number | Pagination page number                   |
| `perPage`    | number | Items per page (0 or omit = return all)  |
| `searchText` | string | Search filter for asset name/description |

**Response:**

```json theme={null}
{
  "status": "success",
  "code": 200,
  "data": {
    "assets": [
      {
        "id": "asset-uuid-1",
        "name": "HVAC Unit #1",
        "description": "Main building HVAC system",
        "model": "Carrier 24ACC636A003",
        "serialNumber": "SN-2024-001234",
        "purchaseDate": "2022-03-15",
        "LocationId": "location-uuid",
        "Location": {
          "id": "location-uuid",
          "name": "Building A - Roof"
        },
        "ParentId": null,
        "isQREnable": true,
        "attachments": ["https://storage.example.com/manual.pdf"],
        "createdAt": "2022-03-20T10:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "perPage": 50,
      "total": 127,
      "totalPages": 3
    }
  }
}
```

### List Assets by Location

Get all assets at a specific location.

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

### List Assets with Location Filter (POST)

Filter assets by multiple locations.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/assets/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 '{
      "locations": ["location-uuid-1", "location-uuid-2"]
    }'
  ```
</CodeGroup>

### Get Asset by ID

Retrieve detailed information about a specific asset.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/assets/{assetId}" \
    -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": "asset-uuid",
    "name": "HVAC Unit #1",
    "description": "Main building HVAC system - Rooftop unit serving floors 1-5",
    "model": "Carrier 24ACC636A003",
    "serialNumber": "SN-2024-001234",
    "purchaseDate": "2022-03-15",
    "LocationId": "location-uuid",
    "Location": {
      "id": "location-uuid",
      "name": "Building A - Roof"
    },
    "ParentId": null,
    "SubAssets": [
      {
        "id": "sub-asset-1",
        "name": "Compressor",
        "model": "Copeland ZR57K3E"
      },
      {
        "id": "sub-asset-2",
        "name": "Air Filter",
        "model": "MERV-13 24x24x2"
      }
    ],
    "isQREnable": true,
    "avatar": "https://storage.example.com/hvac-photo.jpg",
    "attachments": [
      "https://storage.example.com/installation-manual.pdf",
      "https://storage.example.com/warranty.pdf"
    ],
    "createdAt": "2022-03-20T10:00:00Z",
    "updatedAt": "2024-06-15T14:30:00Z"
  }
}
```

### Create Asset

Create a new asset with optional sub-assets.

<CodeGroup>
  ```bash cURL (Simple) theme={null}
  curl -X POST "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/assets" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Industrial Refrigerator",
      "description": "Walk-in cooler for kitchen storage",
      "model": "True TWT-48SD",
      "serialNumber": "TWT48-2024-5678",
      "purchaseDate": "2024-01-10",
      "LocationId": "kitchen-location-uuid",
      "isQREnable": true
    }'
  ```

  ```bash cURL (With Sub-Assets) theme={null}
  curl -X POST "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/assets" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "HVAC System - Building B",
      "description": "Complete HVAC system for Building B",
      "model": "Trane XR15",
      "LocationId": "building-b-roof-uuid",
      "SubAssets": {
        "Compressor Unit": {
          "model": "Copeland ZR57K3E",
          "serialNumber": "COMP-001"
        },
        "Condenser": {
          "model": "Trane 4TTR5036E",
          "serialNumber": "COND-001"
        },
        "Air Handler": {
          "model": "Trane GAM5A0C48M41",
          "serialNumber": "AH-001",
          "SubAssets": {
            "Blower Motor": {
              "model": "GE 5KCP39PGV623S"
            },
            "Air Filter": {
              "model": "MERV-13 20x25x4"
            }
          }
        }
      }
    }'
  ```

  ```bash cURL (As Child of Existing Asset) theme={null}
  curl -X POST "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/assets" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Replacement Filter",
      "model": "MERV-13 24x24x2",
      "ParentId": "hvac-unit-uuid"
    }'
  ```
</CodeGroup>

**Request Body:**

| Field          | Type      | Required | Description                       |
| -------------- | --------- | -------- | --------------------------------- |
| `name`         | string    | Yes      | Asset name                        |
| `description`  | string    | No       | Detailed description              |
| `model`        | string    | No       | Model number/name                 |
| `serialNumber` | string    | No       | Serial number                     |
| `purchaseDate` | string    | No       | Purchase date (ISO 8601)          |
| `LocationId`   | UUID      | No       | Location where asset is installed |
| `ParentId`     | UUID      | No       | Parent asset ID (for sub-assets)  |
| `SubAssets`    | object    | No       | Nested sub-assets structure       |
| `attachments`  | string\[] | No       | URLs to attached documents        |
| `isQREnable`   | boolean   | No       | Enable QR code for this asset     |

<Note>
  **Permission Required:** `CAN_MANAGE_ASSETS`
</Note>

<Info>
  Asset creation may be limited by your subscription plan. Contact support if you receive a paywall error.
</Info>

### Update Asset

Modify an existing asset's details.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PATCH "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/assets/{assetId}" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "HVAC Unit #1 (Primary)",
      "description": "Updated description with maintenance notes",
      "LocationId": "new-location-uuid"
    }'
  ```
</CodeGroup>

### Delete Assets

Delete one or more assets.

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

<Warning>
  Deleting a parent asset will also delete all sub-assets in its hierarchy.
</Warning>

***

## Asset Tasks

Get all tasks associated with an asset.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/assets/{assetId}/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": [
    {
      "id": "task-uuid-1",
      "title": "Monthly HVAC Filter Replacement",
      "status": "Open",
      "dueDate": "2024-12-31T17:00:00Z",
      "assignees": [
        { "id": "user-uuid", "fullName": "John Smith" }
      ]
    },
    {
      "id": "task-uuid-2",
      "title": "Annual HVAC Inspection",
      "status": "Completed",
      "dueDate": "2024-06-15T17:00:00Z"
    }
  ]
}
```

***

## Asset Services (Maintenance Tracking)

Track scheduled maintenance, service history, and costs for your assets.

<Info>
  **Feature Required:** Asset services require the `ASSET_SERVICE` feature to be enabled for your workspace.
</Info>

### List Asset Services

Retrieve services with filtering and pagination.

<CodeGroup>
  ```bash cURL (All Services) theme={null}
  curl -X POST "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/assets/services/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 '{
      "offset": 0,
      "limit": 100
    }'
  ```

  ```bash cURL (Filter by Asset) theme={null}
  curl -X POST "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/assets/services/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 '{
      "filters": {
        "asset": ["asset-uuid-1", "asset-uuid-2"]
      }
    }'
  ```

  ```bash cURL (Filter by Status) theme={null}
  curl -X POST "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/assets/services/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 '{
      "filters": {
        "status": "overdue"
      }
    }'
  ```
</CodeGroup>

**Request Body:**

| Field            | Type      | Description                                                |
| ---------------- | --------- | ---------------------------------------------------------- |
| `filters.asset`  | string\[] | Filter by asset IDs                                        |
| `filters.status` | string    | Filter by status: `"upcoming"`, `"overdue"`, `"completed"` |
| `sort`           | array     | Sort criteria                                              |
| `offset`         | number    | Skip N records (default: 0)                                |
| `limit`          | number    | Max records to return (default: 100)                       |

**Response:**

```json theme={null}
{
  "status": "success",
  "code": 200,
  "data": {
    "services": [
      {
        "id": "service-uuid-1",
        "title": "Quarterly Filter Replacement",
        "description": "Replace MERV-13 filters",
        "date": "2024-12-15T10:00:00Z",
        "isCompleted": false,
        "cost": null,
        "Asset": {
          "id": "asset-uuid",
          "name": "HVAC Unit #1"
        },
        "reminder": {
          "enabled": true,
          "daysBefore": 7
        }
      }
    ],
    "counts": {
      "upcoming": 5,
      "overdue": 2,
      "completed": 48
    }
  }
}
```

### Get Service by ID

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

### Create Asset Service

Schedule a new maintenance service.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/assets/services" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}" \
    -H "Content-Type: application/json" \
    -d '{
      "assetId": "asset-uuid",
      "title": "Annual Compressor Inspection",
      "description": "Full inspection of compressor unit including refrigerant levels, electrical connections, and performance test",
      "date": "2025-03-15T09:00:00Z",
      "reminder": {
        "enabled": true,
        "daysBefore": 14
      }
    }'
  ```
</CodeGroup>

**Request Body:**

| Field                 | Type    | Required | Description                          |
| --------------------- | ------- | -------- | ------------------------------------ |
| `assetId`             | string  | Yes      | Asset this service is for            |
| `title`               | string  | Yes      | Service title                        |
| `description`         | string  | No       | Detailed service description         |
| `date`                | string  | Yes      | Scheduled service date (ISO 8601)    |
| `reminder`            | object  | No       | Reminder configuration               |
| `reminder.enabled`    | boolean | No       | Enable reminder notifications        |
| `reminder.daysBefore` | number  | No       | Days before service to send reminder |
| `isCompleted`         | boolean | No       | Mark as already completed            |
| `cost`                | number  | No       | Service cost (if completed)          |

**Response:**

```json theme={null}
{
  "status": "success",
  "code": 200,
  "data": {
    "id": "new-service-uuid",
    "title": "Annual Compressor Inspection",
    "date": "2025-03-15T09:00:00Z",
    "isCompleted": false,
    "AssetId": "asset-uuid"
  }
}
```

### Update Asset Service

Modify a scheduled service.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PATCH "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/assets/services/{serviceId}" \
    -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": "Annual Compressor Inspection (Rescheduled)",
      "date": "2025-04-01T09:00:00Z",
      "description": "Rescheduled due to parts availability"
    }'
  ```
</CodeGroup>

### Complete Asset Service

Mark a service as completed with optional cost and comments.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PATCH "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/assets/services/{serviceId}/complete" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}" \
    -H "Content-Type: application/json" \
    -d '{
      "cost": 450.00,
      "comment": "Replaced capacitor, recharged refrigerant to spec. System operating normally."
    }'
  ```
</CodeGroup>

**Request Body:**

| Field     | Type   | Required | Description               |
| --------- | ------ | -------- | ------------------------- |
| `cost`    | number | No       | Total service cost        |
| `comment` | string | No       | Completion notes/comments |

### Delete Asset Service

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

***

## Common Workflows

### Importing Assets from CMMS/EAM

```mermaid theme={null}
sequenceDiagram
    participant CMMS as External CMMS
    participant Client as Integration
    participant API as Xenia API

    Client->>CMMS: 1. Fetch asset list
    CMMS-->>Client: Assets with hierarchy

    Client->>API: 2. Get locations
    API-->>Client: Location mapping

    loop For each asset
        Client->>API: 3. Create asset
        Note right of Client: Map CMMS location to Xenia
        API-->>Client: Asset created
    end

    Client->>API: 4. Create service schedules
    API-->>Client: Services scheduled
```

**Example Integration:**

```bash theme={null}
# Step 1: Create parent asset
PARENT_ID=$(curl -X POST ".../assets" \
  -d '{
    "name": "Chiller System #1",
    "model": "Trane CVHE",
    "serialNumber": "CVHE-2020-1234",
    "LocationId": "mechanical-room-uuid"
  }' | jq -r '.data.id')

# Step 2: Create child assets
curl -X POST ".../assets" \
  -d "{
    \"name\": \"Chiller Compressor\",
    \"model\": \"Trane CHHP\",
    \"ParentId\": \"${PARENT_ID}\"
  }"

# Step 3: Schedule maintenance
curl -X POST ".../assets/services" \
  -d "{
    \"assetId\": \"${PARENT_ID}\",
    \"title\": \"Annual Chiller Inspection\",
    \"date\": \"2025-06-01T08:00:00Z\",
    \"reminder\": {\"enabled\": true, \"daysBefore\": 30}
  }"
```

### Tracking Maintenance Costs

```bash theme={null}
# Get all completed services for cost analysis
curl -X POST ".../assets/services/list" \
  -d '{
    "filters": {
      "status": "completed"
    },
    "limit": 1000
  }'

# Sum costs by asset for reporting
# Response includes cost field for each completed service
```

### Asset Lifecycle Management

```bash theme={null}
# 1. Create asset when purchased
curl -X POST ".../assets" \
  -d '{
    "name": "New Equipment",
    "purchaseDate": "2024-12-01",
    "model": "Model XYZ"
  }'

# 2. Schedule initial services
curl -X POST ".../assets/services" \
  -d '{
    "assetId": "asset-uuid",
    "title": "Initial Setup & Calibration",
    "date": "2024-12-15T09:00:00Z"
  }'

# 3. Track ongoing maintenance via services
# 4. When asset is retired, delete it
curl -X DELETE ".../assets" \
  -d '{"assetIds": ["asset-uuid"]}'
```

***

## Best Practices

<AccordionGroup>
  <Accordion title="Use hierarchical assets for complex equipment">
    Break down complex systems into parent/child assets. This enables granular maintenance tracking and makes it easier to identify which component needs service.
  </Accordion>

  <Accordion title="Include model and serial numbers">
    Always populate `model` and `serialNumber` fields. This helps with warranty claims, parts ordering, and maintenance documentation.
  </Accordion>

  <Accordion title="Attach documentation">
    Use the `attachments` field to link manuals, warranty documents, and installation guides directly to assets.
  </Accordion>

  <Accordion title="Enable QR codes for field access">
    Set `isQREnable: true` for assets that field workers need to quickly identify. They can scan the QR to pull up asset details and history.
  </Accordion>

  <Accordion title="Schedule recurring services">
    Create service records for all planned maintenance. Use reminders to ensure nothing is missed.
  </Accordion>

  <Accordion title="Track costs consistently">
    Always record `cost` when completing services. This data enables total cost of ownership analysis and budget planning.
  </Accordion>
</AccordionGroup>

***

## Related Guides

* [Location Hierarchy](/guides/workflows/location-hierarchy) - Organize locations where assets are installed
* [Task Management](/guides/workflows/task-management) - Create maintenance tasks for assets
* [Location Members](/guides/workflows/location-members) - Assign technicians to asset locations