Structify connectors API

openapi: 3.0.3
info:
  contact:
    email: team@structify.ai
    name: Structify Team
  description: Every enterprise's data team.
  license:
    name: Discuss directly with founders for license.
    url: https://structify.ai
  title: Structify account connectors API
  version: 0.1.0
servers:
- description: Production server
  url: https://api.structify.ai
- description: Local server
  url: http://localhost:8080
security:
- api_key: []
- session_token: []
tags:
- name: connectors
paths:
  /connector-type-snippets/{connector_type}:
    put:
      operationId: upsert_connector_type_snippet
      parameters:
      - description: Connector type identifier
        in: path
        name: connector_type
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpsertConnectorTypeSnippetRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectorTypeSnippet'
          description: Connector type snippet created or updated
        '401':
          description: Unauthorized
      security:
      - api_key: []
      - session_token: []
      tags:
      - connectors
  /connectors:
    get:
      operationId: list_connectors
      parameters:
      - in: query
        name: offset
        required: false
        schema:
          minimum: 0
          type: integer
      - in: query
        name: limit
        required: false
        schema:
          minimum: 0
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/ConnectorWithSecrets'
                type: array
          description: List of connectors with their secrets for the team
        '401':
          description: Unauthorized
        '403':
          description: Forbidden - user does not have access to team
      security:
      - api_key: []
      - session_token: []
      tags:
      - connectors
    post:
      operationId: create_connector
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateConnectorRequest'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Connector'
          description: Connector created successfully
        '400':
          description: Invalid request data
        '401':
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Forbidden - user does not have access to team
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal server error
      security:
      - api_key: []
      - session_token: []
      tags:
      - connectors
  /connectors/clarification-requests/{clarification_id}/resolve:
    patch:
      operationId: resolve_clarification
      parameters:
      - in: path
        name: clarification_id
        required: true
        schema:
          $ref: '#/components/schemas/ClarificationRequestId'
      responses:
        '200':
          description: Clarification marked as resolved
        '401':
          description: Unauthorized
        '403':
          description: Forbidden - user does not have write access
        '404':
          description: Clarification request not found
      security:
      - api_key: []
      - session_token: []
      summary: Mark a clarification request as resolved
      tags:
      - connectors
  /connectors/columns/{column_id}:
    patch:
      operationId: update_column
      parameters:
      - in: path
        name: column_id
        required: true
        schema:
          $ref: '#/components/schemas/ConnectorColumnId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateColumnRequest'
        required: true
      responses:
        '200':
          description: Column metadata updated successfully
        '401':
          description: Unauthorized
        '403':
          description: Forbidden - user does not have write access
        '404':
          description: Column not found
      security:
      - api_key: []
      - session_token: []
      summary: Update column metadata (notes)
      tags:
      - connectors
  /connectors/search-tables:
    get:
      operationId: search_tables
      parameters:
      - description: Search query string
        in: query
        name: query
        required: true
        schema:
          type: string
      - description: Team ID to scope table search
        in: query
        name: team_id
        required: true
        schema:
          $ref: '#/components/schemas/TeamId'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TableSearchResults'
          description: List of table mentions
        '401':
          description: Unauthorized
      security:
      - api_key: []
      - session_token: []
      tags:
      - connectors
  /connectors/stores:
    get:
      operationId: list_connector_stores
      responses:
        '200':
          content:
            application/json:
              schema:
                additionalProperties:
                  $ref: '#/components/schemas/LlmInformationStore'
                type: object
          description: Map of connector ID to LLM information store for connectors that have stores
        '401':
          description: Unauthorized
      security:
      - api_key: []
      - session_token: []
      tags:
      - connectors
  /connectors/summaries:
    post:
      operationId: list_connector_summaries
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConnectorSummariesRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/ConnectorSummary'
                type: array
          description: Connector summaries with logos
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Connector not found
      security:
      - api_key: []
      - session_token: []
      tags:
      - connectors
  /connectors/tables/{table_id}:
    patch:
      operationId: update_table
      parameters:
      - in: path
        name: table_id
        required: true
        schema:
          $ref: '#/components/schemas/ConnectorTableId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateTableRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateTableResponse'
          description: Table metadata updated successfully
        '401':
          description: Unauthorized
        '403':
          description: Forbidden - user does not have write access
        '404':
          description: Table not found
      security:
      - api_key: []
      - session_token: []
      summary: Update table metadata (description or notes)
      tags:
      - connectors
  /connectors/tables/{table_id}/lineage:
    get:
      operationId: get_table_lineage
      parameters:
      - description: The table ID
        in: path
        name: table_id
        required: true
        schema:
          $ref: '#/components/schemas/ConnectorTableId'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TableLineageResponse'
          description: Table lineage information
        '404':
          description: Table not found
      security:
      - api_key: []
      - session_token: []
      tags:
      - connectors
  /connectors/tables/{table_id}/path:
    get:
      operationId: get_connector_table_path
      parameters:
      - in: path
        name: table_id
        required: true
        schema:
          $ref: '#/components/schemas/ConnectorTableId'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectorTablePathResponse'
          description: Table location details
        '404':
          description: Table not found
      security:
      - api_key: []
      - session_token: []
      tags:
      - connectors
  /connectors/with-snippets:
    get:
      operationId: list_connectors_with_snippets
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/ConnectorWithSnippets'
                type: array
          description: List of connectors with their usage snippets
        '401':
          description: Unauthorized
      security:
      - api_key: []
      - session_token: []
      tags:
      - connectors
  /connectors/{connector_id}:
    delete:
      operationId: delete_connector
      parameters:
      - description: The connector ID
        in: path
        name: connector_id
        required: true
        schema:
          $ref: '#/components/schemas/ConnectorId'
      responses:
        '204':
          description: Connector deleted successfully
        '401':
          description: Unauthorized
        '403':
          description: Forbidden - user does not have access to connector
        '404':
          description: Connector not found
      security:
      - api_key: []
      - session_token: []
      tags:
      - connectors
    get:
      operationId: get_connector
      parameters:
      - description: The connector ID
        in: path
        name: connector_id
        required: true
        schema:
          $ref: '#/components/schemas/ConnectorId'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectorWithSecretsAndValues'
          description: Connector details
        '401':
          description: Unauthorized
        '403':
          description: Forbidden - user does not have access to connector
        '404':
          description: Connector not found
      security:
      - api_key: []
      - session_token: []
      tags:
      - connectors
    patch:
      operationId: update_connector
      parameters:
      - description: The connector ID
        in: path
        name: connector_id
        required: true
        schema:
          $ref: '#/components/schemas/ConnectorId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateConnectorRequest'
        required: true
      responses:
        '200':
          description: Connector updated successfully
        '400':
          description: Invalid request data
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Connector not found
      security:
      - api_key: []
      - session_token: []
      tags:
      - connectors
  /connectors/{connector_id}/clarification-requests:
    get:
      operationId: get_connector_clarification_requests
      parameters:
      - description: The connector ID
        in: path
        name: connector_id
        required: true
        schema:
          $ref: '#/components/schemas/ConnectorId'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClarificationRequestsResponse'
          description: Clarification requests retrieved successfully
        '403':
          description: Forbidden - user does not have access to connector
        '404':
          description: Connector not found
      security:
      - api_key: []
      - session_token: []
      summary: Get all clarification requests for a connector
      tags:
      - connectors
  /connectors/{connector_id}/explore:
    post:
      operationId: explore_connector
      parameters:
      - description: The connector ID
        in: path
        name: connector_id
        required: true
        schema:
          $ref: '#/components/schemas/ConnectorId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExploreConnectorRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
          description: Exploration started successfully
        '400':
          description: Bad request - connector type not supported or table not found
        '403':
          description: Forbidden - user does not have access to connector
        '404':
          description: Connector not found
      security:
      - api_key: []
      - session_token: []
      tags:
      - connectors
  /connectors/{connector_id}/explore/active-run:
    get:
      operationId: get_active_exploration_run
      parameters:
      - description: The connector ID
        in: path
        name: connector_id
        required: true
        schema:
          $ref: '#/components/schemas/ConnectorId'
      responses:
        '200':
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ExplorationRun'
                nullable: true
          description: Active exploration run retrieved successfully
        '403':
          description: Forbidden - user does not have access to connector
        '404':
          description: Connector not found
      security:
      - api_key: []
      - session_token: []
      tags:
      - connectors
  /connectors/{connector_id}/explore/chat:
    get:
      description: Optionally filter by run, database, schema, or table
      operationId: get_connector_explorer_chat
      parameters:
      - description: The connector ID
        in: path
        name: connector_id
        required: true
        schema:
          $ref: '#/components/schemas/ConnectorId'
      - in: query
        name: run_id
        required: false
        schema:
          allOf:
          - $ref: '#/components/schemas/ExplorationRunId'
          nullable: true
      - in: query
        name: database_id
        required: false
        schema:
          allOf:
          - $ref: '#/components/schemas/ConnectorDatabaseId'
          nullable: true
      - in: query
        name: schema_id
        required: false
        schema:
          allOf:
          - $ref: '#/components/schemas/ConnectorSchemaId'
          nullable: true
      - in: query
        name: table_id
        required: false
        schema:
          allOf:
          - $ref: '#/components/schemas/ConnectorTableId'
          nullable: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExplorerChatResponse'
          description: Chats retrieved successfully
        '400':
          description: Bad request - invalid parameters
        '403':
          description: Forbidden - user does not have debug permission
        '404':
          description: Connector not found
      security:
      - api_key: []
      - session_token: []
      summary: Get chats from connector exploration (requires debug permission)
      tags:
      - connectors
  /connectors/{connector_id}/explore/runs:
    get:
      operationId: get_connector_exploration_runs
      parameters:
      - description: The connector ID
        in: path
        name: connector_id
        required: true
        schema:
          $ref: '#/components/schemas/ConnectorId'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExplorationRunsResponse'
          description: Exploration runs retrieved successfully
        '403':
          description: Forbidden - user does not have debug permission
        '404':
          description: Connector not found
      security:
      - api_key: []
      - session_token: []
      summary: Get all exploration runs for a connector (requires debug permission)
      tags:
      - connectors
  /connectors/{connector_id}/explore/runs/{run_id}/progress:
    get:
      operationId: get_exploration_run_progress
      parameters:
      - in: path
        name: connector_id
        required: true
        schema:
          $ref: '#/components/schemas/ConnectorId'
      - in: path
        name: run_id
        required: true
        schema:
          $ref: '#/components/schemas/ExplorationRunId'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExplorationProgress'
          description: Exploration progress retrieved successfully
        '403':
          description: Forbidden
        '404':
          description: Connector or run not found
      security:
      - api_key: []
      - session_token: []
      tags:
      - connectors
  /connectors/{connector_id}/schema_object:
    delete:
      operationId: delete_connector_schema_object
      parameters:
      - description: The connector ID
        in: path
        name: connector_id
        required: true
        schema:
          $ref: '#/components/schemas/ConnectorId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteSchemaObjectRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteSchemaObjectResponse'
          description: Schema object deleted successfully
        '400':
          description: Bad request - invalid object specification
        '403':
          description: Forbidden - user does not have access to connector
        '404':
          description: Connector or object not found
      security:
      - api_key: []
      tags:
      - connectors
    post:
      operationId: add_connector_schema_object
      parameters:
      - description: The connector ID
        in: path
        name: connector_id
        required: true
        schema:
          $ref: '#/components/schemas/ConnectorId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddSchemaObjectRequest'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddSchemaObjectResponse'
          description: Schema object created successfully
        '400':
          description: Bad request - invalid object specification
        '403':
          description: Forbidden - user does not have access to connector
        '404':
          description: Connector or parent object not found
      security:
      - api_key: []
      - session_token: []
      tags:
      - connectors
  /connectors/{connector_id}/secrets:
    post:
      operationId: create_connector_secret
      parameters:
      - in: path
        name: connector_id
        required: true
        schema:
          $ref: '#/components/schemas/ConnectorId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSecretRequest'
        required: true
      responses:
        '201':
          description: Secret created successfully
        '400':
          description: Invalid request data
        '401':
          description: Unauthorized
        '404':
          description: Connector not found
      security:
      - api_key: []
      - session_token: []
      tags:
      - connectors
  /connectors/{connector_id}/secrets/{secret_name}:
    delete:
      operationId: delete_connector_secret
      parameters:
      - in: path
        name: connector_id
        required: true
        schema:
          $ref: '#/components/schemas/ConnectorId'
      - in: path
        name: secret_name
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Secret deleted successfully
        '401':
          description: Unauthorized
        '404':
          description: Connector or secret not found
      security:
      - api_key: []
      - session_token: []
      tags:
      - connectors
  /connectors/{connector_id}/store:
    get:
      operationId: get_connector_store
      parameters:
      - description: The connector ID
        in: path
        name: connector_id
        required: true
        schema:
          $ref: '#/components/schemas/ConnectorId'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectorStoreResponse'
          description: Connector's LLM information store
        '401':
          description: Unauthorized
        '403':
          description: Forbidden - user does not have access to connector
        '404':
          description: Connector not found
      security:
      - api_key: []
      - session_token: []
      tags:
      - connectors
  /connectors/{connector_id}/tables:
    get:
      description: 'Returns all tables across all databases and schemas for the given connector.

        Useful for finding table IDs to pass to the explore endpoint for single-table exploration.'
      operationId: list_connector_tables
      parameters:
      - description: Connector ID
        in: path
        name: connector_id
        required: true
        schema:
          $ref: '#/components/schemas/ConnectorId'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListTablesResponse'
          description: Successfully retrieved tables
        '403':
          description: Forbidden - user does not have access to connector
        '404':
          description: Connector not found
      security:
      - api_key: []
      - session_token: []
      summary: List all tables for a connector
      tags:
      - connectors
  /internal/connectors/{connector_id}/datahub-artifacts/{kind}:
    get:
      operationId: connectors_download_datahub_artifact
      parameters:
      - in: path
        name: connector_id
        required: true
        schema:
          $ref: '#/components/schemas/ConnectorId'
      - in: path
        name: kind
        required: true
        schema:
          type: string
      - in: query
        name: exploration_run_id
        required: false
        schema:
          allOf:
          - $ref: '#/components/schemas/ExplorationRunId'
          nullable: true
      responses:
        '200':
          content:
            application/octet-stream:
              schema:
                format: binary
                type: string
          description: Connector DataHub artifact bytes
        '403':
          description: Forbidden
        '404':
          description: Artifact or connector not found
      security:
      - api_key: []
      - session_token: []
      tags:
      - connectors
    put:
      operationId: connectors_upload_datahub_artifact
      parameters:
      - in: path
        name: connector_id
        required: true
        schema:
          $ref: '#/components/schemas/ConnectorId'
      - in: path
        name: kind
        required: true
        schema:
          type: string
      - in: query
        name: exploration_run_id
        required: true
        schema:
          $ref: '#/components/schemas/ExplorationRunId'
      requestBody:
        content:
          multipart/form-data:
            schema:
              properties:
                file:
                  format: binary
                  type: string
              required:
              - file
              type: object
        required: true
      responses:
        '204':
          description: Connector DataHub artifact uploaded successfully
        '403':
          description: Forbidden
        '404':
          description: Artifact or connector not found
      security:
      - api_key: []
      - session_token: []
      tags:
      - connectors
