Task Items — List & View

Retrieve task items from boards. Supports pagination, group filtering, text search, and status filtering. Item fields are subject to field masking based on the token's visibleTaskFields setting.

GET/api/access/tasks/boards/{boardId}/itemsBearer Token

List Items

List items/tasks within a board. Supports pagination, group filtering, text search, and status filtering.

Required permission: ViewItems

Path Parameters

Parameter	Type	Description
boardId	string	Board ID

Query Parameters

Parameter	Type	Default	Description
provider	string	auto	Provider code
limit	int	50	Max results (1–200)
cursor	string?	—	Cursor for pagination (Monday, Notion, Linear)
page	int?	—	Page number for pagination (Asana, Jira)
groupId	string?	—	Filter to items in a specific group/section
query	string?	—	Text search in item names (case-insensitive)
status	string?	—	Filter by status value

Response 200 OK

{ 
  "provider": "MONDAY", 
  "items": [ 
    { 
      "id": "987654321", 
      "name": "Fix login bug", 
      "status": "Working on it", 
      "assignees": ["John Doe"], 
      "dueDate": "2026-03-15T00:00:00Z", 
      "priority": "High", 
      "labels": ["Bug", "Frontend"], 
      "description": "Users can't log in on mobile", 
      "groupId": "new_group", 
      "groupName": "To Do", 
      "comments": [ 
        { 
          "id": "c123", 
          "body": "Reproduced on iOS 18", 
          "authorName": "Jane Smith", 
          "createdAt": "2026-03-30T14:22:00Z" 
        } 
      ], 
      "subItems": [], 
      "columnValues": [ 
        { 
          "columnId": "numbers0", 
          "columnTitle": "Story Points", 
          "type": "numbers", 
          "text": "5", 
          "value": "{\"value\":5}" 
        } 
      ] 
    } 
  ], 
  "nextCursor": "MSw5ODc2NTQzMjE=", 
  "nextPage": null, 
  "totalCount": 42, 
  "accessInfo": null 
}

Response Fields

Field	Type	Description
provider	string?	Provider code
items	Item[]	List of items (see Item object)
nextCursor	string?	Cursor for next page
nextPage	int?	Page number for next page
totalCount	int?	Total item count (when available from the provider)
accessInfo	string?	Restriction info

Error Responses

Status	Description
403	Board not in token scope
502	Provider error

GET/api/access/tasks/items/{itemId}Bearer Token

Get Item

Get a single item with all fields (subject to field masking).

Required permission: ViewItems

Path Parameters

Parameter	Type	Description
itemId	string	Item ID from the provider

Query Parameters

Parameter	Type	Default	Description
provider	string	auto	Provider code

Response 200 OK

{ 
  "provider": "MONDAY", 
  "item": { 
    "id": "987654321", 
    "name": "Fix login bug", 
    "status": "Working on it", 
    "assignees": ["John Doe"], 
    "dueDate": "2026-03-15T00:00:00Z", 
    "priority": "High", 
    "labels": ["Bug"], 
    "description": "Full description...", 
    "groupId": "new_group", 
    "groupName": "To Do", 
    "comments": [ 
      { 
        "id": "c123", 
        "body": "Reproduced on iOS 18", 
        "authorName": "Jane Smith", 
        "createdAt": "2026-03-30T14:22:00Z" 
      } 
    ], 
    "subItems": [], 
    "columnValues": [ 
      { 
        "columnId": "numbers0", 
        "columnTitle": "Story Points", 
        "type": "numbers", 
        "text": "5", 
        "value": "{\"value\":5}" 
      } 
    ] 
  }, 
  "accessInfo": null 
}

Response Fields

Field	Type	Description
provider	string?	Provider code
item	Item?	Item object (see Item object)
accessInfo	string?	Restriction info

Error Responses

Status	Description
403	Access denied — board not in scope or assignee restricted by access rules
404	Item doesn’t exist
502	Provider error

GET/api/access/tasks/items/{itemId}/commentsBearer Token

List Comments

Read comments on a task item. Complements the POST endpoint for adding comments.

Required permission: ViewComments

Path Parameters

Parameter	Type	Description
itemId	string	Provider item/task ID

Query Parameters

Parameter	Type	Default	Description
provider	string	auto	Provider code. Required when multiple providers are connected.

Response 200 OK

{ 
  "provider": "NOTION", 
  "itemId": "page-uuid-123", 
  "comments": [ 
    { 
      "id": "comment-id-1", 
      "body": "Deployed to staging, waiting for QA.", 
      "authorName": "Alice Chen", 
      "createdAt": "2026-03-28T14:30:00Z" 
    }, 
    { 
      "id": "comment-id-2", 
      "body": "QA passed. Merging to main.", 
      "authorName": "Bob Lee", 
      "createdAt": "2026-03-29T09:15:00Z" 
    } 
  ], 
  "accessInfo": null 
}

Response Fields

Field	Type	Description
provider	string?	Provider code
itemId	string	The item ID that was queried
comments	Comment[]	List of comments (see Comment object)
accessInfo	string?	Restriction info

Note

If comments is not in the token's visibleTaskFields, the endpoint returns an empty array rather than an error.

Error Responses

