Items carry a dynamic set of fields controlled by their process and container permissions. To understand the field model, available field types, and how to discover which fields you can set, see Items and fields.
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 ascope 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. |
processId | string | Yes | — | Process ID. Use 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
AnItemScreenDto containing:
stage— the requested stage (createorupdate)fields— list ofItemScreenFieldDto:
| 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 withstatusId,statusValue, andphase
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
ACycleItemDto 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.), usefilter_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. |
Returns
A list ofItemMatch objects, each containing:
itemId,itemName,itemSequence— item identitycontainerId,containerName,containerCode— container context
create_item
Create a new work item in the specified container with a given process type. Callget_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.
| Property | |
|---|---|
| Read-only | No |
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
containerId | string | Yes | Container to create the item in. Use get_containers to find IDs. |
processId | string | Yes | Process type for the item. Use get_container_process_list to find IDs. |
fieldsJson | string | No | Required field values as JSON: [{"fieldId":"<id>","value":"<value>"}]. Use get_item_screen to discover field IDs and required flags. Only required fields are needed — optional fields can be set later. |
Returns
ACycleItemDto 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 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 to discover field IDs and valid values. |
Returns
ACycleItemDto 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
ACycleItemDto 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. |
cycleId | string | Yes | Target cycle ID. Use 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
ACycleItemDto 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
ACycleItemDto 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, usefilter_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. |
includeClosed | bool | No | false | When true, includes closed items. |
Returns
A list ofCycleItemDto 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 ofCycleItemDto 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). |