Skip to content

REST API Import

Import software inventory from any source using the SentriKat REST API. Use this method for custom integrations, unsupported platforms, or CI/CD pipelines.

Installing agents on individual hosts?

To deploy the agent on individual machines, prefer Integrations → Agent Deploy (per-host keys). See Install First Agent. The shared API key below is the right fit for scripted/CI imports.

Overview

The REST import works by submitting inventory data to the Agent API endpoint. This is the same endpoint that the native Windows and Linux agents use, so imported data is treated identically.

Prerequisites

  • An API key with agent permissions
  • Network access to your SentriKat instance

Quick Start

Submit a software inventory report:

curl -X POST "https://sentrikat.example.com/api/agent/inventory" \
  -H "X-Agent-Key: sk_agent_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "hostname": "custom-server-01",
    "os": {
      "name": "FreeBSD",
      "version": "14.0-RELEASE"
    },
    "products": [
      {
        "vendor": "F5, Inc.",
        "product": "nginx",
        "version": "1.24.0"
      },
      {
        "vendor": "PostgreSQL Global Development Group",
        "product": "PostgreSQL",
        "version": "15.4"
      },
      {
        "vendor": "OpenSSL Project",
        "product": "OpenSSL",
        "version": "3.1.4"
      }
    ]
  }'

Response:

{
  "status": "success",
  "asset_id": 42,
  "hostname": "custom-server-01",
  "summary": {
    "products_created": 3,
    "products_updated": 0,
    "installations_created": 3,
    "installations_updated": 0,
    "installations_removed": 0,
    "total_products": 3,
    "stale_matches_removed": 0
  }
}

Report Schema

The array is products, not software

The server reads products. A body that sends the list under any other key is accepted with HTTP 200 and imports nothing: the array simply defaults to empty. If a call succeeds but no inventory appears, this is almost always why.

Required Fields

Field Type Description
hostname string Unique identifier for the asset
products array List of installed software items

Optional Fields

Field Type Description Default
os object {"name": …, "version": …, "kernel": …}. An object, not a string omitted
fqdn string Fully-qualified domain name omitted
ip_address string Asset IP address Detected from request
agent object {"id": …, "version": …} for agent-reported inventory omitted

Organization comes from the key

The target organization is resolved from the agent key itself. An organization_id in the body is ignored, as are tags.

Product Item Schema

Field Type Description Required
vendor string Software vendor/publisher Recommended
product string Software product name Yes
version string Installed version Yes
path string Install path, when known No

Vendor accuracy drives matching accuracy

SentriKat resolves each (vendor, product) pair to a CPE identity before matching. A precise vendor string is what lets it find an exact identity rather than falling back to a weaker guess, and an unresolved identity is reported for review rather than matched on a guess.

Use Cases

CI/CD Pipeline Integration

Scan container images or build artifacts and report installed packages:

#!/bin/bash
# Extract packages from Docker image and report to SentriKat

IMAGE="myapp:latest"
SENTRIKAT_URL="https://sentrikat.example.com"
API_KEY="sk_agent_xxxxxxxxxxxx"

# Get package list from container
PACKAGES=$(docker run --rm "$IMAGE" dpkg-query -W -f '{"product":"${Package}","version":"${Version}"},')
PACKAGES="[${PACKAGES%,}]"  # Remove trailing comma, wrap in array

curl -X POST "$SENTRIKAT_URL/api/agent/inventory" \
  -H "X-Agent-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"hostname\": \"container-$IMAGE\",
    \"os\": {\"name\": \"Docker Container\"},
    \"products\": $PACKAGES
  }"

Network Device Inventory

Import software versions from network equipment:

import requests
import json

SENTRIKAT_URL = "https://sentrikat.example.com"
API_KEY = "sk_agent_xxxxxxxxxxxx"

# Example: report firmware versions from network devices
devices = [
    {"hostname": "switch-core-01", "products": [{"vendor": "Cisco", "product": "Cisco IOS", "version": "17.6.5"}]},
    {"hostname": "firewall-01", "products": [{"vendor": "Netgate", "product": "pfSense", "version": "2.7.2"}]},
]

for device in devices:
    response = requests.post(
        f"{SENTRIKAT_URL}/api/agent/inventory",
        headers={"X-Agent-Key": API_KEY, "Content-Type": "application/json"},
        json=device,
    )
    print(f"{device['hostname']}: {response.json()['status']}")

Scheduled Cron Import

Run periodic imports via cron:

# /etc/cron.d/sentrikat-import
0 2 * * * root /opt/scripts/sentrikat-import.sh >> /var/log/sentrikat-import.log 2>&1

Repeat imports

Always send the full current inventory for a hostname. There is no partial/delta submission format: the server reconciles what you send against what it already holds for that host, creating, updating and removing installations as needed, and reports the counts back in the summary object of the response.

Sending a partial list therefore does not "add" to the previous one, it replaces it, and anything you leave out is treated as uninstalled.

Error Handling

Status Code Meaning Action
200 Success Inventory processed
400 Invalid request body Check JSON schema
401 Invalid API key Verify key in Agents → Agent Keys
403 Key lacks permissions Ensure key has agent scope
429 Rate limited Wait and retry (see Retry-After header)

Next Steps