> ## Documentation Index
> Fetch the complete documentation index at: https://docs.textql.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Test Connector

> Test a connector configuration without saving it



## OpenAPI

````yaml POST /v2/connectors/test
openapi: 3.1.0
info:
  title: TextQL v2 API
  version: '2.0'
  description: >
    REST API for TextQL platform operations. All endpoints require Bearer token
    authentication.
servers:
  - url: https://app.textql.com
security:
  - bearerAuth: []
tags:
  - name: Chat
    description: Create and manage AI chat sessions
  - name: Connectors
    description: List available data connectors
  - name: Playbooks
    description: Create, configure, and run automated playbooks
  - name: Sandcastles
    description: Manage Python sandbox environments for code execution
  - name: Changes
    description: Review, approve, and deny Ontology changes
  - name: API Keys
    description: Mint and revoke scoped platform API keys
paths:
  /v2/connectors/test:
    post:
      tags:
        - Connectors
      summary: Test Connector
      description: >
        Test a connector configuration without persisting it. A failed

        connection is reported as `200` with `{"success": false, "error":
        "..."}`

        — the request itself succeeded, only the downstream connection failed.

        HTTP error statuses are reserved for an invalid config (`400`) or

        auth/permission failures.


        Pass `connector_id` to test changes against an existing connector:

        confidential fields left empty in the request are filled in from the

        stored connector before the connection is attempted.
      operationId: v2.testConnector
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TestConnectorRequest'
      responses:
        '200':
          description: Test result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TestConnectorResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    TestConnectorRequest:
      type: object
      required:
        - config
      properties:
        config:
          $ref: '#/components/schemas/ConnectorConfig'
        connector_id:
          type: string
          description: |
            Optional. ID of an existing connector whose confidential fields
            should fill in any empty confidential fields in `config` before the
            connection is attempted.
    TestConnectorResponse:
      type: object
      required:
        - success
      properties:
        success:
          type: boolean
          description: Whether the connection succeeded.
        error:
          type: string
          description: Failure detail when `success` is false; empty otherwise.
    ConnectorConfig:
      type: object
      required:
        - connector_type
        - name
      description: |
        A connector's type, display name, and type-specific connection metadata.

        Set exactly one metadata field matching `connector_type` (e.g.
        `connector_type: POSTGRES` ⇒ set `postgres`). The common database types
        are documented below; every supported type follows the same shape — see
        the proto `ConnectorConfig` for the full list (Snowflake, BigQuery,
        Databricks, Tableau, PowerBI, SQL Server, Trino, etc.).

        Confidential fields (passwords, keys, tokens) are write-only: they are
        never returned by read endpoints, and on update they are preserved from
        the stored connector when sent empty.
      properties:
        connector_type:
          type: string
          description: |
            Connector type enum name, e.g. `POSTGRES`, `REDSHIFT`, `MYSQL`,
            `SNOWFLAKE`, `BIGQUERY`, `DATABRICKS`, `TABLEAU`, `POWERBI`.
          example: POSTGRES
        name:
          type: string
          description: Human-readable connector name
        auth_strategy:
          type: string
          description: |
            Authentication strategy. Defaults to `service_role` when omitted;
            other values (`member_oauth`, `per_member_oauth`) are inferred from
            the metadata for OAuth-capable connectors.
        postgres:
          $ref: '#/components/schemas/PostgresMetadata'
        redshift:
          $ref: '#/components/schemas/RedshiftMetadata'
        mysql:
          $ref: '#/components/schemas/MySQLMetadata'
        snowflake:
          $ref: '#/components/schemas/SnowflakeMetadata'
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Machine-readable error code
              enum:
                - invalid_request
                - unauthenticated
                - permission_denied
                - not_found
                - conflict
                - rate_limit_exceeded
                - internal
                - timeout
                - cancelled
                - execution_failed
                - no_report
            message:
              type: string
              description: Human-readable error message
    PostgresMetadata:
      type: object
      description: 'Connection metadata for `connector_type: POSTGRES`.'
      required:
        - host
        - user
        - password
        - database
      properties:
        host:
          type: string
        port:
          type: integer
          format: int32
          default: 5432
        user:
          type: string
        password:
          type: string
          description: Write-only. Omit on update to keep the stored value.
        database:
          type: string
        schemas:
          type: array
          items:
            type: string
        ssl_mode:
          type: boolean
    RedshiftMetadata:
      type: object
      description: 'Connection metadata for `connector_type: REDSHIFT`.'
      required:
        - host
        - database
      properties:
        host:
          type: string
        port:
          type: integer
          format: int32
          default: 5439
        user:
          type: string
        password:
          type: string
          description: Write-only. Omit on update to keep the stored value.
        database:
          type: string
        schemas:
          type: array
          items:
            type: string
        auth_type:
          type: string
          description: '`PASSWORD` (default) or `IAM_ROLE`.'
    MySQLMetadata:
      type: object
      description: 'Connection metadata for `connector_type: MYSQL`.'
      required:
        - host
        - user
        - password
        - database
      properties:
        host:
          type: string
        port:
          type: integer
          format: int32
          default: 3306
        user:
          type: string
        password:
          type: string
          description: Write-only. Omit on update to keep the stored value.
        database:
          type: string
    SnowflakeMetadata:
      type: object
      description: |
        Connection metadata for `connector_type: SNOWFLAKE`. Authenticate with
        either `username` + `password`, or `username` + `private_key` (key-pair
        auth, PEM-encoded PKCS#8; add `private_key_passphrase` if the key is
        encrypted). The OAuth and SSO fields are for org-level or per-member
        OAuth setups; see the Snowflake datasource docs for those flows.
      required:
        - locator
        - database
        - warehouse
      properties:
        locator:
          type: string
          description: Account locator/identifier, e.g. `myorg-account123`.
        username:
          type: string
        password:
          type: string
          description: Write-only. Omit on update to keep the stored value.
        private_key:
          type: string
          description: Write-only. PEM-encoded private key for key-pair auth.
        private_key_passphrase:
          type: string
          description: Write-only. Passphrase when `private_key` is encrypted.
        role:
          type: string
          description: Snowflake role to assume for queries.
        database:
          type: string
        schema:
          type: string
        warehouse:
          type: string
        oauth_access_token:
          type: string
          description: Write-only.
        oauth_refresh_token:
          type: string
          description: Write-only.
        oauth_client_id:
          type: string
        oauth_client_secret:
          type: string
          description: Write-only.
        enable_sso_auth:
          type: boolean
          description: Pass the caller's IdP token directly to Snowflake External OAuth.
        token_exchange_endpoint:
          type: string
          description: IdP token exchange URL (RFC 8693) for per-member SSO auth.
        token_exchange_audience:
          type: string
        token_exchange_scope:
          type: string
  responses:
    BadRequest:
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: invalid_request
              message: Invalid request body
    Unauthorized:
      description: Missing or invalid authentication
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: unauthenticated
              message: Authentication required
    Forbidden:
      description: Insufficient permissions
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: permission_denied
              message: Insufficient permissions
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: not_found
              message: Resource not found
    RateLimited:
      description: Rate limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: rate_limit_exceeded
              message: Rate limit exceeded
    InternalError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: internal
              message: Internal server error
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key or JWT token

````