List Records - Blue API

POST /v1/list-records

List records (tasks/items) with filtering and pagination. Can filter by workspace, list, status, assignees, tags, or due date (window, presence, or overdue). Returns a summary view — use get-record for full details including checklists and custom fields.

Request body

Field	Type	Required	Description
`workspaceId`	string	No	Filter by workspace ID. If omitted, lists across all workspaces.
`listId`	string	No	Filter by list ID
`done`	boolean	No	Filter by completion status
`archived`	boolean	No	Filter by archived status
`assigneeIds`	string[]	No	Filter by assignee user IDs
`tagIds`	string[]	No	Filter by tag IDs
`search`	string	No	Search by title
`dueStart`	string	No	Due-date window start (ISO date or datetime). Must be sent together with dueEnd. Matches records whose start/due span overlaps the window.
`dueEnd`	string	No	Due-date window end (ISO date or datetime). Must be sent together with dueStart.
`hasDueDate`	boolean	No	true → only records that have a due date; false → only records without one.
`overdue`	boolean	No	true → only records whose due date is in the past (all-day dates count once their day has ended). Combine with done:false for actionable overdue work.
`skip`	number	No	Offset for pagination (default: 0)
`limit`	number	No	Number of results, max 100 (default: 50)

{
  "workspaceId": "string",
  "listId": "string",
  "done": true,
  "archived": true,
  "assigneeIds": [
    "string"
  ],
  "tagIds": [
    "string"
  ],
  "search": "string",
  "dueStart": "string",
  "dueEnd": "string",
  "hasDueDate": true,
  "overdue": true,
  "skip": 0,
  "limit": 0
}

Response

{
  "items": [
    {
      "id": "string",
      "uid": "string",
      "title": "string",
      "done": true,
      "archived": true,
      "rank": "string",
      "startedAt": "2024-01-01T00:00:00Z",
      "duedAt": "2024-01-01T00:00:00Z",
      "dueDateGranularity": "ALL_DAY",
      "color": "string",
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-01T00:00:00Z",
      "list": {
        "id": "string",
        "title": "string"
      },
      "users": [
        {
          "id": "string",
          "firstName": "string",
          "lastName": "string",
          "email": "string"
        }
      ],
      "tags": [
        {
          "id": "string",
          "title": "string",
          "color": "string"
        }
      ]
    }
  ],
  "pageInfo": {
    "hasNextPage": true,
    "hasPreviousPage": true,
    "startCursor": "string",
    "endCursor": "string"
  }
}

Example

curl -X POST https://rest.blue.app/v1/list-records \
  -H "Authorization: Bearer $BLUE_TOKEN" \
  -H "blue-org-id: $BLUE_ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{"workspaceId":"string","listId":"string","done":true,"archived":true,"assigneeIds":["string"],"tagIds":["string"],"search":"string","dueStart":"string","dueEnd":"string","hasDueDate":true,"overdue":true,"skip":0,"limit":0}'