KB Sync API¶

The Knowledge Base (KB) Sync API lets an installation push locally discovered CPE mappings and pull published mappings from the central server. The server stores pushed mappings only from Professional licenses and refuses them from other editions. This creates a community-driven knowledge base that improves vulnerability matching accuracy over time.

The server also maintains the software identity catalogue as a baseline.

These routes are on the license server, not on your own installation:

https://api.sentrikat.com/api/v1

Authentication¶

KB Sync endpoints use a custom authentication scheme based on the signed license data:

Authorization: Bearer <first 64 chars of signed_data>
X-Installation-ID: SK-INST-<32 uppercase hex characters>

• Authorization: First 64 characters of the signed license string (base64url(payload).base64url(signature))
• X-Installation-ID: The installation's unique ID. It must belong to an active, unexpired license whose signed token starts with the one you send

The edition is read from the license, not from any header you send. Pushing requires a Professional license.

Push Mappings¶

Submit locally discovered CPE mappings from a Professional installation.

POST /api/v1/kb/mappings/push
Authorization: Bearer <token>
X-Installation-ID: SK-INST-<32 uppercase hex characters>
Content-Type: application/json

Request Body¶

{
  "mappings": [
    {
      "vendor_pattern": "apache software foundation",
      "product_pattern": "http server",
      "cpe_vendor": "apache",
      "cpe_product": "http_server",
      "confidence": 0.85
    },
    {
      "vendor_pattern": "microsoft corporation",
      "product_pattern": "visual studio code",
      "cpe_vendor": "microsoft",
      "cpe_product": "visual_studio_code",
      "confidence": 0.90
    }
  ]
}

The installation is identified by the X-Installation-ID header only.

Response¶

{
  "accepted": 2
}

Security Model¶

• Mappings are stored with is_published=false by default
• A mapping is automatically published when 3 or more independent installations confirm the same vendor/product pair
• Confidence scores from community contributions are capped at 0.90
• A repeat push from an installation that already confirmed a mapping does not count as a second confirmation; only a new installation increments the contribution_count

Pull Mappings¶

Download published mappings from the central KB. Available to all licensed installations.

GET /api/v1/kb/mappings/pull
Authorization: Bearer <token>
X-Installation-ID: SK-INST-<32 uppercase hex characters>

Query Parameters¶

Results are ordered by (updated_at, id), oldest first.

Response¶

{
  "mappings": [
    {
      "id": 1021,
      "vendor_pattern": "apache software foundation",
      "product_pattern": "http server",
      "cpe_vendor": "apache",
      "cpe_product": "http_server",
      "confidence": 0.85,
      "source": "community",
      "notes": "",
      "updated_at": "2026-02-10T12:00:00"
    },
    {
      "id": 1022,
      "vendor_pattern": "microsoft",
      "product_pattern": "windows_10",
      "cpe_vendor": "microsoft",
      "cpe_product": "windows_10",
      "confidence": 1.0,
      "source": "nvd",
      "notes": "",
      "updated_at": "2026-02-09T03:00:00"
    }
  ],
  "count": 2,
  "timestamp": "2026-10-07T12:00:00"
}

count is the number of mappings in this response. To know whether there is more, request the next page (offset) or the next cursor until a response returns fewer rows than limit.

Incremental Sync¶

The cursor is the pair (updated_at, id) of the last mapping you received. Pass both: since alone can skip mappings that share one timestamp.

# First sync: read page by page (a call with no limit returns at most 50000 mappings).
# Continue with offset=5000, offset=10000 and so on, until a response has fewer rows than limit.
curl -H "Authorization: Bearer $TOKEN" \
     -H "X-Installation-ID: $INST_ID" \
     "https://api.sentrikat.com/api/v1/kb/mappings/pull?limit=5000&offset=0"

# Subsequent syncs: only changes after the last mapping you received
curl -H "Authorization: Bearer $TOKEN" \
     -H "X-Installation-ID: $INST_ID" \
     "https://api.sentrikat.com/api/v1/kb/mappings/pull?since=2026-02-10T12:00:00&since_id=1021"

Mapping Sources¶

Rate Limits¶

Error Codes¶

Errors carry a JSON body of the form {"detail": "..."}.