API reference

The HTTP API of Kairos. The SDK calls it for you; use it directly from any language.

• Conventions
• Authentication
• Errors
• Events · Records · Sessions
• Entities · Entity types · Labels
• Actions · Decisions
• Metrics and dashboards · Counts and usage
• Inbound webhooks · Workflows · Models · Queues and cases
• Accounts and workspaces · Environments

Conventions#

• Base URL. https://kairos.finic.ai. A self-hosted server has its own address.
• JSON in and out. Send Content-Type: application/json with a body.
• Times are ISO 8601. Kairos stores and returns UTC: 2026-10-06T13:58:00.000Z.
• Names of entity types, actions, labels, reason codes and typology codes start with a letter or an underscore and contain only letters, digits and underscores, up to 64 characters.
• Ids of entities, events, records and sessions are any text of 1 to 256 characters.
• Three groups of paths: /v1 is the data API, /auth is sign-in, /app is workspaces and API keys. GET /health returns { "ok": true } and needs no key. POST /mcp is the MCP server for agents.

Authentication#

How keys and sign-in work, how to limit and rotate a key, and every error: Authentication.

The data API (/v1)#

Send an API key as a bearer token:

Authorization: Bearer ksk_…

A key belongs to one workspace and one of its environments, and the request is confined to them. Keys are made in the console (Settings › API keys) or with POST /app/workspaces/:workspace/keys.

A key can be limited to IP addresses or IPv4 ranges. A public key can be limited to websites; the server compares the list with the Origin header of the request. POST /v1/events answers CORS requests from any origin, so that a browser can send events.

The console uses the same API with a session cookie instead of a key, and names the workspace in a header: X-Kairos-Workspace: <workspace id>. X-Kairos-Environment names the environment; without it, Production.

Sign-in and workspaces (/auth, /app)#

These need a person who is signed in: the console, or the CLI after kairos login --email. An API key cannot use them.

Errors#

Every error has the same shape:

{ "error": { "type": "invalid_request", "message": "batch.0.ts: must be an ISO 8601 timestamp" } }

A decision that cannot be made is an error, not a default. Decide in your own code what to do then; the SDK's fallback option does this for you.

Events#

POST /v1/events#

Store a batch of events. Answers 202.

{
  "batch": [
    {
      "id": "evt_01",
      "type": "bank_transfer",
      "ts": "2026-10-06T13:58:00Z",
      "entities": { "user": "user_42", "payee": "payee_new" },
      "properties": { "amount": 2400, "currency": "GBP" },
      "universal_id": "txn_881",
      "status": "pending",
      "session": "sess_7f3a",
      "set": { "user": { "kyc_level": "full" } },
      "set_once": { "user": { "first_transfer": "2026-10-06" } }
    }
  ]
}

{ "accepted": 1, "duplicates": 0 }

POST /v1/events/decide#

Store one event and get the decision it starts. The body is one event, as above (not a batch). The event must be the trigger of an action, and its entities must name that action's subject.

The event is the pending action of the decision. Sending the same id again returns the same decision and does not decide again.

The response is a decision with event_id added.

GET /v1/events/:id#

One event by its id: { id, type, ts, entities, properties, universal_id?, status?, session?, decision }. decision is { id, outcome, risk_score } of the decision it started, or null. 404 when there is no such event.

Records#

GET /v1/records/:id#

One record: every event with that universal_id, oldest first.

{ "universal_id": "txn_881", "status": "completed", "stages": [ { "id": "evt_01", "status": "pending", … }, { "id": "evt_02", "status": "completed", … } ] }

Sessions#

GET /v1/sessions#

Sessions, most recently active first. A session is listed when it has at least one event.

{
  "sessions": [
    {
      "id": "sess_7f3a",
      "started": "2026-10-06T13:54:00.000Z",
      "last_seen": "2026-10-06T13:58:00.000Z",
      "events": 6,
      "decisions": 1,
      "outcome": "block",
      "risk_score": 99,
      "entities": { "user": ["user_42"], "device": ["dev_unknown"] }
    }
  ],
  "total": 54,
  "next_offset": 50
}

