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.
All Agent Volumes Registry API error responses use RFC 9457 Problem Details with the application/problem+json content type. Each error has a type URI that identifies the problem category, a human-readable title, and an HTTP status code. An optional detail field provides context-specific information about the specific failure. The type URI is the stable machine-readable identifier your client should switch on — not the title, which may vary.
{
"type": "https://agentvolumes.org/problems/not-found",
"title": "Not Found",
"status": 404,
"detail": "Volume '@acme/research-agent-pack' does not exist.",
"instance": "/api/v1/volumes/@acme/research-agent-pack/1.4.0"
}
| Field | Type | Description |
|---|
type | string (URI) | Machine-readable problem type identifier. Always present. |
title | string | Human-readable problem title. Always present. |
status | integer | HTTP status code repeated in the body. Always present. |
detail | string | Context-specific human-readable explanation. Optional. |
instance | string (URI reference) | Reference to the specific occurrence. Optional. |
Problem type URIs
All Agent Volumes problem type URIs follow the pattern:
https://agentvolumes.org/problems/<slug>
Complete error table
| Slug | Status | Meaning |
|---|
authentication-required | 401 | Bearer authentication is missing, malformed, unknown, expired, or revoked |
authorization-failed | 403 | The authenticated caller is not authorized for the requested operation or resource |
not-found | 404 | The requested resource does not exist or is not visible to the caller |
validation-failed | 400 | Request payload, parameters, manifest, or metadata failed validation |
invalid-manifest | 400 | A submitted volume.toml is structurally or semantically invalid |
invalid-archive | 400 | A submitted hosted archive violates the v0.1 archive transport profile |
identity-mismatch | 409 | A package identity disagrees with its route, manifest, or metadata |
version-conflict | 409 | The target version already exists or cannot be reused |
digest-mismatch | 400 | Submitted or resolved bytes do not match the declared digest |
subject-binding-mismatch | 400 | A trust artifact does not bind to the intended release subject |
inconsistent-registry-state | 409 | Index, exact metadata, or trust metadata cannot be reconciled |
upload-expired | 410 | An upload intent expired before finalization |
missing-uploaded-bytes | 400 | Finalization was requested before upload bytes were available |
invalid-upload-state | 409 | The upload intent is not in a state that can be finalized |
idempotency-conflict | 409 | A reused idempotency key conflicts with an earlier request |
payload-too-large | 413 | The submitted payload exceeds the bibliotheca’s accepted limit |
unsupported-media-type | 415 | The submitted payload media type is not supported |
permission-escalation | 400 | Component permissions exceed the parent volume permission boundary |
rate-limited | 429 | The request was rate limited |
https://agentvolumes.org/problems/ namespace.
Endpoint-to-error mapping
| Endpoint | Common problem slugs |
|---|
GET /api/v1/search | validation-failed, rate-limited |
GET /api/v1/index/volumes/... | not-found, inconsistent-registry-state, rate-limited |
GET /api/v1/volumes/{name}/{version} | authorization-failed, not-found, inconsistent-registry-state, rate-limited |
POST /api/v1/volumes/{name} | authentication-required, authorization-failed, validation-failed, version-conflict, idempotency-conflict, rate-limited |
POST /api/v1/volumes/{name}/uploads/{uploadId}/finalize | authentication-required, authorization-failed, not-found, invalid-manifest, invalid-archive, digest-mismatch, identity-mismatch, missing-uploaded-bytes, invalid-upload-state, idempotency-conflict, upload-expired, payload-too-large, unsupported-media-type, permission-escalation, rate-limited |
GET /api/v1/volumes/{name}/{version}/trust/summary | not-found, inconsistent-registry-state, rate-limited |
GET /api/v1/volumes/{name}/{version}/trust/detail | not-found, inconsistent-registry-state, rate-limited |
POST /api/v1/volumes/{name}/{version}/trust/uploads | authentication-required, authorization-failed, not-found, subject-binding-mismatch, idempotency-conflict, payload-too-large, unsupported-media-type, rate-limited |
POST /api/v1/volumes/{name}/{version}/trust/uploads/{uploadId}/finalize | authentication-required, authorization-failed, not-found, missing-uploaded-bytes, invalid-upload-state, digest-mismatch, subject-binding-mismatch, idempotency-conflict, upload-expired, payload-too-large, unsupported-media-type, rate-limited |
GET /api/v1/advisories | validation-failed, rate-limited |
GET /api/v1/advisories/{advisoryId} | not-found, rate-limited |
GET /api/v1/capabilities | rate-limited |
Authentication and authorization errors
A 401 always means the token itself is the problem — it is missing, malformed, unknown, expired, or revoked:
{
"type": "https://agentvolumes.org/problems/authentication-required",
"title": "Authentication required",
"status": 401
}
403 means authentication succeeded but the token lacks permission for the specific operation or resource:
{
"type": "https://agentvolumes.org/problems/authorization-failed",
"title": "Authorization failed",
"status": 403,
"detail": "This token is not authorized to publish to @acme/my-volume."
}
Rate limit errors
When you exceed a rate limit tier, you receive:
{
"type": "https://agentvolumes.org/problems/rate-limited",
"title": "Rate limited",
"status": 429
}
Idempotency key errors
If you pass both an Idempotency-Key header and an idempotencyKey body field with different values, or if you reuse a key with conflicting request parameters, you receive:
{
"type": "https://agentvolumes.org/problems/idempotency-conflict",
"title": "Idempotency conflict",
"status": 409
}
Upload lifecycle errors
| Scenario | Problem slug | Status |
|---|
| Finalize called before bytes were uploaded | missing-uploaded-bytes | 400 |
| Upload intent expired before finalize | upload-expired | 410 |
| Intent is in a state that cannot be finalized | invalid-upload-state | 409 |
| Uploaded bytes don’t match declared digest | digest-mismatch | 400 |
| Trust artifact doesn’t bind to the release subject | subject-binding-mismatch | 400 |
Permission escalation errors
If a volume.toml declares a component with permissions broader than its parent volume permits and a bibliotheca detects that escalation during validation, it can return:
{
"type": "https://agentvolumes.org/problems/permission-escalation",
"title": "Permission escalation",
"status": 400,
"detail": "Component 'arxiv-search' declares network=read-write but the volume permits only network=read."
}
Clients must fail before submission when they detect permission escalation locally. Do not rely
solely on the server to catch this — validate your volume.toml before calling the publish
endpoint.
