> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryardent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a connector

> Connect a Postgres source to Ardent

If preflight hasn't passed for this source, create fails with `422` and the response body is the full preflight report — fix the failures it lists and retry.

<Accordion defaultOpen={false} title="Private-network and customer-cloud connectors">
  Include the environment and private connection IDs that your Ardent team has set up:

  ```json theme={null}
  {
    "use_environment": true,
    "environment_id": "env_123",
    "private_link_id": "epl_123"
  }
  ```

  `environment_id` and `private_link_id` are only valid together with `use_environment: true`. Add `"allow_high_rtt_placement": true` to accept a far-away placement despite higher latency.
</Accordion>


## OpenAPI

````yaml openapi.public.json POST /v1/connectors
openapi: 3.1.0
info:
  description: >-
    Public Ardent API. Generated by scripts/export_public_openapi.py — do not
    edit by hand.
  title: Ardent API
  version: v1
servers:
  - url: https://api.tryardent.com
security: []
paths:
  /v1/connectors:
    post:
      tags:
        - v1-connectors
      summary: Create Connector Endpoint
      operationId: create_connector_endpoint_v1_connectors_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateConnectorRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectorRow'
          description: The created connector row plus `can_update`/`can_delete`.
        '400':
          description: Validation, placement, or private-network configuration error.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PreflightReport'
          description: >-
            Preflight hasn't passed for this source; the body is the full
            preflight report. (A malformed request body also returns 422.)
      security:
        - bearerAuth: []
components:
  schemas:
    CreateConnectorRequest:
      properties:
        allow_high_rtt_placement:
          default: false
          description: Allow customer-cloud placement far from the worker region.
          title: Allow High Rtt Placement
          type: boolean
        connection_details:
          additionalProperties: true
          description: Connection details for the source database.
          title: Connection Details
          type: object
        drop_extensions:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          description: Source extensions to drop on branches instead of installing.
          title: Drop Extensions
        environment_id:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Customer-cloud environment; required when your org has more than
            one.
          title: Environment Id
        name:
          description: Connector name.
          title: Name
          type: string
        org_id:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Organization to create the connector in. Inferred from your auth
            when omitted.
          title: Org Id
        private_link_id:
          anyOf:
            - type: string
            - type: 'null'
          description: Private connection for the source database; needs `use_environment`.
          title: Private Link Id
        project_id:
          description: Project to create the connector in.
          title: Project Id
          type: string
        service_name:
          description: Service type. `postgresql` is the only supported value today.
          title: Service Name
          type: string
        use_environment:
          default: false
          description: Create the connector in a customer-cloud environment.
          title: Use Environment
          type: boolean
      required:
        - project_id
        - name
        - service_name
        - connection_details
      title: CreateConnectorRequest
      type: object
    ConnectorRow:
      additionalProperties: true
      properties:
        can_delete:
          anyOf:
            - type: boolean
            - type: 'null'
          description: Whether the caller may delete this connector.
          title: Can Delete
        can_update:
          anyOf:
            - type: boolean
            - type: 'null'
          description: Whether the caller may update this connector.
          title: Can Update
        created_at:
          anyOf:
            - type: string
            - type: 'null'
          description: When the connector was created.
          title: Created At
        id:
          description: Connector ID.
          title: Id
          type: string
        name:
          description: Connector name.
          title: Name
          type: string
        org_id:
          description: Organization the connector belongs to.
          title: Org Id
          type: string
        project_id:
          anyOf:
            - type: string
            - type: 'null'
          description: Project the connector belongs to.
          title: Project Id
        service_name:
          description: Service type. `postgresql` today.
          title: Service Name
          type: string
        status:
          anyOf:
            - type: string
            - type: 'null'
          description: Current connector status.
          title: Status
      required:
        - id
        - org_id
        - name
        - service_name
      title: ConnectorRow
      type: object
    PreflightReport:
      additionalProperties: true
      properties:
        branching_prerequisites_pass:
          anyOf:
            - type: boolean
            - type: 'null'
          description: True when the checks required for branching pass.
          title: Branching Prerequisites Pass
        checks:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          description: Individual check results, keyed by check name.
          title: Checks
        grant_script:
          anyOf:
            - type: string
            - type: 'null'
          description: Ready-to-run SQL grant script for the source database.
          title: Grant Script
        preflight_pass:
          anyOf:
            - type: boolean
            - type: 'null'
          description: True when every preflight check passes.
          title: Preflight Pass
        source_metadata:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          description: Metadata gathered from the source during preflight.
          title: Source Metadata
        source_placement:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Source Placement
        source_preflight:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Source Preflight
        source_provider:
          anyOf:
            - type: string
            - type: 'null'
          description: Detected source provider, for example `supabase` or `vanilla`.
          title: Source Provider
      title: PreflightReport
      type: object
  securitySchemes:
    bearerAuth:
      description: >-
        Ardent API key (sk-ard_live_… / sk-ard_test_…) or a dashboard session
        token.
      scheme: bearer
      type: http

````