---
title: "Create Connector Endpoint"
method: POST
path: "/v1/connectors"
tags: ["v1-connectors"]
---

# Create Connector Endpoint

`POST /v1/connectors`

Create new connector after source prerequisite validation.

Flow:
1. Validate connection_details schema for service_name
2. Run the row-less PostgreSQL source prerequisite gate
3. Store connection details in Key Vault
4. Save connector to database
5. Return connector (without schema_structure - call /discover next)

Response time: 500ms-1s (fast validation only)

Note: After creating, call POST /connectors/{id}/discover to run schema discovery.

Preflight gate scope: steps 1-2 run for every PostgreSQL create where
``byoc`` is None — this deliberately includes BYOC-environment
(``use_environment=True``, ARN-based) connectors as well as direct
(no-environment) connectors. For the BYOC-environment path the gate
probes the source through the discovery tunnel (``private_link_id`` +
resolved ``byoc_access_credentials`` are forwarded to
``run_discovery_preflight``), so the source is validated before any row
or secret is written. Only Neon-BYOC (``byoc='neon'``) and non-PostgreSQL
creates skip the gate.

## Request body

- CreateConnectorRequest
  - `org_id` string, nullable — Organization to create the connector in. Inferred from your auth when omitted.
  - `project_id` string, required — Project to create the connector in.
  - `name` string, required — Connector name.
  - `service_name` string, required — Service type. `postgresql` is the only supported value today.
  - `connection_details` object, required — Connection details for the source database.
  - `byoc` string, nullable
  - `neon_api_key` string, nullable
  - `neon_project_id` string, nullable
  - `deployment_model` 'ardent-cloud' | 'customer-cloud'
  - `byoc_access_credentials` BYOCAccessCredentialsInput — Customer-cloud access block supplied at connector-create time. ``external_id`` is plaintext on the wire; the backend stores it in AKV as part of create_connector and persists only the resulting ``kv://akv/...`` ref on the connector row.
    - `role_arn` string, required — arn:aws:iam::<account-id>:role/ArdentDeployer — provisioned by customer-template CFN.
    - `external_id` string, required — Per-customer UUID from generate-onboarding.sh; stored in AKV and replaced with a ref.
    - `region` string, required — AWS region the customer data plane runs in, e.g. 'us-east-1'.
    - `cluster_name` string, required — EKS cluster name in the customer account where pgstream pods will run. Per-deployment (set by customer's terraform 'cluster_name' variable); backend needs it to call eks:DescribeCluster during branch create.
  - `use_environment` boolean — Create the connector in a customer-cloud environment.
  - `environment_id` string, nullable — Customer-cloud environment; required when your org has more than one.
  - `private_link_id` string, nullable — Private connection for the source database; needs `use_environment`.
  - `allow_high_rtt_placement` boolean — Allow customer-cloud placement far from the worker region.
  - `drop_extensions` string[], nullable — Source extensions to drop on branches instead of installing.

## Response `200`

The created connector row plus `can_update`/`can_delete`.

- 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

- `400` — Validation, placement, or private-network configuration error.
- `422` — Preflight hasn't passed for this source; the body is the full preflight report. (A malformed request body also returns 422.)

---

[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/revisions/71b66f68e19c/schema)