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

# Preflight Connector Endpoint

`POST /v1/connectors/preflight`

Validate a source DB without persisting a connector row (ARD-1146).

The customer's pain this closes: today the only way to learn that
your source is misconfigured is to run ``ardent connector create``,
which persists a row + writes credentials to Key Vault + runs the
duplicate-source fingerprint check at row-create time. Hitting any
discovery failure leaves the customer in a delete/retry loop.

Preflight calls :func:`run_discovery_preflight` (the row-less sibling
of :func:`run_discovery_gate`), which reuses
``PostgresDiscoveryHandler.gate()`` against inline credentials —
*exactly* the function ``/discover`` runs synchronously. No row, no
AKV write, no replication slot side effects.

HTTP semantics:
  - 200 whenever the source DB was actually probed; per-check failure
    detail lives in the response body. The customer is asking a
    question, not asking us to commit state.
  - 400 for request-shape errors (malformed ``connection_details``,
    unknown ``service_name``, **active-private-link symmetry violation**:
    an ``environment_id`` with an active private link cannot be probed
    without ``private_link_id`` because the probe would hit the wrong
    egress).
  - 403 for missing ``connectors.create``.
  - 500 for tunnel / AKV failures we cannot reduce to a check entry.

Compare with ``/discover`` which returns 422 on gate-fail because
discover writes state and the gate result drives that state.

## Request body

- PreflightConnectorRequest — Inline-credentialed prerequisite check before any connector row exists (ARD-1146). Mirrors the CreateConnectorRequest connection surface so the CLI and wizard can call preflight with the exact same form values they would POST to /v1/connectors. No row is persisted, no credentials reach Key Vault — the asyncpg connection lives only for the request lifetime. ``selected_schemas`` and ``database`` are optional and affect only the grant_script block in the response. When either is omitted, the grant_script renders the replication-role-attribute line plus an editable per-database / per-schema template.
  - `org_id` string, nullable — Organization to preflight for. Inferred from your auth when omitted.
  - `service_name` string, required — Service type. `postgresql` is the only supported value today.
  - `connection_details` object, required — Connection details for the source database. Nothing is stored.
  - `byoc` 'neon', nullable
  - `selected_schemas` string[], nullable — Schemas to render in the grant script. Affects only `grant_script`.
  - `database` string, nullable — Database to render in the grant script. Affects only `grant_script`.
  - `use_environment` boolean — Route preflight through 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.

## Response `200`

The full preflight report. A failed gate is still a 200 — read `preflight_pass`.

- PreflightReport — Preflight result: POST /preflight's 200 body, and the 422 body when connector create is gated on failed preflight.
  - `checks` object, nullable — Individual check results, keyed by check name.
  - `source_provider` string, nullable — Detected source provider, for example `supabase` or `vanilla`.
  - `source_metadata` object, nullable — Metadata gathered from the source during preflight.
  - `source_preflight` object, nullable
  - `source_placement` object, nullable
  - `branching_prerequisites_pass` boolean, nullable — True when the checks required for branching pass.
  - `preflight_pass` boolean, nullable — True when every preflight check passes.
  - `grant_script` string, nullable — Ready-to-run SQL grant script for the source database.

## Other responses

- `400` — Unsupported service, or the connection details failed validation.
- `422` — Validation Error

---

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