Skip to main content
Eight objects make up the Katilyst platform. Your integration touches three of them directly, and the other five decide what happens when it does.
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.

​
Attribute

A configurable data element representing progress, status, or relationship. Katilyst supports three types: 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.

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

​
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 on a schedule you control.