Status	Description
400	Missing provider when multiple providers are connected
403	Board not in scope, assignee blocked, or view_comments not allowed
404	Item not found at the provider
422	Task management not enabled, or no provider connected
502	Provider API error

Comment Limits by Provider

Comments come from the provider's single-item fetch. Approximate limits:

Provider	Limit	Notes
Monday.com	~10	“Updates” in Monday terminology
Asana	~25	Filtered to type “comment” (excludes system stories)
Jira Cloud	All	Included in issue response
Linear	All	GraphQL comments nodes
Notion	~100	Separate API call, graceful 403 if integration lacks comment permission

GET/api/access/tasks/items/searchBearer Token

Search Items

Search task items across all accessible boards. Returns results with board context.

Required permission: ViewItems

Query Parameters

Parameter	Type	Default	Description
query	string	—	Search text (max 500 chars). Searches item titles. Required.
provider	string	auto	Provider code. Required when multiple providers are connected.
limit	int	100	Max results across all boards (1–200)
boardIds	string?	all in scope	Comma-separated board IDs to narrow search

Response 200 OK

{ 
  "provider": "NOTION", 
  "query": "dark mode", 
  "results": [ 
    { 
      "boardId": "db-uuid-roadmap", 
      "boardName": "Product Roadmap", 
      "item": { 
        "id": "page-uuid-1", 
        "name": "Implement dark mode toggle", 
        "status": "In Progress", 
        "assignees": ["Alice Chen"], 
        "dueDate": "2026-04-01T00:00:00Z", 
        "priority": "High", 
        "labels": ["frontend"], 
        "description": "Add dark mode...", 
        "groupId": "Status|status|In Progress", 
        "groupName": "In Progress" 
      } 
    }, 
    { 
      "boardId": "db-uuid-bugs", 
      "boardName": "Bug Tracker", 
      "item": { 
        "id": "page-uuid-2", 
        "name": "Dark mode breaks sidebar nav", 
        "status": "To Do", 
        "assignees": ["Bob Lee"], 
        "priority": "Critical" 
      } 
    } 
  ], 
  "totalResults": 7, 
  "boardsSearched": 4, 
  "accessInfo": "ops: view_boards, view_items" 
}

Response Fields

Field	Type	Description
provider	string?	Provider code
query	string	The search text that was used
results	SearchResult[]	Array of matched items with board context (see below)
totalResults	int	Total matches found before the limit cap
boardsSearched	int	Number of boards queried — helps gauge search breadth
accessInfo	string?	Restriction info

Search Result Object

Field	Type	Description
boardId	string	Which board this item belongs to
boardName	string?	Board display name (may be null if not set during scope configuration)
item	Item	Standard Item object \u2014 same shape as GET /boards/{boardId}/items responses

Warning

If boardIds includes boards not in the token's scope, they are silently excluded \u2014 no error is returned. Zero boards configured returns 200 with empty results and an explanatory accessInfo message.

Tip

Search text is passed to the provider as-is. Each provider handles search differently (Notion uses title-contains filter, Jira uses JQL text search, Monday uses native search, etc.). Results may vary by provider.

Error Responses

Status	Description
400	Missing query, query exceeds 500 chars, or missing provider when multiple connected
403	view_items not allowed on token
422	Task management not enabled, or no provider connected
502	All board searches failed

Data Types

Item Object

All fields except id, groupId, and groupName are subject to field masking based on the token's visibleTaskFields setting. Masked fields are returned as null.

Field	Type	Masked By	Description
id	string	never	Item ID from the provider
name	string?	Name	Item title
status	string?	Status	Status label text
assignees	string[]?	Assignee	Display names of assigned people
dueDate	datetime?	DueDate	Due date in UTC
priority	string?	Priority	Priority label text
labels	string[]?	Labels	Tags/labels on the item
description	string?	Description	Item description/notes
groupId	string?	never	Group this item belongs to
groupName	string?	never	Group display name
comments	Comment[]?	Comments	Item comments (see Comment object)
subItems	Item[]?	SubItems	Nested sub-items (same schema, recursive)
columnValues	ColumnValue[]?	ColumnValues	Provider-specific column data (see ColumnValue object)

Comment Object

Field	Type	Description
id	string	Comment ID
body	string?	Comment text
authorName	string?	Author’s display name
createdAt	datetime?	When the comment was posted (UTC)

ColumnValue Object

Provider-specific column data not covered by the standard Item fields.

Field	Type	Description
columnId	string	Column ID (matches Column.id from the board)
columnTitle	string	Column display name
type	string	Column type
text	string?	Human-readable text representation
value	string?	Raw provider JSON value (for programmatic use)

Field Visibility

The token's visibleTaskFields setting controls which Item fields are returned. Fields not in the mask are returned as null. The id, groupId, and groupName fields are structural and always included.

Flag	API String	Item Field Affected
Name	`name`	name
Status	`status`	status
Assignee	`assignee`	assignees
DueDate	`due_date`	dueDate
Priority	`priority`	priority
Labels	`labels`	labels
Description	`description`	description
Comments	`comments`	comments
SubItems	`sub_items`	subItems
ColumnValues	`column_values`	columnValues
All	`all`	All fields visible