Pagination

All list endpoints in the Patholytix API return paginated results. This guide explains the pagination parameters and response format.

Request parameters

Parameter	Type	Default	Description
pageNumber	integer	1	1-based page number. Page 1 is the first page. Maximum 100 items per page.
pageSize	integer	25	Number of items per page (max 100).
sort	string	varies	Sort field. Valid values are documented per endpoint.
sortDirection	string	ASC	ASC for ascending, DESC for descending.

Response format

All list endpoints return a paging envelope:

{
  "paging": {
    "pageNumber": 1,
    "pageSize": 25,
    "totalItems": 143,
    "links": {
      "next": "/api/v1/studies?pageNumber=2&pageSize=25",
      "prev": null
    }
  },
  "items": [ ... ]
}

Field	Type	Description
paging.pageNumber	integer	The current page (1-based)
paging.pageSize	integer	The page size used for this response
paging.totalItems	integer	Total number of matching items across all pages
paging.links.next	string | null	URL of the next page, or null if this is the last page
paging.links.prev	string | null	URL of the previous page, or null if this is the first page
items	array	The items on this page

Worked example

List studies — first page of 25:

curl "https://api.dev2.patholytix.com/api/v1/studies?pageNumber=1&pageSize=25" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

{
  "paging": {
    "pageNumber": 1,
    "pageSize": 25,
    "totalItems": 60,
    "links": {
      "next": "/api/v1/studies?pageNumber=2&pageSize=25",
      "prev": null
    }
  },
  "items": [
    {
      "studyId": "5cd97ae75fdbf7000143cb30",
      "name": "Phase II Oncology Study"
    }
  ]
}

Get the next page using the next link:

curl "https://api.dev2.patholytix.com/api/v1/studies?pageNumber=2&pageSize=25" \
  -H "Authorization: Bearer YOUR_TOKEN"

Iterating all pages

Use paging.links.next to detect when to stop — it is null on the last page.

import requests

def get_all_studies(token: str) -> list:
    base_url = "https://api.dev2.patholytix.com/api"
    headers = {"Authorization": f"Bearer {token}"}
    page = 1
    page_size = 100
    all_items = []

    while True:
        resp = requests.get(
            f"{base_url}/v1/studies",
            params={"pageNumber": page, "pageSize": page_size},
            headers=headers,
        )
        resp.raise_for_status()
        data = resp.json()

        all_items.extend(data["items"])

        if data["paging"]["links"].get("next") is None:
            break

        page += 1

    return all_items

Sorting

All list endpoints support sorting via sort and sortDirection. Valid sort values differ per endpoint — check the API Reference for the full list.

Studies:

sort value	Description
createdDate	Sort by creation timestamp (default)
studyName	Sort by study name
updatedDate	Sort by last update timestamp

Subjects:

sort value	Description
createdDate	Sort by creation timestamp (default)
name	Sort alphabetically by subject name (SUBJID)
updatedDate	Sort by last update timestamp

Organs:

sort value	Description
createdDate	Sort by creation timestamp (default)
name	Sort alphabetically by organ name (MISPEC)
updatedDate	Sort by last update timestamp

# Most recently updated studies first
curl "https://api.dev2.patholytix.com/api/v1/studies?sort=updatedDate&sortDirection=DESC" \
  -H "Authorization: Bearer YOUR_TOKEN"

Page size limits

The maximum pageSize per request is 100. Requests exceeding this limit will receive a 400 Bad Request response.