AIRiskDB Quickstart

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

Base URLs

Use the production API root for custom integrations:

https://api.airiskdb.com

The versioned API root is:

https://api.airiskdb.com/v1

Authentication

Every /v1/* route requires a bearer API key:

Authorization: Bearer <AIRISKDB_API_KEY>

API keys are issued with a fixed mode and a set of scopes. If a key is missing, expired, revoked, invalid, or does not have the required scope, AIRiskDB returns an authentication or permission error.

Store API keys in a secret manager or environment variable. Do not commit them to source control.

Idempotency

Every POST request requires an idempotency key:

Idempotency-Key: <uuid>

AIRiskDB uses idempotency keys to make retries safe. The first successful response for the same method, path, livemode, key, and request body is cached and replayed for repeated identical requests. Reusing the same key with a different request body returns an idempotency_replay_mismatch error.

Use a fresh UUID for each new write operation.

First API Flow

This flow checks service health, submits one MCP server signal, fetches the stored signal, looks up the asset, and expands findings plus AI-BOM data.

Set these environment variables before running the examples:

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

1. Check Service Health

curl -s "$AIRISKDB_BASE_URL/healthz"

Expected response:

{
  "status": "ok"
}

2. Submit One Signal

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",
      "registry": "npm"
    },
    "observed_at": 1711234567,
    "metadata": {
      "environment": "prod"
    }
  }'

The response has status 202 Accepted and returns a signal resource. Save the id from the response as <SIGNAL_ID>.

3. Fetch the Signal

curl -s "$AIRISKDB_BASE_URL/v1/signals/<SIGNAL_ID>" \
  -H "Authorization: Bearer $AIRISKDB_API_KEY"

Use this call to confirm that AIRiskDB stored the observation and associated it with the expected asset.

4. Lookup the Asset by Fingerprint

curl -s "$AIRISKDB_BASE_URL/v1/assets/lookup?fingerprints=$FINGERPRINT&include_candidates=true" \
  -H "Authorization: Bearer $AIRISKDB_API_KEY"

Lookup results can return:

Status	Meaning
`unknown`	No matching asset was found
`pending`	The asset exists but enrichment is not complete
`enriched`	An enriched asset match was returned

5. Expand Findings and AI-BOM

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

Use expanded fields when your integration needs the asset record and enrichment details in a single response.

Next Steps

Use API Examples for copy-paste curl, Python, and JavaScript workflows.
Use Reference for endpoint scopes, query parameters, response codes, and common conventions.

AIRiskDB Quickstart

On this page