Skip to main content
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.

​
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.
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.
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: When you exceed the limit, the bibliotheca returns 429 Too Many Requests with a rate-limited problem type.

​
Endpoint families

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.