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/inventory
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/inventory
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 performed by the agent 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/inventory" \
  -H "X-Agent-Key: sk_agent_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"hostname": "server-01", "software": [...]}'

Create agent API keys in Agents → Agent Keys with the agent scope. See Authentication API for details.

Rate Limits¶

Agent endpoints have a dedicated rate limit:

Error Codes¶