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

# Create Connector Endpoint

`POST /v1/connectors`

## 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`
- Auth: none declared

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.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)