REST API Reference

The KYRA MDR REST API provides programmatic access to alerts, incidents, collectors, and other platform resources. Use it to integrate KYRA MDR with your existing tools, automate workflows, or build custom dashboards.

Base URL: https://api.seekerslab.com/api/v1

Authentication

All API requests require a Bearer token in the Authorization header.

Generate an API Key

Open the KYRA MDR Console
Go to Settings > API Keys
Click Create API Key
Give the key a name (e.g., “SIEM Integration”)
Select the permission scope (read-only or read-write)
Copy the key — it will not be shown again

Using the API Key

Include the key in every request:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.seekerslab.com/api/v1/alerts

Authentication Errors

Status	Meaning
`401 Unauthorized`	Missing or invalid API key
`403 Forbidden`	API key lacks required permissions
`429 Too Many Requests`	Rate limit exceeded (see below)

Rate Limits

Plan	Rate Limit
FREE	60 requests/minute
MDR	300 requests/minute
PRO	1,000 requests/minute
CUSTOM	Custom

Rate limit headers are included in every response:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 297
X-RateLimit-Reset: 1700000060

Common Parameters

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`size`	integer	Items per page (default: 20, max: 100)
`sort`	string	Sort field (e.g., `created_at`)
`order`	string	Sort order: `asc` or `desc`
`from`	ISO 8601	Start of time range
`to`	ISO 8601	End of time range

Alerts

List Alerts

GET /alerts

Query parameters:

Parameter	Type	Description
`severity`	string	Filter by severity: `critical`, `high`, `medium`, `low`, `info`
`status`	string	Filter by status: `open`, `in_progress`, `resolved`, `false_positive`
`source_type`	string	Filter by source: `fortigate`, `windows`, `aws-cloudtrail`, etc.

Example:

# Get all open critical alerts from the last 24 hours
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.seekerslab.com/api/v1/alerts?severity=critical&status=open&from=2026-03-21T00:00:00Z"

Response:

{
  "data": [
    {
      "id": "alert-550e8400-e29b",
      "title": "Brute Force Authentication Attempt",
      "severity": "high",
      "status": "open",
      "source_type": "windows",
      "source_ip": "10.0.1.55",
      "mitre_tactic": "Credential Access",
      "mitre_technique": "T1110",
      "created_at": "2026-03-22T08:15:30Z",
      "event_count": 47,
      "ai_summary": "47 failed logon attempts (Event ID 4625) from 10.0.1.55 targeting 3 accounts in 2 minutes."
    }
  ],
  "pagination": {
    "page": 1,
    "size": 20,
    "total": 1,
    "total_pages": 1
  }
}

Get Alert Detail

GET /alerts/{alert_id}

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.seekerslab.com/api/v1/alerts/alert-550e8400-e29b

Update Alert Status

PATCH /alerts/{alert_id}

curl -X PATCH \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "resolved", "comment": "False positive - authorized penetration test"}' \
  https://api.seekerslab.com/api/v1/alerts/alert-550e8400-e29b

Incidents

List Incidents

GET /incidents

Parameter	Type	Description
`severity`	string	Filter by severity
`status`	string	`open`, `investigating`, `contained`, `resolved`, `closed`
`assignee`	string	Filter by assigned analyst

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.seekerslab.com/api/v1/incidents?status=open"

Response:

{
  "data": [
    {
      "id": "inc-7c9e6679-a1f4",
      "title": "Suspected Lateral Movement - WORKSTATION-12",
      "severity": "critical",
      "status": "investigating",
      "alert_count": 5,
      "created_at": "2026-03-22T07:00:00Z",
      "updated_at": "2026-03-22T08:30:00Z",
      "assignee": "analyst@company.com",
      "mitre_tactics": ["Lateral Movement", "Credential Access"],
      "ai_summary": "Multiple pass-the-hash logons from WORKSTATION-12 to 4 servers within 10 minutes, followed by LSASS memory access."
    }
  ]
}

Get Incident Detail

GET /incidents/{incident_id}

Returns the full incident with timeline, related alerts, affected assets, and response actions.

Add Incident Comment

