Pagination

Most list endpoints in the Truss API return every matching record in a single response. A firm's projects, contacts, and tasks are sized so that this is practical, and it keeps simple integrations simple: one request, one data array.

curl https://app2.gettruss.io/api/v1/contacts \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "data": [
    { "id": 7001, "first_name": "Frodo", "last_name": "Baggins", "..." : "..." },
    { "id": 7002, "first_name": "Samwise", "last_name": "Gamgee", "..." : "..." }
  ]
}

Two collections can grow large enough that they are paginated: entities and drive folders. Their list endpoints accept page parameters and return pagination metadata alongside the data.

Paginated endpoints

Endpoint	Default page size	Maximum
`GET /entities`	500	500
`GET /drive_folders`	100	500, from the values 10, 100, 200, 500

Parameters

page — optional, default is 1
The page to return, counting from 1. Requesting a page past the last one returns 400 with { "error": "Page number is out of range" }.

per_page — optional
The number of records per page. GET /entities accepts any value from 1 to 500. GET /drive_folders accepts exactly 10, 100, 200, or 500, and falls back to 100 for any other value.

curl "https://app2.gettruss.io/api/v1/entities?page=2&per_page=100" \
  -H "Authorization: Bearer YOUR_API_KEY"

Paginated response format

Paginated responses carry a pagy object next to data.

{
  "data": [ "..." ],
  "pagy": {
    "count": 1340,
    "page": 2,
    "items": 100,
    "pages": 14,
    "prev": 1,
    "next": 3
  }
}

count — integer
The total number of records across all pages.

page — integer
The page this response contains.

items — integer
The page size in effect.

pages — integer
The total number of pages.

prev — integer or null
The previous page number, or null on the first page.

next — integer or null
The next page number, or null on the last page. To walk a whole collection, request pages until next is null.

Pages are numbered by position, not by cursor. If records are added or removed while you are paging, a record can appear twice or be skipped. For a one-time import this rarely matters; for ongoing sync, use webhooks to learn about changes as they happen.

Filtering instead of paging

The search endpoints narrow a collection before it is returned, which is usually better than fetching everything and filtering locally.

GET /projects/search filters by name or client details (query), archived, tag, project_status_id, the owning firm_user, and more, with sort and direction.
GET /contacts/search and GET /entities/search filter their collections the same way.
GET /projects?active=true returns only projects that haven't been archived.
GET /projects/list_by_metadata_key returns the projects whose metadata contains an exact key and value, which is the fastest way to find the project that corresponds to a record in your own system.

The full parameter list for each is in the API Reference.