Security advisory discovery API

The advisory API lets you discover security advisories for volumes hosted on a bibliotheca. You can list all advisories that affect a given volume or fetch a single advisory by its local ID. Advisory records follow a structured schema compatible with OSV-style range/event semantics. No authentication is required for read operations. Advisory write operations — create, update, withdrawal — are bibliotheca-local and not standardized in v0.1.

Endpoints

GET /api/v1/advisories?volume={name}
GET /api/v1/advisories/{advisoryId}

List advisories for a volume

string

Volume name (scopeless or @scope/name). Returns all advisories that affect the specified volume.

GET /api/v1/advisories?volume=@acme/research-agent-pack

Fetch a single advisory

string

required

The bibliotheca-local advisory ID.

GET /api/v1/advisories/AV-2026-0042

Advisory response fields

object

required

Advisory identifier object.

Show id fields

string

required

Bibliotheca-local advisory identifier.

string

Preferred external identifier, e.g. CVE-2026-12345, GHSA-xxxx-yyyy-zzzz, or an OSV ID.

string[]

Additional external identifiers for this advisory.

object

required

Source ecosystem information.

Show source fields

string

required

One of cve, ghsa, osv, bibliotheca, or other.

string

URL to the original advisory source.

string

required

One of critical, high, medium, or low.

string

required

ISO 8601 timestamp when this advisory was first published.

string

required

ISO 8601 timestamp of the most recent update to this advisory.

object

Present when the advisory has been withdrawn.

Show withdrawn fields

string

required

ISO 8601 timestamp when the advisory was withdrawn.

string

Optional human-readable reason for withdrawal.

object

required

Affected volume and version range information.

Show affected fields

string

required

Affected volume name (scopeless or @scope/name).

string

Optional pkg:volume/... purl for the affected volume (without version).

object[]

required

One or more SemVer ranges describing affected versions.

Show range fields

string

required

Range type. semver for SemVer ranges.

object[]

required

Ordered events describing the affected version history. Each event object has exactly one key: introduced, fixed, lastAffected, or limit.

introduced: The version where the vulnerability was introduced. Use "0" as the beginning-of-time sentinel.
fixed: The version where the vulnerability was fixed (exclusive upper bound for affected range).
lastAffected: The last affected version (inclusive upper bound).
limit: An upper bound for the range.

object[]

Informational component-level impact notes. Does not change the normative volume-level advisory target.

object[]

Advisory relationships for tracking supersession, related advisories, or duplicates.

Show relationship fields

string

required

One of supersedes, superseded-by, related, or duplicate-of.

string

required

The advisory ID of the related advisory.

string

Short human-readable summary of the advisory.

string

Full human-readable details about the vulnerability.

Example advisory

{
  "id": {
    "local": "AV-2026-0042",
    "preferredExternal": "GHSA-xxxx-yyyy-zzzz",
    "aliases": ["CVE-2026-12345"]
  },
  "source": {
    "ecosystem": "ghsa",
    "url": "https://github.com/advisories/GHSA-xxxx-yyyy-zzzz"
  },
  "severity": "high",
  "published": "2026-05-01T12:00:00Z",
  "updated": "2026-05-10T09:30:00Z",
  "affected": {
    "volume": "@acme/research-agent-pack",
    "purl": "pkg:volume/%40acme/research-agent-pack",
    "ranges": [
      {
        "type": "semver",
        "events": [{ "introduced": "0" }, { "fixed": "1.4.0" }]
      }
    ]
  },
  "summary": "Prompt injection vulnerability in arxiv-search tool",
  "details": "Unsanitized query parameters in the arxiv-search component allow a malicious query string to inject instructions into the agent context."
}

List response envelope

The list endpoint returns a collection envelope:

{
  "items": [
    { ... },
    { ... }
  ]
}

Affected version semantics

Affected version ranges use OSV-style event sequences. Read the events in order to determine which versions are affected:

introduced: "0" means affected from the beginning of version history
fixed: "1.4.0" means versions >= 0 and < 1.4.0 are affected
lastAffected: "1.3.9" means versions up to and including 1.3.9 are affected

Advisory targeting in v0.1 is volume-level only. Component-level impact metadata in componentImpact is informational and does not narrow or change the normative volume-level advisory target.

Scanner findings are not advisory records by themselves. A bibliotheca may create or update an advisory based on scanner information under local policy, but the portable contract is the advisory read and discovery model, not scanner-result interchange.

​Endpoints

​List advisories for a volume

​Fetch a single advisory

​Advisory response fields

​Example advisory

​List response envelope

​Affected version semantics

Endpoints

List advisories for a volume

Fetch a single advisory

Advisory response fields

Example advisory

List response envelope

Affected version semantics