Items API

The items API is the most commonly used part of the ProBeya API. It lets you manage items (tasks, tickets, records) on boards.

Procedures

item.list

List items on a board with optional filtering, sorting, and pagination.

Type: Query Required scope: read:board

GET /trpc/item.list?input={"boardId":"brd_abc123","limit":50}

Input parameters:

Parameter	Type	Required	Description
boardId	string	Yes	The board to list items from
groupId	string	No	Filter to a specific group
filter	object	No	Filter criteria (see below)
sort	array	No	Sort rules
cursor	string	No	Pagination cursor
limit	number	No	Max items per page (default: 50, max: 200)

Filter example:

{
  "boardId": "brd_abc123",
  "filter": {
    "status": { "eq": "in_progress" },
    "assignee": { "eq": "usr_abc123" },
    "dueDate": { "lte": "2026-03-31" }
  },
  "sort": [
    { "field": "priority", "direction": "desc" },
    { "field": "createdAt", "direction": "asc" }
  ]
}

Response:

{
  "result": {
    "data": {
      "items": [
        {
          "id": "itm_abc123",
          "title": "Implement user auth",
          "boardId": "brd_abc123",
          "groupId": "grp_abc123",
          "position": 0,
          "fields": {
            "status": "in_progress",
            "priority": "high",
            "assignee": "usr_abc123",
            "dueDate": "2026-03-25",
            "tags": ["backend", "auth"]
          },
          "createdBy": "usr_def456",
          "createdAt": "2026-03-01T10:00:00Z",
          "updatedAt": "2026-03-18T14:30:00Z"
        }
      ],
      "nextCursor": "itm_def456"
    }
  }
}

item.byId

Get a specific item by ID, including all field values and sub-items.

Type: Query Required scope: read:board

GET /trpc/item.byId?input={"id":"itm_abc123"}

item.create

Create a new item on a board.

Type: Mutation Required scope: write:board

POST /trpc/item.create

Input:

{
  "boardId": "brd_abc123",
  "groupId": "grp_abc123",
  "title": "New feature request",
  "description": "Detailed description in **markdown**",
  "fields": {
    "status": "todo",
    "priority": "medium",
    "assignee": "usr_abc123",
    "dueDate": "2026-04-01",
    "tags": ["feature"]
  }
}

item.update

Update an item's title, description, or field values.

Type: Mutation Required scope: write:board

POST /trpc/item.update

Input:

{
  "id": "itm_abc123",
  "title": "Updated title",
  "fields": {
    "status": "done",
    "priority": "low"
  }
}

Only the fields included in the fields object are updated. Omitted fields retain their current values.

item.delete

Delete an item (moves to trash, recoverable for 30 days).

Type: Mutation Required scope: write:board

POST /trpc/item.delete

Input:

{
  "id": "itm_abc123"
}

item.move

Move an item to a different group, board, or position.

Type: Mutation Required scope: write:board

POST /trpc/item.move

Input:

{
  "id": "itm_abc123",
  "targetGroupId": "grp_def456",
  "targetBoardId": "brd_xyz789",
  "position": 0
}

item.duplicate

Create a copy of an item.

Type: Mutation Required scope: write:board

POST /trpc/item.duplicate

Input:

{
  "id": "itm_abc123",
  "includeComments": false,
  "includeSubItems": true
}