openapi: 3.1.0
info:
  description: Public Ardent API. Generated by scripts/export_public_openapi.py — do not edit by hand.
  title: Ardent v1-api-keys v1-connectors API
  version: v1
servers:
- url: https://api.tryardent.com
tags:
- name: v1-connectors
paths:
  /v1/connectors:
    get:
      operationId: list_connectors_endpoint_v1_connectors_get
      parameters:
      - in: query
        name: org_id
        required: true
        schema:
          title: Org Id
          type: string
      - in: query
        name: connector_category
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Connector Category
      - in: query
        name: service_name
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Service Name
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectorListResponse'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      security:
      - bearerAuth: []
      summary: List Connectors Endpoint
      tags:
      - v1-connectors
    post:
      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: []
      summary: Create Connector Endpoint
      tags:
      - v1-connectors
  /v1/connectors/preflight:
    post:
      operationId: preflight_connector_endpoint_v1_connectors_preflight_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PreflightConnectorRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PreflightReport'
          description: The full preflight report. A failed gate is still a 200 — read `preflight_pass`.
        '400':
          description: Unsupported service, or the connection details failed validation.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      security:
      - bearerAuth: []
      summary: Preflight Connector Endpoint
      tags:
      - v1-connectors
  /v1/connectors/{connector_id}:
    delete:
      operationId: delete_connector_endpoint_v1_connectors__connector_id__delete
      parameters:
      - in: path
        name: connector_id
        required: true
        schema:
          title: Connector Id
          type: string
      - in: query
        name: force
        required: false
        schema:
          default: false
          title: Force
          type: boolean
      responses:
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationHandle'
          description: Delete accepted (or already in progress). Poll `GET /v1/operations/{operation_id}`.
        '403':
          description: No delete permission on this connector.
        '404':
          description: Connector not found (or not visible to the caller).
        '409':
          description: Deletion is locked, or a conflicting delete is active.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
        '503':
          description: Ardent could not start the work — safe to retry.
      security:
      - bearerAuth: []
      summary: Delete Connector Endpoint
      tags:
      - v1-connectors
    get:
      operationId: get_connector_endpoint_v1_connectors__connector_id__get
      parameters:
      - in: path
        name: connector_id
        required: true
        schema:
          title: Connector Id
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectorRow'
          description: Successful Response
        '404':
          description: Connector not found (or not visible to the caller).
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      security:
      - bearerAuth: []
      summary: Get Connector Endpoint
      tags:
      - v1-connectors
    put:
      operationId: update_connector_endpoint_v1_connectors__connector_id__put
      parameters:
      - in: path
        name: connector_id
        required: true
        schema:
          title: Connector Id
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateConnectorRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectorRow'
          description: The updated connector row.
        '400':
          description: Validation error.
        '404':
          description: Connector not found (or not visible to the caller).
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      security:
      - bearerAuth: []
      summary: Update Connector Endpoint
      tags:
      - v1-connectors
  /v1/connectors/{connector_id}/deletion-lock:
    delete:
      operationId: unlock_connector_deletion_endpoint_v1_connectors__connector_id__deletion_lock_delete
      parameters:
      - in: path
        name: connector_id
        required: true
        schema:
          title: Connector Id
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectorEnvelope'
          description: The unlocked connector.
        '403':
          description: No update permission on this connector.
        '404':
          description: Connector not found (or not visible to the caller).
        '409':
          description: A delete is already in progress.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      security:
      - bearerAuth: []
      summary: Unlock Connector Deletion Endpoint
      tags:
      - v1-connectors
    post:
      operationId: lock_connector_deletion_endpoint_v1_connectors__connector_id__deletion_lock_post
      parameters:
      - in: path
        name: connector_id
        required: true
        schema:
          title: Connector Id
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConnectorDeletionLockRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectorEnvelope'
          description: The locked connector.
        '403':
          description: No update permission on this connector.
        '404':
          description: Connector not found (or not visible to the caller).
        '409':
          description: A delete is already in progress.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      security:
      - bearerAuth: []
      summary: Lock Connector Deletion Endpoint
      tags:
      - v1-connectors
  /v1/connectors/{connector_id}/discover:
    post:
      operationId: discover_connector_endpoint_v1_connectors__connector_id__discover_post
      parameters:
      - in: path
        name: connector_id
        required: true
        schema:
          title: Connector Id
          type: string
      responses:
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DiscoverAccepted'
          description: Discovery started (or joined, if one is already running). Poll the operation.
        '400':
          description: The connector isn't in a state that can be discovered.
        '404':
          description: Connector not found (or not visible to the caller).
        '422':
          description: Discovery prerequisites failed.
        '503':
          description: Ardent could not start the work — safe to retry.
      security:
      - bearerAuth: []
      summary: Discover Connector Endpoint
      tags:
      - v1-connectors
  /v1/connectors/{connector_id}/engine-setup:
    post:
      operationId: engine_setup_endpoint_v1_connectors__connector_id__engine_setup_post
      parameters:
      - in: path
        name: connector_id
        required: true
        schema:
          title: Connector Id
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectorRow'
          description: 'Nothing to do: the engine is already set up. Returns the connector row with a `message`.'
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationHandle'
          description: Setup started (or joined). Poll `GET /v1/operations/{operation_id}`.
        '400':
          description: The connector isn't in a state that can run setup.
        '403':
          description: No update permission on this connector.
        '404':
          description: Connector not found (or not visible to the caller).
        '409':
          description: A conflicting setup operation exists.
        '422':
          description: Setup prerequisites failed (for example, unresolved replica identity decisions).
        '503':
          description: Ardent could not start the work — safe to retry.
      security:
      - bearerAuth: []
      summary: Engine Setup Endpoint
      tags:
      - v1-connectors
  /v1/connectors/{connector_id}/quarantine:
    get:
      operationId: list_connector_quarantines_endpoint_v1_connectors__connector_id__quarantine_get
      parameters:
      - in: path
        name: connector_id
        required: true
        schema:
          title: Connector Id
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuarantineListResponse'
          description: Active (paused) replication deployments.
        '404':
          description: Connector not found (or not visible to the caller).
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      security:
      - bearerAuth: []
      summary: List Connector Quarantines Endpoint
      tags:
      - v1-connectors
  /v1/connectors/{connector_id}/quarantine/{quarantine_id}/release:
    post:
      operationId: release_quarantine_endpoint_v1_connectors__connector_id__quarantine__quarantine_id__release_post
      parameters:
      - in: path
        name: connector_id
        required: true
        schema:
          title: Connector Id
          type: string
      - in: path
        name: quarantine_id
        required: true
        schema:
          title: Quarantine Id
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuarantineRow'
          description: The released quarantine entry.
        '403':
          description: No update permission on this connector.
        '404':
          description: Connector or quarantine entry not found.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      security:
      - bearerAuth: []
      summary: Release Quarantine Endpoint
      tags:
      - v1-connectors
  /v1/connectors/{connector_id}/replica-identity-decisions:
    put:
      operationId: set_replica_identity_decisions_endpoint_v1_connectors__connector_id__replica_identity_decisions_put
      parameters:
      - in: path
        name: connector_id
        required: true
        schema:
          title: Connector Id
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReplicaIdentityDecisionsRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectorRow'
          description: The refreshed connector row, including `replica_identity_preflight`.
        '400':
          description: A decision is invalid, covers an unknown table, or the map is incomplete.
        '403':
          description: No update permission on this connector.
        '404':
          description: Connector not found (or not visible to the caller).
        '409':
          description: The decisions could not be applied — state changed underneath; retry.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      security:
      - bearerAuth: []
      summary: Set Replica Identity Decisions Endpoint
      tags:
      - v1-connectors
  /v1/connectors/{connector_id}/selection:
    post:
      operationId: set_selection_endpoint_v1_connectors__connector_id__selection_post
      parameters:
      - in: path
        name: connector_id
        required: true
        schema:
          title: Connector Id
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SelectionRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectorRow'
          description: The connector row with the applied selection fields.
        '400':
          description: No discovered schema to select from, or an invalid selection.
        '404':
          description: Connector not found (or not visible to the caller).
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      security:
      - bearerAuth: []
      summary: Set Selection Endpoint
      tags:
      - v1-connectors
