---
title: "Create Service Branch"
method: POST
path: "/v1/branch/create"
tags: ["v1-branching"]
---

# Create Service Branch

`POST /v1/branch/create`

CLI endpoint to create a new branch for a connector.

## Headers

- `X-Idempotency-Key` string

## Request body

- object — Body of POST /v1/branch/create. Spec-only today: the handler parses the raw body by hand so a missing field keeps returning the documented 400, not Pydantic's 422. Keep the fields in sync with the hand parsing below.
  - `connector_id` string, required — Connector to branch from.
  - `service_type` string, required — Service to branch; `postgres`, not the connector type `postgresql`.
  - `name` string, required — Branch name, unique per connector.

## Response `202`

Create accepted. Poll `GET /v1/operations/{operation_id}` for the branch details. Idempotent replays carry an `X-Idempotency-Replay: true` response header.

- OperationHandle — 202 acceptance body for async endpoints (branch create today). Declared on routes so the OpenAPI spec documents the handle shape. Handlers keep building the dict by hand; declaring this model on a route is spec-only and never changes a live response.
  - `operation_id` string, required — Operation to poll at `GET /v1/operations/{operation_id}`.
  - `status` 'pending' | 'running' | 'completed' | 'failed', required — Lifecycle status of an async operation. Mirrors the async_operations_status_valid CHECK constraint.
  - `type` 'connector_engine_setup' | 'connector_reset' | 'connector_deep_reset' | 'connector_discovery' | 'connector_delete' | 'connector_secret_purge' | 'connector_rollout' | 'connector_replication_rollback' | 'connector_debezium_cutover' | 'connector_debezium_shadow_cleanup' | 'environment_deploy' | 'environment_destroy' | 'branch_create' | 'branch_delete', required — Discriminator for an async operation. Must match the async_operations_type_valid CHECK constraint in the migration — extending the set requires a migration to widen the constraint AND a worker registered in the dispatcher.
  - `resource_id` string, nullable, required — ID of the resource being created or acted on (the branch ID for branch create).

## Other responses

- `400` — A required field is missing, or the branch name or idempotency key is invalid.
- `409` — A branch with this name already exists on the connector, this create is already in flight, or the idempotency key was reused for a different request.
- `422` — The connector's engine isn't ready to branch.
- `503` — Ardent could not start the work — safe to retry.

---

[API](https://skmtc.net/tryardent/apis/fastapi.md) · [All operations](https://skmtc.net/tryardent/apis/fastapi/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/tryardent/fastapi/revisions/71b66f68e19c/schema)