SuperAlign Docs

AIRiskDB API Examples

Copy-paste AIRiskDB API examples in curl, Python, and JavaScript for signals, lookups, findings, AI-BOMs, threats, and webhooks.

These examples use placeholders so they are safe to copy into your own environment.

export AIRISKDB_API_KEY="<AIRISKDB_API_KEY>"
export AIRISKDB_BASE_URL="https://api.airiskdb.com"
export FINGERPRINT="<FINGERPRINT>"

Replace <AIRISKDB_API_KEY> with your issued key and <FINGERPRINT> with a valid asset fingerprint such as a sha256: value.

Submit One MCP Server Signal

Use this when an integration observes one AI asset and wants AIRiskDB to store the observation and enrich the asset.

curl

curl -s -X POST "$AIRISKDB_BASE_URL/v1/signals" \
  -H "Authorization: Bearer $AIRISKDB_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "fingerprint": "'"$FINGERPRINT"'",
    "asset_type": "mcp_server",
    "org_id": "org_demo",
    "name": "@modelcontextprotocol/server-filesystem",
    "version": "1.2.3",
    "source_url": "https://github.com/modelcontextprotocol/servers",
    "raw_manifest": {
      "name": "@modelcontextprotocol/server-filesystem",
      "version": "1.2.3",
      "description": "MCP server for filesystem access",
      "tools": [
        { "name": "read_file" },
        { "name": "write_file" },
        { "name": "execute_command" }
      ],
      "dependencies": {
        "express": "4.18.2"
      }
    },
    "observed_at": 1711234567,
    "metadata": {
      "source": "asset-inventory",
      "environment": "prod"
    }
  }'

Python

import os
import uuid
import requests

base_url = os.environ.get("AIRISKDB_BASE_URL", "https://api.airiskdb.com")
api_key = os.environ["AIRISKDB_API_KEY"]
fingerprint = os.environ["FINGERPRINT"]

payload = {
    "fingerprint": fingerprint,
    "asset_type": "mcp_server",
    "org_id": "org_demo",
    "name": "@modelcontextprotocol/server-filesystem",
    "version": "1.2.3",
    "source_url": "https://github.com/modelcontextprotocol/servers",
    "raw_manifest": {
        "name": "@modelcontextprotocol/server-filesystem",
        "version": "1.2.3",
        "tools": [
            {"name": "read_file"},
            {"name": "write_file"},
            {"name": "execute_command"},
        ],
    },
    "observed_at": 1711234567,
    "metadata": {"source": "asset-inventory", "environment": "prod"},
}

response = requests.post(
    f"{base_url}/v1/signals",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Idempotency-Key": str(uuid.uuid4()),
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=30,
)
response.raise_for_status()
print(response.json())

JavaScript

const baseUrl = process.env.AIRISKDB_BASE_URL ?? "https://api.airiskdb.com";
const apiKey = process.env.AIRISKDB_API_KEY;
const fingerprint = process.env.FINGERPRINT;

const response = await fetch(`${baseUrl}/v1/signals`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    fingerprint,
    asset_type: "mcp_server",
    org_id: "org_demo",
    name: "@modelcontextprotocol/server-filesystem",
    version: "1.2.3",
    source_url: "https://github.com/modelcontextprotocol/servers",
    raw_manifest: {
      name: "@modelcontextprotocol/server-filesystem",
      version: "1.2.3",
      tools: [
        { name: "read_file" },
        { name: "write_file" },
        { name: "execute_command" },
      ],
    },
    observed_at: 1711234567,
    metadata: { source: "asset-inventory", environment: "prod" },
  }),
});

if (!response.ok) {
  throw new Error(await response.text());
}

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

Submit Bulk Signals

Use bulk signals when your scanner, inventory system, or SIEM integration needs to submit multiple observations at once. A bulk request accepts between 1 and 500 signal items.

curl

curl -s -X POST "$AIRISKDB_BASE_URL/v1/signals/bulk" \
  -H "Authorization: Bearer $AIRISKDB_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "signals": [
      {
        "fingerprint": "'"$FINGERPRINT"'",
        "asset_type": "mcp_server",
        "org_id": "org_demo",
        "name": "@modelcontextprotocol/server-filesystem",
        "version": "1.2.3",
        "observed_at": 1711234567
      },
      {
        "fingerprint": "sha256:<SECOND_FINGERPRINT>",
        "asset_type": "ide_plugin",
        "org_id": "org_demo",
        "name": "example-ai-extension",
        "version": "2.0.0",
        "observed_at": 1711234567
      }
    ]
  }'

