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

# Item

> MCP tools for creating, reading, updating, deleting, copying, and managing work item dependencies.

<Note>
  Items carry a dynamic set of fields controlled by their [process](/guide/concepts/processes) and [container permissions](/guide/concepts/processes#field-level-access-control). To understand the field model, available field types, and how to discover which fields you can set, see [Items and fields](/guide/api/items-and-fields).
</Note>

## get\_item\_screen

Discover available fields for creating or updating an item. Returns field definitions, types, required flags, default values, and valid options. List fields include selectable options inline. Picker fields include a `scope` and `pickerHint` indicating which tool to call for valid entity IDs.

| Property      |     |
| ------------- | --- |
| **Read-only** | Yes |

### Parameters

| Parameter     | Type   | Required | Default  | Description                                                                                      |
| ------------- | ------ | -------- | -------- | ------------------------------------------------------------------------------------------------ |
| `containerId` | string | Yes      | —        | Container ID. Use [`get_containers`](/mcp-tools/container#get_containers).                       |
| `processId`   | string | Yes      | —        | Process ID. Use [`get_container_process_list`](/mcp-tools/container#get_container_process_list). |
| `stage`       | string | No       | `create` | `create` for new items, `update` for existing items (requires `itemId`).                         |
| `itemId`      | string | No       | —        | Item ID or key. Required when `stage` is `update`.                                               |

### Returns

An `ItemScreenDto` containing:

* **`stage`** — the requested stage (`create` or `update`)
* **`fields`** — list of `ItemScreenFieldDto`:

| Property       | Description                                                                       |
| -------------- | --------------------------------------------------------------------------------- |
| `fieldId`      | Field identifier to use in `fieldsJson`                                           |
| `fieldName`    | Human-readable name                                                               |
| `fieldType`    | Data type (`List`, `Picker`, `Text`, `Date`, etc.)                                |
| `defaultValue` | Current/default value                                                             |
| `required`     | Whether the field must be provided                                                |
| `scope`        | *(Picker fields only)* Entity scope, e.g. `User`, `Area`, `Board`                 |
| `pickerHint`   | *(Picker fields only)* Which tool to call for valid IDs, e.g. `Use get_user_list` |
| `options`      | *(List fields only)* Available options with `id`, `value`, `metadata`             |

* **`workflow`** — available status transitions with `statusId`, `statusValue`, and `phase`

***

## get\_item

Get a single work item by ID or key (e.g. `GEM-123`). Returns item details including status, priority, assignment, and time logged.

| Property      |     |
| ------------- | --- |
| **Read-only** | Yes |

### Parameters

| Parameter | Type   | Required | Description                      |
| --------- | ------ | -------- | -------------------------------- |
| `itemId`  | string | Yes      | Item ID or key (e.g. `GEM-123`). |

### Returns

A `CycleItemDto` with the item's key, name, url, status, container, board, cycle, work estimate, time logged, and resource assignment. The `url` field links directly to the item in the Ekso web app. Returns an error if the item is not found.

***

## search\_items

Search for work items by keyword across containers. Matches on item name or sequence number. For structured queries by field values (status, priority, etc.), use [`filter_items`](/mcp-tools/container#filter_items) instead.

| Property      |     |
| ------------- | --- |
| **Read-only** | Yes |

### Parameters

| Parameter      | Type   | Required | Description                                                                                                                                    |
| -------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `keyword`      | string | Yes      | Search term to match against item names and sequence numbers.                                                                                  |
| `containerIds` | string | No       | Comma-separated container IDs to limit scope. Searches all containers if omitted. Use [`get_containers`](/mcp-tools/container#get_containers). |

### Returns

A list of `ItemMatch` objects, each containing:

* `itemId`, `itemName`, `itemSequence` — item identity
* `containerId`, `containerName`, `containerCode` — container context

***

## create\_item

Create a new work item in the specified container with a given process type. Call [`get_item_screen`](#get_item_screen) with stage `create` first to discover available fields. Only include fields marked as required — optional fields (priority, severity, etc.) can be set later via [`update_item`](#update_item).

| Property      |    |
| ------------- | -- |
| **Read-only** | No |

### Parameters

| Parameter     | Type   | Required | Description                                                                                                                                                                                                                      |
| ------------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `containerId` | string | Yes      | Container to create the item in. Use [`get_containers`](/mcp-tools/container#get_containers) to find IDs.                                                                                                                        |
| `processId`   | string | Yes      | Process type for the item. Use [`get_container_process_list`](/mcp-tools/container#get_container_process_list) to find IDs.                                                                                                      |
| `fieldsJson`  | string | No       | Required field values as JSON: `[{"fieldId":"<id>","value":"<value>"}]`. Use [`get_item_screen`](#get_item_screen) to discover field IDs and required flags. Only required fields are needed — optional fields can be set later. |

### Returns

A `CycleItemDto` with the created item's key, name, status, container, and planning details.

***

## update\_item

Update an existing work item. Supports item ID or key format (e.g. `GEM-123`). Only provided fields are updated. Call [`get_item_screen`](#get_item_screen) with stage `update` and the `itemId` to discover updatable fields, current values, and valid workflow transitions.

| Property      |    |
| ------------- | -- |
| **Read-only** | No |

### Parameters

| Parameter    | Type   | Required | Description                                                                                                                                               |
| ------------ | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `itemId`     | string | Yes      | Item ID or key (e.g. `GEM-123`).                                                                                                                          |
| `fieldsJson` | string | No       | Changed field values as JSON: `[{"fieldId":"<id>","value":"<value>"}]`. Use [`get_item_screen`](#get_item_screen) to discover field IDs and valid values. |

### Returns

A `CycleItemDto` with the updated item details.

***

## delete\_item

Delete a work item by ID or key (e.g. `GEM-123`).

| Property      |    |
| ------------- | -- |
| **Read-only** | No |

### Parameters

| Parameter | Type   | Required | Description     |
| --------- | ------ | -------- | --------------- |
| `itemId`  | string | Yes      | Item ID or key. |

### Returns

A confirmation message with the deleted item's key.

***

## copy\_item

Duplicate a work item within the same container. Requires Add permission on the item's container.

| Property      |    |
| ------------- | -- |
| **Read-only** | No |

### Parameters

| Parameter | Type   | Required | Description                      |
| --------- | ------ | -------- | -------------------------------- |
| `itemId`  | string | Yes      | Item ID or key (e.g. `GEM-123`). |

### Returns

A `CycleItemDto` with the newly created copy's details.

***

## plan\_item

Assign a work item to a board and cycle, optionally assigning a resource.

| Property      |    |
| ------------- | -- |
| **Read-only** | No |

### Parameters

| Parameter      | Type   | Required | Description                                                                 |
| -------------- | ------ | -------- | --------------------------------------------------------------------------- |
| `itemId`       | string | Yes      | Item ID or key.                                                             |
| `boardId`      | string | Yes      | Target board ID. Use [`get_board_cycle`](/mcp-tools/board#get_board_cycle). |
| `cycleId`      | string | Yes      | Target cycle ID. Use [`get_board_cycle`](/mcp-tools/board#get_board_cycle). |
| `resourceId`   | string | No       | User or job role ID to assign.                                              |
| `resourceType` | string | No       | `User` or `JobRole`. Required when `resourceId` is provided.                |

### Returns

A `CycleItemDto` with the updated planning details.

***

## unplan\_item

Remove an item from its board and cycle, clearing all planning fields (board, cycle, resource).

| Property      |    |
| ------------- | -- |
| **Read-only** | No |

### Parameters

| Parameter | Type   | Required | Description     |
| --------- | ------ | -------- | --------------- |
| `itemId`  | string | Yes      | Item ID or key. |

### Returns

A `CycleItemDto` with the cleared planning fields.

***

## get\_items\_by\_resource

Get work items assigned to a specific user, filtered by the current user's visibility permissions. For filtering by multiple criteria, use [`filter_items`](/mcp-tools/container#filter_items) with resource conditions.

| Property      |     |
| ------------- | --- |
| **Read-only** | Yes |

### Parameters

| Parameter       | Type   | Required | Default | Description                                                                       |
| --------------- | ------ | -------- | ------- | --------------------------------------------------------------------------------- |
| `userId`        | string | Yes      | —       | User ID to query items for. Use [`get_user_list`](/mcp-tools/user#get_user_list). |
| `includeClosed` | bool   | No       | `false` | When true, includes closed items.                                                 |

### Returns

A list of `CycleItemDto` objects for items assigned to the specified user.

***

## get\_item\_dependencies

Get the full dependency tree for a work item. Requires View permission on the container and FieldView permission on the dependency field.

| Property      |     |
| ------------- | --- |
| **Read-only** | Yes |

### Parameters

| Parameter | Type   | Required | Description                      |
| --------- | ------ | -------- | -------------------------------- |
| `itemId`  | string | Yes      | Item ID or key (e.g. `GEM-123`). |

### Returns

A list of `CycleItemDto` objects representing the dependency tree, filtered to items the current user can see.

***

## add\_item\_dependency

Add a parent-child dependency between two work items. Both IDs support key format (e.g. `GEM-123`). Requires View permission on both items.

| Property      |    |
| ------------- | -- |
| **Read-only** | No |

### Parameters

| Parameter  | Type   | Required | Description            |
| ---------- | ------ | -------- | ---------------------- |
| `parentId` | string | Yes      | Parent item ID or key. |
| `childId`  | string | Yes      | Child item ID or key.  |

### Returns

A confirmation message showing the created dependency link.

***

## remove\_item\_dependency

Remove a work item from its dependency tree. The item becomes standalone but retains its children. Requires View permission on the item.

| Property      |    |
| ------------- | -- |
| **Read-only** | No |

### Parameters

| Parameter | Type   | Required | Description                      |
| --------- | ------ | -------- | -------------------------------- |
| `itemId`  | string | Yes      | Item ID or key (e.g. `GEM-123`). |

### Returns

A confirmation message with the detached item's key.