​
Overview

All list endpoints in the ProBeya REST API support query parameter-based filtering and sorting. Combine multiple filters to narrow results precisely, and apply sort orders to control how records are returned.

Filtering and sorting work alongside cursor-based pagination — filters are applied server-side before pagination, so page sizes reflect filtered counts.

​
Filtering

​
Basic Filters

Pass field names as query parameters with the desired value. Only records matching all specified filters are returned (AND logic):

# Get only high-priority open items
curl "https://acme.probeya.com/api/v1/items?boardId=brd_clx9xyz789&status=open&priority=high" \
  -H "Authorization: Bearer probeya_sk_live_abc123..."

​
Multiple Values (OR within a Field)

Pass comma-separated values to match any of them (OR logic within a single field):

# Items that are either open OR in_progress
curl "https://acme.probeya.com/api/v1/items?boardId=brd_clx9xyz789&status=open,in_progress" \
  -H "Authorization: Bearer probeya_sk_live_abc123..."

​
Supported Filter Operators

For fields that support operator syntax, use bracket notation:

OperatorSyntaxDescriptionExample
Equalfield=valueExact match (default)status=open
Not equalfield[ne]=valueExclude matching recordsstatus[ne]=done
Greater thanfield[gt]=valueStrictly greater thancreatedAt[gt]=2026-03-01
Greater or equalfield[gte]=valueGreater than or equalpriority[gte]=high
Less thanfield[lt]=valueStrictly less thandueDate[lt]=2026-04-01
Less or equalfield[lte]=valueLess than or equalupdatedAt[lte]=2026-03-31
Containsfield[contains]=valueSubstring match (case-insensitive)name[contains]=audit
Is nullfield[is]=nullField has no valueassigneeId[is]=null
Is not nullfield[is]=not_nullField has a valuedueDate[is]=not_null

​
Date Range Filters

Filter by date ranges using [gt], [gte], [lt], [lte] operators with ISO 8601 date strings:

# Items created in March 2026
curl "https://acme.probeya.com/api/v1/items?boardId=brd_clx9xyz789&createdAt[gte]=2026-03-01T00:00:00Z&createdAt[lt]=2026-04-01T00:00:00Z" \
  -H "Authorization: Bearer probeya_sk_live_abc123..."

​
Filtering by Assignee

# Items assigned to a specific user
curl "https://acme.probeya.com/api/v1/items?boardId=brd_clx9xyz789&assigneeId=usr_clx9def456" \
  -H "Authorization: Bearer probeya_sk_live_abc123..."

# Unassigned items
curl "https://acme.probeya.com/api/v1/items?boardId=brd_clx9xyz789&assigneeId[is]=null" \
  -H "Authorization: Bearer probeya_sk_live_abc123..."

​
Sorting

​
Basic Sort

Use the sort query parameter with the format field:direction where direction is asc (ascending) or desc (descending):

# Most recently created items first
curl "https://acme.probeya.com/api/v1/items?boardId=brd_clx9xyz789&sort=createdAt:desc" \
  -H "Authorization: Bearer probeya_sk_live_abc123..."

​
Multi-Field Sort

Pass multiple sort clauses separated by commas. Records are sorted by the first field, then by the second field for ties, and so on:

# Sort by priority (high first), then by due date (earliest first)
curl "https://acme.probeya.com/api/v1/items?boardId=brd_clx9xyz789&sort=priority:desc,dueDate:asc" \
  -H "Authorization: Bearer probeya_sk_live_abc123..."

​
Default Sort Order

If no sort parameter is provided, list endpoints default to createdAt:desc (newest first).

​
Sortable Fields

Not every field supports sorting. Common sortable fields across endpoints:

EndpointSortable Fields
/itemsname, status, priority, createdAt, updatedAt, dueDate
/actionstitle, status, priority, createdAt, dueDate, escalationLevel
/kpisname, category, createdAt, updatedAt
/projectsname, createdAt, updatedAt
/workspacesname, level, createdAt

​
Combining Filters, Sort, and Pagination

Filters, sorting, and pagination compose naturally. Apply them all in a single request:

# High-priority open items, sorted by due date, page 2 of 25 per page
curl "https://acme.probeya.com/api/v1/items?\
boardId=brd_clx9xyz789&\
status=open&\
priority=high&\
sort=dueDate:asc&\
limit=25&\
cursor=itm_clx9abc025" \
  -H "Authorization: Bearer probeya_sk_live_abc123..."

Response:

{
  "data": [
    {
      "id": "itm_clx9abc026",
      "name": "Calibrate pH meter — Lab 3",
      "status": "open",
      "priority": "high",
      "dueDate": "2026-04-05T00:00:00.000Z"
    },
    {
      "id": "itm_clx9abc027",
      "name": "Validate cleaning procedure CL-07",
      "status": "open",
      "priority": "high",
      "dueDate": "2026-04-08T00:00:00.000Z"
    }
  ],
  "meta": {
    "cursor": "itm_clx9abc027",
    "has_more": true,
    "limit": 25
  }
}

​
Full Example: JavaScript Client

/**
 * Fetch items with filters, sorting, and automatic pagination.
 * Demonstrates composing all query parameter features together.
 */
async function fetchFilteredItems({
  boardId,
  status,
  priority,
  sort = "createdAt:desc",
  limit = 50,
}) {
  const allItems = [];
  let cursor = undefined;

  do {
    const params = new URLSearchParams({
      boardId,
      sort,
      limit: String(limit),
    });

    // Only add optional filters when provided
    if (status) params.set("status", status);
    if (priority) params.set("priority", priority);
    if (cursor) params.set("cursor", cursor);

    const response = await fetch(
      `https://acme.probeya.com/api/v1/items?${params}`,
      {
        headers: {
          Authorization: `Bearer ${process.env.PROBEYA_API_KEY}`,
        },
      }
    );

    if (!response.ok) {
      const error = await response.json();
      throw new Error(`API error: ${error.error.message}`);
    }

    const body = await response.json();
    allItems.push(...body.data);
    cursor = body.meta.cursor;
  } while (cursor);

  return allItems;
}

// Usage
const criticalOpenItems = await fetchFilteredItems({
  boardId: "brd_clx9xyz789",
  status: "open",
  priority: "critical",
  sort: "dueDate:asc",
});

​
Errors

HTTP StatusError CodeCause
400BAD_REQUESTUnknown filter field name
400BAD_REQUESTInvalid sort direction (must be asc or desc)
400BAD_REQUESTSort field does not support sorting
400BAD_REQUESTInvalid operator for the given field type

Was this page helpful?

ErrorsOrganizations