# AutoVault API Reference

Current v0.5.0 surfaces are the local CLI, source ESM library exports, local stdio MCP, remote Streamable HTTP MCP at /mcp, and the hosted sync routes under /v/<slug>/. There is no public REST API or separately published SDK package yet. MCP tools are the agent-facing API. Hosted sync has exactly one write, POST /v/<slug>/devices, which any keypair may call to enrol itself as pending; the rest is reads, and admission gates bundles rather than the catalog.

## Current v0.5.0 surfaces

- CLI commands for add install, remove/uninstall cleanup, profile sync, doctor checks, local skill search/list/which, repo audit, setup, capability resolve, and remote service startup.
- Source ESM library exports for resolveCapabilities, syncProfiles, addSkill, updateSkill, deleteSkill, proposeSkill, transforms, auditRepo, and profile discovery.
- MCP tools for discovery/full reads through get_skill, trusted adds, updates, deletes, proposals, and drift checks.
- Remote Streamable HTTP MCP with OAuth and role-aware filtering at /mcp.
- AutoVault Cloud hosted sync at /v/<slug>/: four device-signed routes, one write (POST devices, which enrols a key as pending) and three reads.

## Hosted sync routes

Served by AutoVault Cloud under /v/<slug>/. Every route is signed. There are no anonymous reads and no API keys: a device holds an Ed25519 keypair, signs the string `<METHOD>\n<pathname>\n<unix-seconds>`, and sends three headers.

```http
X-AutoVault-Device      base64url Ed25519 public key
X-AutoVault-Timestamp   whole seconds since epoch
X-AutoVault-Signature   base64url detached signature
```

Timestamps more than 300 seconds off are rejected. Pathname is the full request path as sent, not a path rebuilt from route parameters.

| Route | Who may call it |
|---|---|
| POST /v/<slug>/devices | any keypair, signed by itself. This is first contact. |
| GET /v/<slug>/devices/current | any enrolled device, including a revoked one |
| GET /v/<slug>/catalog.json | a pending or active device |
| GET /v/<slug>/bundles/<bundle_hash>.json | an active device, on an active subscription |

- Enrollment is idempotent per key, so running `autovault link` twice returns the same device_id. A vault holds at most 20 pending devices at once.
- The catalog is readable while a device is still pending, because `autovault link` enrols and then immediately reads the catalog to pin the publishing public key.
- Catalog and bundles are served byte-for-byte from KV. Re-serialising the JSON changes the bytes and every release signature stops verifying.
- A vault with nothing published answers 404 for its catalog. That is the normal state of a new vault, not an error.
- Bundles additionally check the hosted subscription and answer 402 when it lapses, while the catalog keeps answering.
- Nothing under /v/ returns a 3xx. The client fetches with redirect: "manual" and throws on any redirect.
- Device responses are no-store, private, because they are authorized per device rather than per URL.

There is no route that writes a catalog. Publishing is owner-side and out of band: the release signing key stays on the owner's machine and Cloud never holds one.

## Agent guidance

Prefer inventory lookup first, full reads second, and get_skill with include_resources when packaged resources are needed. Use local sync-profiles when a filesystem-native host needs files under its local skill root.

## add examples

```bash
autovault add ./skills/skill-author --sync-profiles --yes
autovault add ./staging/skill-author --source local --provenance '<existing-identifier>' --sync-profiles --yes
autovault add autoworks-ai/autovault:skills/skill-author/SKILL.md --sync-profiles --yes
autovault add skill-slug --source agentskills --sync-profiles --agent codex --yes
autovault add https://example.com/SKILL.md --source url --no-sync-profiles --yes
```

`autovault add` infers the source for common local paths and GitHub inputs. Use `--source` when the input is ambiguous, `--agent` when a remote skill does not declare target agents, `--sync-profiles` when visible agent roots should be refreshed, and `--provenance` to keep the recorded source identifier when replacing a staged local bundle.