Python

import os
import uuid
import requests

base_url = os.environ.get("AIRISKDB_BASE_URL", "https://api.airiskdb.com")
api_key = os.environ["AIRISKDB_API_KEY"]

payload = {
    "signals": [
        {
            "fingerprint": os.environ["FINGERPRINT"],
            "asset_type": "mcp_server",
            "org_id": "org_demo",
            "name": "@modelcontextprotocol/server-filesystem",
            "version": "1.2.3",
            "observed_at": 1711234567,
        },
        {
            "fingerprint": "sha256:<SECOND_FINGERPRINT>",
            "asset_type": "ide_plugin",
            "org_id": "org_demo",
            "name": "example-ai-extension",
            "version": "2.0.0",
            "observed_at": 1711234567,
        },
    ]
}

response = requests.post(
    f"{base_url}/v1/signals/bulk",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json=payload,
    timeout=30,
)
response.raise_for_status()
print(response.json())

JavaScript

const baseUrl = process.env.AIRISKDB_BASE_URL ?? "https://api.airiskdb.com";
const apiKey = process.env.AIRISKDB_API_KEY;

const response = await fetch(`${baseUrl}/v1/signals/bulk`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    signals: [
      {
        fingerprint: process.env.FINGERPRINT,
        asset_type: "mcp_server",
        org_id: "org_demo",
        name: "@modelcontextprotocol/server-filesystem",
        version: "1.2.3",
        observed_at: 1711234567,
      },
      {
        fingerprint: "sha256:<SECOND_FINGERPRINT>",
        asset_type: "ide_plugin",
        org_id: "org_demo",
        name: "example-ai-extension",
        version: "2.0.0",
        observed_at: 1711234567,
      },
    ],
  }),
});

if (!response.ok) {
  throw new Error(await response.text());
}

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

Lookup Assets by Fingerprint

Use fingerprint lookup when you already have stable identifiers from a scanner, package registry, model catalog, or asset inventory.

curl

curl -s "$AIRISKDB_BASE_URL/v1/assets/lookup?fingerprints=$FINGERPRINT&fingerprints=sha256:<SECOND_FINGERPRINT>&include_candidates=true&expand[]=findings&expand[]=aibom" \
  -H "Authorization: Bearer $AIRISKDB_API_KEY"

Python

import os
import requests

base_url = os.environ.get("AIRISKDB_BASE_URL", "https://api.airiskdb.com")
api_key = os.environ["AIRISKDB_API_KEY"]

response = requests.get(
    f"{base_url}/v1/assets/lookup",
    headers={"Authorization": f"Bearer {api_key}"},
    params=[
        ("fingerprints", os.environ["FINGERPRINT"]),
        ("fingerprints", "sha256:<SECOND_FINGERPRINT>"),
        ("include_candidates", "true"),
        ("expand[]", "findings"),
        ("expand[]", "aibom"),
    ],
    timeout=30,
)
response.raise_for_status()
print(response.json())

JavaScript

const baseUrl = process.env.AIRISKDB_BASE_URL ?? "https://api.airiskdb.com";
const apiKey = process.env.AIRISKDB_API_KEY;

const params = new URLSearchParams();
params.append("fingerprints", process.env.FINGERPRINT);
params.append("fingerprints", "sha256:<SECOND_FINGERPRINT>");
params.append("include_candidates", "true");
params.append("expand[]", "findings");
params.append("expand[]", "aibom");

const response = await fetch(`${baseUrl}/v1/assets/lookup?${params}`, {
  headers: { Authorization: `Bearer ${apiKey}` },
});

if (!response.ok) {
  throw new Error(await response.text());
}

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

Lookup Assets by Name, Version, and Ecosystem

Use name-based lookup when you do not have a fingerprint. Repeatable lookup_* parameters are aligned by index.

curl

curl -s "$AIRISKDB_BASE_URL/v1/assets/lookup?lookup_name=%40modelcontextprotocol%2Fserver-filesystem&lookup_version=1.2.3&lookup_ecosystem=npm&include_candidates=true&expand[]=findings" \
  -H "Authorization: Bearer $AIRISKDB_API_KEY"

Python

import os
import requests

base_url = os.environ.get("AIRISKDB_BASE_URL", "https://api.airiskdb.com")
api_key = os.environ["AIRISKDB_API_KEY"]

