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 Agent Volumes Registry API is an HTTP API that bibliothecas expose for package operations, version discovery, trust metadata, advisory discovery, and capability introspection. Every operation maps to a resource under the /api/v1/ prefix, response bodies use JSON when present, and errors follow the RFC 9457 Problem Details format. You call the same API whether you are building a client library, a CI publishing tool, or a resolver.

​
Base URL and versioning

All endpoints are prefixed with /api/v1/. The v1 segment identifies the HTTP API major family, distinct from the Agent Volumes spec version. You can confirm the exact spec version a bibliotheca implements by calling the capabilities endpoint. 
GET https://registry.example.com/api/v1/capabilities

​
Authentication

Read operations — search, fetch, download, version index, trust metadata, advisories, and capabilities — require no authentication. Write operations — publish, unpublish, and trust upload — require a Bearer token in the Authorization header. Token issuance is bibliotheca-local and not standardized in v0.1. 
Authorization: Bearer <your-token>
See Authentication for the full authorization table and error responses.

​
Response format

Successful responses that include a body return application/json; some lifecycle operations, such as accepted unpublish requests, can return an empty success body. Error responses return application/problem+json following RFC 9457 Problem Details. 
{
  "type": "https://agentvolumes.org/problems/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "Volume 'my-volume' does not exist."
}
Problem type URIs follow the pattern https://agentvolumes.org/problems/<slug>. See Errors for the complete slug table.

​
Rate limiting

Bibliothecas should implement rate limiting. The recommended tiers are:
TierLimit
Anonymous60 req/min
Authenticated300 req/min
CI tokens1,000 req/min
When you exceed the limit, the bibliotheca returns 429 Too Many Requests with a rate-limited problem type.

​
Endpoint families

FamilyDescription
POST /api/v1/volumes/{name}Publish a new volume release
POST /api/v1/volumes/{name}/uploads/{uploadId}/finalizeFinalize a release upload
GET /api/v1/volumes/{name}/{version}Fetch release metadata
DELETE /api/v1/volumes/{name}/{version}Unpublish a release
GET /api/v1/index/volumes/{name}Version index for dependency resolution
GET /api/v1/searchSearch the catalog
GET /api/v1/volumes/{name}/{version}/trust/summaryTrust attachment summary
GET /api/v1/volumes/{name}/{version}/trust/detailTrust attachment detail
POST /api/v1/volumes/{name}/{version}/trust/uploadsUpload a trust attachment
POST /api/v1/volumes/{name}/{version}/trust/uploads/{uploadId}/finalizeFinalize a trust attachment upload
GET /api/v1/advisoriesList security advisories
GET /api/v1/advisories/{advisoryId}Fetch a single advisory
GET /api/v1/capabilitiesBibliotheca capability metadata
Package operation routes that start with /api/v1/volumes/{name} have scoped equivalents of the form /api/v1/volumes/@{scope}/{name}/.... Version index routes keep the /api/v1/index/volumes/ prefix, so a scoped version index is /api/v1/index/volumes/@{scope}/{name}.

​
OpenAPI contract

The normative machine-readable API contract is published as openapi/bibliotheca.openapi.yaml in the Agent Volumes specification repository. Companion JSON Schema artifacts for individual payload shapes are published under schemas/ in the same repository. See section 11 (Conformance) of the specification for the full companion artifact inventory.
The prose specification is the final normative authority. If a companion artifact appears to conflict with the prose, the prose wins.