components:
  schemas:
    ReplicaIdentityDecisionsRequest:
      properties:
        decisions:
          additionalProperties:
            type: string
          description: 'Per-table decision: `exclude`, `add_pk`, or `replica_identity_full`.'
          title: Decisions
          type: object
      required:
      - decisions
      title: ReplicaIdentityDecisionsRequest
      type: object
    QuarantineListResponse:
      properties:
        quarantines:
          description: Active (still paused) quarantines for the connector.
          items:
            $ref: '#/components/schemas/QuarantineRow'
          title: Quarantines
          type: array
      required:
      - quarantines
      title: QuarantineListResponse
      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
    ValidationError:
      properties:
        ctx:
          title: Context
          type: object
        input:
          title: Input
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          title: Location
          type: array
        msg:
          title: Message
          type: string
        type:
          title: Error Type
          type: string
      required:
      - loc
      - msg
      - type
      title: ValidationError
      type: object
    QuarantineRow:
      additionalProperties: true
      properties:
        connector_id:
          description: Connector the quarantine belongs to.
          title: Connector Id
          type: string
        deployment_name:
          anyOf:
          - type: string
          - type: 'null'
          description: Replication deployment that was paused.
          title: Deployment Name
        id:
          description: Quarantine ID.
          title: Id
          type: string
        message:
          anyOf:
          - type: string
          - type: 'null'
          description: Human-readable status message.
          title: Message
        released_at:
          anyOf:
          - type: string
          - type: 'null'
          description: When the quarantine was released. Null while paused.
          title: Released At
        released_by:
          anyOf:
          - type: string
          - type: 'null'
          description: Who released the quarantine. Null while paused.
          title: Released By
        status:
          description: '`quarantined` while paused, `released` after release.'
          title: Status
          type: string
      required:
      - id
      - connector_id
      - status
      title: QuarantineRow
      type: object
    UpdateConnectorRequest:
      properties:
        connection_details:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          description: Replacement connection details for the source database.
          title: Connection Details
        drop_extensions:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          description: Extensions to drop on branches; omit to leave unchanged, `[]` clears.
          title: Drop Extensions
        name:
          anyOf:
          - type: string
          - type: 'null'
          description: New connector name.
          title: Name
        project_id:
          anyOf:
          - type: string
          - type: 'null'
          description: Move the connector to this project.
          title: Project Id
      title: UpdateConnectorRequest
      type: object
    PreflightConnectorRequest:
      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. Nothing is stored.
          title: Connection Details
          type: object
        database:
          anyOf:
          - type: string
          - type: 'null'
          description: Database to render in the grant script. Affects only `grant_script`.
          title: Database
        environment_id:
          anyOf:
          - type: string
          - type: 'null'
          description: Customer-cloud environment; required when your org has more than one.
          title: Environment Id
        org_id:
          anyOf:
          - type: string
          - type: 'null'
          description: Organization to preflight for. 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
        selected_schemas:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          description: Schemas to render in the grant script. Affects only `grant_script`.
          title: Selected Schemas
        service_name:
          description: Service type. `postgresql` is the only supported value today.
          title: Service Name
          type: string
        use_environment:
          default: false
          description: Route preflight through a customer-cloud environment.
          title: Use Environment
          type: boolean
      required:
      - service_name
      - connection_details
      title: PreflightConnectorRequest
      type: object
    OperationStatus:
      enum:
      - pending
      - running
      - completed
      - failed
      title: OperationStatus
      type: string
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          title: Detail
          type: array
      title: HTTPValidationError
      type: object
    SelectionRequest:
      properties:
        selected_paths:
          description: Discovered paths to replicate. Use `["*"]` to select everything.
          items:
            type: string
          title: Selected Paths
          type: array
      required:
      - selected_paths
      title: SelectionRequest
      type: object
    DiscoverAccepted:
      properties:
        operation_id:
          description: Operation to poll at `GET /v1/operations/{operation_id}`.
          title: Operation Id
          type: string
        prerequisites:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          description: Pre-discovery prerequisite check results.
          title: Prerequisites
        resource_id:
          anyOf:
          - type: string
          - type: 'null'
          description: ID of the resource being created or acted on (the branch ID for branch create).
          title: Resource Id
        source_metadata:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          description: Metadata gathered from the source.
          title: Source Metadata
        status:
          $ref: '#/components/schemas/OperationStatus'
          description: Status at acceptance time.
        type:
          $ref: '#/components/schemas/OperationType'
          description: The kind of work this operation tracks, for example `branch_create`.
      required:
      - operation_id
      - status
      - type
      - resource_id
      title: DiscoverAccepted
      type: object
    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
    ConnectorDeletionLockRequest:
      properties:
        reason:
          anyOf:
          - maxLength: 500
            type: string
          - type: 'null'
          description: Why the connector is locked, up to 500 characters.
          title: Reason
      title: ConnectorDeletionLockRequest
      type: object
    OperationHandle:
      properties:
        operation_id:
          description: Operation to poll at `GET /v1/operations/{operation_id}`.
          title: Operation Id
          type: string
        resource_id:
          anyOf:
          - type: string
          - type: 'null'
          description: ID of the resource being created or acted on (the branch ID for branch create).
          title: Resource Id
        status:
          $ref: '#/components/schemas/OperationStatus'
          description: Status at acceptance time.
        type:
          $ref: '#/components/schemas/OperationType'
          description: The kind of work this operation tracks, for example `branch_create`.
      required:
      - operation_id
      - status
      - type
      - resource_id
      title: OperationHandle
      type: object
    ConnectorEnvelope:
      properties:
        connector:
          $ref: '#/components/schemas/ConnectorRow'
          description: The connector's current row.
      required:
      - connector
      title: ConnectorEnvelope
      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
    OperationType:
      enum:
      - 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
      title: OperationType
      type: string
    ConnectorListResponse:
      properties:
        connectors:
          description: Connectors in the organization, visible to the caller.
          items:
            $ref: '#/components/schemas/ConnectorRow'
          title: Connectors
          type: array
      required:
      - connectors
      title: ConnectorListResponse
      type: object
  securitySchemes:
    bearerAuth:
      description: Ardent API key (sk-ard_live_… / sk-ard_test_…) or a dashboard session token.
      scheme: bearer
      type: http