API Reference

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:

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):

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:

# 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:

# 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)

These endpoints are served at the root of api.root.io (no /v1 prefix).

Method	Path	Description
`GET`	`https://api.root.io/external/patch_feed`	Public patch feed (filterable by ecosystem)
`GET`	`https://api.root.io/external/osv/all.json`	OSV-format index of all Root-tracked CVEs
`GET`	`https://api.root.io/external/osv/all.zip`	Bulk download of the full OSV feed
`GET`	`https://api.root.io/external/osv/{osv_id}.json`	OSV-format record for a specific CVE
`GET`	`https://api.root.io/external/globals/sys_matrix`	Supported ecosystems and distros

Fetching a single OSV record:

curl -X GET "https://api.root.io/external/osv/OSV-12345.json" \
  -H "accept: application/json"

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:

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()

Documentation Index

​Authentication

​Base URL

​Endpoints

​Account

​API Keys

​Subscriptions

​Patches

​Image Catalog

​Packages

​AVR Artifacts

​Public Feeds (No Auth Required)

​Rate Limits

​SDKs