> ## Documentation Index
> Fetch the complete documentation index at: https://developer.kyberis.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Call Kyberis directly, resolve an entity, retrieve evidence, and run a deterministic assessment.

This quickstart uses direct REST calls. For agent-native access, start with [Set up Kyberis in your agent](/install/overview).

## Prerequisites

* A Kyberis API key ID and secret
* `curl`
* `jq`, optional but useful for reading responses

Set local shell variables:

```bash theme={null}
export KYBERIS_BASE_URL="https://api.kyberis.ai"
export KYBERIS_API_KEY_ID="<key_id>"
export KYBERIS_API_KEY_SECRET="<secret>"
```

## Check Health

<CodeGroup>
  ```bash cURL theme={null}
  curl -sS "$KYBERIS_BASE_URL/v2/health" \
    -H "Authorization: ApiKey $KYBERIS_API_KEY_ID:$KYBERIS_API_KEY_SECRET" \
    -H "Accept: application/json"
  ```

  ```javascript Node.js theme={null}
  const baseUrl = process.env.KYBERIS_BASE_URL ?? 'https://api.kyberis.ai';
  const keyId = process.env.KYBERIS_API_KEY_ID;
  const secret = process.env.KYBERIS_API_KEY_SECRET;

  const response = await fetch(`${baseUrl}/v2/health`, {
    headers: {
      Authorization: `ApiKey ${keyId}:${secret}`,
      Accept: 'application/json',
    },
  });

  console.log(await response.json());
  ```

  ```python Python theme={null}
  import json
  import os
  import urllib.request

  base_url = os.environ.get('KYBERIS_BASE_URL', 'https://api.kyberis.ai')
  key_id = os.environ['KYBERIS_API_KEY_ID']
  secret = os.environ['KYBERIS_API_KEY_SECRET']

  request = urllib.request.Request(
      f'{base_url}/v2/health',
      headers={
          'Authorization': f'ApiKey {key_id}:{secret}',
          'Accept': 'application/json',
      },
  )

  with urllib.request.urlopen(request) as response:
      print(json.load(response))
  ```
</CodeGroup>

A successful response confirms your credentials can reach the API.

## Mint a Bearer Token

You can call most Kyberis investigation endpoints directly with `Authorization: ApiKey <key_id>:<secret>`. That is the simplest path for a first request and for trusted server-side integrations.

For runtime agent sessions, prefer a short-lived bearer token. The API key remains the long-lived machine credential, while the bearer token is scoped by expiry. This reduces the blast radius if runtime logs, traces, or agent configuration expose an authorization header.

```bash theme={null}
curl -sS -X POST "$KYBERIS_BASE_URL/v2/auth/token" \
  -H "Authorization: ApiKey $KYBERIS_API_KEY_ID:$KYBERIS_API_KEY_SECRET" \
  -H "Accept: application/json"
```

The response includes `access_token`, `token_type`, `expires_in`, `expires_at`, `scopes`, `audiences`, and `issuer`. Store the API key in your trusted credential store, mint bearers as needed, and refresh them when they expire.

## Resolve an Entity

```bash theme={null}
curl -sS -X POST "$KYBERIS_BASE_URL/v2/entity-resolution" \
  -H "Authorization: ApiKey $KYBERIS_API_KEY_ID:$KYBERIS_API_KEY_SECRET" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "agent_context": {
      "objective": "Normalize a CVE for investigation.",
      "requested_outcome": "Return the canonical entity identifier.",
      "workflow_stage": "resolve",
      "run_id": "run-quickstart-001",
      "step_id": "step-01"
    },
    "query": "CVE-2024-3094",
    "expected_types": ["cve"],
    "resolution": {
      "max_results": 5,
      "include_aliases": true,
      "include_metadata": true
    }
  }'
```

Branch on `resolution.status`:

* `resolved`: use `canonical_id` and `entity_type` downstream.
* `ambiguous`: retry with tighter `expected_types` or ask for disambiguation.
* `not_found`: stop or use a different enrichment source.

## Retrieve Evidence

Use focused evidence calls. Prefer one claim per request.

```bash theme={null}
curl -sS -X POST "$KYBERIS_BASE_URL/v2/evidence" \
  -H "Authorization: ApiKey $KYBERIS_API_KEY_ID:$KYBERIS_API_KEY_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_context": {
      "objective": "Check whether the CVE is exploited in the wild.",
      "requested_outcome": "Return bounded evidence for active exploitation.",
      "workflow_stage": "evidence",
      "run_id": "run-quickstart-001",
      "step_id": "step-02"
    },
    "query": "CVE-2024-3094",
    "claim_type": "active_exploitation",
    "max_results": 5
  }'
```

## Run an Assessment

Use the most specific assessment endpoint available for the subject.

```bash theme={null}
curl -sS -X POST "$KYBERIS_BASE_URL/v2/cve-assessments" \
  -H "Authorization: ApiKey $KYBERIS_API_KEY_ID:$KYBERIS_API_KEY_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_context": {
      "objective": "Decide whether this CVE needs immediate attention.",
      "requested_outcome": "Return deterministic risk guidance with evidence references.",
      "workflow_stage": "assessment",
      "run_id": "run-quickstart-001",
      "step_id": "step-03"
    },
    "query": "CVE-2024-3094",
    "context": {
      "targeted_industries": ["technology"],
      "known_targets": ["XZ Utils 5.6.0", "XZ Utils 5.6.1"],
      "intel_confidence": "medium"
    }
  }'
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Set up an agent" icon="https://mintcdn.com/kyberis/c-TjxE2WqJIPZVhQ/icons/mcp.svg?fit=max&auto=format&n=c-TjxE2WqJIPZVhQ&q=85&s=7863df3c06b580b0bb617a65bf1f7b4a" href="/install/overview" width="24" height="24" data-path="icons/mcp.svg" />

  <Card title="Interpret responses" icon="https://mintcdn.com/kyberis/c-TjxE2WqJIPZVhQ/icons/responses.svg?fit=max&auto=format&n=c-TjxE2WqJIPZVhQ&q=85&s=0eb4bb372658ecffc0247d946d07fdcb" href="/responses/overview" width="24" height="24" data-path="icons/responses.svg" />
</CardGroup>