---
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`

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.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/versions/f92d8d54bae2/schema)