Conventions
Pagination, filtering, sorting, and date formats used across every endpoint.
The API is designed to be predictable: once you have used one endpoint, you have used them all. The conventions on this page apply everywhere.
Pagination
Collections paginate using opaque cursors. A list response looks like:
To fetch the next page, pass the cursor back as the cursor query parameter:
When next_cursor is absent or null, there are no more pages. Cursors are opaque: do not parse them, and do not construct them yourself. Treat them as a bookmark.
See Pagination for details.
Filtering
Filters are passed as query parameters. Available filters are documented per endpoint. Unknown query parameters are ignored rather than rejected, so adding a filter in a future version of the API does not break older clients.
Sorting
Where endpoints support sorting, the sort order is stable within a cursor: you will not see the same resource twice even if new data is written between pages. If no sort is specified, endpoints return results in the order that is most useful for their specific data (most recent first for scans, citation volume descending for cited pages, and so on).
Date and time
All timestamps are ISO 8601 in UTC with second precision, for example:
SurfacedBy never returns naive datetimes. When you pass a date in a query parameter, use the same format and the same timezone.
Field naming
Fields in request and response bodies are lowercase snake_case. Enumerated values are also lowercase snake_case. This holds across every endpoint.
Unknown fields
Clients should ignore fields they do not recognise. SurfacedBy may add new optional fields to responses within v1, and existing integrations must tolerate them.
Content types
Requests and responses are application/json. Error responses use application/problem+json per RFC 7807. Webhook deliveries are also JSON. See Errors for the problem+json structure.