Pagination

Most list operations in the Blue REST API page with two arguments: skip (an offset) and limit (a page size). They behave the same whether you call the operation RPC-style in the request body or resource-style as query parameters.

Omit both to get the first 50 records. Pass limit up to 100 to fetch larger pages; values above 100 are silently capped at 100 (a larger value is not an error). Advance through the result set by increasing skip by your page size on each call.

Response shape

List responses are the operation’s raw data - they do not wrap results in a generic envelope and do not echo skip/limit back. The exact shape is per-operation (see each reference page), but most list operations return an items array alongside a pagination object:

{
  "items": [{ "id": "clm4n8qwx000008l0g4oxdqn7", "title": "Draft launch plan" }],
  "pageInfo": {
    "hasNextPage": true,
    "hasPreviousPage": false,
    "startCursor": "...",
    "endCursor": "..."
  }
}

Some operations name the array differently or carry a count instead of pageInfo - for example list-workspaces returns { "items": [...], "totalCount": 42 } and list-users returns { "users": [...], "totalCount": 42 }. Check the operation’s reference page for its precise keys.

First page

The defaults return the first 50 records, so the smallest list call just names the workspace:

curl https://rest.blue.app/v1/list-records \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_PERSONAL_ACCESS_TOKEN" \
  -H "x-bloo-company-id: YOUR_COMPANY_ID" \
  -d '{ "workspaceId": "WORKSPACE_ID" }'

pageInfo.hasNextPage tells you whether another page is waiting, so you always know when you’ve reached the end of the set.

Fetching a specific page

To fetch the second page of 100, skip the first 100 and request 100 more:

curl https://rest.blue.app/v1/list-records \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_PERSONAL_ACCESS_TOKEN" \
  -H "x-bloo-company-id: YOUR_COMPANY_ID" \
  -d '{
    "workspaceId": "WORKSPACE_ID",
    "skip": 100,
    "limit": 100
  }'

Resource-style, the same page is query parameters:

curl "https://rest.blue.app/v1/records?workspaceId=WORKSPACE_ID&skip=100&limit=100" \
  -H "Authorization: Bearer YOUR_PERSONAL_ACCESS_TOKEN" \
  -H "x-bloo-company-id: YOUR_COMPANY_ID"

Paging through every record

Page size is capped at 100, so reading a large workspace means looping: request a page, process its items, then advance skip by limit. Stop when pageInfo.hasNextPage is false (equivalently, when a page comes back with fewer than limit items).

import requests

url = "https://rest.blue.app/v1/list-records"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_PERSONAL_ACCESS_TOKEN",
    "x-bloo-company-id": "YOUR_COMPANY_ID",
}

skip, limit = 0, 100
all_records = []

while True:
    body = {"workspaceId": "WORKSPACE_ID", "skip": skip, "limit": limit}
    data = requests.post(url, json=body, headers=headers).json()
    all_records.extend(data["items"])
    if not data["pageInfo"]["hasNextPage"]:
        break  # last page
    skip += limit

print(f"fetched {len(all_records)} records")

const url = 'https://rest.blue.app/v1/list-records'
const headers = {
  'Content-Type': 'application/json',
  Authorization: 'Bearer YOUR_PERSONAL_ACCESS_TOKEN',
  'x-bloo-company-id': 'YOUR_COMPANY_ID',
}

const limit = 100
let skip = 0
const all = []

while (true) {
  const body = JSON.stringify({ workspaceId: 'WORKSPACE_ID', skip, limit })
  const res = await fetch(url, { method: 'POST', headers, body })
  const { items, pageInfo } = await res.json()
  all.push(...items)
  if (!pageInfo.hasNextPage) break // last page
  skip += limit
}

console.log(`fetched ${all.length} records`)

Related

• Making Requests
• Errors & Rate Limits