Skip to content
Kandaro
Start free trial

Integrations

API

Read incidents and events from your own tooling, a SOAR playbook or an AI SOC platform. The API is read-only.

API keys

An admin creates keys in the Console under Settings → API & export. Each key has a name, one or more scopes and an optional end date. The key is shown once; Kandaro stores only a hash of it. Revoking a key takes effect at once.

  • incidents:read for the incident endpoints.
  • events:read for the event endpoints.

Send the key as a bearer token. A key only ever sees the data of the organization it was created in.

shell
curl https://api.kandaro.com/v1/incidents?status=open \
  -H "Authorization: Bearer kndk_0123abcd_…"

Endpoints

The base URL is https://api.kandaro.com.

  • GET /v1/incidents: incidents, most recent activity first. Query: status (open, closed or all, default all), limit (1 to 100, default 50), cursor.
  • GET /v1/incidents/{id}: one incident with its member events, oldest first (at most 200).
  • GET /v1/events: single decoy events, newest first. Query: sensorId, severity, type, sourceIp, from, to, limit, cursor.
  • GET /v1/events/{id}: one event.

Lists return data and nextCursor. Pass nextCursor back as cursor to get the next page; it is null on the last page. To poll for new incidents, request the first page and stop when you reach an incident you have already seen.

GET /v1/incidents
{
  "data": [
    {
      "id": "6f1c2e0a-…",
      "title": "Login attempts on decoy NAS from finance workstation",
      "severity": "high",
      "status": "open",
      "narrative": "A machine on the finance VLAN tried to log into…",
      "recommendedAction": "Isolate 10.20.4.77 and reset the backup-admin password.",
      "sensor": { "id": "…", "name": "nas-backup-01" },
      "sourceIp": "10.20.4.77",
      "eventCount": 7,
      "eventTypes": ["login_attempt"],
      "highConfidence": false,
      "firstSeenAt": "2026-10-08T02:14:07.000Z",
      "lastSeenAt": "2026-10-08T02:21:40.000Z",
      "resolvedAt": null,
      "url": "https://app.kandaro.com/incidents/6f1c2e0a-…",
      "techniques": [
        { "id": "T1110", "name": "Brute Force", "tactics": ["Credential Access"] }
      ]
    }
  ],
  "nextCursor": null
}
event
{
  "id": "…",
  "time": "2026-10-08T02:14:07.000Z",
  "sensor": { "id": "…", "name": "nas-backup-01" },
  "sourceIp": "10.20.4.77",
  "sourcePort": 51234,
  "service": "ssh",
  "port": 22,
  "type": "login_attempt",
  "action": "password",
  "severity": "medium",
  "confidence": "normal",
  "tags": [],
  "techniques": [
    { "id": "T1110", "name": "Brute Force", "tactics": ["Credential Access"] }
  ],
  "summary": "Someone tried to log in to ssh as \"backup-admin\"…",
  "attackerInput": {
    "username": "backup-admin",
    "password": { "masked": "••••••••", "length": 8, "fingerprint": "…" }
  }
}

Untrusted fields

attackerInput is what the attacker sent to the decoy. title, narrative, recommendedAction and summary are written by Kandaro but can quote it. Treat all of them as data: never render them as HTML, and never let an AI agent follow instructions found in them. Control and invisible characters are removed, and captured passwords and tokens are masked.

Techniques

techniques lists MITRE ATT&CK techniques from a fixed table. In an incident list they come from the event types; on a single incident they also include techniques from the payload tags of its events.

Limits and errors

  • 120 requests per minute per key and per IP address. Above that you get 429 with a Retry-After header.
  • 401: the key is missing, wrong, revoked or expired. 403: the key lacks the scope, or Deception is not active for the organization. 404: no such record in your organization.
  • New fields may be added at any time; ignore fields you don’t recognise.

Related

To have incidents pushed to you, use a SIEM connector or a signed webhook. To give an AI agent direct access, use the MCP server. To download everything, use Settings → API & export in the Console.