TextQL Connectors API

openapi: 3.2.0
info:
  title: TextQL v2 Connectors 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: Connectors
  description: List available data connectors
paths:
  /v2/connectors:
    get:
      tags:
      - Connectors
      summary: List Connectors
      description: List all data connectors available to the authenticated organization.
      operationId: v2.listConnectors
      responses:
        '200':
          description: List of connectors
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Connector'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      tags:
      - Connectors
      summary: Create Connector
      description: 'Create a new data connector from the supplied configuration. Creation

        validates the config but does not open a connection — call

        `POST /v2/connectors/test` first if you want to verify reachability.'
      operationId: v2.createConnector
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateConnectorRequest'
      responses:
        '201':
          description: Created connector
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Connector'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
  /v2/connectors/types:
    get:
      tags:
      - Connectors
      summary: List Connector Types
      description: 'Enumerate every supported connector type and the fields each requires,

        so you can build a valid `config` without reading the proto. For each

        type, `connector_type` is the value to set as `config.connector_type`

        and `config_key` is the metadata object to nest under `config`.


        Fields flagged `confidential` are write-only (passwords, keys, tokens) —

        they are never returned by read endpoints, and when `optional_on_update`

        is true they may be omitted on `PATCH` to preserve the stored value.'
      operationId: v2.listConnectorTypes
      responses:
        '200':
          description: Supported connector types and their field schemas
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListConnectorTypesResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
  /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'
  /v2/connectors/{id}:
    patch:
      tags:
      - Connectors
      summary: Update Connector
      description: 'Update an existing connector. The `connector_type` in the body must

        match the stored connector''s type. Confidential fields (passwords, keys,

        tokens) left empty are preserved from the stored connector, so you only

        need to send the fields you are changing.'
      operationId: v2.updateConnector
      parameters:
      - $ref: '#/components/parameters/ConnectorId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateConnectorRequest'
      responses:
        '200':
          description: Updated connector
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Connector'
        '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'
    delete:
      tags:
      - Connectors
      summary: Delete Connector
      description: 'Delete a connector by id. Example/system connectors cannot be deleted

        (TextQL Usage connectors return `400`; example connectors are hidden

        rather than removed).'
      operationId: v2.deleteConnector
      parameters:
      - $ref: '#/components/parameters/ConnectorId'
      responses:
        '200':
          description: Deletion result
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    format: int32
                  success:
                    type: boolean
        '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'
  /v2/connectors/{id}/access:
    get:
      tags:
      - Connectors
      summary: Get Connector Access
      description: 'Get a connector''s access configuration: its org-wide visibility and the

        member, role, and group grants on it. Requires read access to the

        connector.'
      operationId: v2.getConnectorAccess
      parameters:
      - $ref: '#/components/parameters/ConnectorId'
      responses:
        '200':
          description: Current access configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectorAccess'
        '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'
    put:
      tags:
      - Connectors
      summary: Update Connector Access
      description: 'Declaratively replace a connector''s access configuration. Grants not in

        the request are revoked, new ones are created, and `is_public` sets

        org-wide visibility. The caller''s own owner grant is always preserved,

        even when omitted from `grants`.


        Requires owner access to the connector (or org admin). Grants are

        validated (members, roles, and groups must exist in the organization)

        up front, and the replacement is applied atomically in a single

        transaction, so a failed request leaves access unchanged.'
      operationId: v2.updateConnectorAccess
      parameters:
      - $ref: '#/components/parameters/ConnectorId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateConnectorAccessRequest'
      responses:
        '200':
          description: Resulting access configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectorAccess'
        '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:
    ConnectorAccessGrant:
      type: object
      required:
      - access_type
      description: 'One access grant. Set exactly one of `member_id`, `role_id`, or

        `group_id`. Resolve ids via `GET /v2/members` and `GET /v2/roles`.

        '
      properties:
        member_id:
          type: string
          example: 9b2f7a64-11d0-4c1b-8f3e-2f9c5b7f6e10
        role_id:
          type: string
          example: 80de0196-496f-44fe-9d4c-8013b3b44082
        group_id:
          type: string
        access_type:
          type: string
          enum:
          - owner
          - editor
          - viewer
    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
    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
    UpdateConnectorRequest:
      type: object
      required:
      - config
      properties:
        config:
          $ref: '#/components/schemas/ConnectorConfig'
        allow_sql_write_operations:
          type: boolean
          description: Allow the connector to execute write/DDL SQL.
        include_db_session_metadata:
          type: boolean
          description: Attach database session metadata to queries.
    ConnectorTypeInfo:
      type: object
      description: A supported connector type and the shape of its config.
      properties:
        connector_type:
          type: string
          description: Value to set as config.connector_type (e.g. `KDB`).
        config_key:
          type: string
          description: Metadata object key to nest under config (e.g. `kdb`).
        fields:
          type: array
          items:
            $ref: '#/components/schemas/ConnectorTypeField'
    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
    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.
    Connector:
      type: object
      properties:
        id:
          type: integer
          format: int32
          description: Connector ID
        name:
          type: string
          description: Connector name
        type:
          type: string
          description: Connector type
    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.

            '
    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'
    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`.'
    ConnectorAccess:
      type: object
      properties:
        is_public:
          type: boolean
        grants:
          type: array
          items:
            allOf:
            - $ref: '#/components/schemas/ConnectorAccessGrant'
            - type: object
              properties:
                granted_by:
                  type: string
                  description: Member id that created the grant.
                expires_at:
                  type: string
                  description: RFC 3339 timestamp; absent for non-expiring grants.
    CreateConnectorRequest:
      type: object
      required:
      - config
      properties:
        config:
          $ref: '#/components/schemas/ConnectorConfig'
        access:
          allOf:
          - $ref: '#/components/schemas/UpdateConnectorAccessRequest'
          description: 'Access configuration applied atomically with creation. Grants are

            validated before the connector is created, so an invalid grant

            never leaves a partially configured connector. When omitted, the

            connector is created org-visible (`is_public: true`). The creating

            member always receives an owner grant.

            '
    UpdateConnectorAccessRequest:
      type: object
      required:
      - is_public
      properties:
        is_public:
          type: boolean
          description: When true, every member of the organization can use the connector.
        grants:
          type: array
          items:
            $ref: '#/components/schemas/ConnectorAccessGrant'
    ListConnectorTypesResponse:
      type: object
      required:
      - types
      properties:
        types:
          type: array
          items:
            $ref: '#/components/schemas/ConnectorTypeInfo'
    ConnectorTypeField:
      type: object
      description: One configurable field of a connector type.
      properties:
        name:
          type: string
        type:
          type: string
          description: 'JSON-friendly type: string, number, boolean, array, or object.'
        confidential:
          type: boolean
          description: Write-only field (password/key/token); never returned by read endpoints.
        optional_on_update:
          type: boolean
          description: May be omitted on PATCH to preserve the stored value.
    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
  parameters:
    ConnectorId:
      name: id
      in: path
      required: true
      schema:
        type: integer
        format: int32
      description: Connector ID
  responses:
    Conflict:
      description: Resource already exists
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: conflict
              message: A connector already exists for this account
    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
    Forbidden:
      description: Insufficient permissions
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: permission_denied
              message: Insufficient permissions
    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
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key or JWT token