Branches

Create copy-on-write branches of a database, manage them, and restore to a point in time.

A branch is a copy-on-write fork of a database. Branching is instant because it forks the underlying snapshots rather than copying data — ideal for previews, tests, and experiments.

The API is stabilizing. The paths below reflect the current interface; field-level details may still change before general availability.

List branches

`GET /v1/databases/{database_id}/branches`

Terminal

curl https://api.silos.sh/v1/databases/db_abc123/branches \
  -H "Authorization: Bearer $SILOS_API_KEY"

Response

{
  "branches": [
    {
      "id": "br_main",
      "name": "main",
      "is_default": true
    },
    {
      "id": "br_xyz789",
      "name": "preview",
      "parent_branch_id": "br_main",
      "is_default": false
    }
  ]
}

Create a branch

`POST /v1/databases/{database_id}/branches`

Fork a branch. Omit parent_lsn to branch from the latest state.

Terminal

curl -X POST https://api.silos.sh/v1/databases/db_abc123/branches \
  -H "Authorization: Bearer $SILOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "preview",
    "parent_branch_id": "br_main"
  }'

Response

{
  "branch": {
    "id": "br_xyz789",
    "name": "preview",
    "parent_branch_id": "br_main",
    "is_default": false,
    "created_at": "2026-06-01T12:00:00Z"
  }
}

To branch from a specific point, include a parent_lsn:

Terminal

curl -X POST https://api.silos.sh/v1/databases/db_abc123/branches \
  -H "Authorization: Bearer $SILOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "preview",
    "parent_branch_id": "br_main",
    "parent_lsn": "0/1ABC123"
  }'

Get a branch

`GET /v1/branches/{id}`

Terminal

curl https://api.silos.sh/v1/branches/br_xyz789 \
  -H "Authorization: Bearer $SILOS_API_KEY"

Response

{
  "branch": {
    "id": "br_xyz789",
    "name": "preview",
    "parent_branch_id": "br_main",
    "is_default": false
  }
}

Update a branch

`PATCH /v1/branches/{id}`

Rename a branch, or promote it to the default with is_default.

Terminal

curl -X PATCH https://api.silos.sh/v1/branches/br_xyz789 \
  -H "Authorization: Bearer $SILOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "is_default": true }'

Response

{
  "branch": {
    "id": "br_xyz789",
    "name": "preview",
    "is_default": true
  }
}

Restore a branch

`POST /v1/branches/{id}/restore`

Restore a branch to a point in time, by LSN or timestamp.

Terminal

curl -X POST https://api.silos.sh/v1/branches/br_xyz789/restore \
  -H "Authorization: Bearer $SILOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "target_timestamp": "2026-06-01T00:00:00Z" }'

Or by LSN:

Terminal

curl -X POST https://api.silos.sh/v1/branches/br_xyz789/restore \
  -H "Authorization: Bearer $SILOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "target_lsn": "0/1ABC123" }'

Response

{
  "operation": {
    "id": "op_abc123",
    "action": "restore_branch",
    "status": "running"
  }
}

Restore is asynchronous and returns an operation you can poll for completion. How far back you can restore depends on your plan's WAL retention.

Delete a branch

`DELETE /v1/branches/{id}`

Terminal

curl -X DELETE https://api.silos.sh/v1/branches/br_xyz789 \
  -H "Authorization: Bearer $SILOS_API_KEY"

Deleting a branch is irreversible and also removes any branches forked from it. The default branch of a database cannot be deleted.

Branches

On this page