Skip to main content
The Katilyst Public API is a REST API served at https://api.katilyst.com/v1. Every endpoint returns JSON.

​
API keys

To use the Katilyst Public API, you need an API key. API keys are issued per account and have access to all information and operations within that account that are available through the public API. Treat a key the way you would treat the password to a powerful account. Send your key in the Authorization header of every request, prefixed with API-Key:
Keys are shown once when generated. The secret portion is stored only as a hash, so a lost key cannot be recovered. Generate a new one instead.

​
Your first call

Listing your Projects is the simplest way to confirm a key works, and you need a projectId for almost everything else.
A 401 means the key is invalid, missing, or sent without the API-Key prefix on the header value. Once you have a projectId, Core concepts explains what the objects are and how Katilyst decides what an event is worth.

​
Paging

GET endpoints that return arrays page automatically. Two optional query parameters control it. start counts records rather than pages. With a limit of 25, successive pages begin at 0, 25, 50, and so on.
Every paged response carries the parameters it used, the total, and links:
count is the total number of matching records across all pages, not the number returned in this one. links.next and links.prev are absolute URLs, callable as they are with the same Authorization header. Following them is the recommended way to page, since it keeps your code correct if the offset behavior or default page size ever changes.
A link is absent from the response entirely when there is no page in that direction. The last page has no next, and the first page has no prev. Check for the key’s presence rather than testing it against null.

​
Results that change while you page

Any paginated API reading live data can return a shifted result set if records are created or modified between requests, and Katilyst is no exception. A record added partway through a loop can push others onto a page you have already read. For logged actions, pin the window using maxDateApplied so that records created after you started are excluded from every page:
This matters most for scheduled jobs that walk a large collection. A nightly export running against a busy program should fix its upper bound before the first request rather than between pages.

​
Filters

The filter parameters on an endpoint — status, the date ranges, availableActionId — apply before paging. count reflects the filtered total, and paging walks the filtered set.

​
Timestamps

For POST and PUT inputs that take timestamps, the value must be a string in ISO 8601 format carrying a Z to designate UTC or an explicit timezone offset.

​
Versioning

The current version is v1. Versions remain backward compatible within themselves. Breaking changes appear in a new version, and versions run concurrently so you can migrate on your own schedule.