Create a branch
Start an async branch create and get an operation handle
service_type is postgres — not the connector type postgresql.
The response is 202 Accepted with an operation handle:
completed, its result holds the branch details:
?wait= parameter.
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
Ardent API key (sk-ard_live_… / sk-ard_test_…) or a dashboard session token.
Headers
Makes retries safe: re-sending the same connector, service type, and name resumes the original request instead of creating a duplicate.
Body
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.
Response
Create accepted. Poll GET /v1/operations/{operation_id} for the branch details. Idempotent replays carry an X-Idempotency-Replay: true response header.
Operation to poll at GET /v1/operations/{operation_id}.
ID of the resource being created or acted on (the branch ID for branch create).
Status at acceptance time.
pending, running, completed, failed The kind of work this operation tracks, for example branch_create.
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