Structify connectors API

openapi: 3.2.0
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'
          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'
      - in: query
        name: database_id
        required: false
        schema:
          allOf:
          - $ref: '#/components/schemas/ConnectorDatabaseId'
      - in: query
        name: schema_id
        required: false
        schema:
          allOf:
          - $ref: '#/components/schemas/ConnectorSchemaId'
      - in: query
        name: table_id
        required: false
        schema:
          allOf:
          - $ref: '#/components/schemas/ConnectorTableId'
      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'
      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:
    ConnectorExplorerChatId:
      format: uuid
      type: string
    DecodingParams:
      properties:
        parameters:
          items:
            $ref: '#/components/schemas/DecodingParamEnum'
          type: array
      required:
      - parameters
      type: object
    ToolResult:
      oneOf:
      - enum:
        - Pending
        type: string
      - enum:
        - NoResult
        type: string
      - properties:
          Error:
            type: string
        required:
        - Error
        type: object
      - properties:
          Text:
            type: string
        required:
        - Text
        type: object
      - properties:
          CodeExecution:
            $ref: '#/components/schemas/CodeExecutionResult'
        required:
        - CodeExecution
        type: object
      - properties:
          WebMarkdown:
            type: string
        required:
        - WebMarkdown
        type: object
      - properties:
          WebSearch:
            items:
              $ref: '#/components/schemas/DocSnippet'
            type: array
        required:
        - WebSearch
        type: object
      - properties:
          ConnectorSearch:
            items:
              $ref: '#/components/schemas/ConnectorTableResult'
            type: array
        required:
        - ConnectorSearch
        type: object
      - properties:
          NodeLogs:
            items:
              type: string
            type: array
        required:
        - NodeLogs
        type: object
      - enum:
        - Completed
        type: string
      - properties:
          Image:
            $ref: '#/components/schemas/ImageResult'
        required:
        - Image
        type: object
      - properties:
          Pinned:
            type: string
        required:
        - Pinned
        type: object
    ConnectorStoreResponse:
      properties:
        store:
          allOf:
          - $ref: '#/components/schemas/LlmInformationStore'
      type: object
    Verbosity:
      enum:
      - low
      - medium
      - high
      type: string
    ConnectorTableResult:
      properties:
        columns:
          items:
            $ref: '#/components/schemas/ConnectorColumnResult'
          type: array
        database:
          type: string
        description:
          type:
          - string
          - 'null'
        notes:
          type:
          - string
          - 'null'
        schema:
          type: string
        table_name:
          type: string
      required:
      - schema
      - database
      - table_name
      - columns
      type: object
    ConnectorColumnId:
      format: uuid
      type: string
    ClarificationRequestId:
      format: uuid
      type: string
    SaveMemoryInput:
      properties:
        key:
          type: string
        value:
          type: string
      required:
      - key
      - value
      type: object
    ExitInput:
      properties:
        reason:
          type: string
      required:
      - reason
      type: object
    DeleteFileInput:
      properties:
        file:
          type: string
      required:
      - file
      type: object
    InspectStepInput:
      properties:
        step_name:
          type: string
      required:
      - step_name
      type: object
    ConnectorTable:
      description: Represents a table (for relational databases) or resource (for APIs)
      properties:
        columns:
          description: List of columns in this table/resource
          items:
            $ref: '#/components/schemas/ConnectorColumn'
          type: array
        description:
          description: Optional description
          type:
          - string
          - 'null'
        endpoint:
          description: API endpoint (None for relational DB tables, Some for API resources)
          type:
          - string
          - 'null'
        id:
          $ref: '#/components/schemas/ConnectorTableId'
        name:
          description: Name of the table or resource
          type: string
        notes:
          description: Optional notes
          type:
          - string
          - 'null'
      required:
      - id
      - name
      - columns
      type: object
    CreatedSchemaObject:
      discriminator:
        propertyName: type
      oneOf:
      - properties:
          id:
            $ref: '#/components/schemas/ConnectorDatabaseId'
          type:
            enum:
            - database
            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/ConnectorTableId'
          type:
            enum:
            - table
            type: string
        required:
        - id
        - type
        type: object
      - properties:
          id:
            $ref: '#/components/schemas/ConnectorColumnId'
          type:
            enum:
            - column
            type: string
        required:
        - id
        - type
        type: object
    ExplorationPhaseId:
      description: 'Identifies the phase of connector exploration


        This enum is used to track which phase of exploration a chat session belongs to.

        It''s stored as JSONB in the database to allow for flexible phase identification.'
      discriminator:
        propertyName: type
      oneOf:
      - description: 'First phase: discovering all databases in the connector'
        properties:
          connector_id:
            $ref: '#/components/schemas/ConnectorId'
          type:
            enum:
            - discover_databases
            type: string
        required:
        - connector_id
        - type
        type: object
      - description: 'Second phase: discovering all schemas in a database'
        properties:
          database_id:
            $ref: '#/components/schemas/ConnectorDatabaseId'
          database_name:
            type: string
          type:
            enum:
            - discover_schemas
            type: string
        required:
        - database_id
        - database_name
        - type
        type: object
      - description: 'Third phase: discovering all tables in a schema'
        properties:
          schema_id:
            $ref: '#/components/schemas/ConnectorSchemaId'
          schema_name:
            type: string
          type:
            enum:
            - discover_tables
            type: string
        required:
        - schema_id
        - schema_name
        - type
        type: object
      - description: 'Fourth phase: discovering columns for a specific table'
        properties:
          table_id:
            $ref: '#/components/schemas/ConnectorTableId'
          table_name:
            type: string
          type:
            enum:
            - discover_columns
            type: string
        required:
        - table_id
        - table_name
        - type
        type: object
      - description: 'Initial phase: discovering all API resources'
        properties:
          connector_id:
            $ref: '#/components/schemas/ConnectorId'
          type:
            enum:
            - discover_api_resources
            type: string
        required:
        - connector_id
        - type
        type: object
 

# --- 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