> ## Documentation Index
> Fetch the complete documentation index at: https://docs.katilyst.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> How to authenticate and make requests against the Katilyst Public API.

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`:

```bash theme={null}
Authorization: API-Key katilyst_oMeofDAJ_thisisanexamplekey
```

> [!WARNING]
>
> 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.

```bash theme={null}
curl https://api.katilyst.com/v1/projects \
  --header "Authorization: API-Key your_key_here"
```

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](https://docs.katilyst.com/core-concepts.md) 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.

| Parameter | Meaning |
| - | - |
| `limit` | How many records to return per page. |
| `start` | A zero-based record offset. |

`start` counts records rather than pages. With a `limit` of 25, successive pages begin at `0`, `25`, `50`, and so on.

```text theme={null}
GET /v1/projects?limit=25&start=0    → records 1–25
GET /v1/projects?limit=25&start=25   → records 26–50
GET /v1/projects?limit=25&start=50   → records 51–75
```

Every paged response carries the parameters it used, the total, and links:

```json theme={null}
{
  "start": 0,
  "limit": 25,
  "count": 312,
  "links": {
    "next": "https://api.katilyst.com/v1/projects?limit=25&start=25"
  },
  "projects": [ ... ]
}
```

`count` is the total number of matching records across all pages, not the number returned in this one.

### Follow the links

`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.

> [!NOTE]
>
> 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:

```bash theme={null}
curl "https://api.katilyst.com/v1/projects/{projectId}/logged-actions?maxDateApplied=2026-10-07T00:00:00Z&limit=25&start=0" \
  --header "Authorization: API-Key your_key_here"
```

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.

```text theme={null}
2026-10-07T14:32:10Z          valid
2026-10-07T10:32:10-04:00     valid
2026-10-07T14:32:10           rejected
```

## 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.