API Reference

Complete reference for the DBackup REST API. Use these endpoints to automate backups, monitor executions, manage resources, and integrate with external systems.

Interactive API Documentation

DBackup ships with an interactive API reference powered by Scalar:

• In your instance: Open /docs/api in your browser (e.g., http://localhost:3000/docs/api)
• Online: api.dbackup.app

The interactive docs let you explore all endpoints, view request/response schemas, and generate code snippets for Shell, Python, Node.js, PHP, Ruby, and more.

Base URL

https://your-dbackup-instance.com/api

Authentication

DBackup supports two authentication methods:

Session Authentication (Browser)

Used automatically when logged in via the web UI. Session cookies are sent with each request.

API Key Authentication (Programmatic)

For scripts, CI/CD pipelines, and external integrations. Create an API key under Access Management → API Keys.

Authorization: Bearer dbackup_your_api_key

Note: API keys do not inherit SuperAdmin privileges. Only explicitly assigned permissions are available.

Error Responses

Status	Description
401 Unauthorized	Missing, invalid, disabled, or expired credentials
403 Forbidden	Valid credentials but insufficient permissions
404 Not Found	Resource does not exist
429 Too Many Requests	Rate limit exceeded
500 Internal Server Error	Unexpected server error

Standard error format:

{
  "error": "Human-readable error message"
}

Rate Limits

Request Type	Limit
Authentication (login, etc.)	5/min per IP
GET requests	100/min per IP
POST / PUT / DELETE	20/min per IP

Rate limits are configurable in Settings → Rate Limits.

Endpoints

For the full endpoint documentation with request/response schemas, examples, and code snippets, use the interactive API reference:

• In your instance: /docs/api
• Online: api.dbackup.app

Endpoint Overview

Section	Endpoints	Description
Jobs	GET/POST/PUT/DELETE /api/jobs	CRUD + trigger backups
Executions	GET /api/executions/:id	Poll execution status
History	GET /api/history	List execution history
Adapters	GET/POST/PUT/DELETE /api/adapters	Sources, destinations & notifications
Connection Testing	POST /api/adapters/test-connection	Test adapter connections
Storage Explorer	GET/POST/DELETE /api/storage/:id/*	Browse, download, delete, restore backups
Vault	GET /api/vault/:id/recovery-kit	Download encryption recovery kit
Settings	GET/POST/PUT /api/settings/system-tasks	System tasks configuration
Health	GET /api/health	Health check (public, no auth)

Permissions

Every API endpoint requires a specific permission. Permissions are assigned to API keys and user groups.

For the complete permission reference, see Groups & Permissions.

Common Patterns

Trigger a Backup and Wait for Completion

#!/bin/bash
API_KEY="dbackup_your_api_key"
BASE_URL="https://your-instance.com"

# 1. Trigger
RESPONSE=$(curl -s -X POST "${BASE_URL}/api/jobs/${JOB_ID}/run" \
  -H "Authorization: Bearer ${API_KEY}")
EXECUTION_ID=$(echo "$RESPONSE" | jq -r '.executionId')

# 2. Poll
while true; do
  STATUS=$(curl -s "${BASE_URL}/api/executions/${EXECUTION_ID}" \
    -H "Authorization: Bearer ${API_KEY}" | jq -r '.data.status')

  case "$STATUS" in
    "Success") echo "Done!"; exit 0 ;;
    "Failed")  echo "Failed!"; exit 1 ;;
    *) sleep 5 ;;
  esac
done

Download Latest Backup

# 1. List files
FILES=$(curl -s "${BASE_URL}/api/storage/${STORAGE_ID}/files" \
  -H "Authorization: Bearer ${API_KEY}")

# 2. Get latest file path
LATEST=$(echo "$FILES" | jq -r '.[0].path')

# 3. Generate download URL
URL=$(curl -s -X POST "${BASE_URL}/api/storage/${STORAGE_ID}/download-url" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d "{\"file\": \"${LATEST}\"}" | jq -r '.url')

# 4. Download
wget -O latest_backup.sql.gz "$URL"