# ReClaw Developer Guide

## Authentication

Use a scoped API key with `Authorization: Bearer <key>` or `x-api-key: <key>`.

Permissions:

- `backups:read`
- `backups:write`
- `backups:restore`

## OpenAPI

The machine-readable API description is available at https://reclaw.io/openapi.json.

## API lifecycle

- `GET /api/backup-account`: Read encrypted backup account state.
- `PATCH /api/backup-account`: Reserved cadence update endpoint.
- `POST /api/backup-account/bootstrap`: Initialize client-wrapped vault material.
- `POST /api/backup-account/rotate`: Rotate wrapped vault material.
- `POST /api/backup-account/reset`: Reset backup account state.
- `GET /api/backups`: List visible backups.
- `POST /api/backups`: Create encrypted archive upload slot.
- `POST /api/backups/upload`: Upload encrypted archive bytes.
- `GET /api/backups/{id}`: Read backup detail.
- `DELETE /api/backups/{id}`: Delete a backup.
- `POST /api/backups/{id}/finalize`: Finalize encrypted backup metadata.
- `GET /api/backups/{id}/content`: Download encrypted archive bytes.
- `GET /api/backups/{id}/events`: Stream backup status progress events over Server-Sent Events.

## Streaming

`GET /api/backups/<backup-id>/events` returns `text/event-stream` for progress-aware agents. Listen for `backup.status` events while a backup moves through `PENDING_UPLOAD`, `UPLOADED`, `READY`, `FAILED`, `DELETING`, or `DELETED`.

## MCP

The public read-only MCP endpoint is https://reclaw.io/mcp. It exposes tools for ReClaw product context, pricing, CLI install guidance, and developer documentation. Backup operations still use the authenticated API or CLI.

## Webhooks

Webhooks are not currently emitted. Agents should use the SSE endpoint above for in-flight progress and poll documented API endpoints for durable state.

## Errors

Errors are JSON:

```json
{
  "error": "Authentication is required.",
  "code": "authentication_required",
  "message": "Authentication is required.",
  "resolution": "Send a browser session or ReClaw API key with Authorization: Bearer <key> or x-api-key."
}
```

Validation errors include a `details.issues` array.