outcome is the most severe outcome among the session's decisions and risk_score the highest. entities holds up to five ids of each type.

GET /v1/sessions/:id#

One session: its events oldest first, every entity they name, and the decisions made in it.

{ "id": "sess_7f3a", "started": "…", "last_seen": "…", "entities": { "user": ["user_42"] }, "events": [ … ], "decisions": [ … ] }

?limit= sets how many of the most recent events are returned: default 500, at most 2,000.

Entities#

PUT /v1/entities/:type/:id#

Create or update one entity. Properties are merged into what is stored; unset removes properties.

{ "properties": { "kyc_country": "GB", "plan": "pro" }, "unset": ["trial_ends"] }

{ "type": "user", "id": "user_42", "properties": { "kyc_country": "GB", "plan": "pro" }, "metadata": {}, "first_seen": "…", "updated": "…" }

PUT /v1/objects#

The same for a batch of 1 to 500: { "batch": [{ "type": "user", "id": "user_42", "properties": { … } }] }. Answers { "accepted": 2 }.

GET /v1/objects/:type/:id#

The properties and labels of one entity: { type, id, properties, first_seen, labels }.

GET /v1/entities#

Without type: the entity types in use, in types (see GET /v1/entity-types).

With ?type=user: the entities of that type.

GET /v1/entities?type=user&prop=kyc_country:eq:GB&prop=age:gt:40&label=*&sort=risk

{
  "types": [ … ],
  "type": "user",
  "entities": [
    { "id": "user_42", "events": 169, "first_seen": "…", "last_seen": "…", "labels": ["fraud_confirmed"], "decision": { "decision": "block", "risk_score": 98, … }, "properties": { "kyc_country": "GB" } }
  ],
  "total": 12,
  "next_offset": null
}

GET /v1/entities/:type/:id#

Everything about one entity: { type, id, properties, first_seen, labels, events, decisions, sessions }. events are the most recent, newest first (?limit=, default 100, at most 500). decisions are the 20 most recent about it, and sessions the 20 most recent it was in.

Facts and lists of an entity#

Facts and lists of cases count only the queues the caller can see.

DELETE /v1/entities/:type/:id#

Erases a person's data, for a privacy request such as a GDPR erasure or Shopify's customers/redact. A secret key, or a signed-in admin or owner (a member gets 403 forbidden, a public key 403 public_key_scope), in the key's environment only. One transaction.

{
  "entity": { "type": "user", "id": "user_42" },
  "dry_run": false,
  "erased": {
    "entity": 1, "labels": 2, "events": 118, "events_redacted": 3, "decisions": 4, "decisions_redacted": 1,
    "cases": 1, "case_items": 3, "case_evidence": 2, "workflow_runs": 4, "workflow_runs_redacted": 2,
    "webhook_deliveries": 4, "webhook_payloads_redacted": 6
  }
}

?dry_run=true answers the same counts and deletes nothing. 404 not_found when Kairos holds nothing about the entity, not even a copy in someone else's decision, so a second erasure answers 404: a client can treat 404 as done.

Erasing a person's data. What goes:

• The entity: its properties and labels.
• Its own events: those that name no other entity. A record or a session loses those stages.
• The decisions about it, and the finished workflow runs of those decisions.
• The cases about it (with their evidence, items and activity), and in other cases the items and evidence that name it, its events or its decisions.
• Outbound webhook deliveries about it, its decisions or its cases.

What stays, changed:

• Events that also name another entity, such as the other side of a transfer or a shared device: they stay for that entity, without the link to this one and without their properties, because nothing tells whose the properties are.
• Decisions about someone else that one of its events started, or whose request or context named it (as { "<type>": "<id>" }, or as a linked entity): the outcome, risk score and resolution stay; context and raw become { "erased": true } and request becomes null.
• Other finished workflow runs that its events started, or whose trigger named it: they stay, with trigger { "erased": true } and no steps or output.
• Inbound webhook deliveries that stored its events: the row stays in the log, without its payload and headers.

What stays:

• Entities that were only linked to it, such as a shared device. A decision about a linked subject shows counts of other users, never who they are.
• Workflow runs that are still going: they need their trigger to finish. Erase again once they end.
• Background jobs. They hold ids.
• Other ids of the same person: erase each one (for example user, email and phone).

