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

# Package version index for dependency resolution

> GET /api/v1/index/volumes/{name} — machine-facing version index rows for resolver inputs and candidate selection before exact metadata fetch.

The version index is a machine-facing resolver input, not a search surface. It gives you a package-scoped collection of version rows that a resolver can use to discover eligible version candidates and prune them against dependency constraints. Each row includes the SemVer version string, integrity value, dependency declarations, lifecycle status, and a pointer to the authoritative exact release metadata endpoint. You must still fetch exact release metadata before installation or trust evaluation — the index is not authoritative on its own. No authentication is required.

## Endpoints

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

### 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. Omit for scopeless volumes.
</ParamField>

## Response fields

The response is a collection envelope with an `items` array.

<ResponseField name="items" type="object[]" required>
  Array of version index rows. Each row represents one published version.

  <Expandable title="row fields">
    <ResponseField name="version" type="string" required>
      SemVer version string for this row.
    </ResponseField>

    <ResponseField name="integrity" type="string">
      `sha256:<hex>` normalized-file-tree digest when available. Not authoritative — verify against exact release metadata.
    </ResponseField>

    <ResponseField name="dependencies" type="object">
      Volume-level dependency declarations for this version. Keys are volume names (scopeless or `@scope/name`); values are portable v0.1 SemVer range expressions. Use these for candidate pruning during resolution.
    </ResponseField>

    <ResponseField name="status" type="object" required>
      <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 reason for the current state.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="release" type="object" required>
      <Expandable title="release fields">
        <ResponseField name="release.url" type="string" required>
          URL pointing to the authoritative exact release metadata endpoint for this version.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

## Example request and response

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

```json theme={null}
{
  "items": [
    {
      "version": "1.4.0",
      "integrity": "sha256:a3f2b8c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2",
      "dependencies": {
        "search-toolkit": "^2.0.0"
      },
      "status": {
        "state": "available"
      },
      "release": {
        "url": "/api/v1/volumes/@acme/research-agent-pack/1.4.0"
      }
    },
    {
      "version": "1.3.2",
      "integrity": "sha256:b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2",
      "dependencies": {
        "search-toolkit": "^1.8.0"
      },
      "status": {
        "state": "yanked",
        "reason": "Security fix available in 1.4.0"
      },
      "release": {
        "url": "/api/v1/volumes/@acme/research-agent-pack/1.3.2"
      }
    },
    {
      "version": "1.2.0",
      "status": {
        "state": "tombstoned"
      },
      "release": {
        "url": "/api/v1/volumes/@acme/research-agent-pack/1.2.0"
      }
    }
  ]
}
```

## Version lifecycle behavior for resolvers

| State         | Ordinary resolution | Exact pinned fetch / install                        |
| ------------- | ------------------- | --------------------------------------------------- |
| `available`   | Allowed             | Allowed                                             |
| `yanked`      | Excluded            | Allowed with warning                                |
| `tombstoned`  | Excluded            | Fails unless using non-baseline cache-only behavior |
| `blocked`     | Excluded            | Fails                                               |
| `unavailable` | Excluded            | Fails or reports an availability error              |

During ordinary dependency resolution, select only `available` candidates. Never select `yanked`, `tombstoned`, `blocked`, or `unavailable` versions during ordinary resolution.

## Client rules

1. **Prefer highest SemVer.** Among eligible stable `available` candidates that satisfy the applicable constraints, prefer the candidate with the highest SemVer precedence.

2. **Always fetch exact release metadata before installation.** The version index is a candidate discovery input, not an authoritative release record. Call the endpoint in `release.url` and verify the result before installing.

3. **Treat index/metadata conflicts as inconsistent registry state.** If version index data conflicts with exact release metadata (for example, different lifecycle states or mismatched integrity values), treat this as an inconsistent registry state error rather than silently preferring either representation.

<Warning>
  Never use version index rows as a substitute for exact release metadata during installation or
  trust evaluation. The `integrity` value in an index row is informational. Only the `integrity`
  returned by the exact release metadata endpoint is authoritative.
</Warning>

## Relationship to search

The version index and the search endpoint serve different purposes:

|                       | Version index                | Search                           |
| --------------------- | ---------------------------- | -------------------------------- |
| **Purpose**           | Resolver candidate discovery | Human-oriented catalog discovery |
| **Ordering**          | SemVer                       | Bibliotheca-local ranking        |
| **Scope**             | One package                  | Entire catalog                   |
| **Use in resolution** | Yes                          | Never                            |

<Note>
  Bibliothecas update the version index promptly when publish, unpublish, yank, tombstone, blocking,
  or equivalent version-state changes occur.
</Note>