---
title: "Branch a timeline."
method: POST
path: "/api/v1/tenants/{tenant_id}/timelines/{timeline_id}/branch"
tags: ["PITR"]
---

# Branch a timeline.

`POST /api/v1/tenants/{tenant_id}/timelines/{timeline_id}/branch`

## Request

- Base URL: `https://api.scalix.world`
- URL: `https://api.scalix.world/api/v1/tenants/{tenant_id}/timelines/{timeline_id}/branch`
- Auth: HTTP bearer

Restores the parent timeline's durable base backup + archived WAL into a
NEW compute worker replayed to `branch_lsn` (`0` = latest), then routes the
branch endpoint. The branch archives onto its own timeline from that point.

## Path parameters

- `tenant_id` string, required
- `timeline_id` string, required

## Request body

- BranchTimelineRequest: Request to branch a timeline.
  - `new_timeline_id` string, nullable: Explicit id (UUID) for the new branch timeline; server-generated when omitted.
  - `branch_lsn` integer: LSN to branch at; `0` (the default) branches at the latest recoverable point.

## Response `201`

Branch created and routed

- BranchTimelineResponse: A created branch, routed and ready.
  - `timeline_id` string, required: The new branch timeline id.
  - `parent_timeline_id` string, required: The timeline the branch was taken from.
  - `branch_lsn` integer, required: LSN the branch was taken at (`0` = latest).
  - `endpoint` BranchTimelineEndpoint, required: Connection endpoint of the branch's compute worker.
    - `host` string, required
    - `port` integer, required
  - `status` string, required: Always `ready` on success.

## Other responses

- `400`: Invalid tenant, timeline, or new_timeline_id
- `401`: Missing or invalid API key
- `409`: Branch LSN is beyond the archived WAL
- `500`: Internal error
- `501`: Durability is not configured for this deployment
- `503`: No compute capacity for the branch worker

---

[API](https://skmtc.dev/scalix/apis/scalix-cloud-api.md) · [All operations](https://skmtc.dev/scalix/apis/scalix-cloud-api/llms.txt) · [OpenAPI document](https://skmtc.dev/scalix/apis/scalix-cloud-api/revisions/2c04ca0a90bb?raw)