Entity types#

PUT /v1/entity-types/:type#

Define what a kind of entity means. Optional: an event that names an undefined type still creates the entity.

{
  "kind": "person",
  "description": "A customer with an account",
  "properties": { "kyc_country": "The country the identity document is from" },
  "link": true
}

link: false says that two subjects who share an entity of this type are not connected by it. properties documents the fields; it does not constrain them.

display.formats maps a property to how it shows: text, number, money, datetime, date, boolean, country, link, image or document. At most 100.

facts (at most 12) and lists (at most 6) are what the entity's page and the case pages about it show. The guides are Facts and Lists.

{
  "facts": [
    { "name": "money_out_7d", "label": "Money out this week", "source": "events", "measure": "sum", "field": "amount",
      "filters": { "event_type": "transaction", "property": { "name": "direction", "value": "out" } },
      "window": "7d", "usual": "90d", "format": "money", "currency": "GBP" }
  ],
  "lists": [
    { "name": "transactions", "label": "Transactions", "source": "events", "filters": { "event_type": ["transaction"] },
      "columns": ["ts", { "field": "event.amount", "label": "Amount", "format": "money", "currency": "event.currency" }, "decision.outcome"],
      "sort": "newest", "window": "all" }
  ]
}

• A fact's source is events, decisions, labels or cases. measure is count, sum, avg, unique (how many different entities of the type field the events name), first or last; labels and cases take count, first and last. sum and avg read a number property of events, or risk_score of decisions.
• filters: event_type (one or a list of up to 10) and property: { name, value } for events; action and outcome (a list) for decisions; label; queue and status (a list) for cases. A list of linked entities takes event_type.
• window is like 24h, 7d or 30d, at most 400 days, or all (the default). usual, for count and sum with a window, is at least two times the window. format is number, money (with a currency code) or percent.
• A list's source is events, decisions, linked (with entity_type) or cases. Its columns: for events ts, id, type, decision.outcome, decision.risk_score and event.<property>; for decisions ts, id, action, decision.outcome, decision.risk_score, final_outcome and request.<property>; for linked entities id, name, first_seen, last_seen, events and entity.<property>; for cases ts, id, status, priority, queue, assignee and resolution. A column format is text, number, money, datetime, date, boolean or country; money takes a currency code or a field of the row.

GET /v1/entity-templates#

{ templates }: entity type definitions to start from, with their facts and lists. The server reads them from templates/entities/.

GET /v1/entity-types#

Every type that is defined or in use: { "types": [{ type, count, events, labelled, last_seen, definition? }] }.

GET /v1/entity-types/:type#

One definition, or 404 when the type was never defined.

GET /v1/entity-types/:type/shape#

What entities of the type look like in the stored data, from the 500 most recently updated: each property with its value types, an example and how many entities carry it; the event types that name the type; and the labels in use. Works for a type that no one defined.

Labels#

POST /v1/labels#

{ "batch": [{ "entity": { "type": "user", "id": "user_42" }, "label": "fraud_confirmed", "ts": "2026-10-09T10:00:00Z", "properties": { "source": "chargeback" } }] }

batch holds 1 to 500 labels. ts is when the outcome became known; without it, now. A decision made as of an earlier moment does not see the label. Adding the same label again replaces its time and properties. Answers { "accepted": 1 }.

Actions#

PUT /v1/actions/:name#

Define or change an action. :name is its key.

{
  "displayName": "Bank Transfer",
  "description": "Outgoing transfers to a payee",
  "subject": "user",
  "hold": "Should this transfer be held because the account shows signs of fraud or takeover?",
  "reasons": {
    "new_device": "The request comes from a device the user has not used before",
    "new_payee": "The money goes to a payee added shortly before the request"
  },
  "typologies": {
    "legit": "An ordinary payment by the owner of the account",
    "account_takeover": "Someone who is not the owner is using the account"
  },
  "trigger": { "event": "transaction", "status": "pending" },
  "policy": {
    "block": 0.9,
    "review": 0.5,
    "rules": [
      { "id": "both", "allOf": ["new_device", "new_payee"], "outcome": "step_up" },
      { "id": "drained", "when": [{ "total": "money_out", "is": "sum", "op": ">=", "value": 5000 }], "outcome": "review" }
    ]
  },
  "context": {
    "recentEvents": 30,
    "reasonThreshold": 0.5,
    "linkTypes": ["device", "payee"],
    "totals": [{ "name": "money_out", "event": "transfer", "sum": "usd", "where": { "status": "completed" }, "window": "24h", "usual": "90d", "covers": "usd" }]
  }
}

