# AIRiskDB Quickstart



## Base URLs

Use the production API root for custom integrations:

```text
https://api.airiskdb.com
```

The versioned API root is:

```text
https://api.airiskdb.com/v1
```

***

## Authentication

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

```http
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:

```http
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:

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

### 1. Check Service Health

```bash
curl -s "$AIRISKDB_BASE_URL/healthz"
```

Expected response:

```json
{
  "status": "ok"
}
```

### 2. Submit One Signal

```bash
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

```bash
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

```bash
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

```bash
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](/docs/airiskdb/api-examples) for copy-paste `curl`, Python, and JavaScript workflows.
* Use [Reference](/docs/airiskdb/reference) for endpoint scopes, query parameters, response codes, and common conventions.