Reference

REST API

A small job API. The CLI is a client for it; anything that speaks HTTP can drive snapshotdb the same way.

Every request carries Authorization: Bearer $SNAPSHOTDB_TOKEN. The API is a command executor: you submit a CLI command as a JSON array, poll the job, and read its output.

Endpoints

Method & path	Purpose
`GET /v1/health`	Liveness; returns `{ "version": "…" }`.
`POST /v1/commands`	Submit a command (JSON array of args). Returns `202 { "id", "state":"queued" }`.
`GET /v1/jobs/{id}`	Poll a job: `{ state, exit_code, stdout, stderr }`.

Example

# submit `list --format json`
$ curl -sX POST $SNAPSHOTDB_SERVER/v1/commands \
    -H "Authorization: Bearer $SNAPSHOTDB_TOKEN" -H 'Content-Type: application/json' \
    -d '["list","--format","json"]'
{ "id": "<id>", "state": "queued" }

$ curl -s $SNAPSHOTDB_SERVER/v1/jobs/<id> -H "Authorization: Bearer $SNAPSHOTDB_TOKEN"

Allowed commands over the API are the branch and source lifecycle: preflight, clone, sync, import, create, prepare, info, url, switch, list, status, repair, reconcile, reset, settings, lock, unlock, start, stop, rm.

Why one endpoint, not dozens: a multi-tenant managed service needs many resource routes (projects, connectors, branches, operations, api-keys, orgs). the BYOC server exposes a generic job endpoint. Hosted access goes through an authenticated web gateway that selects a private workspace and enforces plan allowances; the gateway token must never be distributed to users.

← Configuration FAQ →