A total:

A rule's when compares a number of a total: is is sum (default), events, times_usual (needs usual) or share_covered (needs covers); op is >, >=, < or <=.

The response is the definition with name and version. A change to anything the model reads is a new version. Sending the same definition again changes nothing, so this is safe to call at every startup.

GET /v1/actions#

{ "actions": [ … ] }: the latest version of each.

GET /v1/actions/:name#

One action, latest version. ?version=2 reads an earlier version.

GET /v1/actions/:name/versions#

{ "versions": [{ version, created, created_by }] }, newest first.

GET /v1/actions/:name/automatic#

What deciding automatically means for the action: { available, per_day, missed_last_day, window_minutes }. per_day is the matching events a day over the last 7 days (each would be one model call); missed_last_day is how many since it was turned on were not decided within the hour (the model was down, for example). available is false on a server that does not run automatic decisions.

An automatic decision has "automatic": true in GET /v1/decisions, GET /v1/decisions/:id and the decision.created webhook. One event has at most one decision: POST /v1/events/decide for an event that was already decided returns that decision.

GET /v1/templates#

{ "templates": [ … ] }: action definitions offered as starting points. Nothing is defined until one is sent to PUT /v1/actions/:name.

Decisions#

POST /v1/decide#

Ask for a decision on a pending action.

{
  "action": "bank_transfer",
  "entities": { "user": "user_42", "device": "dev_9", "payee": "payee_new" },
  "properties": { "amount": 2400, "currency": "GBP" },
  "session": "sess_7f3a",
  "ts": "2026-10-06T14:00:00Z"
}

{
  "decision": "block",
  "probability": 0.977,
  "risk_score": 98,
  "reasons": ["new_device", "new_payee"],
  "typology": "account_takeover",
  "rules": [],
  "action": "bank_transfer@2",
  "decision_id": "kdec_8cd38292942f4c4084d42bc960404c8f"
}

The pending action is not stored as an event. To store it too, use POST /v1/events/decide.

When the action has a published, active decision workflow, that workflow makes the decision: the answer has the same fields, and also workflow_run_id. When the workflow fails, or does not answer in its time, the answer is 502 with the type workflow_failed, and no decision is saved.

GET /v1/decisions#

The decision log, newest first, without the context and the raw answer.

{ "decisions": [{ "id": "kdec_…", "ts": "…", "action": "bank_transfer@2", "subject": { "type": "user", "id": "user_42" }, "decision": { … }, "session": "sess_7f3a" }], "total": 298, "next_before": "…" }

A decision that a workflow made also has "metadata": { "decision_workflow": "review_transfers@3" }.

GET /v1/decisions/:id#

One decision in full: the fields above, plus context (exactly what the model was shown), raw (what the model answered, with token usage), and event_id when an event started it.

POST /v1/decisions/:id/resolution#

A person's decision on a decision: { "outcome": "approve" | "block", "note"?, "by"? }. note is up to 2,000 characters. by says who; with the console's session it is the person's email address, and without by it is API. The model's decision stays; resolution, final_outcome and revision change, and decision.updated is sent. A new resolution replaces the last one. The answer is the decision without context and raw.

Metrics and dashboards#

POST /v1/metrics/query#

One metric, for a dashboard tile or for your own reporting.

{
  "source": "decisions",
  "measure": "share",
  "field": "review,block",
  "filters": { "action": "bank_transfer" },
  "group_by": "action",
  "from": "2026-09-06T00:00:00Z",
  "to": "2026-10-06T00:00:00Z",
  "interval": "day",
  "compare": true
}

