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.

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

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

​
Path parameters

​
name
string
required
Volume name. Lowercase alphanumeric and hyphens, 1–128 characters.
​
scope
string
Scope name for scoped volumes. Omit for scopeless volumes.

​
Response fields

The response is a collection envelope with an items array.
​
items
object[]
required
Array of version index rows. Each row represents one published version.

​
Example request and response

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

{
  "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

StateOrdinary resolutionExact pinned fetch / install
availableAllowedAllowed
yankedExcludedAllowed with warning
tombstonedExcludedFails unless using non-baseline cache-only behavior
blockedExcludedFails
unavailableExcludedFails 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.
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.
The version index and the search endpoint serve different purposes:
Version indexSearch
PurposeResolver candidate discoveryHuman-oriented catalog discovery
OrderingSemVerBibliotheca-local ranking
ScopeOne packageEntire catalog
Use in resolutionYesNever
Bibliothecas update the version index promptly when publish, unpublish, yank, tombstone, blocking, or equivalent version-state changes occur.