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 capabilities endpoint is your primary structured discovery surface for registry-wide facts about a bibliotheca. Before your client starts making API calls, fetch capabilities to learn which API surfaces are available, what scope policy the bibliotheca enforces, which delivery modes it supports, and which upload profiles it advertises. No authentication is required.

​
Endpoint

GET /api/v1/capabilities

​
Response fields

​
schemaVersion
string
required
Capability metadata document-shape major version. The v0.1 baseline value is "1".
​
specVersion
string
required
Agent Volumes specification release implemented by this bibliotheca, e.g. "0.1.0-rc.1".
​
compatibleSpecVersions
string[]
Explicit set of exact Agent Volumes spec versions this bibliotheca claims compatibility with. This is an exact-version set, not a SemVer range expression. Treat each value as an exact string to match against.
​
apiVersion
string
required
HTTP API major family advertised by this bibliotheca. The v0.1 baseline value is "v1". This is not a complete spec compatibility boundary on its own.
​
scopePolicy
object
required
Describes the bibliotheca’s scope/scopeless namespace policy.
​
deliveryModes
string[]
required
Delivery modes supported by this bibliotheca. Known v0.1 baseline values: cdn (hosted archive delivery) and git (Git-backed source delivery). Unknown values are ignored by baseline clients.
​
apis
object
required
Availability flags for optional API surfaces.
​
uploadProfiles
object
Supported upload profiles by upload surface. Required when apis.releaseUploads or apis.trustUploads is true.
​
extensions
object
Reserved extension container for non-core capability fields. Extension data is partitioned by namespace keys. Keys follow the same naming rules as Agent Volumes name segments: lowercase ASCII letters, digits, and hyphens, with no leading hyphen, trailing hyphen, or consecutive hyphens. The namespace keys agent-volumes, core, and spec are reserved for the specification and cannot be used for ordinary extensions.
​
cache
object
Optional caching guidance for this document.

​
Example response

GET /api/v1/capabilities

{
  "schemaVersion": "1",
  "specVersion": "0.1.0-rc.1",
  "compatibleSpecVersions": ["0.1.0-rc.1"],
  "apiVersion": "v1",
  "scopePolicy": {
    "scopesSupported": true,
    "scopelessSupported": true,
    "scopesRequired": false,
    "curatedScopelessModel": true
  },
  "deliveryModes": ["cdn"],
  "apis": {
    "trustMetadata": true,
    "versionIndex": true,
    "releaseUploads": true,
    "trustUploads": true,
    "advisories": true
  },
  "uploadProfiles": {
    "releaseUploads": ["http-put"],
    "trustUploads": ["http-put"]
  },
  "cache": {
    "maxAgeSeconds": 300,
    "revalidate": true
  }
}

​
Client rules

Ignore unknown fields. Your client must not reject a capability metadata document solely because it contains unknown fields or values. Unknown capability fields and delivery modes are ignored by baseline clients. compatibleSpecVersions is an exact-version set. Do not interpret the values as SemVer ranges. Each string is an exact version to match against, not a constraint expression. apiVersion is the HTTP API family, not the full spec compatibility boundary. Use specVersion and compatibleSpecVersions to assess spec-level compatibility. Check uploadProfiles before uploading. If your client supports only http-put and the bibliotheca advertises only unsupported profiles, fail with a local unsupported-upload-profile diagnostic rather than proceeding with an unsupported transfer mode.

​
Bridge metadata and migration warnings

Capability metadata can be accompanied by extension-to-core bridge metadata when an extension field is being promoted into the core specification. Bridge metadata uses schemas/bridge-metadata.schema.json and carries these fields:
FieldMeaning
activeAlways true for a bridge metadata object.
canonicalFormThe canonical core field or representation clients should prefer.
statusOne of bridge-active, bridge-ending, or bridge-ended.
removalTargetObject describing the target spec version, phase, or profile where the bridge can be removed.
acceptedAliasesOptional list of extension aliases accepted during the bridge period.
warningCategoryFixed to migration when present.
During a bridge period, clients surface migration warnings instead of silently treating the alias as ordinary extension data. This behavior is covered by AV-CLI-016 and the bridge-metadata.json / bridge-metadata-status-variants.json fixtures. Warning payloads use schemas/warning.schema.json. The base schema requires a slug-like category, allows optional message, path, field, value, and context fields, and leaves category-specific context semantics to the relevant fixture or schema. Core v0.1 warning categories include unknown-field, deprecated, migration, unknown-capability-field, unknown-capability-value, yanked-version, stale-trust-evidence-only, insufficient-current-trust-evidence, noncanonical-entrypoint, and external-dependency-potential-exposure.
Fetch capabilities once at startup and cache the response according to the cache hints. Capability metadata changes infrequently — there is no need to re-fetch it on every operation.
When apis.releaseUploads or apis.trustUploads is true, the uploadProfiles object is required and must include "http-put" for the corresponding upload surface. This is a conformance requirement, not just a recommendation.