{ "buckets": ["2026-09-06T00:00:00.000Z", …], "series": [{ "key": "bank_transfer", "total": 46.3, "values": [ … ] }], "total": 46.3, "previous_total": 41.0, "unit": "percent", "truncated": false }

One request reads at most 250,000 rows of its period. Past that, truncated is true and the numbers are a lower bound. More than eight groups come back as eight and "Other" for a count. risk_band has ten bands.

GET /v1/metrics/options#

What a metric can be filtered and grouped by in this workspace: { actions, signals, typologies, event_types, labels, entity_types, event_properties }. ?event_type= fills event_properties with the properties of that event type and whether each is numeric.

Dashboards#

{
  "name": "Payouts",
  "range": "30d",
  "visibility": "workspace",
  "tiles": [{ "id": "t1", "title": "Held", "view": "number", "w": 3, "link": "decisions", "query": { "source": "decisions", "measure": "share", "field": "review,block" } }]
}

range is 24h, 7d, 30d or 90d. view is number, line, area, bar, stacked, hbar, table or list. w is the width, 2 to 12 columns. query is a metric without its period. At most 40 tiles.

visibility is workspace or private. A private dashboard exists only for the person who made it. One made with an API key has no owner and cannot be private. Anyone who can see a dashboard can change its tiles; only its owner renames it, changes who sees it, or deletes it.

Counts and usage#

Client settings#

What the JavaScript tag, the mobile SDKs, the edge and the SDK middleware collect, for the environment of the key. The console shows them in Settings › Integrations › Client settings. A secret key only.

{
  "consent": "required",
  "defaults": { "country": "GB", "off": ["address"], "sessionCookie": "sid" },
  "routing": { "mode": "monitor", "other": "ignore" },
  "pages": [{ "path": "/checkout", "type": "checkout_viewed" }],
  "screens": [{ "name": "Transfer", "type": "transfer_screen_viewed" }],
  "routes": [
    {
      "route": "POST /login",
      "mode": "decide_response",
      "type": "login",
      "failed": "login_failed",
      "fields": { "userId": { "from": "response.header", "path": "x-kairos-user" } },
      "fallback": "approve",
      "enforce": false
    }
  ]
}

Inbound webhooks#

A provider sends its webhooks to Kairos, which stores them as events and labels. The guide is Inbound webhooks.

Sources are managed under /app/workspaces/:workspace/webhooks with a session and the admin role: see Accounts and workspaces below.

Workflows#

A workflow has one trigger and a list of steps, and Kairos runs it in the background. The guide, with each trigger, each step and the expressions, is Workflows. A workflow belongs to the environment of the key.

A run's status is queued, running, waiting, filtered, done, failed or cancelled. See Runs.

Models#

The models that workflow steps use: the built-in question model grayson-1, and the scoring models you upload. The guide is Models. An uploaded model belongs to the environment of the key.

A slug is lowercase letters and digits, in groups joined by one -, at most 64 characters. A step names a version as slug@2, or the latest as slug.

Queues and cases#

A queue's rules open cases for the decisions that need a person. The guides are Queues and Cases.

{
  "name": "Onboarding review",
  "description": "New accounts held for an identity check",
  "visibility": "workspace",
  "enabled": true,
  "sources": { "actions": ["onboard_user"] },
  "intake": [
    {
      "id": "held_or_risky",
      "name": "Held or risky",
      "priority": "high",
      "conditions": {
        "any": [
          { "field": "decision.outcome", "op": "in", "value": ["review", "step_up", "block"] },
          { "field": "decision.risk_score", "op": ">=", "value": 80 },
          { "field": "signal.identity_mismatch", "op": ">=", "value": 0.9 }
        ]
      }
    }
  ],
  "correlation": { "by": "subject", "window_days": 30, "reopen_days": 7, "when_missing": "create" },
  "due_hours": { "urgent": 1, "high": 4, "normal": 24 },
  "columns": ["target", "priority", "status", "assignee", "risk", "request.country", "age"],
  "sort": "oldest",
  "display": { "icon": "person", "color": "purple" }
}

