Sign in

v1

latestOpenAPI 3.1.02026-08-0413468163.9 KB
v1-connectors

Preflight Connector Endpoint

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.

post/v1/connectors/preflight

Request body

org_idstring nullable

Organization to preflight for. Inferred from your auth when omitted.

service_namestring required

Service type. postgresql is the only supported value today.

connection_detailsobject required

Connection details for the source database. Nothing is stored.

byoc'neon' nullable
selected_schemasstring[] nullable

Schemas to render in the grant script. Affects only grant_script.

databasestring nullable

Database to render in the grant script. Affects only grant_script.

use_environmentboolean

Route preflight through a customer-cloud environment.

environment_idstring nullable

Customer-cloud environment; required when your org has more than one.

private_link_idstring nullable

Private connection for the source database; needs use_environment.

allow_high_rtt_placementboolean

Allow customer-cloud placement far from the worker region.

Response

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

checksobject nullable

Individual check results, keyed by check name.

source_providerstring nullable

Detected source provider, for example supabase or vanilla.

source_metadataobject nullable

Metadata gathered from the source during preflight.

source_preflightobject nullable
source_placementobject nullable
branching_prerequisites_passboolean nullable

True when the checks required for branching pass.

preflight_passboolean nullable

True when every preflight check passes.

grant_scriptstring nullable

Ready-to-run SQL grant script for the source database.