SuperAlign Docs

AIRiskDB API Reference

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

Base URLs

ResourceURL
API roothttps://api.airiskdb.com
Versioned APIhttps://api.airiskdb.com/v1

Public API Routes

Signals

MethodPathRequired ScopeDescriptionResponse Codes
POST/v1/signalssignals:writeCreate one signal and trigger enrichment when applicable202, 400, 401, 500
POST/v1/signals/bulksignals:writeCreate 1 to 500 signals in one request202, 400, 401, 500
GET/v1/signals/{signal_id}signals:readRetrieve a stored signal200, 400, 401, 404, 500

Assets

MethodPathRequired ScopeDescriptionResponse Codes
GET/v1/assetsassets:readList assets with filters and pagination200, 400, 401, 500
GET/v1/assets/lookupassets:readLookup assets by fingerprint or name-based keys200, 400, 401, 500
GET/v1/assets/{fingerprint}assets:readRetrieve one asset by fingerprint200, 400, 401, 404, 500
GET/v1/assets/{fingerprint}/findingsassets:readRetrieve findings for an enriched asset200, 400, 401, 404, 500
GET/v1/assets/{fingerprint}/aibomassets:readRetrieve AI-BOM data for an enriched asset200, 400, 401, 404, 500
GET/v1/assets/{fingerprint}/threatsassets:readList threats that match an asset200, 400, 401, 404, 500

Threats

MethodPathRequired ScopeDescriptionResponse Codes
POST/v1/threatsthreats:writeCreate a shared threat record201, 400, 401, 403, 500
GET/v1/threatsthreats:readList shared threat records200, 400, 401, 500
GET/v1/threats/{threat_id}threats:readRetrieve one threat by ID200, 400, 401, 404, 500
POST/v1/threats/{threat_id}threats:writeUpdate mutable fields on a threat200, 400, 401, 403, 404, 500

Webhooks

MethodPathRequired ScopeDescriptionResponse Codes
POST/v1/webhookswebhooks:writeCreate a webhook subscription201, 400, 401, 500

Authentication and Scopes