• op is =, in (a list), >, >=, <, <= or between (two numbers). Outcomes and typologies take = or in; scores take the comparisons.
• correlation.by is subject, entity (with type), request (with property), session or event. window_days (1 to 90, default 30) is only for the first three. reopen_days (1 to 90): a trigger within that many days after a case is resolved reopens it. when_missing is for a trigger with no key: create (default) makes a case that cannot be joined, skip makes none.
• due_hours sets, for each priority, the hours a case can wait (more than 0, at most 8,760). A case gets due_at when it opens; a raised priority can make it sooner.
• columns are target, priority, status, assignee, age, due, last_activity, outcome, risk, evidence, reason, and request.<property> or subject.<property>. At most 12.
• sort is oldest, newest, priority, risk or due (soonest first; cases with no due time last).

A case:

{
  "id": "case_…", "queue_id": "que_…", "status": "open", "priority": "high",
  "assignee": null, "target": { "type": "user", "id": "user_42" }, "correlation_key": "subject:user:user_42",
  "reason": "Held or risky", "outcome": "review", "risk": 84, "evidence_count": 2,
  "last_evidence_at": "…", "last_activity": "…", "resolution": null, "due_at": "…", "created": "…",
  "values": { "request.country": "BR" }
}

Outbound webhooks can send case.created, case.assigned, case.resolved and case.reopened. data is the case as above, with case_id and queue_id. filter.queues (queue ids) limits them to some queues.

Case layouts#

A queue's case layout is display.view of its definition. The guide is Case layouts. A change to it does not add one to the queue's version.

"display": {
  "icon": "person",
  "view": {
    "template": "onboarding_identity",
    "header": ["subject.country", "decision.risk_score", "case.due"],
    "blocks": [
      { "id": "why", "type": "evidence", "region": "main" },
      { "id": "check", "type": "checklist", "region": "main", "w": 6, "points": ["The ID matches the selfie"] },
      { "id": "applicant", "type": "fields", "region": "main", "w": 6, "fields": ["subject.first_name", { "field": "request.amount", "format": "money", "currency": "request.currency" }] },
      { "id": "photos", "type": "images", "region": "side", "fields": ["subject.id_front_url", "subject.selfie_url"] },
      { "id": "device", "type": "facts", "region": "side", "of": "item.device" },
      { "id": "logins", "type": "list", "region": "main", "lists": ["logins"], "rows": 5 }
    ],
    "facts": [{ "for": "user", "name": "devices", "label": "Devices used", "source": "events", "measure": "unique", "field": "device" }],
    "lists": [{ "for": "user", "name": "logins", "label": "Logins", "source": "events", "filters": { "event_type": "login" }, "columns": ["ts", "event.ip_country"] }]
  }
}

• A block's type is evidence (required), decisions, timeline, details, fields, facts, list, objects, activity, text, images, documents or checklist; region is main or side; w (main only) is 3 to 12, default 12. At most 24 blocks and 6 header fields.
• A field is a path, or { field, label, format, currency }: case.<status|priority|assignee|queue|opened|age|due|reason>, decision.<outcome|risk_score|action|typology>, signal.<code>, request.<property>, event.<property> (of the latest decision), subject.<property> and item.<type>.<property>. A fields block has at most 16; an images or documents block 1 to 8, each holding an address.
• of (facts and list) is case.target (the default) or item.<type>: up to 5 objects of that type. facts and lists name what the block shows: the view's own (with for, an entity type) first, then the type's. Without them, the view's own for the type, or the type's.
• sensitive (images and documents, default true): hidden until opened, and each opening recorded. points (checklist): 1 to 12 different points. rows (list): 3 to 25. text (text): up to 2,000 characters.

Accounts and workspaces#

These need a person who is signed in, in the console or with kairos login --email. An API key cannot use them.

Workspaces and members#

The role needed is in the last column. A workspace you are not in answers 404.

API keys#

kind is secret or public. allowed_ips is a list of IP addresses and IPv4 ranges such as 203.0.113.0/24. allowed_origins is for a public key only: websites such as https://app.example.com or https://*.example.com.

Webhooks#

Inbound sources and outbound endpoints share these routes; direction is in or out. All need the admin role.

