Skip to main content
POST
Create Service Branch
Branch creation is asynchronous: the create call returns an operation handle, and polling that operation gives you the branch’s connection details. All three body fields are required. For Postgres branches, service_type is postgres — not the connector type postgresql. The response is 202 Accepted with an operation handle:
Poll the operation until it finishes. On completed, its result holds the branch details:
See Operations for the polling model and the ?wait= parameter.
Treat branch_url as sensitive, and use it exactly as returned — including sslmode=require and channel_binding=disable. A completed operation can still return a null result or a null branch_url, so confirm result.branch_url is present and non-empty before using it. If it’s missing, fail closed: never fall back to the main connection string or any other configured URL.
Retries are safe. Send an X-Idempotency-Key header with the create request; re-sending the same connector, service type, and name resumes the original request instead of creating a duplicate. Create can fail with: 400 (a required field is missing), 409 (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), or 503 (Ardent could not start the work — retry).

Authorizations

Authorization
string
header
required

Ardent API key (sk-ard_live_… / sk-ard_test_…) or a dashboard session token.

Headers

X-Idempotency-Key
string

Makes retries safe: re-sending the same connector, service type, and name resumes the original request instead of creating a duplicate.

Body

application/json

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.

name
string
required

Branch name, unique per connector.

service_type
string
required

Service to branch; postgres, not the connector type postgresql.

Response

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

operation_id
string
required

Operation to poll at GET /v1/operations/{operation_id}.

resource_id
string | null
required

ID of the resource being created or acted on (the branch ID for branch create).

status
enum<string>
required

Status at acceptance time.

Available options:
pending,
running,
completed,
failed
type
enum<string>
required

The kind of work this operation tracks, for example branch_create.

Available options:
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