backupd-api
/backupd-api
Call the backupd HTTP API directly with curl or from any language (Python, Go, Ruby and others): authentication with the x-api-key header, the POST-per-action endpoint shape, triggering and polling backups, downloading backups, error codes and rate limits. Use when the user wants to integrate backupd without the CLI or TypeScript SDK, generate a client from its OpenAPI spec, or debug raw API calls.
- Author
- backupd-dev ↗
- Repository
- backupd-js ↗
- Licence
- MIT
- Last repository change
- 07.11.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 6
No signals detected. Repository changed on 07.11.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Call the backupd HTTP API directly with curl or from any language (Python, Go, Ruby and others): authentication with the x-api-key header, the POST-per-action endpoint shape, triggering and polling backups, downloading backups, error codes and rate limits. Use when the user wants to integrate backupd without the CLI or TypeScript SDK, generate a client from its OpenAPI spec, or debug raw API calls.
Original author description
Call the backupd HTTP API directly with curl or from any language (Python, Go, Ruby and others): authentication with the x-api-key header, the POST-per-action endpoint shape, triggering and polling backups, downloading backups, error codes and rate limits. Use when the user wants to integrate backupd without the CLI or TypeScript SDK, generate a client from its OpenAPI spec, or debug raw API calls.
How it works
- Shape of a request
- Back up and wait
- Download
- Errors
- Restores and destructive calls
- MCP
SKILL.md preview
---
name: backupd-api
description: "Call the backupd HTTP API directly with curl or from any language (Python, Go, Ruby and others): authentication with the x-api-key header, the POST-per-action endpoint shape, triggering and polling backups, downloading backups, error codes and rate limits. Use when the user wants to integrate backupd without the CLI or TypeScript SDK, generate a client from its OpenAPI spec, or debug raw API calls."
---
# backupd HTTP API
Use this skill when the CLI (backupd-cli) and the TypeScript SDK (backupd-sdk) don't fit. Both wrap this API and handle workspaces, polling and retries for you, so recommend them first for shell or TypeScript work.
- Reference: https://api.backupd.dev/api-reference
- OpenAPI: https://api.backupd.dev/api-reference/spec.json. Generate clients from it, and check request and response shapes against it rather than guessing.
- Guide: https://docs.backupd.dev/docs/api
## Shape of a request
Every action is a `POST` with a JSON body to `https://api.backupd.dev/api-reference/<area>/<action>`, with the key in `x-api-key`:
```sh
curl -sf -X POST https://api.backupd.dev/api-reference/databases/list \
-H "x-api-key: $BACKUPD_API_KEY" \
-H "content-type: application/json" \
-d "{\"organizationId\": \"$ORG\"}"
```
- **Auth:** only the `x-api-key` header. `Authorization: Bearer` and keys in the URL are rejected. Keys start with `bkp_`, are created in **Settings → API & MCP**, and act as the user who made them, with their role in each workspace.
- **Workspace:** most bodies need `organizationId` (the workspace ID), and database calls need `databaseId`. Both are in the console under a database's **Settings → Identifiers**, or come from `databases/list`.
- Read the key from the environment or a secret store. Never inline it in code, commands you show, or logs.
## Back up and wait
```sh
BACKUP_ID=$(curl -sf -X POST "$API/api-reference/backups/trigger" \
-H "x-api-key: $BACKUPD_API_KEY" -H "content-type: application/json" \
-d "{\"organizationId\": \"$ORG\", \"databaseId\": \"$DB\"}" | jq -r .backupId)
while true; do
STATUS=$(curl -sf -X POST "$API/api-reference/backups/get" \
-H "x-api-key: $BACKUPD_API_KEY" -H "content-type: application/json" \
-d "{\"organizationId\": \"$ORG\", \"backupId\": \"$BACKUP_ID\"}" | jq -r .status)
case "$STATUS" in
succeeded) break ;;
failed|cancelled) exit 1 ;;
esac
sleep 15
done
```
- `trigger` uses one of the plan's manual backups for that database per rolling 24 hours (2 on Starter, 5 on Pro). Never retry it automatically on `429`, and never call it in a loop.
- Poll every 10–30 seconds. Status goes `queued` → `running` → `succeeded`, `failed` or `cancelled`. Afterwards, `verificationStatus` moves to `verified` or `failed` once the restore test runs.
## Download
```sh
# Decrypted dump in its native format
curl -fOJ "$API/downloads/backups/$BACKUP_ID?organizationId=$ORG" -H "x-api-key: $BACKUPD_API_KEY"
# As stored (age-encrypted, zstd-compressed). Supports ranges, so resume with -C -
curl -f -C - -o backup.zst.age "$API/downloads/backups/$BACKUP_ID?organizationId=$ORG&raw=1" \
-H "x-api-key: $BACKUPD_API_KEY"
age -d -i key.agekey backup.zst.age | zstd -d > backup.dump
```
Downloads are `GET`s on `/downloads/…`, not `/api-reference`. They need the download permission and are recorded in the audit log. The file is production data, so don't print it.
## Errors
The body is `{ code, status, message }`:
| Status | Code | Do |
| ------ | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400 | `BAD_REQUEST` | Fix the body. The response lists the fields that failed. |
| 401 | `UNAUTHORIZED` | The key is missing, wrong, revoked or expired. Tell the user and don't retry. |
| 403 | `FORBIDDEN` | The role doesn't allow it, or the plan doesn't include it. Tell the user. |
| 404 | `NOT_FOUND` | Wrong ID or workspace, or the user isn't a member. |
| 409 | `CONFLICT` | Busy, for example a backup is already running. Wait for that one. |
| 429 | `TOO_MANY_REQUESTS` | Either the rate limit (120 per minute per key, so back off and honour `Retry-After`) or no manual backups left today (the message says when the next frees up, so don't retry). |
## Restores and destructive calls
Restores, deleting backups and removing databases change data. Before writing code or running a request that does any of them, say exactly what it will overwrite or delete and get the user's confirmation. A restore over the original database requires its exact name in the body. Get that name from the user; don't fill it in from `databases/list`. See the backupd-restore skill.
## MCP
For interactive use from Claude, Cursor and similar clients, backupd has an MCP server with OAuth sign-in, so no key is needed. The user adds it from **Settings → API & MCP**, for example `claude mcp add --transport http backupd <MCP URL>`. Destructive MCP tools are off unless a workspace owner enables them. Docs: https://docs.backupd.dev/docs/api-and-mcp
Versions
The database has no other skills named backupd-api.
Database snapshot: 13.11.2026 · package version 83f1526d4cc1 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 95backupd-sdk
Write TypeScript that uses the backupd SDK (`@backupd/sdk`, `@backupd/sdk/effect`, `@backupd/sdk/local`) to list databases, trigger and wait for backups, start restores, download backups and decrypt them with an age key. Covers the Promise and Effect APIs, typed errors, waiters… - 100backupd-restore
Restore backupd backups safely, into another database, over the original, or on the user's own machine with their own age key, and decrypt backups without backupd using age, zstd and pg_restore, mysql or mongorestore. Use when the user wants to restore, recover, roll back,… - 100tikhub-rest-api
Call the TikHub REST API directly with curl/HTTP. Use for zero-install scripting, CI, non-Python environments, or when the MCP path is unavailable. Covers base URLs, Bearer auth, the /api/v1/{platform}/... path scheme, pagination, rate limits, retries, error handling, and credit/cost awareness. - 100opencode-api
Use when calling or scripting the opencode server's HTTP API - sessions, prompts, messages, the event stream, PTYs and shells, files, MCP, config, permissions, worktrees, integrations - with curl, opencode api or another HTTP client, when reading the server's OpenAPI spec, or… - 100inngest-api
Use when the user explicitly asks for the Inngest REST API v2, raw HTTP, OpenAPI, API docs, API authentication, or an endpoint that the Inngest CLI does not expose. Covers api-docs.inngest.com, llms.txt, the OpenAPI v2 spec, Bearer authentication with API keys or signing keys,… - 95tarn-api-testing
Write, run, debug, and iterate on API tests using Tarn — a CLI-first API testing tool with .tarn.yaml files and structured JSON output. Use when: writing API tests, running tarn commands, debugging test failures, generating tests from OpenAPI specs or curl commands, setting up…