verification is { "scheme": "hmac", "header", "algorithm"?, "encoding"?, "prefix"? }, { "scheme": "timestamped", "header", "timestampHeader"?, "timestampKey"?, "signatureKey"?, "join"?, "algorithm"?, "encoding"?, "tolerance"? }, { "scheme": "standard", "tolerance"? }, { "scheme": "stripe", "tolerance"? }, { "scheme": "header", "header" } or { "scheme": "none" }. See Verification. A wrong mapping is refused with 400 and the problems in words.

Jobs#

The background work of one environment: webhook deliveries, workflow runs, automatic decisions and the queue rules' test of new decisions. Send the environment in X-Kairos-Environment; without it, production. All need the admin role. Jobs of no workspace, such as the cleanup, are not listed.

status is pending (waits to run, or to run again after a failure: then last_error is set and run_at is the retry), paused (its webhook endpoint is disabled), done or dead (it failed on each attempt). Done jobs are kept 7 days, dead ones 30. kind is webhook.deliver, workflow.run, decision.automatic or case.evaluate.

Environments#

What an environment holds, and how to work in a sandbox: Environments. Environment management uses a signed-in session under /app/workspaces/:workspace.

Each workspace creates Production automatically. Its kind cannot be changed, and it cannot be renamed or deleted independently. Names are unique within a workspace, ignoring case.

Each copy category accepts true for all, false or omission for none, or a selection object. Any enabled category requires copy_from, an environment in the same workspace. Empty selection lists copy nothing. Select action names, dashboard IDs, queue IDs, decision IDs, model slugs, individual { type, id } entities, or entity/event types:

{
  "name": "Payment experiment",
  "copy_from": "env_…",
  "copy": {
    "actions": { "ids": ["payment", "withdrawal"] },
    "entities": { "types": ["merchant"], "records": [{ "type": "user", "id": "user_42" }] },
    "events": { "types": ["payment_requested"], "ids": ["event_42"] },
    "dashboards": { "ids": ["dashboard_42"] },
    "decisions": { "ids": ["kdec_42"] },
    "models": { "ids": ["loan-default"] }
  }
}

Selections are unions: selected types include all records of those types, plus any individually selected records. Each list is limited to 1,000 entries; use true for an entire category. Unknown, stale, foreign, or inaccessible selections return 400 invalid_copy_selection without creating a sandbox. The options endpoint accepts category=actions|entity_types|entities|event_types|events|dashboards|queues|decisions|models, an optional literal text search q, and pagination (offset=0, limit=30, maximum 100). It lists only items in that source environment and hides other people's private dashboards and queues.

Entities includes selected definitions, profiles and properties, labels, and identities discovered from history. Events preserves the selected records' entity, session, and record links. Selected Decisions automatically include only their triggering events and required action versions, preserving context, raw answers, resolutions, and timestamps. Other actions and events follow their explicit selections. Without decision history, selected Actions start at version 1 from their latest definition; with history, their source versions are preserved. Dashboards copies only shared dashboards and the caller's own private dashboards. Queues copies the same way, the setup only: not the cases. Models copies the active models with all their versions, the same version numbers and their files; it is never in the default copy, and archived models are not offered. { "copy": {} } starts empty. For compatibility, omitting copy when using copy_from copies action and entity definitions only; the older copy_dashboards flag can add accessible dashboards in that mode. It cannot be combined with copy.

The selected data is copied atomically from one consistent snapshot. Copies are independent; automatic decisions start disabled, and copying history does not execute actions or send webhooks. Keys, webhook endpoints, credentials, and delivery logs are never copied.

API keys select both workspace and environment. For session requests to /v1, supply X-Kairos-Workspace and X-Kairos-Environment. Omit the environment only to select Production for compatibility. A provided environment must belong to the workspace. Keys ignore these headers and always use their own scope.

Session requests to /app/workspaces/:workspace/keys, /webhooks, /webhook-deliveries, and /jobs endpoints use X-Kairos-Environment with the same Production default. Key creation also accepts environment_id in its body, which takes precedence over the header; returned key metadata includes workspace_id and environment_id. Outgoing webhook messages include environment_id beside workspace_id.