API の概要
REST API は、Web コンソールと CLI が使っているものと同じです。コンソールや CLI でできることは、スクリプトからも実行できます。リファレンスは次のページに分かれています。
ベース URL
Section titled “ベース URL”https://<任意のノード>:7080/v1どのノードも、コンソールと同じ TLS 証明書で、ポート 7080 の API を提供します。クラスターでは、どのノードにリクエストを送っても、対象のリソースを持つノードに転送されます。証明書は自己署名です。https://<node>:7080/tls.pem からダウンロードして信頼させるか、試す間は curl に -k を付けてください。
リクエストとレスポンスは JSON です（Content-Type: application/json）。フィールド名は snake_case、時刻は UTC の RFC 3339、容量はバイト、期間は 72h、30m のような Go 形式の文字列です。リクエストボディは 2 MiB までで、API が知らないフィールドは 400 invalid_request で拒否されます。
Branch と Base の名前は、小文字の英字、数字、単独のハイフンで、先頭は英字、最大 32 文字です（feature-x）。ランタイムは engine@version の形で書きます（例: postgres@18.6）。
/v1 の外にある次の 3 つは、ログインなしで使えます。GET /healthz（常に ok）、GET /readyz（初期化前やクラスターのリーダーがいない間は 503）、GET /tls.pem です。
API トークンを Authorization ヘッダーで送ります。
curl -sk -H "Authorization: Bearer dbb_..." https://node1:7080/v1/branchesトークンは 2 種類あります。どちらも dbb_ で始まり、作成時に 1 度だけ表示され、ハッシュだけが保存されます。
| 種類 | 作る人 | 動作の主体 | スコープ |
|---|---|---|---|
| サービストークン | 管理者（Settings → Service tokens、db-branch token create、POST /v1/tokens） |
トークン自身（CI や外部連携向け） | branches（既定）または full |
| 個人トークン | ログイン済みの本人（Account → MCP access、POST /v1/account/tokens） |
作った本人 | branches |
スコープで、できることが決まります。
branchesは、Branch の作成、利用、削除と、そのほかの多くのリソースの読み取りができます。Base、ランタイム、設定、トークンは変更できません。秘密を含みうる設定、トークン、ルートユーザー、バックアップ、Base の refresh 元は読み取れません。fullは、管理者と同じことができます。
無効、期限切れ、失効したトークンには 401 unauthenticated を返します。トークンから別のトークンは作れません。
コンソールはトークンを使いません。POST /v1/auth/login でサインインし、dbb_session Cookie（HttpOnly、Secure、SameSite=Strict）を受け取ります。以降、GET 以外のリクエストには、ログイン応答の csrf_token の値を X-CSRF-Token ヘッダーで付ける必要があります。付けないと 403 csrf_failed になります。スクリプトからはトークンを使ってください。Bearer トークン付きのリクエストには CSRF の検査はありません。
資格情報なしで使える呼び出しは限られます。公開 Snapshot からの Branch 作成、open な Branch の参照と接続、オペレーションの参照、公開 Base の一覧です。詳しくは Branch を見てください。
db-branch コマンドは、ローカルの UNIX ソケット経由でエージェントと通信します。ソケットを開ける人（root または db-branch グループ）は管理者として動作します。POST /v1/auth/reset、POST /v1/cluster/token、POST /v1/backups/restore はソケットでだけ使え、HTTPS では 403 socket_only を返します。
呼び出しが許されるかどうかは、リクエストごとにアクション名（branch.create、base.delete など）で判定されます。このリファレンスでは、各エンドポイントにアクション名を示しています。標準のログインは管理者 1 人で、すべての操作ができます。有償の auth などのモジュールを入れると、ロールが加わり、ロールごとにこれらのアクションが割り当てられます。
リクエストが失敗すると、ステータスコードと次の形のボディを返します。
{ "error": { "code": "not_found", "message": "branch feature-x: not found" }}処理の分岐には code を使ってください。message は人が読むためのもので、変わることがあります。
| ステータス | code |
意味 |
|---|---|---|
| 400 | invalid_request |
JSON が壊れている、未知または不足したフィールドがある、名前・ランタイム・TTL・設定値が正しくない |
| 400 | weak_password |
新しいパスワードが弱い |
| 401 | unauthenticated |
セッションやトークンがない、または期限切れ |
| 401 | invalid_credentials |
ユーザー名またはパスワードが違う |
| 403 | forbidden |
その呼び出しは、この呼び出し元やトークンのスコープでは許されない |
| 403 | csrf_failed |
Cookie セッションなのに X-CSRF-Token が合わない |
| 403 | socket_only |
ノードのローカルソケットでしか使えない |
| 404 | not_found |
そのリソースがない |
| 404 | runtime_not_installed |
そのノードにランタイムがインストールされていない |
| 409 | already_exists |
同じ名前がすでにある |
| 409 | conflict |
リソースがその操作を受け付ける状態にない（例: ready でない Branch のリセット） |
| 409 | in_use |
まだ使われている（Branch がある Base、使用中のランタイム） |
| 409 | unclean_shutdown |
Base のサーバーが正常に停止せず、Snapshot を取れなかった |
| 409 | other_node |
その作業は別のノードのもの |
| 409 | rollout_running |
クラスターのアップデートがすでに進行中 |
| 422 | runtime_unavailable |
そのランタイムのバージョンは提供されていない |
| 422 | query_failed |
SQL の実行に失敗した |
| 429 | rate_limited |
ログインの試行が多すぎる。Retry-After ヘッダーを見る |
| 503 | no_leader |
現在クラスターにリーダーがいない。Retry-After のあとで再試行する |
| 503 | no_capacity |
Branch を置けるノードに空きがない |
| 503 | cluster_upgrading |
クラスターのアップデートでプロトコルが切り替わっている |
| 503 | not_initialized |
ノードが db-branch init 前、またはその機能が未設定 |
| 503 | modules_pending |
クラスターが必要とするモジュールを、このノードがまだ動かしていない |
| 500 | internal |
想定外のエラー |
エンドポイントによっては独自の code も返します。該当する箇所に書いています。
一覧のエンドポイントは {"items": [...], "next_cursor": null} を返します。すべての項目が 1 回の応答に入ります。limit や cursor のパラメーターはまだなく、next_cursor は常に null です。Branch と Base は名前順、オペレーションは新しい順です。
時間のかかる操作
Section titled “時間のかかる操作”Branch の作成、リセット、削除、Base の作成と Snapshot、ダンプの読み込み、Base の refresh、ランタイムのインストールは、数秒から数分かかります。これらの呼び出しはすぐに 202 Accepted を返し、Location ヘッダーと次のようなオペレーションを返します。
{ "id": "op_01JC8Z6Q4M7V3X2N9K5R8T1W0B", "kind": "branch.create", "target": { "resource": "branch", "name": "feature-x" }, "node": "node1", "state": "running", "phase": "cloning", "created_at": "2026-11-09T12:00:00Z", "updated_at": "2026-11-09T12:00:03Z", "seq": 1762689600000000000}state は running、succeeded、failed のいずれかです。実行中は phase が現在の段階を示します。失敗すると error に理由が入り、終了すると finished_at が入ります。対象のリソース（たとえば Branch）は作成直後から status つきで見えるので、そちらをポーリングしてもかまいません。
state が running でなくなるまで GET /v1/operations/{id} をポーリングするか、イベントストリームを購読します。クライアントが切断しても、オペレーションは動き続けます。完了したオペレーションは、新しい 200 件が残ります。
Base の起動や Branch の延長のような短い操作は、リクエストの中で完了して 200 か 204 を返します。
GET /v1/events は、Branch、Base、オペレーション、ランタイム、ノード、設定、モジュールの変更を流す Server-Sent Events のストリームです。クライアントがポーリングする必要はありません。
curl -skN -H "Authorization: Bearer dbb_..." https://node1:7080/v1/eventsid: 18343event: branch.updateddata: {"name":"feature-x","status":"ready", ...}
id: 18344event: operation.updateddata: {"id":"op_...","state":"succeeded", ...}| イベント | データ |
|---|---|
branch.updated、base.updated |
GET が返すのと同じオブジェクト（Base は can フィールドなし） |
branch.deleted、base.deleted |
{"name": "..."} |
operation.updated |
オペレーション |
runtime.updated、runtime.deleted |
ランタイムのオブジェクト。削除では {"runtime": "..."} |
node.updated |
ノードが変わった。GET /v1/cluster で読み直す |
setting.updated |
変更された設定のスコープ |
module.updated、update.updated |
モジュールやクラスターのアップデートに変化があった。リソースを取り直す |
各イベントには id があります。接続が切れたら Last-Event-ID: <最後の id> を付けて再接続すると、取りこぼした分が届きます。古すぎて再送できない場合は、最初に event: resync が届くので、クライアントは一覧を取り直してください。15 秒ごとにコメント行（: ping）が届きます。読み取りが遅いクライアントは切断されるので、再接続してください。イベントの種類による絞り込みはまだありません。
未実装のもの
Section titled “未実装のもの”設計メモには、API がまだ実装していないものがあります。Idempotency-Key ヘッダー、ETag と If-Match、カーソル方式のページング、オペレーションの取り消しです。これらには頼らないでください。
例: Branch を作って接続する
Section titled “例: Branch を作って接続する”export DBB=https://node1:7080/v1export AUTH="Authorization: Bearer $DBB_TOKEN"
# 1. Branch を作る。応答はオペレーションOP=$(curl -sk -H "$AUTH" -H 'Content-Type: application/json' \ -d '{"name":"feature-x","base":"prod","ttl":"72h"}' \ $DBB/branches | jq -r .id)
# 2. 完了を待つwhile :; do STATE=$(curl -sk -H "$AUTH" $DBB/operations/$OP | jq -r .state) [ "$STATE" != running ] && break sleep 1doneecho "operation: $STATE"
# 3. 接続 URL（パスワード付き）を取得するcurl -sk -H "$AUTH" $DBB/branches/feature-x/dsn# {"dsn":"postgres://feature-x:...@node1:41203/postgres"}
# 4. 使い終わったら削除するcurl -sk -X DELETE -H "$AUTH" $DBB/branches/feature-xこの 4 つの手順は、branches スコープのトークンで実行できます。