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

# Core concepts

> Projects, Users, Actions, and how Katilyst decides what an event is worth.

Eight objects make up the Katilyst platform. Your integration touches three of them directly, and the other five decide what happens when it does.

> [!NOTE]
>
> Only one of these is something your integration creates. Everything else is either configured in Katilyst beforehand or happens as a consequence.

## Project

A single program, or a track within one. "Developer Champions" and "Security Awareness Champions" might be separate Projects in the same account.

Projects are how you segment participants by focus area or maturity. Every action you log lands in a Project and is evaluated against that Project's configuration.

## User

The people whose contributions you care about: Security Champions, program managers, stakeholders, and optionally other developers you want to benchmark against.

In API payloads a User is identified by email address. Most GET endpoints address them by `userId` instead, which you can look up with [List a project's users](https://docs.katilyst.com/api-reference/v1/list-a-projects-users.md).

## Attribute

A configurable data element representing progress, status, or relationship. Katilyst supports three types:

| Type | Example |
| - | - |
| Whole number | Points, vulnerabilities found |
| Value list | Apprentice → Advocate → Ambassador |
| Connection | Mentor to mentee |

Attributes are never set directly through the API. They change as a consequence of actions you log.

## Available Action

An activity your team has configured that a User can complete — "Resolve a vulnerability in JIRA," "Complete secure code training."

Each one carries its own business logic: which Attribute it changes, by how much, under what conditions, and how often it can be claimed. Available Actions come in two kinds, and the distinction decides which endpoint you call.

> **Instance**
>
> Awards its Attribute change every time it is logged. Closing a vulnerability ticket is an instance action.
>
> Logged with [`POST /v1/logged-actions`](https://docs.katilyst.com/api-reference/v1/log-an-action).

> **State**
>
> Switched on or off for a User, holding its credit until switched off. Annual training completion is a state action — enable it when they finish, disable it when the certification lapses.
>
> Driven with [`PUT .../action-states`](https://docs.katilyst.com/api-reference/v1/set-a-users-action-states).

> [!WARNING]
>
> A webhook fires on completion and never fires on expiry. If a State action tracks something that lapses, such as a certification, you need a scheduled job that reconciles against [Get a user's action states](https://docs.katilyst.com/api-reference/v1/get-a-users-action-states.md) rather than an event listener alone.

## Logged Action

What an Available Action becomes once it has been registered for a specific User.

The Logged Action carries the outcome: which Attribute changed, by what operator and amount, the resulting value, and the status Katilyst assigned. This is the object you read back when you want to know what actually happened to an event you sent.

## Reward

The outcome of an eligible action — points awarded, a badge earned, a level advanced. Rewards are defined in your Project configuration rather than in your API call.

## Guardrails and limits

The rules controlling when and how often an action can be rewarded: admin approval requirements, time-based expiration, conditional availability, and maximum frequency.

Actions logged through the API are treated as admin-driven, which changes which of these apply to your integration.

| Guardrail | Logged through the API |
| - | - |
| Eligibility conditions | Enforced. A User who does not meet them gets a `409`, and nothing is created. |
| Approval requirements | Enforced. The Logged Action is created with a `status` of `PENDING` until an admin approves it. |
| Frequency limits | **Overridden.** The action is logged regardless of how recently that User last earned it. |

> [!WARNING]
>
> Because frequency limits do not constrain API calls, rate limiting an integration is your responsibility rather than Katilyst's. A bulk ticket close, a replayed automation, or a misconfigured rule logs every event it fires, and a champion can collect a month of rewards in an afternoon.
>
> Put the constraint in the conditions on your side — the trigger, the filter, the `if` statement — rather than relying on the limit configured on the Available Action.

Reading actions back, you may still see a `status` of `LIMIT_EXCEEDED_TIMEFRAME`. Those are actions people submitted inside the platform, where frequency limits do apply. They did not come from your integration.

## Recognition

Slack and Teams shout-outs come from the Katilyst rules engine rather than from the API. Your call may trigger an action; whether that action produces a public celebration depends on the Rules you have defined in the platform.

## Where each concept lives

| Concept | Where it comes from | What your integration does with it |
| - | - | - |
| Project | You create it in Katilyst | Pass its ID in the URL |
| User | You add them in Katilyst | Identify by email or ID |
| Attribute | You define it in Katilyst | Nothing — it changes as a result |
| Available Action | You configure it in Katilyst | Pass its ID in the request |
| Logged Action | Created when you call the API | This is what you create |
| Reward | Rules you set on the Available Action | Nothing — Katilyst applies it |
| Guardrails | Rules you set on the Available Action | Nothing — enforced server-side |
| Recognition | Rules you set in the platform | Nothing — fires independently |

## You send signals, not rewards

Your integration never sets a point value, grants a badge, or advances a level. It reports that something happened.

All of the business logic lives in your Katilyst project configuration, which means program managers can retune what an action is worth without anyone touching the integration.

## Events flow in; reporting is pulled out

To get program data into a warehouse or BI tool, pull it with [List a project's logged actions](https://docs.katilyst.com/api-reference/v1/list-a-projects-logged-actions.md) on a schedule you control.


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