API reference
For what the API is for and how to manage keys and webhooks, see Integration API. This page is the short technical pointer.
OpenAPI description
Section titled “OpenAPI description”The REST API lives under /api/v1; its OpenAPI description is generated from the same Zod schemas the API validates requests against, and served at:
GET /api/v1/openapi.jsonPoint any OpenAPI-aware tool (Swagger UI, Postman, an SDK generator, …) at that URL against your own installation to get the full, exact, endpoint-by-endpoint contract. This documentation site does not duplicate it by hand, since a hand-copied contract would drift from the running server.
Authentication
Section titled “Authentication”- API keys and provider keys (see Integration API):
Authorization: Bearer <key>, rate-limited to 600 requests per 10 minutes per key. - The web interface itself authenticates with a session cookie (better-auth); that session mechanism is not meant for third-party integrations, use an API key instead.
Live progress
Section titled “Live progress”Job progress is available as a server-sent-events stream: GET /api/v1/jobs/{id}/events.
Servers, clients and versions
Section titled “Servers, clients and versions”GET /api/v1/endpoints lists the servers and clients backed up by the Restow agent. GET /api/v1/status carries counts of them and the version object (running, latest, updateAvailable, channel, latestTag, publishedAt, checkError, maintenance and more). Both need the scope status:read. The fields are described under Integration API.
Operational endpoints (outside /api/v1)
Section titled “Operational endpoints (outside /api/v1)”| Endpoint | Purpose |
|---|---|
GET /healthz |
Process is up. |
GET /readyz |
Process is ready to serve (dependencies such as the database are reachable). |
These are unauthenticated and unversioned on purpose, so a load balancer or container orchestrator can probe them without credentials.
Endpoints for the agent (outside /api/v1)
Section titled “Endpoints for the agent (outside /api/v1)”| Endpoint | Purpose |
|---|---|
/agent/v1/* |
The API of the Restow agent: enrollment, configuration, heartbeat, runs, agent update. Enrollment uses a one-time token, every other call the agent’s own per-endpoint secret; no API key is involved. |
/agent/restic/<endpoint id>/ |
The restic repository of one endpoint. It is append-only for the agent. |
/install/* |
The install scripts and the agent and restic binaries with their SHA256SUMS, for the install command. |
They are served on the same public address as the web interface and are used by the agent and the install command, not by integrations. For machine data, use GET /api/v1/endpoints. See Endpoint backup.