openapi: 3.1.0
info:
  title: Soda Cloud REST Attributes Users 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: Users
  description: User and user group management
paths:
  /api/v1/userGroups:
    get:
      summary: List user groups
      operationId: listUserGroups
      tags:
      - Users
      parameters:
      - name: size
        in: query
        schema:
          type: integer
          minimum: 10
          maximum: 1000
          default: 1000
      - name: page
        in: query
        schema:
          type: integer
          default: 0
      - name: search
        in: query
        schema:
          type: string
      responses:
        '200':
          description: Paginated list of user groups
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    post:
      summary: Create user group
      operationId: createUserGroup
      tags:
      - Users
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                userIds:
                  type: array
                  items:
                    type: string
      responses:
        '200':
          description: User group created
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /api/v1/userGroups/{userGroupId}:
    get:
      summary: Get user group
      operationId: getUserGroup
      tags:
      - Users
      parameters:
      - name: userGroupId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: User group details
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    post:
      summary: Update user group
      operationId: updateUserGroup
      tags:
      - Users
      parameters:
      - name: userGroupId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                userIds:
                  type: array
                  items:
                    type: string
      responses:
        '200':
          description: User group updated
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    delete:
      summary: Delete user group
      operationId: deleteUserGroup
      tags:
      - Users
      parameters:
      - name: userGroupId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: User group deleted
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /api/v1/users:
    get:
      summary: List users
      operationId: listUsers
      tags:
      - Users
      parameters:
      - name: size
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 1000
          default: 1000
      - name: page
        in: query
        schema:
          type: integer
          default: 0
      - name: search
        in: query
        schema:
          type: string
      responses:
        '200':
          description: Paginated list of users
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    post:
      summary: Invite users
      description: Send invitations to new users (up to 10 per request).
      operationId: inviteUsers
      tags:
      - Users
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                emails:
                  type: array
                  items:
                    type: string
                    format: email
                  maxItems: 10
      responses:
        '200':
          description: Invitations sent
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /api/v1/users/{userId}/disable:
    post:
      summary: Disable user
      description: Deactivate a user account.
      operationId: disableUser
      tags:
      - Users
      parameters:
      - name: userId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: User disabled
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
  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'
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: 'Base64-encoded API key ID and secret: base64(api_key_id:api_key_secret)'