Package version index for dependency resolution

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

string

required

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

string

Scope name for scoped volumes. Omit for scopeless volumes.

Response fields

The response is a collection envelope with an items array.

object[]

required

Array of version index rows. Each row represents one published version.

Show row fields

string

required

SemVer version string for this row.

string

sha256:<hex> normalized-file-tree digest when available. Not authoritative — verify against exact release metadata.

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.

object

required

Show status fields

string

required

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

string

Optional human-readable reason for the current state.

object

required

Show release fields

string

required

URL pointing to the authoritative exact release metadata endpoint for this 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

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

Prefer highest SemVer. Among eligible stable available candidates that satisfy the applicable constraints, prefer the candidate with the highest SemVer precedence.
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.
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.

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

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

​Endpoints

​Path parameters

​Response fields

​Example request and response

​Version lifecycle behavior for resolvers

​Client rules

​Relationship to search

Endpoints

Path parameters

Response fields

Example request and response

Version lifecycle behavior for resolvers

Client rules

Relationship to search