components:
  schemas:
    PinPreviousToolInput:
      properties:
        path:
          type: string
      required:
      - path
      type: object
    RunPythonInput:
      properties:
        code:
          type: string
        connector:
          nullable: true
          type: string
        timeout_seconds:
          format: int64
          minimum: 0
          nullable: true
          type: integer
        working_dir:
          nullable: true
          type: string
      required:
      - code
      type: object
    TableDescriptor:
      additionalProperties: false
      description: The full definition of what a schema is - without duplicate information.
      properties:
        description:
          type: string
        expected_cardinality:
          description: 'Expected number of unique values in the complete dataset.


            This is used for our probabilistic merge strategy.'
          format: int64
          minimum: 0
          nullable: true
          type: integer
        name:
          description: Organized in a name, description format.
          type: string
        primary_column:
          nullable: true
          type: string
        properties:
          description: Organized in a name, description format.
          items:
            $ref: '#/components/schemas/PropertyDescriptor'
          type: array
      required:
      - name
      - description
      - properties
      type: object
    ScraperMeta:
      properties:
        html_content:
          type: string
        url:
          type: string
      required:
      - html_content
      - url
      type: object
    SchemaObjectId:
      discriminator:
        propertyName: type
      oneOf:
      - properties:
          id:
            $ref: '#/components/schemas/ConnectorColumnId'
          type:
            enum:
            - column
            type: string
        required:
        - id
        - type
        type: object
      - properties:
          id:
            $ref: '#/components/schemas/ConnectorTableId'
          type:
            enum:
            - table
            type: string
        required:
        - id
        - type
        type: object
      - properties:
          id:
            $ref: '#/components/schemas/ConnectorSchemaId'
          type:
            enum:
            - schema
            type: string
        required:
        - id
        - type
        type: object
      - properties:
          id:
            $ref: '#/components/schemas/ConnectorDatabaseId'
          type:
            enum:
            - database
            type: string
        required:
        - id
        - type
        type: object
    CreateConnectorRequest:
      properties:
        description:
          nullable: true
          type: string
        known_connector_type:
          type: string
        name:
          type: string
        nango_connection_id:
          description: Nango connection ID for OAuth token management
          nullable: true
          type: string
        secrets:
          additionalProperties:
            type: string
          description: Optional secrets/environment variables for the connector
          type: object
      required:
      - name
      - known_connector_type
      type: object
    ChatEvent:
      description: Events in a chat session timeline, including messages and unified tool calls/results
      oneOf:
      - properties:
          TextMessage:
            properties:
              message:
                type: string
            required:
            - message
            type: object
        required:
        - TextMessage
        type: object
      - properties:
          Thinking:
            properties:
              block_id:
                format: int64
                minimum: 0
                type: integer
              complete:
                type: boolean
              content:
                type: string
            required:
            - content
            - complete
            - block_id
            type: object
        required:
        - Thinking
        type: object
      - properties:
          File:
            description: 'The file event can''t be serialized to the database safely without the content.

              When streaming, we start with the path only, then add the content as we go.'
            properties:
              block_id:
                format: int64
                minimum: 0
                type: integer
              complete:
                type: boolean
              content:
                nullable: true
                type: string
              path:
                type: string
            required:
            - path
            - complete
            - block_id
            type: object
        required:
        - File
        type: object
      - properties:
          Action:
            properties:
              actions:
                items:
                  $ref: '#/components/schemas/ActionDef'
                type: array
              block_id:
                format: int64
                minimum: 0
                type: integer
              complete:
                type: boolean
            required:
            - actions
            - complete
            - block_id
            type: object
        required:
        - Action
        type: object
      - properties:
          Connector:
            properties:
              description:
                nullable: true
                type: string
              env_vars:
                items:
                  type: string
                type: array
              name:
                type: string
            required:
            - name
            - env_vars
            type: object
        required:
        - Connector
        type: object
      - properties:
          ToolCall:
            properties:
              block_id:
                format: int64
                minimum: 0
                type: integer
              complete:
                type: boolean
              invocation:
                $ref: '#/components/schemas/ToolInvocation'
              tool_result:
                $ref: '#/components/schemas/ToolResult'
            required:
            - invocation
            - tool_result
            - block_id
            - complete
            type: object
        required:
        - ToolCall
        type: object
      - properties:
          Question:
            properties:
              block_id:
                format: int64
                minimum: 0
                type: integer
              complete:
                type: boolean
              content:
                type: string
              options:
                items:
                  type: string
                type: array
            required:
            - content
            - complete
            - options
            - block_id
            type: object
        required:
        - Question
        type: object
      - properties:
          InternalError:
            properties:
              error_kind:
                $ref: '#/components/schemas/InternalErrorKind'
              message:
                type: string
            required:
            - message
            type: object
        required:
        - InternalError
        type: object
      - properties:
          ReviewReque

# --- truncated at 32 KB (97 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/structify/refs/heads/main/openapi/structify-connectors-api-openapi.yml