Agent API¶

Endpoints used by SentriKat agents and custom integrations to submit software inventory.

Submit Inventory Report¶

Submit a full or delta software inventory for an asset.

POST /api/agent/report
X-Agent-Key: <agent-api-key>
Content-Type: application/json

Request Body¶

{
  "hostname": "workstation-001",
  "os": "Windows 11 23H2",
  "organization_id": 1,
  "ip_address": "192.168.1.50",
  "tags": ["office", "finance"],
  "software": [
    {
      "name": "Google Chrome",
      "version": "121.0.6167.85",
      "vendor": "Google LLC",
      "cpe": "cpe:2.3:a:google:chrome:121.0.6167.85:*:*:*:*:*:*:*"
    },
    {
      "name": "7-Zip",
      "version": "23.01",
      "vendor": "Igor Pavlov"
    }
  ]
}

Required Fields¶

Optional Fields¶

Response¶

{
  "status": "accepted",
  "asset_id": 42,
  "hostname": "workstation-001",
  "products_processed": 2,
  "products_matched": 2,
  "vulnerabilities_found": 1
}

Submit Delta Report¶

Send only changes since the last full report.

POST /api/agent/report
X-Agent-Key: <agent-api-key>
Content-Type: application/json

{
  "hostname": "workstation-001",
  "delta": true,
  "software_added": [
    {"name": "Slack", "version": "4.36.0", "vendor": "Salesforce"}
  ],
  "software_removed": [
    {"name": "Slack", "version": "4.35.126"}
  ]
}

Response¶

{
  "status": "accepted",
  "asset_id": 42,
  "products_added": 1,
  "products_removed": 1,
  "vulnerabilities_found": 0
}

Submit Container Scan Results¶

Submit container image vulnerability scan results from Trivy. See the Container Scanning API documentation for full details.

POST /api/agent/container-scan
X-Agent-Key: <agent-api-key>
Content-Type: application/json

This endpoint accepts Trivy JSON output for Docker/Podman images scanned on the agent endpoint. Container scanning is automatically performed by agents v1.2.0+ when Docker or Podman is detected. See Container Scanning for the agent configuration guide.

Agent Heartbeat¶

Send a heartbeat to indicate the agent is active without a full scan.

POST /api/agent/heartbeat
X-Agent-Key: <agent-api-key>
Content-Type: application/json

{
  "hostname": "workstation-001",
  "agent_version": "1.2.0"
}

Response¶

{
  "status": "ok",
  "asset_id": 42,
  "server_time": "2024-02-01T12:00:00Z",
  "config": {
    "scan_interval": 86400,
    "include_updates": false
  }
}

The config field can be used to dynamically adjust agent settings from the server.

Get Agent Configuration¶

Retrieve server-side configuration for the agent.

GET /api/agent/config
X-Agent-Key: <agent-api-key>

Response¶

{
  "scan_interval": 86400,
  "include_updates": false,
  "include_services": true,
  "minimum_agent_version": "1.0.0",
  "force_full_scan": false
}

Authentication¶

Agent endpoints use API key authentication via the X-Agent-Key header:

curl -X POST "https://sentrikat.example.com/api/agent/report" \
  -H "X-Agent-Key: sk_agent_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"hostname": "server-01", "software": [...]}'

Create agent API keys in Integrations > Agent Keys with the agent scope. See Authentication API for details.

Rate Limits¶

Agent endpoints have a dedicated rate limit:

Error Codes¶