Skip to main content
Version: Latest

Create Connection

POST 
/api/v1/connections

Create a new data connection.

After the row is inserted, this handler runs the standard test + discover-schema chain inline before returning, so the response object already contains the final status, last_tested_at, and last_error and the connection is immediately usable for queries. Failures of the test or discover steps are soft — the connection row is always committed in one of three terminal states:

  • test pass + discover pass → status="healthy"
  • test pass + discover fail → status="degraded" (schema introspection broke but credentials work)
  • test fail (or timeout) → status="error" (and discover skipped)

The HTTP response is always 201 — the soft-failure detail lives in the response body's status and last_error fields. This matches REST semantics (the row was successfully created) and lets the frontend surface the right toast without having to poll.

Request​

Responses​

Successful Response