Pagination and filtering

List endpoints answer one page of results at a time. Each list takes one of four sets of paging parameters, and many take filters as well. The API reference gives the parameters of every route. This page lists the conventions, the page sizes of the main lists, and how to read a total.

page starts at 1, and page n skips the first (n - 1) × limit results (or (n - 1) × per_page). A page past the last one answers an empty list.

Lists come newest first unless the tables below say otherwise. Invoices, transactions, customers and Commerce orders break a tie on the ID, so while nothing changes, every row appears on exactly one page. On a list sorted newest first, a row added while you page pushes the others down by one, and the next page then starts with the last row of the page before. Skip IDs you already hold.

Leave out limit or per_page to get the default. On most lists, a value above the largest size, or below 1, answers 422, and the entry in detail names the parameter and the largest size:

{
  "detail": [
    {
      "type": "less_than_equal",
      "loc": ["query", "limit"],
      "msg": "Input should be less than or equal to 200",
      "input": "500",
      "ctx": {"le": 200}
    }
  ]
}

GET /billing/crypto/deposits takes limit alone (50 by default, at most 200) and answers the newest deposits, with no way to ask for older ones.

Where the table says cut down, a larger limit does not fail: the list answers 500 results instead.

Store products come newest first by default. order changes that: -created_at, created_at, -title or title.

Most lists answer a bare JSON array with no total. Those below say how many results match.

total and count are the number of results the filters match, across every page. counts gives the number for each status or type as if no status or type filter were set, with all for the whole list. Invoices add open, which is unpaid and overdue together, and Client API transactions add credit, which is credit added and credit used together. Organization invoices also carry outstanding: what the open invoices owe, for each currency.

A filter narrows the list before it is cut into pages, so total and every page reflect it. A filter the route does not know is ignored.

resource_type, type_filter, priority and the Client API's status_filter answer 422 for a word they do not list. The other filters match nothing when no result has the value you send. The reference for each route lists the rest of its filters.

Ask for pages until one holds fewer results than you asked for, or until you have total results. This reads every service, 100 at a time:

offset=0
while :; do
  page=$(curl -s "https://api.coritan.com/api/v1/services/?limit=100&offset=$offset" \
    -H "Authorization: Bearer $CORITAN_TOKEN")
  echo "$page" | jq -c '.[]'
  [ "$(echo "$page" | jq length)" -lt 100 ] && break
  offset=$((offset + 100))
done

On a list that uses before_id, stop when next_before_id is null.

Messages in a support conversation page by ID rather than by position:

No parameters

The latest limit messages, oldest first.

before_id

The latest limit messages older than that message ID, oldest first. Send the ID of the first message you hold to read further back.

after_id

Up to limit messages newer than that message ID, oldest first. Send the ID of the last message you hold to fetch only what is new.

Internal notes from Coritan's team never appear in the list. Poll no more often than you need to: Rate limits applies to every request.

When you poll GET /orgs/{org_slug}/portal/services for changes, add consistency=eventual. The answer may miss a change made a moment ago, so leave it out on the first read after a change of your own.