Kairos Open console

Quickstart

This page takes you from a new account to a first decision, in about ten minutes.

1. Create an account and a key#

  1. Sign up at kairos.finic.ai.
  2. Go to Settings › API keys and choose Create key. Pick Secret.
  3. Copy the key. It starts with ksk_, and it is shown once. Keep it on your server, for example as KAIROS_API_KEY.

The console also has a Get started page that walks through these steps and gives you a prompt for a coding agent.

2. Install the SDK#

npm install @finic-ai/kairos
pip install finic-kairos

Or use any HTTP client: the API reference has every endpoint.

3. Say what you want decided#

An action is a decision in plain language: what it is about (its subject) and a yes-or-no question. Define it once, at startup or from a script.

import { Kairos } from "@finic-ai/kairos";

const kairos = new Kairos({ apiKey: process.env.KAIROS_API_KEY! });

await kairos.defineAction("withdrawal", {
  subject: "user",
  hold: "Should this withdrawal be held because the account shows signs of fraud or takeover?",
});
import os
from kairos import Kairos

kairos = Kairos(os.environ["KAIROS_API_KEY"])

kairos.define_action("withdrawal", {
    "subject": "user",
    "hold": "Should this withdrawal be held because the account shows signs of fraud or takeover?",
})

4. Record what happens#

Send events as they happen. A field that ends in Id (user_id in Python) names an entity: here, the user and their device.

kairos.track("login", { userId: "user_42", deviceId: "dev_9", ipCountry: "GB" });
kairos.track("login", {"user_id": "user_42", "device_id": "dev_9", "ip_country": "GB"})

track returns at once and sends in the background. To load the history you already have, see Import your history.

5. Ask at the moment of action#

const decision = await kairos.decide({ type: "withdrawal", userId: "user_42", usd: 900 }, { fallback: "review" });
if (decision.decision !== "approve") {
  // hold it: decision.riskScore, decision.reasons
}
decision = kairos.decide("withdrawal", {"user_id": "user_42", "usd": 900}, fallback="review")
if decision.decision != "approve":
    ...  # hold it: decision.risk_score, decision.reasons

The answer is approve, step_up, review or block, with a risk score and the signals behind it. With a fallback, decide always answers: when Kairos cannot be reached or fails, you get the fallback outcome, marked fallback: true.

With curl:

curl -X PUT https://kairos.finic.ai/v1/actions/withdrawal \
  -H "Authorization: Bearer $KAIROS_API_KEY" -H "Content-Type: application/json" \
  -d '{ "subject": "user", "hold": "Should this withdrawal be held because the account shows signs of fraud or takeover?" }'

curl -X POST https://kairos.finic.ai/v1/decide \
  -H "Authorization: Bearer $KAIROS_API_KEY" -H "Content-Type: application/json" \
  -d '{ "action": "withdrawal", "entities": { "user": "user_42" }, "properties": { "usd": 900 } }'

6. See why#

Open Decisions in the console. Each decision opens to what the model was shown, what it answered, and the policy that made the outcome.

Next#

Esc