---
title: "Discover Connector Endpoint"
method: POST
path: "/v1/connectors/{connector_id}/discover"
tags: ["v1-connectors"]
---

# Discover Connector Endpoint

`POST /v1/connectors/{connector_id}/discover`

Dispatch the connector's schema discovery (ARD-1098).

The connectivity + branching-prerequisites gate runs synchronously
(fast after ARD-1095). On gate success the per-database catalog walk
is dispatched as a ``connector_discovery`` async_operation and the
endpoint returns **202** with the operation id plus the prerequisite
payload — enough for the customer to know "your connection works"
before the schema crawl finishes. On gate failure (network
unreachable, auth, missing prereqs) the endpoint returns 422 with a
structured remediation message; no worker is dispatched.

The CLI polls ``GET /v1/operations/{operation_id}`` for the
terminal status of the catalog walk. Concurrent /discover calls on
the same connector are deduped by the async_operations partial unique
index — the second call rejoins the in-flight operation rather than
launching a second crawl.

Always reads credentials from Key Vault (single source of truth). To
update credentials first, call PUT /connectors/{connector_id}.

## Path parameters

- `connector_id` string, required

## Response `202`

Discovery started (or joined, if one is already running). Poll the operation.

- DiscoverAccepted — 202 body of POST /{connector_id}/discover: an operation handle plus discovery context.
  - `operation_id` string, required — Operation to poll at `GET /v1/operations/{operation_id}`.
  - `status` 'pending' | 'running' | 'completed' | 'failed', required — Lifecycle status of an async operation. Mirrors the async_operations_status_valid CHECK constraint.
  - `type` 'connector_engine_setup' | 'connector_reset' | 'connector_deep_reset' | 'connector_discovery' | 'connector_delete' | 'connector_secret_purge' | 'connector_rollout' | 'connector_replication_rollback' | 'connector_debezium_cutover' | 'connector_debezium_shadow_cleanup' | 'environment_deploy' | 'environment_destroy' | 'branch_create' | 'branch_delete', required — Discriminator for an async operation. Must match the async_operations_type_valid CHECK constraint in the migration — extending the set requires a migration to widen the constraint AND a worker registered in the dispatcher.
  - `resource_id` string, nullable, required — ID of the resource being created or acted on (the branch ID for branch create).
  - `prerequisites` object, nullable — Pre-discovery prerequisite check results.
  - `source_metadata` object, nullable — Metadata gathered from the source.

## Other responses

- `400` — The connector isn't in a state that can be discovered.
- `404` — Connector not found (or not visible to the caller).
- `422` — Discovery prerequisites failed.
- `503` — Ardent could not start the work — safe to retry.

---

[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/versions/f92d8d54bae2/schema)