Pagination

The lists of a workspace, such as its invoices or its bank transactions, return one page at a time. A page holds up to limit items: 20 by default, 100 at most.

Read every page

A list answers with its items in data, the limit of the request, and a nextCursor when the page is full. Send that cursor back as startAfter to get the next page, and stop at a page without nextCursor:

async function listAllInvoices(workspaceId) {
const url = new URL(process.env.SWAY_API + '/workspaces/' + workspaceId + '/invoices');
const headers = {Authorization: 'Bearer ' + process.env.SWAY_API_KEY};
url.searchParams.set('limit', '100');
const invoices = [];
while (true) {
  const response = await fetch(url, {headers});
  if (!response.ok) throw new Error('Sway API answered ' + response.status);
  const page = await response.json();
  invoices.push(...page.data);
  if (!page.nextCursor) return invoices;
  url.searchParams.set('startAfter', page.nextCursor);
}
}

import os
import requests

def list_all_invoices(workspace_id):
url = os.environ["SWAY_API"] + "/workspaces/" + workspace_id + "/invoices"
headers = {"Authorization": "Bearer " + os.environ["SWAY_API_KEY"]}
params = {"limit": 100}
invoices = []
while True:
response = requests.get(url, headers=headers, params=params)
response.raise_for_status()
page = response.json()
invoices.extend(page["data"])
if "nextCursor" not in page:
return invoices
params["startAfter"] = page["nextCursor"]

• A full last page still carries a nextCursor, and the page that it points to is empty, so the loop ends one request later.
• The cursor is opaque: send it back as it came. It holds the sort value and the ID of the last item, so items with equal values still come back in a stable order.
• A malformed cursor gets 400 invalid-argument. A missing or invalid limit falls back to 20, and a larger one to 100.

Fetch items by their IDs

?ids= takes up to 30 comma-separated IDs and returns those items in one call, such as ?ids=Hk2xNq8vR4tYw6ZbPj3c,Rm5tB8wQ2zLx7nVc4pKs. It ignores limit, startAfter and the filters.

Keep only some fields

?fields= keeps only the properties that it names in the answer, or in each item of a list; a dot reaches a nested property. ?fields=firestoreId,invoiceStatus,totalAmount.amount returns three properties of each invoice. Every endpoint takes it.

Search results

The five search endpoints page by number instead: bank transactions, counterparties, invoices, draft payments and workspace files.

• page counts from 0, and size takes 1 to 100 items, 20 by default.
• The answer holds data only, with no cursor and no total: ask for the next page until one comes back with fewer than size items.

Workspaces

GET /workspaces returns every workspace of the key’s user in one answer, with no page and no limit.