Fetch volume release metadata

Fetching release metadata gives you the authoritative record for a single published version of a volume. The response includes the canonical package identity, the immutable content digest, lifecycle status, optional external dependency declarations, and conditional delivery metadata for installable releases. No authentication is required.

Endpoints

GET /api/v1/volumes/{name}/{version}
GET /api/v1/volumes/@{scope}/{name}/{version}

Path parameters

string

required

Volume name. Lowercase alphanumeric and hyphens, 1–128 characters.

string

Scope name for scoped volumes. Lowercase alphanumeric and hyphens, 1–64 characters. Omit for scopeless volumes.

string

required

SemVer version string, e.g. 1.4.0.

Response fields

string

required

Canonical full user-facing volume name. Scopeless releases use name; scoped releases use @scope/name.

string

required

SemVer version string for this release.

string

required

Canonical pkg:volume/...@version identifier for this release. For scoped volumes, the scope is percent-encoded as %40, for example pkg:volume/%40acme/research-agent-pack@1.4.0.

string

required

sha256:<hex> digest of the normalized file tree. Verify downloaded content against this value before installation or trust evaluation.

object

required

Lifecycle status for this release.

Show status fields

string

required

One of available, yanked, tombstoned, blocked, or unavailable.

string

Optional human-readable explanation of the current state.

object

Delivery metadata. Present for available and yanked releases. Not present for tombstoned, blocked, or unavailable releases.

Show dist fields

string

required

Delivery source type. cdn for hosted archive; git for Git-backed delivery.

string

Required for cdn source. The portable hosted archive media type is application/gzip.

string

Required for cdn source. Opaque download URL for the .tar.gz archive.

string

Required for git source. Source repository URL.

string

Required for git source. Concrete Git reference for reproducible resolution.

object[]

External package dependency declarations copied from the release manifest. These are audit metadata and potential-exposure inputs, not resolver inputs. Each item contains declarationKey, purl, constraint, and purpose; components is optional.

Example request and response

GET /api/v1/volumes/@acme/research-agent-pack/1.4.0

{
  "name": "@acme/research-agent-pack",
  "version": "1.4.0",
  "purl": "pkg:volume/%40acme/research-agent-pack@1.4.0",
  "integrity": "sha256:a3f2b8c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2",
  "status": {
    "state": "available"
  },
  "externalDependencies": [
    {
      "declarationKey": "av-extdep-v1:sha256:1111111111111111111111111111111111111111111111111111111111111111",
      "purl": "pkg:npm/%40modelcontextprotocol/sdk",
      "constraint": "vers:npm/>=1.7.0|<2.0.0",
      "purpose": "runtime"
    },
    {
      "declarationKey": "av-extdep-v1:sha256:2222222222222222222222222222222222222222222222222222222222222222",
      "purl": "pkg:pypi/requests?extra=socks",
      "constraint": "vers:pypi/>=2.31.0|<3.0.0",
      "purpose": "runtime",
      "components": ["arxiv-search"]
    }
  ],
  "dist": {
    "source": "cdn",
    "mediaType": "application/gzip",
    "url": "https://cdn.example.com/volumes/%40acme/research-agent-pack/1.4.0.tar.gz"
  }
}

Version lifecycle states and client behavior

State	Ordinary resolution	Exact fetch / install
`available`	Allowed	Allowed
`yanked`	Excluded	Allowed — surface a `yanked-version` warning before installing
`tombstoned`	Excluded	Fails — version identity preserved but artifact not installable
`blocked`	Excluded	Fails
`unavailable`	Excluded	Fails with an availability or inconsistent-registry-state error

For blocked, tombstoned, or unavailable releases, portable install behavior fails because no installable dist is available. A bibliotheca should use RFC 9457 Problem Details for failure responses, and may expose non-installable audit metadata where the API contract permits it.

Always verify the downloaded archive’s normalized-file-tree digest against the integrity field before installation or trust evaluation. If they disagree, reject the release as inconsistent.

Route identity and purl matching

The name and purl fields in the response must match the route you requested. If they do not, treat the response as inconsistent registry state and fail rather than silently accepting either representation. For scoped volumes, the response name includes the scope prefix (@acme/research-agent-pack) and the purl uses the percent-encoded form (%40acme). These are not byte-for-byte interchangeable — compare purl strings only after parsing and validating the purl fields.

Delivery metadata

Delivery metadata (dist) is subordinate to integrity. For cdn, download from dist.url; for git, resolve dist.repository at dist.ref. In both cases, reconstruct the normalized-file-tree digest and reject the release if it disagrees with integrity. HTTP redirects, CDN caches, Git hosting choices, and backend storage choices do not change this requirement.

​Endpoints

​Path parameters

​Response fields

​Example request and response

​Version lifecycle states and client behavior

​Route identity and purl matching

​Delivery metadata

Endpoints

Path parameters

Response fields

Example request and response

Version lifecycle states and client behavior

Route identity and purl matching

Delivery metadata