API Reference

The local web interface exposes an HTTP API on 127.0.0.1:7788. It is not reachable from outside the host it runs on.

Overview

When Latchbox is started with latchbox serve, it listens on the address configured under [web] in latchbox.toml — by default 127.0.0.1:7788. All endpoints are namespaced under /api/v1 and return JSON.

The API binds to a loopback address only. It has no notion of remote users; the key in web.api_key is the sole access control.

Endpoints

Method	Path	Description
GET	`/api/v1/status`	Current scheduler state: whether it is running, and the next scheduled run per target.
GET	`/api/v1/targets`	Lists configured targets with their type and last run outcome.
POST	`/api/v1/run`	Triggers an immediate backup of one target, or all targets if none is given.
GET	`/api/v1/snapshots`	Lists snapshots, optionally filtered by target.
GET	`/api/v1/snapshots/{id}`	Returns details for one snapshot, including its checksum and size.
POST	`/api/v1/restore`	Restores a snapshot by id to its original location or a given path.
GET	`/api/v1/health`	Basic liveness check. Does not require authentication.

Authentication

Every endpoint except /api/v1/health requires the X-Latchbox-Key header, set to the value of web.api_key from latchbox.toml. Requests without the header, or with a value that doesn't match, receive 401.

$ curl -s http://127.0.0.1:7788/api/v1/status \
    -H "X-Latchbox-Key: change-me"

Examples

Status

$ curl -s http://127.0.0.1:7788/api/v1/status \
    -H "X-Latchbox-Key: change-me"

{
  "running": true,
  "targets": [
    { "name": "core-router", "next_run": "2026-08-24T15:00:00Z" },
    { "name": "photos", "next_run": "2026-08-25T02:00:00Z" }
  ]
}

List targets

$ curl -s http://127.0.0.1:7788/api/v1/targets \
    -H "X-Latchbox-Key: change-me"

{
  "targets": [
    {
      "name": "core-router",
      "type": "keenetic",
      "last_run": "2026-08-24T09:00:00Z",
      "last_status": "ok"
    },
    {
      "name": "photos",
      "type": "filesystem",
      "last_run": "2026-08-23T02:00:00Z",
      "last_status": "ok"
    }
  ]
}

Trigger a run

$ curl -s -X POST http://127.0.0.1:7788/api/v1/run \
    -H "X-Latchbox-Key: change-me" \
    -H "Content-Type: application/json" \
    -d '{"target": "core-router"}'

{
  "target": "core-router",
  "snapshot_id": "sn_9f3a1c",
  "status": "ok",
  "checksum": "sha256:7c1e...4b2a"
}

Restore a snapshot

$ curl -s -X POST http://127.0.0.1:7788/api/v1/restore \
    -H "X-Latchbox-Key: change-me" \
    -H "Content-Type: application/json" \
    -d '{"snapshot_id": "sn_9f3a1c"}'

{
  "snapshot_id": "sn_9f3a1c",
  "restored_to": "/srv/latchbox/core-router/sn_9f3a1c",
  "status": "ok"
}

Errors

Code	Meaning
400	Malformed request body or missing required field.
401	Missing or incorrect `X-Latchbox-Key` header.
404	Unknown target or snapshot id.
409	A run is already in progress for the requested target.
500	Backup or restore failed on the server side; check the Latchbox log for details.

Versioning

The API is versioned by path prefix (/api/v1). Breaking changes will arrive under a new prefix rather than altering existing responses; new optional fields may be added to /api/v1 responses without a version bump.