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 uses registry-local, resource-scoped bearer tokens for protected write operations. Tokens are opaque to clients — the bibliotheca derives authorization decisions from its own local state based on the token subject, the requested action, and the target resource. Token issuance is not standardized in v0.1; consult your bibliotheca’s documentation for how to obtain a token.

​
Which operations require authentication

OperationAuth requiredPortable authorization semantics
SearchNoN/A
Fetch release metadataNoN/A
DownloadNoN/A
Version indexNoN/A
Capability metadataNoN/A
Trust metadata (summary + detail)NoN/A
Advisory discoveryNoN/A
PublishYes (Bearer token)Authorized to publish the volume identity or namespace
UnpublishYes (Bearer token)Authorized to unpublish the volume identity or exact release
Trust uploadYes (Bearer token)Authorized to add trust attachments for the exact release

​
Passing the token

Include the bearer token in the Authorization header on every authenticated request. 
POST /api/v1/volumes/my-volume
Authorization: Bearer <your-token>
Content-Type: application/json

{
  "version": "1.0.0",
  "mediaType": "application/gzip"
}
The token value is an opaque string. Do not parse or decode it — treat it as a credential you pass verbatim.

​
Token format

Bearer tokens are:
  • Opaque — clients must not parse or decode the token value
  • Registry-local — tokens issued by one bibliotheca are not valid on another
  • Resource-scoped — a token may be authorized for a specific scope, volume, or release; the bibliotheca enforces the scope boundary

​
Error responses

If the token is missing, malformed, unknown, expired, or revoked, the bibliotheca returns 401 Unauthorized: 
{
  "type": "https://agentvolumes.org/problems/authentication-required",
  "title": "Authentication required",
  "status": 401,
  "detail": "Bearer token is missing or invalid."
}
If the token is valid but the caller lacks the needed permission for the requested action or resource, the bibliotheca returns 403 Forbidden: 
{
  "type": "https://agentvolumes.org/problems/authorization-failed",
  "title": "Authorization failed",
  "status": 403,
  "detail": "This token is not authorized to publish to @acme/my-volume."
}
A 401 means authentication failed — the token itself is the problem. A 403 means authentication succeeded but the token lacks permission for this specific operation or resource.

​
Authenticated request example

The following example creates a release upload intent for a scoped volume: 
POST /api/v1/volumes/@acme/research-agent-pack
Authorization: Bearer eyJhbGc...
Content-Type: application/json

{
  "version": "2.0.0",
  "mediaType": "application/gzip",
  "declaredDigest": "sha256:a3f2b8c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2"
}
Token issuance — how you register, log in, or generate API tokens — is bibliotheca-local and is not standardized in Agent Volumes v0.1.