Every /v1/* route requires:

Authorization: Bearer <AIRISKDB_API_KEY>

Public API keys can be issued with these scopes:

ScopeAllows
signals:writeSubmit one or more observed asset signals
signals:readRead submitted signals
assets:readList, lookup, and retrieve assets, findings, AI-BOMs, and asset threats
threats:readList and retrieve shared threat records
threats:writeCreate and update shared threat records
webhooks:writeRegister webhook subscriptions

Invalid, expired, revoked, or missing keys return 401 authentication_error. Keys without the required scope return 403 permission_error.

Idempotency

All POST routes require:

Idempotency-Key: <uuid>

Idempotency keys are scoped by method, path, livemode, and request body.

BehaviorResult
First successful request with a new keyResponse is processed and cached
Same key, same method, same path, same bodyCached response is replayed
Same key with a different request body400 idempotency_replay_mismatch
Missing or invalid key on POST400 invalid_request_error

Keys are retained for a 24-hour window.

Pagination

List routes use cursor-style pagination.

ParameterDescription
limitOptional page size. Defaults to 20. Minimum 1, maximum 100
starting_afterOptional forward cursor
ending_beforeOptional reverse cursor on routes that support it

List responses use this envelope:

{
  "object": "list",
  "data": [],
  "has_more": false,
  "url": "/v1/assets",
  "next_cursor": "aset_123"
}

Use next_cursor as the next starting_after value while has_more is true.

Expansions

AIRiskDB uses repeated expand[] query parameters.

ExpansionSupported Routes
expand[]=findingsGET /v1/assets, GET /v1/assets/{fingerprint}, GET /v1/assets/lookup
expand[]=aibomGET /v1/assets, GET /v1/assets/{fingerprint}, GET /v1/assets/lookup
expand[]=threatsGET /v1/assets/{fingerprint}/findings

Example:

curl -s "https://api.airiskdb.com/v1/assets/<FINGERPRINT>?expand[]=findings&expand[]=aibom" \
  -H "Authorization: Bearer <AIRISKDB_API_KEY>"

When an expandable field is not expanded, it may be absent, null, or represented as a stored identifier depending on the resource.

Query Parameters

GET /v1/assets

ParameterDescription
limitPage size
starting_afterForward pagination cursor
ending_beforeReverse pagination cursor
asset_typeFilter by asset type
enrichment_statusFilter by pending, enriched, failed, or stale
intrinsic_risk_severityFilter by critical, high, medium, low, or informational
expand[]findings or aibom

GET /v1/assets/lookup

ParameterDescription
fingerprintsRepeatable exact fingerprint lookup
lookup_nameRepeatable asset name lookup
lookup_versionRepeatable version value aligned by index with lookup_name
lookup_ecosystemRepeatable ecosystem value aligned by index with lookup_name
lookup_fingerprintRepeatable fallback fingerprint aligned by index with lookup_name
include_candidatesSet to true to include candidate matches
expand[]findings or aibom

Lookup notes:

  • Combined fingerprints and lookup keys must include between 1 and 500 entries.
  • lookup_name is required when any other lookup_* parameter is used.
  • Repeatable lookup_* parameters are aligned by index.
  • Name-only lookup can return flexible matches and candidates.

GET /v1/assets/{fingerprint}/aibom

ParameterDescription
format=jsonDefault. Returns the full AI-BOM resource
format=spdx_jsonReturns only the SPDX JSON document
format=spdx_tvReturns SPDX tag-value text

GET /v1/threats

ParameterDescription
limitPage size
starting_afterForward pagination cursor
ending_beforeReverse pagination cursor
categoryFilter by threat category
severityFilter by risk severity
affected_asset_typeFilter by affected asset type

Error Responses

All error responses use the same envelope:

{
  "error": {
    "type": "invalid_request_error",
    "code": "missing_required_param",
    "param": "fingerprint",
    "message": "The fingerprint field is required.",
    "request_id": "req_1234567890abcdef12345678"
  }
}

Known error types:

TypeMeaning
invalid_request_errorThe request is malformed or failed validation
authentication_errorThe API key is missing, invalid, expired, or revoked
permission_errorThe API key does not have the required scope
not_found_errorThe requested resource does not exist
conflict_errorThe request conflicts with current resource state
api_errorAIRiskDB encountered an internal error

Every response includes an X-Request-Id header. Error responses also include the request ID inside error.request_id. Include this ID when contacting SuperAlign support.

Resource Notes

Signal

A signal is an immutable observation submitted by a caller. Required fields are:

FieldDescription
fingerprintAsset fingerprint
asset_typeSupported asset type
org_idOrganization identifier
observed_atUnix timestamp for the observation

Optional fields include name, version, source_url, raw_manifest, and metadata.

Asset

Assets are global and fingerprint-keyed. Important fields include enrichment_status, intrinsic_risk_score, intrinsic_risk_severity, publisher_trust, benchmark_summary, findings, and aibom.

Finding

A finding captures derived capabilities, related threat links, ATLAS techniques, CVE IDs, score breakdowns, and benchmark details.

AI-BOM

An AI-BOM contains SPDX metadata, a machine-readable SPDX document, normalized component inventory, model lineage when derivable, and a monotonically increasing bom_version.

Threat

A threat is a shared intelligence record. Threats can include category, title, severity, confidence, affected asset types, fingerprints, ATLAS techniques, CVE ID, remediation, source, risk penalty, and metadata.

Webhook

A webhook subscription includes URL, event list, status, metadata, and a generated secret. The secret is returned once in the creation response.

AIRiskDB API Examples

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

On this page

Base URLs
Public API Routes
Signals
Assets
Threats
Webhooks
Authentication and Scopes
Idempotency
Pagination
Expansions
Query Parameters
GET /v1/assets
GET /v1/assets/lookup
GET /v1/assets/{fingerprint}/aibom
GET /v1/threats
Error Responses
Resource Notes
Signal
Asset
Finding
AI-BOM
Threat
Webhook