> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentvolumes.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Registry API overview and base URL

> Overview of the Agent Volumes bibliotheca HTTP API, covering versioning, base URL, authentication, response formats, and rate limiting tiers.

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](/spec/0.1.0-rc.1/api/capabilities).

```http theme={null}
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.

```http theme={null}
Authorization: Bearer <your-token>
```

See [Authentication](/spec/0.1.0-rc.1/api/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](https://www.rfc-editor.org/rfc/rfc9457).

```json theme={null}
{
  "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](/spec/0.1.0-rc.1/api/errors) for the complete slug table.

## Rate limiting

Bibliothecas should implement rate limiting. The recommended tiers are:

| Tier          | Limit         |
| ------------- | ------------- |
| Anonymous     | 60 req/min    |
| Authenticated | 300 req/min   |
| CI tokens     | 1,000 req/min |

When you exceed the limit, the bibliotheca returns `429 Too Many Requests` with a `rate-limited` problem type.

## Endpoint families

| Family                                                                    | Description                             |
| ------------------------------------------------------------------------- | --------------------------------------- |
| `POST /api/v1/volumes/{name}`                                             | Publish a new volume release            |
| `POST /api/v1/volumes/{name}/uploads/{uploadId}/finalize`                 | Finalize 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/search`                                                      | Search the catalog                      |
| `GET /api/v1/volumes/{name}/{version}/trust/summary`                      | Trust attachment summary                |
| `GET /api/v1/volumes/{name}/{version}/trust/detail`                       | Trust attachment detail                 |
| `POST /api/v1/volumes/{name}/{version}/trust/uploads`                     | Upload a trust attachment               |
| `POST /api/v1/volumes/{name}/{version}/trust/uploads/{uploadId}/finalize` | Finalize a trust attachment upload      |
| `GET /api/v1/advisories`                                                  | List security advisories                |
| `GET /api/v1/advisories/{advisoryId}`                                     | Fetch a single advisory                 |
| `GET /api/v1/capabilities`                                                | Bibliotheca 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.

<Note>
  The prose specification is the final normative authority. If a companion artifact appears to
  conflict with the prose, the prose wins.
</Note>