Skip to main content

Documentation Index

Fetch the complete documentation index at: https://agentvolumes.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

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

​
name
string
required
Volume name. Lowercase alphanumeric and hyphens, 1–128 characters.
​
scope
string
Scope name for scoped volumes. Lowercase alphanumeric and hyphens, 1–64 characters. Omit for scopeless volumes.
​
version
string
required
SemVer version string, e.g. 1.4.0.

​
Response fields

​
name
string
required
Canonical full user-facing volume name. Scopeless releases use name; scoped releases use @scope/name.
​
version
string
required
SemVer version string for this release.
​
purl
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.
​
integrity
string
required
sha256:<hex> digest of the normalized file tree. Verify downloaded content against this value before installation or trust evaluation.
​
status
object
required
Lifecycle status for this release.
​
dist
object
Delivery metadata. Present for available and yanked releases. Not present for tombstoned, blocked, or unavailable releases.
​
externalDependencies
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

StateOrdinary resolutionExact fetch / install
availableAllowedAllowed
yankedExcludedAllowed — surface a yanked-version warning before installing
tombstonedExcludedFails — version identity preserved but artifact not installable
blockedExcludedFails
unavailableExcludedFails 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.