> ## Documentation Index
> Fetch the complete documentation index at: https://docs.root.io/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Root's REST API for querying patch status, accessing SBOMs and VEX statements, and managing registry configuration.

Root exposes a REST API for programmatic access to patch status, SBOM and VEX data, vulnerability reports, and registry management.

## Authentication

All API requests require a Bearer token:

```bash theme={null}
curl -H "Authorization: Bearer $ROOT_TOKEN" https://api.root.io/v1/...
```

Alternatively, use an API key with Basic Auth (API key as username, empty password):

```bash theme={null}
curl -u "apik_yourkey:" https://api.root.io/v1/...
```

To generate an API key, navigate to **Settings → API Keys** in the Root platform.

## Base URL

```
https://api.root.io/v1
```

## Endpoints

### Account

| Method | Path     | Description                           |
| ------ | -------- | ------------------------------------- |
| `GET`  | `/me`    | Get the current authenticated account |
| `GET`  | `/orgs/` | Get your organization                 |

### API Keys

| Method   | Path                    | Description            |
| -------- | ----------------------- | ---------------------- |
| `POST`   | `/api_keys/`            | Create a new API key   |
| `GET`    | `/api_keys/`            | List API keys          |
| `GET`    | `/api_keys/{apiKeyID}/` | Get a specific API key |
| `DELETE` | `/api_keys/{apiKeyID}/` | Delete an API key      |

### Subscriptions

| Method   | Path                               | Description                      |
| -------- | ---------------------------------- | -------------------------------- |
| `POST`   | `/subscriptions/`                  | Subscribe to an image or package |
| `GET`    | `/subscriptions/`                  | List your subscriptions          |
| `GET`    | `/subscriptions/{subscriptionID}/` | Get a specific subscription      |
| `DELETE` | `/subscriptions/`                  | Remove a subscription            |

### Patches

| Method | Path       | Description                     |
| ------ | ---------- | ------------------------------- |
| `GET`  | `/patches` | List CVE patches with filtering |

**Query parameters for `/patches`:**

| Parameter          | Type    | Description                                                                |
| ------------------ | ------- | -------------------------------------------------------------------------- |
| `cve_id`           | string  | Filter by CVE ID (e.g., `CVE-2024-1234`)                                   |
| `package_src_name` | string  | Filter by source package name                                              |
| `ecosystem`        | string  | Filter by ecosystem (`alpine`, `debian`, `ubuntu`, `pypi`, `npm`, `maven`) |
| `severities`       | string  | Comma-separated severities (`critical`, `high`, `medium`, `low`)           |
| `ticket_statuses`  | string  | Comma-separated statuses (`open`, `in_progress`, `done`, `deferred`)       |
| `order`            | string  | Sort order (e.g., `created_at:desc`)                                       |
| `limit`            | integer | Page size (default: 100, max: 1000)                                        |
| `after`            | string  | Cursor for pagination                                                      |

**Example:**

```bash theme={null}
# Get all patched critical CVEs in PyPI packages
curl -H "Authorization: Bearer $ROOT_TOKEN" \
  "https://api.root.io/v1/patches?ecosystem=pypi&severities=critical&ticket_statuses=done"
```

### Image Catalog

| Method | Path                       | Description                          |
| ------ | -------------------------- | ------------------------------------ |
| `GET`  | `/images/`                 | List images in Root Image Catalog    |
| `GET`  | `/images/{rriID}`          | Get image details                    |
| `GET`  | `/images/{imageRepo}/tags` | List tags for an image               |
| `GET`  | `/tags/`                   | List all tags                        |
| `GET`  | `/tags/{rrtID}`            | Get details for a specific tag       |
| `GET`  | `/tags/{rrtID}/sbom`       | Get SBOM download URL for a tag      |
| `GET`  | `/tags/{rrtID}/vex`        | Get VEX download URL for a tag       |
| `GET`  | `/tags/{rrtID}/provenance` | Get provenance attestation for a tag |

**Example:**

```bash theme={null}
# Get SBOM for an image tag
curl -H "Authorization: Bearer $ROOT_TOKEN" \
  "https://api.root.io/v1/images/tags/{rrtID}/sbom"

# Response includes a presigned URL - fetch the SBOM:
# curl -o sbom.json "https://presigned-url..."
```

### Packages

| Method | Path                                     | Description                      |
| ------ | ---------------------------------------- | -------------------------------- |
| `GET`  | `/packages/`                             | List packages                    |
| `GET`  | `/packages/{pkgID}/`                     | Get package details              |
| `GET`  | `/packages/{pkgID}/artifacts/patches`    | Get patches applied to a package |
| `GET`  | `/packages/{pkgID}/artifacts/provenance` | Get provenance for a package     |

**Package Catalog (pkg.root.io):**

```
GET https://pkg.root.io/packages/ecosystems/{ecosystem}/packages/{name}/versions
GET https://pkg.root.io/packages/ecosystems/{ecosystem}/packages/{name}/versions/{version}/cves
GET https://pkg.root.io/packages/ecosystems/{ecosystem}/packages/{name}/versions/{version}/details
GET https://pkg.root.io/packages/ecosystems/{ecosystem}/packages/{name}/versions/{version}/provenance/{arch}
```

### AVR Artifacts

AVR (Artifact Vulnerability Remediation) endpoints provide access to artifacts from Root's remediation pipeline:

| Method | Path                                 | Description                        |
| ------ | ------------------------------------ | ---------------------------------- |
| `GET`  | `/avrs/{avrID}/artifacts/sbom`       | Get SBOM for a remediated artifact |
| `GET`  | `/avrs/{avrID}/artifacts/vex`        | Get VEX for a remediated artifact  |
| `GET`  | `/avrs/{avrID}/artifacts/provenance` | Get SLSA provenance                |

### Public Feeds (No Auth Required)

| Method | Path                           | Description                                 |
| ------ | ------------------------------ | ------------------------------------------- |
| `GET`  | `/external/patch_feed`         | Public patch feed (filterable by ecosystem) |
| `GET`  | `/external/cve_feed`           | Public CVE feed                             |
| `GET`  | `/external/osv/{id}.json`      | OSV-format record for a specific CVE        |
| `GET`  | `/external/globals/sys_matrix` | Supported ecosystems and distros            |

**Patch feed query parameters:**

| Parameter          | Description                                                                |
| ------------------ | -------------------------------------------------------------------------- |
| `ecosystem`        | Filter by ecosystem (`alpine`, `debian`, `ubuntu`, `pypi`, `npm`, `maven`) |
| `os_distro_major`  | Filter by OS distro version (e.g., `22.04`)                                |
| `package_src_name` | Filter by package source name                                              |

## Rate Limits

API requests are rate-limited. If you exceed the limit, you'll receive a `429 Too Many Requests` response. The response headers include:

* `X-RateLimit-Limit` - requests allowed per window
* `X-RateLimit-Remaining` - requests remaining in the current window
* `Retry-After` - seconds to wait before retrying

For high-volume use cases, use pagination (`limit` + `after` cursor) rather than making many small requests.

## SDKs

Official Python and JavaScript SDKs are in development. In the meantime, any HTTP client works with the REST API. For Python:

```python theme={null}
import requests

headers = {"Authorization": f"Bearer {ROOT_TOKEN}"}
response = requests.get("https://api.root.io/v1/patches", headers=headers, params={
    "ecosystem": "pypi",
    "severities": "critical,high",
    "ticket_statuses": "done",
    "limit": 100
})
patches = response.json()
```