---
title: "Engine Setup Endpoint"
method: POST
path: "/v1/connectors/{connector_id}/engine-setup"
tags: ["v1-connectors"]
---

# Engine Setup Endpoint

`POST /v1/connectors/{connector_id}/engine-setup`

## 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/connectors/{connector_id}/engine-setup`
- Auth: none declared

Dispatch a branching-engine setup as an async operation.

The actual provisioning (Neon project, pgstream, snapshot, RLS) runs
5–10 minutes — far past the ALB 60s idle timeout — so this endpoint
returns 202 with an operation_id within ~1s. The CLI polls
GET /v1/operations/{id} for stage transitions and the terminal
outcome (ARD-741).

Fast paths preserved from the prior synchronous endpoint:
  - Already-healthy connector → 200 with the existing connector row.
  - Wrong starting status → 400 with the rejected status name.
  - Service has no engine-setup handler → 400.
Anything past that point goes to the worker.

Requirements:
  - Connector must exist
  - branching_engine_status must be retryable for setup dispatch

## Path parameters

- `connector_id` string, required

## Response `200`

Nothing to do: the engine is already set up. Returns the connector row with a `message`.

- ConnectorRow: Loose core of a connector response. The connector row is the most dynamic shape in the system; extra="allow" is the contract — responses carry many more columns and clients must tolerate fields not listed here. can_update/can_delete are added by the permission projection on create/get/update/list responses.
  - `id` string, required: Connector ID.
  - `org_id` string, required: Organization the connector belongs to.
  - `project_id` string, nullable: Project the connector belongs to.
  - `name` string, required: Connector name.
  - `service_name` string, required: Service type. `postgresql` today.
  - `status` string, nullable: Current connector status.
  - `created_at` string, nullable: When the connector was created.
  - `can_update` boolean, nullable: Whether the caller may update this connector.
  - `can_delete` boolean, nullable: Whether the caller may delete this connector.

## Other responses

- `202`: Setup started (or joined). Poll `GET /v1/operations/{operation_id}`.
- `400`: The connector isn't in a state that can run setup.
- `403`: No update permission on this connector.
- `404`: Connector not found (or not visible to the caller).
- `409`: A conflicting setup operation exists.
- `422`: Setup prerequisites failed (for example, unresolved replica identity decisions).
- `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)