response = requests.get(
    f"{base_url}/v1/assets/lookup",
    headers={"Authorization": f"Bearer {api_key}"},
    params=[
        ("lookup_name", "@modelcontextprotocol/server-filesystem"),
        ("lookup_version", "1.2.3"),
        ("lookup_ecosystem", "npm"),
        ("include_candidates", "true"),
        ("expand[]", "findings"),
    ],
    timeout=30,
)
response.raise_for_status()
print(response.json())

JavaScript

const baseUrl = process.env.AIRISKDB_BASE_URL ?? "https://api.airiskdb.com";
const apiKey = process.env.AIRISKDB_API_KEY;

const params = new URLSearchParams({
  lookup_name: "@modelcontextprotocol/server-filesystem",
  lookup_version: "1.2.3",
  lookup_ecosystem: "npm",
  include_candidates: "true",
});
params.append("expand[]", "findings");

const response = await fetch(`${baseUrl}/v1/assets/lookup?${params}`, {
  headers: { Authorization: `Bearer ${apiKey}` },
});

if (!response.ok) {
  throw new Error(await response.text());
}

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

Fetch Asset Findings With Expanded Threats

Use findings to understand capabilities, score breakdowns, ATLAS techniques, CVEs, and matched threats for an enriched asset.

curl

curl -s "$AIRISKDB_BASE_URL/v1/assets/$FINGERPRINT/findings?expand[]=threats" \
  -H "Authorization: Bearer $AIRISKDB_API_KEY"

Python

import os
import requests

base_url = os.environ.get("AIRISKDB_BASE_URL", "https://api.airiskdb.com")
api_key = os.environ["AIRISKDB_API_KEY"]
fingerprint = os.environ["FINGERPRINT"]

response = requests.get(
    f"{base_url}/v1/assets/{fingerprint}/findings",
    headers={"Authorization": f"Bearer {api_key}"},
    params=[("expand[]", "threats")],
    timeout=30,
)
response.raise_for_status()
print(response.json())

JavaScript

const baseUrl = process.env.AIRISKDB_BASE_URL ?? "https://api.airiskdb.com";
const apiKey = process.env.AIRISKDB_API_KEY;
const fingerprint = process.env.FINGERPRINT;

const params = new URLSearchParams();
params.append("expand[]", "threats");

const response = await fetch(
  `${baseUrl}/v1/assets/${encodeURIComponent(fingerprint)}/findings?${params}`,
  { headers: { Authorization: `Bearer ${apiKey}` } },
);

if (!response.ok) {
  throw new Error(await response.text());
}

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

Fetch AI-BOM Output

The AI-BOM endpoint supports three output modes.

Full AI-BOM JSON

curl -s "$AIRISKDB_BASE_URL/v1/assets/$FINGERPRINT/aibom" \
  -H "Authorization: Bearer $AIRISKDB_API_KEY"

Raw SPDX JSON

curl -s "$AIRISKDB_BASE_URL/v1/assets/$FINGERPRINT/aibom?format=spdx_json" \
  -H "Authorization: Bearer $AIRISKDB_API_KEY"

SPDX Tag-Value

curl -s "$AIRISKDB_BASE_URL/v1/assets/$FINGERPRINT/aibom?format=spdx_tv" \
  -H "Authorization: Bearer $AIRISKDB_API_KEY"

Python

import os
import requests

base_url = os.environ.get("AIRISKDB_BASE_URL", "https://api.airiskdb.com")
api_key = os.environ["AIRISKDB_API_KEY"]
fingerprint = os.environ["FINGERPRINT"]

for output_format in [None, "spdx_json", "spdx_tv"]:
    params = {} if output_format is None else {"format": output_format}
    response = requests.get(
        f"{base_url}/v1/assets/{fingerprint}/aibom",
        headers={"Authorization": f"Bearer {api_key}"},
        params=params,
        timeout=30,
    )
    response.raise_for_status()
    print(response.text)

JavaScript

const baseUrl = process.env.AIRISKDB_BASE_URL ?? "https://api.airiskdb.com";
const apiKey = process.env.AIRISKDB_API_KEY;
const fingerprint = process.env.FINGERPRINT;

for (const format of [undefined, "spdx_json", "spdx_tv"]) {
  const params = new URLSearchParams();
  if (format) params.set("format", format);

  const response = await fetch(
    `${baseUrl}/v1/assets/${encodeURIComponent(fingerprint)}/aibom?${params}`,
    { headers: { Authorization: `Bearer ${apiKey}` } },
  );

  if (!response.ok) {
    throw new Error(await response.text());
  }

  console.log(await response.text());
}

