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

# Create Service Branch

`POST /v1/branch/create`

## Request

- Base URL: `https://api.tryardent.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.tryardent.com/v1/branch/create`
- Auth: none declared

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.dev/tryardent/apis/tryardent-api.md) - [All operations](https://skmtc.dev/tryardent/apis/tryardent-api/llms.txt) - [OpenAPI document](https://skmtc.dev/tryardent/apis/tryardent-api/revisions/a0512915b997?raw)