Skip to main content
The Kyberis Threat Investigator API helps machine consumers resolve entities, retrieve bounded evidence, pivot through relationships, recommend hunt pivots, prioritize signals, and produce deterministic threat assessments. The API is intentionally LLM-free on the serving path. Use it when you need structured JSON outputs that are explainable, repeatable, and suitable for agent workflows.

Base URL

Authentication

Kyberis supports long-lived API key credentials and short-lived machine bearer tokens. Use API key credentials for most agent-facing /v2 endpoints:
Mint a short-lived bearer token from API key credentials:
Then call bearer-protected endpoints:
Machine bearer tokens minted by POST /v2/auth/token are for agent-facing API calls. The /v2/api-keys management endpoints are dashboard operations and require a Kyberis console login session; they do not accept API keys or machine bearer tokens.

Agent Context

Most POST /v2/* investigation endpoints require an agent_context object so Kyberis can validate intent, correlate requests, and return auditable outputs. Required fields:
  • objective
  • requested_outcome
  • workflow_stage
  • run_id
  • step_id
Allowed workflow_stage values include resolve, evidence, relationships, assessment, hunt, hydrate, batch, finalize, and other.
For GET /v2/entities/{canonical_id} and GET /v2/evidence/{evidence_id}, send the same context with request headers:
  • X-Agent-Objective
  • X-Agent-Requested-Outcome
  • X-Agent-Workflow-Stage
  • X-Agent-Run-ID
  • X-Agent-Step-ID

Optional client and skill attribution

agent_context.client.agent_name identifies your calling agent; agent_version and framework are optional. Use a truthful client name, not a user principal ID. If you know which skill is executing, you can also send:
These are optional fields inside agent_context; retain the required fields above. Skill IDs accept 1–128 characters and versions accept 1–64 characters. Values are trimmed; control characters and unknown skill properties are rejected. Omit version if you do not know it, and omit skill if no skill is executing. Skill attribution is self-reported and does not confirm an investigation outcome. For the GET hydration endpoints above, send the optional objects as JSON in X-Agent-Client and X-Agent-Skill. Omit an absent header rather than sending JSON null. Metadata does not change authentication, permissions, or transport. See intelligence flow for contribution counts and the API-key fallback when no agent identity was recorded.

Request Correlation

You can send X-Request-ID on any request. Responses include X-Request-ID with either your sanitized value or a generated identifier. Error responses include error_code, message, status_code, and request_id. When agent context is available, errors also include run_id and step_id.

Investigation Flow

Use this default workflow for threat investigations:
  1. Normalize raw input with POST /v2/entity-resolution.
  2. If the result is ambiguous, constrain expected_types or ask for disambiguation.
  3. Retrieve claim-level evidence with POST /v2/evidence.
  4. Pivot from canonical entities with POST /v2/relationships.
  5. Use POST /v2/hunt-pivots when agents need ranked next investigative actions.
  6. Use POST /v2/prioritize for environment-aware triage.
  7. Use the matching assessment endpoint for a deterministic verdict.
  8. Hydrate referenced entities and evidence by ID when you need bounded detail.

Endpoint Groups

Health

Check authenticated service availability.

Auth

Mint machine bearer tokens and inspect console-session API key endpoints.

Resolution

Normalize raw inputs into canonical Kyberis entities.

Intel and evidence

Search intelligence and retrieve bounded evidence for specific claims.

Relationships

Pivot through bounded relationships for canonical entities.

Prioritize

Rank signals by environment-aware deterministic relevance.

Assessments

Produce structured CVE, actor, IOC, environment, and threat assessments.

IoC feed (enterprise-only)

Maintain a local indicator dataset with snapshots and daily incremental changes. Requires explicitly enabled enterprise feed access.

OpenAPI