POST /incidents/{incident_id}/comments

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "Isolated WORKSTATION-12 from network. Investigating root cause."}' \
  https://api.seekerslab.com/api/v1/incidents/inc-7c9e6679-a1f4/comments

Collectors

List Collectors

GET /collectors

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.seekerslab.com/api/v1/collectors

Response:

{
  "data": [
    {
      "id": "col-abc123",
      "name": "DC-Collector-01",
      "hostname": "collector01.internal.company.com",
      "status": "connected",
      "version": "1.5.2",
      "os": "Ubuntu 22.04",
      "last_seen": "2026-03-22T09:00:15Z",
      "events_per_second": 245,
      "uptime_hours": 720
    }
  ]
}

Get Collector Detail

GET /collectors/{collector_id}

Returns detailed information including health metrics, configured sources, and buffer status.

Log Search

Search Events

POST /search

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "source_type:windows AND event_id:4625",
    "from": "2026-03-21T00:00:00Z",
    "to": "2026-03-22T00:00:00Z",
    "size": 50
  }' \
  https://api.seekerslab.com/api/v1/search

Response:

{
  "data": [
    {
      "timestamp": "2026-03-21T14:22:10Z",
      "source_type": "windows",
      "source_ip": "10.0.1.55",
      "event_id": 4625,
      "message": "An account failed to log on.",
      "fields": {
        "TargetUserName": "admin",
        "LogonType": 3,
        "WorkstationName": "ATTACKER-PC",
        "IpAddress": "192.168.1.100"
      }
    }
  ],
  "total": 342
}

Search Query Syntax

Operator	Example	Description
Field match	`source_type:windows`	Exact field match
AND	`severity:critical AND status:open`	Both conditions
OR	`src_ip:10.0.1.1 OR src_ip:10.0.1.2`	Either condition
NOT	`NOT source_type:sysmon`	Exclude matches
Wildcard	`user:admin*`	Prefix match
Range	`event_count:[10 TO 100]`	Numeric range

Webhooks

Create Webhook

POST /webhooks

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Slack Critical Alerts",
    "url": "https://hooks.slack.com/services/T00/B00/xxx",
    "events": ["alert.created"],
    "filters": {
      "severity": ["critical", "high"]
    }
  }' \
  https://api.seekerslab.com/api/v1/webhooks

Webhook Events

Event	Description
`alert.created`	New alert detected
`alert.updated`	Alert status changed
`incident.created`	New incident created
`incident.updated`	Incident status changed
`collector.disconnected`	Collector went offline

Webhook Payload

{
  "event": "alert.created",
  "timestamp": "2026-03-22T08:15:30Z",
  "data": {
    "id": "alert-550e8400-e29b",
    "title": "Brute Force Authentication Attempt",
    "severity": "high",
    "source_type": "windows",
    "url": "https://kyra-mdr-console.seekerslab.com/alerts/alert-550e8400-e29b"
  }
}

Error Responses

All errors follow a consistent format:

{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "Invalid severity value. Allowed: critical, high, medium, low, info",
    "details": {
      "parameter": "severity",
      "value": "urgent"
    }
  }
}

HTTP Status	Error Code	Description
400	`INVALID_PARAMETER`	Invalid request parameter
401	`UNAUTHORIZED`	Missing or invalid API key
403	`FORBIDDEN`	Insufficient permissions
404	`NOT_FOUND`	Resource not found
429	`RATE_LIMITED`	Too many requests
500	`INTERNAL_ERROR`	Server error — contact support

SDKs and Libraries

The REST API works with any HTTP client. Below are examples in common languages:

# Python example
import requests

API_KEY = "your-api-key"
BASE_URL = "https://api.seekerslab.com/api/v1"

headers = {"Authorization": f"Bearer {API_KEY}"}

# Get open critical alerts
response = requests.get(
    f"{BASE_URL}/alerts",
    headers=headers,
    params={"severity": "critical", "status": "open"}
)

alerts = response.json()["data"]
for alert in alerts:
    print(f"[{alert['severity']}] {alert['title']}")

Need Help?

API Issues: api-kyra@seekerslab.com
Rate Limit Increase: Contact kyra@seekerslab.com
Bug Reports: Include the X-Request-Id response header when reporting issues