API Reference
BitVault exposes a public REST API at /v1/... consumed by the web app, CLI,
third-party integrations, and the (future) React Native mobile client. The API
is URI-versioned (ADR-0015). The authoritative specification is the OpenAPI 3.1
document generated from the proto definitions:
gen/openapi/bitvault.yaml
Never edit this file manually — it is regenerated by task gen from proto/.
API Design Principles
- URI versioning:
/v1/...is a stable, long-lived contract. Breaking changes require/v2/with a documented overlap window. - Bytes bypass compute: upload/download flows issue presigned URLs (ADR-0011); the REST API never streams file content.
- Machine-readable errors: every error response includes a typed
codefrompkg/apperrfor programmatic handling. - Stable error taxonomy: error codes are versioned alongside the API and never silently repurposed.
Contents
| Page | What it covers |
|---|---|
| Versioning | URI versioning, backwards compatibility rules, deprecation, buf breaking-change CI |
| Authentication | Bearer tokens, OAuth 2.1 + PKCE, API tokens, rate-limit headers |
| Errors | Error shape, HTTP status mapping, request_id for support |
Endpoint Groups
| Group | Base path | Owned by |
|---|---|---|
| Files & folders | /v1/files |
File & Metadata context |
| Upload protocol | /v1/uploads |
Storage + File contexts |
| Storage & blobs | /v1/storage |
Storage context |
| Sync | /v1/sync |
Sync context |
| Sharing | /v1/shares |
Sharing context |
| Search | /v1/search |
Search context |
| Identity & tokens | /v1/auth, /v1/api-tokens |
Identity context |
| Admin | /v1/admin |
Admin context |
Full schema for each endpoint group is in gen/openapi/bitvault.yaml.