openapi: 3.1.0
info:
  title: Soda Cloud REST Attributes Datasources API
  description: The Soda Cloud REST API enables programmatic access to trigger data quality scans, retrieve check results, update incident status, manage datasets, datasources, contracts, runners, secrets, notification rules, and integrate data quality workflows into CI/CD pipelines. Supports EU and US cloud regions.
  version: 1.0.0
  contact:
    name: Soda Support
    url: https://soda.io
servers:
- url: https://cloud.soda.io
  description: EU Cloud
- url: https://cloud.us.soda.io
  description: US Cloud
security:
- basicAuth: []
tags:
- name: Datasources
  description: Data source connection and configuration management
paths:
  /api/v1/datasources:
    get:
      summary: List datasources
      operationId: listDatasources
      tags:
      - Datasources
      parameters:
      - name: size
        in: query
        schema:
          type: integer
          minimum: 10
          maximum: 1000
          default: 10
      - name: page
        in: query
        schema:
          type: integer
          default: 0
      - name: search
        in: query
        schema:
          type: string
      responses:
        '200':
          description: Paginated list of datasources
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    post:
      summary: Create datasource
      description: Create a new V4 datasource from a YAML configuration.
      operationId: createDatasource
      tags:
      - Datasources
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDatasourceRequest'
      responses:
        '200':
          description: Datasource created
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /api/v1/datasources/actions/testConnection:
    post:
      summary: Test datasource connection
      description: Initiates an async connection test. Returns 202 with operation ID to poll.
      operationId: testDatasourceConnection
      tags:
      - Datasources
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - configurationFileContents
              - runnerId
              properties:
                configurationFileContents:
                  type: string
                runnerId:
                  type: string
      responses:
        '202':
          description: Test initiated
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /api/v1/datasources/actions/testConnection/{operationId}:
    get:
      summary: Poll connection test status
      operationId: getConnectionTestStatus
      tags:
      - Datasources
      parameters:
      - name: operationId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Operation status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationStatusResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /api/v1/datasources/roles:
    get:
      summary: List datasource roles
      operationId: listDatasourceRoles
      tags:
      - Datasources
      parameters:
      - name: size
        in: query
        schema:
          type: integer
          default: 10
      - name: page
        in: query
        schema:
          type: integer
          default: 0
      responses:
        '200':
          description: List of roles
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    post:
      summary: Create datasource role
      operationId: createDatasourceRole
      tags:
      - Datasources
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DatasourceRoleRequest'
      responses:
        '200':
          description: Role created
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /api/v1/datasources/roles/{roleId}:
    post:
      summary: Update datasource role
      operationId: updateDatasourceRole
      tags:
      - Datasources
      parameters:
      - name: roleId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DatasourceRoleRequest'
      responses:
        '200':
          description: Role updated
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    delete:
      summary: Delete datasource role
      operationId: deleteDatasourceRole
      tags:
      - Datasources
      parameters:
      - name: roleId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Role deleted (async)
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /api/v1/datasources/{datasourceId}:
    get:
      summary: Get datasource
      operationId: getDatasource
      tags:
      - Datasources
      parameters:
      - name: datasourceId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Datasource details
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    post:
      summary: Update datasource
      operationId: updateDatasource
      tags:
      - Datasources
      parameters:
      - name: datasourceId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                configurationFileContents:
                  type: string
                label:
                  type: string
                runnerId:
                  type: string
      responses:
        '200':
          description: Datasource updated
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    delete:
      summary: Delete datasource
      description: Remove datasource and all associated resources (async operation).
      operationId: deleteDatasource
      tags:
      - Datasources
      parameters:
      - name: datasourceId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Deletion initiated
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /api/v1/datasources/{datasourceId}/diagnosticsWarehouse:
    get:
      summary: Get datasource diagnostics warehouse config
      operationId: getDatasourceDiagnosticsWarehouse
      tags:
      - Datasources
      parameters:
      - name: datasourceId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Diagnostics warehouse configuration
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    post:
      summary: Update datasource diagnostics warehouse
      operationId: updateDatasourceDiagnosticsWarehouse
      tags:
      - Datasources
      parameters:
      - name: datasourceId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Updated
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /api/v1/datasources/{datasourceId}/discover:
    post:
      summary: Trigger on-demand discovery scan
      operationId: triggerDiscovery
      tags:
      - Datasources
      parameters:
      - name: datasourceId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Discovery scan triggered
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /api/v1/datasources/{datasourceId}/onboardDatasets:
    post:
      summary: Onboard datasets
      description: Async operation to onboard discovered datasets from a datasource.
      operationId: onboardDatasets
      tags:
      - Datasources
      parameters:
      - name: datasourceId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - discoveredDatasetIds
              properties:
                discoveredDatasetIds:
                  type: array
                  items:
                    type: string
      responses:
        '202':
          description: Onboarding initiated
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /api/v1/datasources/{datasourceId}/onboardDatasets/{operationId}:
    get:
      summary: Poll onboarding operation status
      operationId: getOnboardingStatus
      tags:
      - Datasources
      parameters:
      - name: datasourceId
        in: path
        required: true
        schema:
          type: string
      - name: operationId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Onboarding status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationStatusResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /api/v1/datasources/{datasourceId}/responsibilities:
    get:
      summary: List datasource responsibilities
      operationId: listDatasourceResponsibilities
      tags:
      - Datasources
      parameters:
      - name: datasourceId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: User/group permission assignments
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    post:
      summary: Update datasource responsibilities
      operationId: updateDatasourceResponsibilities
      tags:
      - Datasources
      parameters:
      - name: datasourceId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                responsibilities:
                  type: array
                  items:
                    type: object
                    properties:
                      roleId:
                        type: string
                      type:
                        type: string
                        enum:
                        - user
                        - userGroup
                      userId:
                        type: string
                      userGroupId:
                        type: string
      responses:
        '200':
          description: Responsibilities updated
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  schemas:
    PaginatedResponse:
      type: object
      properties:
        content:
          type: array
          items:
            type: object
        first:
          type: boolean
        last:
          type: boolean
        number:
          type: integer
        size:
          type: integer
        totalElements:
          type: integer
        totalPages:
          type: integer
    CreateDatasourceRequest:
      type: object
      required:
      - configurationFileContents
      properties:
        configurationFileContents:
          type: string
          description: YAML configuration for the datasource
        label:
          type: string
        runnerId:
          type: string
    ErrorResponse:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
    OperationStatusResponse:
      type: object
      properties:
        id:
          type: string
        state:
          type: string
          enum:
          - queued
          - processing
          - completed
          - failed
          - cancelled
        message:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    DatasourceRoleRequest:
      type: object
      required:
      - name
      properties:
        name:
          type: string
        viewDatasource:
          type: boolean
        createDatasets:
          type: boolean
        manageDatasourceSettings:
          type: boolean
        managePermissions:
          type: boolean
        deleteDatasource:
          type: boolean
  responses:
    Unauthorized:
      description: Unauthorized - authentication required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    TooManyRequests:
      description: Rate limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: 'Base64-encoded API key ID and secret: base64(api_key_id:api_key_secret)'