openapi: 3.1.0
info:
  title: Soda Cloud REST Attributes Datasets 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: Datasets
  description: Dataset management, monitoring, and configuration
paths:
  /api/v1/datasets:
    get:
      summary: List datasets
      description: Retrieve a paginated list of datasets with optional filtering.
      operationId: listDatasets
      tags:
      - Datasets
      parameters:
      - name: size
        in: query
        schema:
          type: integer
          minimum: 10
          maximum: 1000
          default: 10
      - name: page
        in: query
        schema:
          type: integer
          default: 0
      - name: from
        in: query
        schema:
          type: string
          format: date-time
        description: ISO 8601 timestamp filter
      - name: datasourceName
        in: query
        schema:
          type: string
      - name: search
        in: query
        schema:
          type: string
      responses:
        '200':
          description: Paginated list of datasets
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiDatasetsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/v1/datasets/byDatasetQualifiedName/{datasetQualifiedName}:
    get:
      summary: Get dataset by qualified name
      description: Retrieve a single dataset by its qualified name.
      operationId: getDatasetByQualifiedName
      tags:
      - Datasets
      parameters:
      - name: datasetQualifiedName
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Dataset details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DatasetsContentDTO'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/v1/datasets/{datasetId}:
    get:
      summary: Get dataset by ID
      description: Retrieve a single dataset by its ID.
      operationId: getDataset
      tags:
      - Datasets
      parameters:
      - name: datasetId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Dataset details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DatasetsContentDTO'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      summary: Update dataset
      description: Update dataset metadata including label, tags, attributes, owners, and configuration settings.
      operationId: updateDataset
      tags:
      - Datasets
      parameters:
      - name: datasetId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicApiUpdateDatasetDTO'
      responses:
        '200':
          description: Updated dataset
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DatasetsContentDTO'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      summary: Delete dataset
      description: Delete a dataset. Deletion is not immediate and can take some time to complete.
      operationId: deleteDataset
      tags:
      - Datasets
      parameters:
      - name: datasetId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Deletion initiated
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/v1/datasets/roles:
    get:
      summary: List dataset roles
      operationId: listDatasetRoles
      tags:
      - Datasets
      parameters:
      - name: size
        in: query
        schema:
          type: integer
          minimum: 10
          maximum: 100
          default: 100
      - name: page
        in: query
        schema:
          type: integer
          default: 0
      responses:
        '200':
          description: List of dataset roles
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    post:
      summary: Create dataset role
      operationId: createDatasetRole
      tags:
      - Datasets
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DatasetRoleRequest'
      responses:
        '200':
          description: Created role
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /api/v1/datasets/roles/{roleId}:
    post:
      summary: Update dataset role
      operationId: updateDatasetRole
      tags:
      - Datasets
      parameters:
      - name: roleId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DatasetRoleRequest'
      responses:
        '200':
          description: Updated role
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    delete:
      summary: Delete dataset role
      operationId: deleteDatasetRole
      tags:
      - Datasets
      parameters:
      - name: roleId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Role deleted
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /api/v1/datasets/{datasetId}/columnAttributes:
    post:
      summary: Set column attributes in bulk
      operationId: setColumnAttributes
      tags:
      - Datasets
      parameters:
      - name: datasetId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              description: Mapping of column names to attribute key-value pairs
      responses:
        '200':
          description: Attributes set
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /api/v1/datasets/{datasetId}/columnMetricMonitors:
    post:
      summary: Create column metric monitor
      operationId: createColumnMetricMonitor
      tags:
      - Datasets
      parameters:
      - name: datasetId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ColumnMetricMonitorRequest'
      responses:
        '200':
          description: Monitor created
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /api/v1/datasets/{datasetId}/columnMetricMonitors/{monitorId}:
    post:
      summary: Update column metric monitor
      operationId: updateColumnMetricMonitor
      tags:
      - Datasets
      parameters:
      - name: datasetId
        in: path
        required: true
        schema:
          type: string
      - name: monitorId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Monitor updated
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    delete:
      summary: Delete column metric monitor
      operationId: deleteColumnMetricMonitor
      tags:
      - Datasets
      parameters:
      - name: datasetId
        in: path
        required: true
        schema:
          type: string
      - name: monitorId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Monitor deleted
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /api/v1/datasets/{datasetId}/customSqlMonitors:
    post:
      summary: Create custom SQL monitor
      operationId: createCustomSqlMonitor
      tags:
      - Datasets
      parameters:
      - name: datasetId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomSqlMonitorRequest'
      responses:
        '200':
          description: Monitor created
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /api/v1/datasets/{datasetId}/customSqlMonitors/{monitorId}:
    post:
      summary: Update custom SQL monitor
      operationId: updateCustomSqlMonitor
      tags:
      - Datasets
      parameters:
      - name: datasetId
        in: path
        required: true
        schema:
          type: string
      - name: monitorId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Monitor updated
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    delete:
      summary: Delete custom SQL monitor
      operationId: deleteCustomSqlMonitor
      tags:
      - Datasets
      parameters:
      - name: datasetId
        in: path
        required: true
        schema:
          type: string
      - name: monitorId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Monitor deleted
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /api/v1/datasets/{datasetId}/computeWarehouse:
    get:
      summary: Get dataset compute warehouse configuration
      operationId: getDatasetComputeWarehouse
      tags:
      - Datasets
      parameters:
      - name: datasetId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Compute warehouse configuration
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /api/v1/datasets/{datasetId}/diagnosticsWarehouse:
    get:
      summary: Get dataset diagnostics warehouse information
      operationId: getDatasetDiagnosticsWarehouse
      tags:
      - Datasets
      parameters:
      - name: datasetId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Diagnostics warehouse information
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  schemas:
    CustomSqlMonitorRequest:
      type: object
      properties:
        name:
          type: string
        sqlQuery:
          type: string
        resultMetric:
          type: string
        configuration:
          type: object
    PublicApiDatasetsResponse:
      allOf:
      - $ref: '#/components/schemas/PaginatedResponse'
      - type: object
        properties:
          content:
            type: array
            items:
              $ref: '#/components/schemas/DatasetsContentDTO'
    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
    DatasetsContentDTO:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        label:
          type: string
        qualifiedName:
          type: string
        datasourceId:
          type: string
        datasourceName:
          type: string
        tags:
          type: array
          items:
            type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        cloudUrl:
          type: string
          format: uri
    DatasetRoleRequest:
      type: object
      required:
      - name
      properties:
        name:
          type: string
        viewDataset:
          type: boolean
        configureDataset:
          type: boolean
        manageDataset:
          type: boolean
        deleteDataset:
          type: boolean
    PublicApiUpdateDatasetDTO:
      type: object
      properties:
        label:
          type: string
        tags:
          type: array
          items:
            type: string
        attributes:
          type: object
        owners:
          type: array
          items:
            type: string
    ErrorResponse:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
    ColumnMetricMonitorRequest:
      type: object
      properties:
        columnName:
          type: string
        metricType:
          type: string
        configuration:
          type: object
  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'
    Forbidden:
      description: Forbidden - insufficient permissions
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalServerError:
      description: Internal server error
      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)'