RESOURCES · DEVELOPERS
Katilyst API Overview
Automatically identify the signals of positive behavior and turn them into recognized program contributions
Your allies are doing the work today: resolving vulnerability tickets in JIRA, completing secure code training, running threat models. Most of that effort is invisible to your program without manual intervention, which means it can go unmeasured and unrecognized.
The Katilyst API is how that work gets in. You send an event from any tool that can make an HTTP request, and Katilyst evaluates it against the rules you configured, awarding points, granting badges, advancing levels, and triggering recognition in Slack or Teams. You send the signal; Katilyst decides what it's worth.
Base URL https://api.katilyst.com/v1/ · JSON · API key authentication · Open the API explorer
Example request body
POST /v1/logged-actions
{
"userEmail": "johnsmith@example.com",
"availableActionId": "1111-2002-3333-action-id"
}
What you can connect
Anything that can send an authenticated HTTP request can feed Katilyst. In practice, customers connect four kinds of tools.
Learning & development platforms
Course completions, assessment scores, and certification milestones from platforms like CMD+CTRL, Secure Code Warrior, and more.
Issue tracking and management
Vulnerability tickets closed, security work items completed, and remediation SLAs met in JIRA or equivalent.
Source control and continuous integration
Resolved SAST findings, security-relevant pull request reviews, dependency upgrades, and pipeline events from GitHub, GitLab, or your build system.
Threat modeling and design review
Completed threat models, design reviews attended, and architecture risk assessments signed off.
How the connection gets made
Katilyst does not ship pre-built connectors for these tools. Each integration is a small piece of plumbing you own, built one of three ways:
-
No code. Configure a workflow tool to listen for events in your systems and post to Katilyst. This covers most cases, and we've published step-by-step guides for Power Automate and JIRA Automation.
-
Low code. Write a short script or config file inside tooling you already have, like GitHub Actions or JIRA ScriptRunner, telling it when and what to send to Katilyst.
-
Your code. Build a small endpoint that receives webhooks from your tool, or a scheduled job that queries your tool's API, and post the results to Katilyst as actions. For when the built-in tooling can't reach the event.
If you would rather not build it alone, our team helps customers design and stand up these integrations as part of program delivery.
How it works
The API is a bridge between the tools your allies use and the Katilyst rules engine.
When an event happens in one of your tools, your integration sends it to Katilyst as a "Logged Action" against a specific User. Katilyst then evaluates that action against the configuration you have already set up in the platform (the reward, the guardrails, the frequency limits) and decides whether and how to apply it. If a rule exists for the outcome, recognition fires in Slack or Teams.
Two things follow from this that are worth knowing before you build.
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 flows out.
The API has no outbound webhooks, and so Katilyst will not call your systems when something happens. If you need program data in a warehouse or BI tool, you pull it with the logged-actions endpoints on a schedule you control.
Core concepts
Eight objects make up the platform. You will touch three of them directly.
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: Allies ("champions", "ambassadors", etc.), 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 use their userId.
Attribute
A configurable data element representing progress, status, or relationship. Katilyst supports three types: integers (points, vulnerabilities found), value lists (for level progression or earning badges), and connections (mentor/mentee relationships). 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 carries its own business logic, like which Attribute it changes, by how much, under what conditions, and how often it can be claimed. Available Actions come in two kinds:
-
Instance actions award their Attribute change every time they are logged. Closing a vulnerability ticket is an instance action.
-
State actions are switched on or off for a User and hold their credit until switched off. Annual training completion is a state action - enable it when they finish, disable it when the certification lapses.
Logged Action
What an Available Action becomes once registered for a specific User. It 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.
Result
The outcome of an eligible action: points awarded, a badge earned, a level advanced. Results are defined in your Project configuration, not in your API call.
Guardrails and limits
The rules controlling when and how often an action can be rewarded: admin approval, time-based expiration, conditional availability, and maximum frequency. Enforced on the Katilyst side. Your integration does not need to check them, because if an action isn't eligible, Katilyst simply doesn't apply a result and tells you so in the response.
Recognition
Slack and Teams shout-outs are part of the Katilyst rules engine, not the API. Your call may trigger an action; whether it produces a public celebration depends on the Rules defined in the platform.
Only one of these is something your integration creates. Everything else is either configured in Katilyst beforehand or happens as a consequence.
Concept | Where it comes from | What your integration does with it |
|---|---|---|
Recognition | You configure this setting in the Rules and Integration pages in Katilyst | Nothing, it fires independently |
Guardrails | Defined as part of the Action setup in Katilyst | Nothing, it's enforced automatically |
Result | Defined as part of the Action setup in Katilyst | Nothing, Katilyst applies it |
Logged Action | Created when you call the API | This is what you create with our API |
Available Action | You configure them in the Actions page in Katilyst | Pass its ID in the request |
Attribute | You define them in the Attributes page in Katilyst | Nothing, it changes as a result |
User | You add them in the Users page in Katilyst | Identify by email or ID |
Project | You create Projects in Katilyst under your Account | Pass its ID in the URL |
Getting Started
1.
Get an API key. An Account Admin generates keys from the Admin Portal. Keys are issued per account, not per Project. A single key reaches every Project in your account and every operation the public API exposes. Treat it like a password to a privileged account.
2.
Send it on every request. Include the key in the Authorization header, prefixed with API-Key:
Request header
Authorization: API-Key katilyst_oMeofDAJ_thisisanexamplekey
A missing or invalid key returns 401.
3.
Format your requests. HTTPS only. JSON bodies. Timestamps must be ISO 8601 strings carrying a Z or an explicit UTC offset.
2026-08-28T17:45:10Z is valid, 2026-08-28T17:45:10 is not.
4.
Explore. Every endpoint, parameter, and response schema is in the API explorer.
Paging. GET endpoints returning arrays page automatically. Every paged response carries start, limit, count, and a links object with next and prev URLs. Follow those links rather than constructing page offsets yourself.
Errors
A 409 on a write means the champion didn't meet the action's conditions, usually a frequency limit. The call worked; no reward was applied.
Endpoint Reference
Eleven endpoints, grouped by what you're trying to do. This is the map; the API explorer has full parameters, schemas, and response codes, and is generated from the API itself.
Discovery
You will need a handful of unique IDs before you can log any Actions. These four endpoints get them.
Endpoint | What it does |
|---|---|
GET /v1/projects | Lists every Project your key can reach |
GET /v1/projects/{projectId}/available-actions | Lists configured actions, with the ID you'll log against |
GET /v1/projects/{projectId}/users | Lists active Users in a Project |
GET /v1/available-actions/{availableActionId} | Full configuration of a single action |
Logging work
The two endpoints your integrations call to log an Action or change the state of an Action.
Endpoint | What it does |
|---|---|
POST /v1/logged-actions | Logs a completed Instance action for a User |
PUT /v1/projects/{projectId}/users/{userId}/action-states | Switches a State action on or off for a User |
Reading Results
These endpoints are how you verify an integration is working, debug a failed award, and get program data out of Katilyst.
Endpoint | What it does |
|---|---|
GET /v1/users/{userId} | A User across every Project they belong to |
GET /v1/projects/{projectId}/users/{userId}/action-states | Which State actions are enabled for a User |
GET /v1/projects/{projectId}/users/{userId}/attributes | Current Attribute values for a User |
GET /v1/projects/{projectId}/users/{userId}/logged-actions | The same, scoped to one User |
GET /v1/projects/{projectId}/logged-actions | Every logged action in a Project, filterable |
-
Only userEmail and availableActionId are required on POST.
-
A 409 means the User didn't meet the action's conditions, usually a frequency limit.
-
Use POST /logged-actions for Instance actions, PUT .../action-states for State actions.
-
Timestamps need a Z or an explicit offset.
Step-by-step guides
Ready to get started? The integration patterns above are common enough that we've documented them end to end. One uses a native automation feature (JIRA), the others use a workflow tool, so neither requires writing code.
PDF Guide
JIRA Automation
Award credit automatically when a champion moves a vulnerability ticket to Done. Covers building the rule, setting conditions on ticket type and owner, configuring the web request, and testing with the audit log.
Download the guide →
PDF Guide
Microsoft Power Automate
Log actions from across Microsoft 365: a post in a Teams channel, a submitted Form, a SharePoint event. Covers the trigger, associating the user profile, and building the HTTP action.
Download the guide →