restorable docs
Reference

API endpoints

Two surfaces. The agent-to-orchestrator wire protocol under /v1/ and the customer-and-operator dashboard API under /api/. Bearer-token auth on most endpoints; auth-key on the bootstrap-attach path.

Auth

Agent endpoints authenticate with a per-agent bearer token:

Authorization: Bearer rbl_<base64>

Dashboard endpoints use the session token from the dashboard. Same header shape for programmatic access.

TLS 1.3, modern suites only. Responses are JSON with snake-case keys. Error body: 

{
  "error": "code_string",
  "message": "human-readable explanation",
  "request_id": "req_01hz...",
  "details": { }
}

Agent endpoints: /v1/

POST /api/bootstrap/attach

Trade an auth key for an agent_id and api_token. Unauthenticated; the auth key is the credential. See Auth key setup.

POST /v1/heartbeat

Liveness ping and command pull. The agent polls at the configured cadence (default 60s). Response carries queued commands and the next expected interval.

POST /v1/backups/upload-url

Request a 15-minute pre-signed PUT URL scoped to one object key.

POST /v1/backups/<id>/download-url

Same shape for a 15-minute GET URL on restore.

POST /v1/backups

Register metadata for a newly uploaded ciphertext. Source, sha256, size, cipher, source metadata (engine version, dump format, schema hash). Creates the backup record receipts reference.

POST /v1/receipts

Submit a signed DSSE envelope. The orchestrator verifies the signature against the agent's registered pubkey, validates the in-toto Statement schema, appends to the transparency log, and stores the receipt. Returns receipt id and log index.

POST /v1/events

Non-receipt events: backup_failed, restore_failed, attestation failures. Also append to the transparency log.

GET /v1/log/head

Most recent signed transparency-log tree head for the calling agent's org. Heads emit hourly.

GET /v1/log/proof

Inclusion and consistency proofs. Leaf and target tree head via query string. Used by restorable-verify --prove once sec-M11 lands.

Dashboard endpoints: /api/

Auth

  • POST /api/auth/signup. Self-serve signup. See Sign up.
  • POST /api/auth/signup/verify. Exchange the signup code for a session.
  • POST /api/auth/login. Magic-code login for existing users.
  • POST /api/auth/verify. Exchange the login code for a session.
  • GET /api/auth/me. Current user and org.
  • POST /api/auth/impersonate. Operator-only. Impersonate a customer user. Every call lands in the transparency log.
  • POST /api/auth/end-impersonate. Exit impersonation.

Orgs and users

  • POST /api/orgs. Operator-only. Create an org.
  • GET /api/orgs. List orgs the current actor can read.
  • GET /api/orgs/{orgID}. Org detail.
  • POST /api/orgs/{orgID}/users. Invite a user.

Agents

  • GET /api/orgs/{orgID}/agents. List agents in the org.
  • PATCH /api/orgs/{orgID}/agents/{agentID}. Rename.
  • POST /api/orgs/{orgID}/agents/{agentID}/revoke. Soft-delete.

Auth keys + bootstrap (REST-1 attach surface)

  • POST /api/orgs/{orgID}/auth-keys. Mint an auth key + install one-liner; key plaintext is shown once.
  • GET /api/orgs/{orgID}/auth-keys. List active keys.
  • POST /api/orgs/{orgID}/auth-keys/{id}/revoke. Kill a key.
  • POST /api/bootstrap/attach (no auth). Agent presents an auth-key bearer; orchestrator mints agent + api_token.
  • POST /api/bootstrap/start (no auth). Begin an interactive attach; returns a code + poll_token + attach URL.
  • GET /api/bootstrap/{poll_token} (no auth). Long-poll; 200 returns the api_token after operator approval.
  • GET /api/orgs/{orgID}/bootstraps/{code}. Operator review.
  • POST /api/orgs/{orgID}/bootstraps/{code}/approve. Operator approve (mints the agent).
  • POST /api/orgs/{orgID}/bootstraps/{code}/deny. Operator deny.

Sources

  • POST /api/orgs/{orgID}/sources. Register source metadata.
  • GET /api/orgs/{orgID}/sources. List.
  • POST /api/orgs/{orgID}/sources/{sourceID}/configure. Update schedule and retention.
  • DELETE /api/orgs/{orgID}/sources/{sourceID}. Remove a source.
  • POST /api/orgs/{orgID}/sources/{sourceID}/trigger. Manual backup or restore test.
  • GET /api/orgs/{orgID}/sources/{sourceID}/timeline. Per-source event timeline.
  • GET /api/orgs/{orgID}/sources/{sourceID}/drift. Schema and env drift indicators.

Receipts and backups

  • GET /api/orgs/{orgID}/receipts. List.
  • GET /api/receipts/{receiptID}. Receipt detail.
  • GET /api/orgs/{orgID}/backups. List backups.
  • GET /api/backups/{backupID}. Backup detail.
  • POST /api/orgs/{orgID}/backups/{backupID}/download-url. Mint a 15-minute pre-signed S3 GET URL for the ciphertext. Session-authed counterpart of the agent's POST /v1/backups/<id>/download-url; lets a bare recovery host pull ciphertext via curl without needing an agent install. Returns {download_url, expires_at}.

Events and commands

  • GET /api/orgs/{orgID}/events. Transparency-log events.
  • GET /api/orgs/{orgID}/commands. Queued, delivered, acked.
  • GET /api/commands/{commandID}. Command detail.

API logs

  • GET /api/orgs/{orgID}/api-logs. Audit trail of API calls.
  • GET /api/api-logs/{logID}. Individual log detail.

Idempotency

Every state-changing POST accepts an Idempotency-Key header (ULID or UUID, client-generated). Same key + same body within 24 hours returns the original response. Same key + different body returns 409 Conflict. Receipt submission extends the window to 30 days.

Rate limits

Per-endpoint in the orchestrator. The ones worth knowing:

  • POST /api/auth/signup. 10/hour per IP, 3/hour per email.
  • POST /api/bootstrap/attach. Auth keys burn on 5 wrong attempts; a fresh code is required after.
  • POST /v1/heartbeat. No hard limit. Agents exceeding the configured cadence by 10× are logged.

Exceeding a limit returns 429 with a Retry-After header.