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

# Fetch volume release metadata

> GET /api/v1/volumes/{name}/{version} — retrieve release metadata including purl, integrity digest, lifecycle status, distribution metadata, and external dependency declarations.

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

```http theme={null}
GET /api/v1/volumes/{name}/{version}
GET /api/v1/volumes/@{scope}/{name}/{version}
```

### Path parameters

<ParamField path="name" type="string" required>
  Volume name. Lowercase alphanumeric and hyphens, 1–128 characters.
</ParamField>

<ParamField path="scope" type="string">
  Scope name for scoped volumes. Lowercase alphanumeric and hyphens, 1–64 characters. Omit for
  scopeless volumes.
</ParamField>

<ParamField path="version" type="string" required>
  SemVer version string, e.g. `1.4.0`.
</ParamField>

## Response fields

<ResponseField name="name" type="string" required>
  Canonical full user-facing volume name. Scopeless releases use `name`; scoped releases use
  `@scope/name`.
</ResponseField>

<ResponseField name="version" type="string" required>
  SemVer version string for this release.
</ResponseField>

<ResponseField name="purl" type="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`.
</ResponseField>

<ResponseField name="integrity" type="string" required>
  `sha256:<hex>` digest of the normalized file tree. Verify downloaded content against this value before installation or trust evaluation.
</ResponseField>

<ResponseField name="status" type="object" required>
  Lifecycle status for this release.

  <Expandable title="status fields">
    <ResponseField name="status.state" type="string" required>
      One of `available`, `yanked`, `tombstoned`, `blocked`, or `unavailable`.
    </ResponseField>

    <ResponseField name="status.reason" type="string">
      Optional human-readable explanation of the current state.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="dist" type="object">
  Delivery metadata. Present for `available` and `yanked` releases. Not present for `tombstoned`, `blocked`, or `unavailable` releases.

  <Expandable title="dist fields">
    <ResponseField name="dist.source" type="string" required>
      Delivery source type. `cdn` for hosted archive; `git` for Git-backed delivery.
    </ResponseField>

    <ResponseField name="dist.mediaType" type="string">
      Required for `cdn` source. The portable hosted archive media type is `application/gzip`.
    </ResponseField>

    <ResponseField name="dist.url" type="string">
      Required for `cdn` source. Opaque download URL for the `.tar.gz` archive.
    </ResponseField>

    <ResponseField name="dist.repository" type="string">
      Required for `git` source. Source repository URL.
    </ResponseField>

    <ResponseField name="dist.ref" type="string">
      Required for `git` source. Concrete Git reference for reproducible resolution.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="externalDependencies" type="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.
</ResponseField>

## Example request and response

```http theme={null}
GET /api/v1/volumes/@acme/research-agent-pack/1.4.0
```

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

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

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