List High or Critical Threats

Use threat list filters to review the highest-priority intelligence records.

curl

curl -s "$AIRISKDB_BASE_URL/v1/threats?limit=25&severity=critical" \
  -H "Authorization: Bearer $AIRISKDB_API_KEY"

curl -s "$AIRISKDB_BASE_URL/v1/threats?limit=25&severity=high" \
  -H "Authorization: Bearer $AIRISKDB_API_KEY"

Python

import os
import requests

base_url = os.environ.get("AIRISKDB_BASE_URL", "https://api.airiskdb.com")
api_key = os.environ["AIRISKDB_API_KEY"]

for severity in ["critical", "high"]:
    response = requests.get(
        f"{base_url}/v1/threats",
        headers={"Authorization": f"Bearer {api_key}"},
        params={"limit": 25, "severity": severity},
        timeout=30,
    )
    response.raise_for_status()
    print(response.json())

JavaScript

const baseUrl = process.env.AIRISKDB_BASE_URL ?? "https://api.airiskdb.com";
const apiKey = process.env.AIRISKDB_API_KEY;

for (const severity of ["critical", "high"]) {
  const params = new URLSearchParams({ limit: "25", severity });
  const response = await fetch(`${baseUrl}/v1/threats?${params}`, {
    headers: { Authorization: `Bearer ${apiKey}` },
  });

  if (!response.ok) {
    throw new Error(await response.text());
  }

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

Register a Webhook

Use webhooks to receive AIRiskDB events in your own system. The generated webhook secret is returned once in the creation response.

curl

curl -s -X POST "$AIRISKDB_BASE_URL/v1/webhooks" \
  -H "Authorization: Bearer $AIRISKDB_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/risk-intel",
    "events": [
      "ai.superalign.ri.asset.enriched",
      "ai.superalign.ri.asset.threat_matched",
      "ai.superalign.ri.threat.created"
    ],
    "description": "Primary AIRiskDB webhook endpoint",
    "metadata": {
      "team": "security"
    }
  }'

Python

import os
import uuid
import requests

base_url = os.environ.get("AIRISKDB_BASE_URL", "https://api.airiskdb.com")
api_key = os.environ["AIRISKDB_API_KEY"]

payload = {
    "url": "https://example.com/webhooks/risk-intel",
    "events": [
        "ai.superalign.ri.asset.enriched",
        "ai.superalign.ri.asset.threat_matched",
        "ai.superalign.ri.threat.created",
    ],
    "description": "Primary AIRiskDB webhook endpoint",
    "metadata": {"team": "security"},
}

response = requests.post(
    f"{base_url}/v1/webhooks",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json=payload,
    timeout=30,
)
response.raise_for_status()
print(response.json())

JavaScript

const baseUrl = process.env.AIRISKDB_BASE_URL ?? "https://api.airiskdb.com";
const apiKey = process.env.AIRISKDB_API_KEY;

const response = await fetch(`${baseUrl}/v1/webhooks`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://example.com/webhooks/risk-intel",
    events: [
      "ai.superalign.ri.asset.enriched",
      "ai.superalign.ri.asset.threat_matched",
      "ai.superalign.ri.threat.created",
    ],
    description: "Primary AIRiskDB webhook endpoint",
    metadata: { team: "security" },
  }),
});

if (!response.ok) {
  throw new Error(await response.text());
}

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

AIRiskDB Quickstart

Make your first AIRiskDB API calls with authentication, idempotency, signals, lookups, findings, and AI-BOM expansion.

AIRiskDB API Reference

Public AIRiskDB endpoint reference with scopes, parameters, response codes, pagination, expansions, errors, and idempotency behavior.

On this page

Submit One MCP Server Signal
curl
Python
JavaScript
Submit Bulk Signals
curl
Python
JavaScript
Lookup Assets by Fingerprint
curl
Python
JavaScript
Lookup Assets by Name, Version, and Ecosystem
curl
Python
JavaScript
Fetch Asset Findings With Expanded Threats
curl
Python
JavaScript
Fetch AI-BOM Output
Full AI-BOM JSON
Raw SPDX JSON
SPDX Tag-Value
Python
JavaScript
List High or Critical Threats
curl
Python
JavaScript
Register a Webhook
curl
Python
JavaScript