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

# Security advisory discovery API

> GET /api/v1/advisories — list and retrieve security advisories for volumes by advisory ID or volume name. Includes severity, affected ranges, and relationships.

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

```http theme={null}
GET /api/v1/advisories?volume={name}
GET /api/v1/advisories/{advisoryId}
```

### List advisories for a volume

<ParamField query="volume" type="string">
  Volume name (scopeless or `@scope/name`). Returns all advisories that affect the specified volume.
</ParamField>

```http theme={null}
GET /api/v1/advisories?volume=@acme/research-agent-pack
```

### Fetch a single advisory

<ParamField path="advisoryId" type="string" required>
  The bibliotheca-local advisory ID.
</ParamField>

```http theme={null}
GET /api/v1/advisories/AV-2026-0042
```

## Advisory response fields

<ResponseField name="id" type="object" required>
  Advisory identifier object.

  <Expandable title="id fields">
    <ResponseField name="id.local" type="string" required>
      Bibliotheca-local advisory identifier.
    </ResponseField>

    <ResponseField name="id.preferredExternal" type="string">
      Preferred external identifier, e.g. `CVE-2026-12345`, `GHSA-xxxx-yyyy-zzzz`, or an OSV ID.
    </ResponseField>

    <ResponseField name="id.aliases" type="string[]">
      Additional external identifiers for this advisory.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="source" type="object" required>
  Source ecosystem information.

  <Expandable title="source fields">
    <ResponseField name="source.ecosystem" type="string" required>
      One of `cve`, `ghsa`, `osv`, `bibliotheca`, or `other`.
    </ResponseField>

    <ResponseField name="source.url" type="string">
      URL to the original advisory source.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="severity" type="string" required>
  One of `critical`, `high`, `medium`, or `low`.
</ResponseField>

<ResponseField name="published" type="string" required>
  ISO 8601 timestamp when this advisory was first published.
</ResponseField>

<ResponseField name="updated" type="string" required>
  ISO 8601 timestamp of the most recent update to this advisory.
</ResponseField>

<ResponseField name="withdrawn" type="object">
  Present when the advisory has been withdrawn.

  <Expandable title="withdrawn fields">
    <ResponseField name="withdrawn.at" type="string" required>
      ISO 8601 timestamp when the advisory was withdrawn.
    </ResponseField>

    <ResponseField name="withdrawn.reason" type="string">
      Optional human-readable reason for withdrawal.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="affected" type="object" required>
  Affected volume and version range information.

  <Expandable title="affected fields">
    <ResponseField name="affected.volume" type="string" required>
      Affected volume name (scopeless or `@scope/name`).
    </ResponseField>

    <ResponseField name="affected.purl" type="string">
      Optional `pkg:volume/...` purl for the affected volume (without version).
    </ResponseField>

    <ResponseField name="affected.ranges" type="object[]" required>
      One or more SemVer ranges describing affected versions.

      <Expandable title="range fields">
        <ResponseField name="ranges[].type" type="string" required>
          Range type. `semver` for SemVer ranges.
        </ResponseField>

        <ResponseField name="ranges[].events" type="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.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="affected.componentImpact" type="object[]">
      Informational component-level impact notes. Does not change the normative volume-level advisory target.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="relationships" type="object[]">
  Advisory relationships for tracking supersession, related advisories, or duplicates.

  <Expandable title="relationship fields">
    <ResponseField name="relationships[].type" type="string" required>
      One of `supersedes`, `superseded-by`, `related`, or `duplicate-of`.
    </ResponseField>

    <ResponseField name="relationships[].target" type="string" required>
      The advisory ID of the related advisory.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="summary" type="string">
  Short human-readable summary of the advisory.
</ResponseField>

<ResponseField name="details" type="string">
  Full human-readable details about the vulnerability.
</ResponseField>

## Example advisory

```json theme={null}
{
  "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:

```json theme={null}
{
  "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

<Note>
  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.
</Note>

<Warning>
  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.
</Warning>