CloudQuery Admin API

openapi: 3.2.0
info:
  contact:
    email: support@cloudquery.io
    name: CloudQuery Support Team
    url: https://cloudquery.io
  description: Welcome to the CloudQuery Platform API documentation!
  license:
    name: MIT
    url: https://spdx.org/licenses/MIT
  termsOfService: https://www.cloudquery.io/terms
  title: CloudQuery Platform OpenAPI Spec Admin API
  version: 1.0.0
security:
- bearerAuth: []
- cookieAuth: []
tags:
- name: Admin
paths:
  /users:
    post:
      description: Add new user
      operationId: PlatformAddUser
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
              - email
              - name
              - roles
              properties:
                email:
                  type: string
                name:
                  type: string
                password:
                  type: string
                roles:
                  description: Roles for the user
                  type: array
                  minItems: 0
                  items:
                    $ref: '#/components/schemas/PlatformRoleID'
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformUser'
        '400':
          $ref: '#/components/responses/PlatformBadRequest'
        '401':
          $ref: '#/components/responses/PlatformRequiresAuthentication'
        '403':
          $ref: '#/components/responses/PlatformForbidden'
        '404':
          $ref: '#/components/responses/PlatformNotFound'
        '405':
          $ref: '#/components/responses/PlatformMethodNotAllowed'
        '422':
          $ref: '#/components/responses/PlatformUnprocessableEntity'
        '500':
          $ref: '#/components/responses/PlatformInternalError'
      tags:
      - Admin
      summary: Platform add user
      x-summary-source: derived
  /users/{user_id}:
    get:
      description: Get user details
      operationId: PlatformGetUser
      parameters:
      - $ref: '#/components/parameters/platform_user_id'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformUser'
          description: Response
        '400':
          $ref: '#/components/responses/PlatformBadRequest'
        '401':
          $ref: '#/components/responses/PlatformRequiresAuthentication'
        '403':
          $ref: '#/components/responses/PlatformForbidden'
        '404':
          $ref: '#/components/responses/PlatformNotFound'
        '422':
          $ref: '#/components/responses/PlatformUnprocessableEntity'
        '500':
          $ref: '#/components/responses/PlatformInternalError'
      tags:
      - Admin
      summary: Platform get user
      x-summary-source: derived
    patch:
      description: Update user
      operationId: PlatformUpdateUser
      parameters:
      - $ref: '#/components/parameters/platform_user_id'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                email:
                  type: string
                name:
                  type: string
                password:
                  type: string
                enabled:
                  type: boolean
                roles:
                  description: Roles for the user
                  type: array
                  minItems: 0
                  items:
                    $ref: '#/components/schemas/PlatformRoleID'
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformUser'
        '400':
          $ref: '#/components/responses/PlatformBadRequest'
        '401':
          $ref: '#/components/responses/PlatformRequiresAuthentication'
        '403':
          $ref: '#/components/responses/PlatformForbidden'
        '404':
          $ref: '#/components/responses/PlatformNotFound'
        '422':
          $ref: '#/components/responses/PlatformUnprocessableEntity'
        '500':
          $ref: '#/components/responses/PlatformInternalError'
      tags:
      - Admin
      summary: Platform update user
      x-summary-source: derived
    delete:
      description: Delete user
      operationId: PlatformDeleteUser
      parameters:
      - $ref: '#/components/parameters/platform_user_id'
      responses:
        '204':
          description: Response
        '400':
          $ref: '#/components/responses/PlatformBadRequest'
        '401':
          $ref: '#/components/responses/PlatformRequiresAuthentication'
        '403':
          $ref: '#/components/responses/PlatformForbidden'
        '404':
          $ref: '#/components/responses/PlatformNotFound'
        '422':
          $ref: '#/components/responses/PlatformUnprocessableEntity'
        '500':
          $ref: '#/components/responses/PlatformInternalError'
      tags:
      - Admin
      summary: Platform delete user
      x-summary-source: derived
  /auth/saml:
    get:
      description: Get SAML integration information
      operationId: PlatformGetSAML
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformSAMLConfig'
        '400':
          $ref: '#/components/responses/PlatformBadRequest'
        '500':
          $ref: '#/components/responses/PlatformInternalError'
      tags:
      - Admin
      summary: Platform get SAML
      x-summary-source: derived
    patch:
      description: Update SAML integration information
      operationId: PlatformUpdateSAML
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlatformSAMLConfigUpdate'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformSAMLConfig'
        '400':
          $ref: '#/components/responses/PlatformBadRequest'
        '404':
          $ref: '#/components/responses/PlatformNotFound'
        '422':
          $ref: '#/components/responses/PlatformUnprocessableEntity'
        '500':
          $ref: '#/components/responses/PlatformInternalError'
      tags:
      - Admin
      summary: Platform update SAML
      x-summary-source: derived
  /auth/saml/rollover:
    put:
      description: Create new SAML rollover certificate
      operationId: PlatformCreateSAMLRolloverCertificate
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformSAMLConfig'
        '400':
          $ref: '#/components/responses/PlatformBadRequest'
        '404':
          $ref: '#/components/responses/PlatformNotFound'
        '409':
          $ref: '#/components/responses/PlatformConflict'
        '422':
          $ref: '#/components/responses/PlatformUnprocessableEntity'
        '500':
          $ref: '#/components/responses/PlatformInternalError'
      tags:
      - Admin
      summary: Platform create SAML rollover certificate
      x-summary-source: derived
    delete:
      description: Delete current SAML rollover certificate
      operationId: PlatformDeleteSAMLRolloverCertificate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - fingerprint
              properties:
                fingerprint:
                  type: string
                  description: The fingerprint of the rollover certificate to delete
                  example: SHA256:AB:CD:EF:12:34:56:78:90:AB:CD:EF:12:34:56:78:90
      responses:
        '204':
          description: Success
        '400':
          $ref: '#/components/responses/PlatformBadRequest'
        '404':
          $ref: '#/components/responses/PlatformNotFound'
        '422':
          $ref: '#/components/responses/PlatformUnprocessableEntity'
        '500':
          $ref: '#/components/responses/PlatformInternalError'
      tags:
      - Admin
      summary: Platform delete SAML rollover certificate
      x-summary-source: derived
  /auth/saml/rollover/promote:
    put:
      description: Promote SAML rollover certificate
      operationId: PlatformPromoteSAMLRolloverCertificate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - fingerprint
              properties:
                fingerprint:
                  type: string
                  description: The fingerprint of the rollover certificate to promote
                  example: SHA256:AB:CD:EF:12:34:56:78:90:AB:CD:EF:12:34:56:78:90
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformSAMLConfig'
        '400':
          $ref: '#/components/responses/PlatformBadRequest'
        '404':
          $ref: '#/components/responses/PlatformNotFound'
        '422':
          $ref: '#/components/responses/PlatformUnprocessableEntity'
        '500':
          $ref: '#/components/responses/PlatformInternalError'
      tags:
      - Admin
      summary: Platform promote SAML rollover certificate
      x-summary-source: derived
  /settings:
    get:
      description: Show current platform settings
      operationId: PlatformGetSettings
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformSettings'
        '401':
          $ref: '#/components/responses/PlatformRequiresAuthentication'
        '403':
          $ref: '#/components/responses/PlatformForbidden'
        '404':
          $ref: '#/components/responses/PlatformNotFound'
        '422':
          $ref: '#/components/responses/PlatformUnprocessableEntity'
        '500':
          $ref: '#/components/responses/PlatformInternalError'
      tags:
      - Admin
      summary: Platform get settings
      x-summary-source: derived
    patch:
      description: Update platform settings
      operationId: PlatformUpdateSettings
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlatformSettingsUpdate'
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformSettings'
        '401':
          $ref: '#/components/responses/PlatformRequiresAuthentication'
        '403':
          $ref: '#/components/responses/PlatformForbidden'
        '404':
          $ref: '#/components/responses/PlatformNotFound'
        '422':
          $ref: '#/components/responses/PlatformUnprocessableEntity'
        '500':
          $ref: '#/components/responses/PlatformInternalError'
      tags:
      - Admin
      summary: Platform update settings
      x-summary-source: derived
  /settings/data:
    get:
      description: Show current platform data settings
      operationId: PlatformGetDataSettings
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformDataSettings'
        '401':
          $ref: '#/components/responses/PlatformRequiresAuthentication'
        '403':
          $ref: '#/components/responses/PlatformForbidden'
        '404':
          $ref: '#/components/responses/PlatformNotFound'
        '422':
          $ref: '#/components/responses/PlatformUnprocessableEntity'
        '500':
          $ref: '#/components/responses/PlatformInternalError'
      tags:
      - Admin
      summary: Platform get data settings
      x-summary-source: derived
    patch:
      description: Update platform data settings
      operationId: PlatformUpdateDataSettings
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlatformDataSettingsUpdate'
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformDataSettings'
        '401':
          $ref: '#/components/responses/PlatformRequiresAuthentication'
        '403':
          $ref: '#/components/responses/PlatformForbidden'
        '404':
          $ref: '#/components/responses/PlatformNotFound'
        '422':
          $ref: '#/components/responses/PlatformUnprocessableEntity'
        '500':
          $ref: '#/components/responses/PlatformInternalError'
      tags:
      - Admin
      summary: Platform update data settings
      x-summary-source: derived
components:
  schemas:
    PlatformBasicError:
      additionalProperties: false
      description: Basic Error
      required:
      - message
      - status
      properties:
        message:
          type: string
        status:
          type: integer
      title: Basic Error
      type: object
    PlatformSettingsUpdate:
      type: object
      description: Platform settings partial update
      properties:
        enforce_mfa:
          type: boolean
          description: Whether or not to require MFA for all users
          default: false
        ai_agent_data_access:
          type: boolean
          description: Whether AI agents can execute queries against the data warehouse. When false, agents can only explore schemas and generate queries for the user to run manually.
          default: false
    PlatformRole:
      type: object
      description: Role
      required:
      - id
      - name
      - description
      - permissions
      - created_by
      - created_at
      - updated_at
      - type
      properties:
        id:
          description: The unique ID for the role.
          type: string
          format: uuid
          x-go-name: ID
        name:
          type: string
        description:
          type: string
        permissions:
          type: array
          items:
            $ref: '#/components/schemas/PlatformRBACPermission'
        created_by:
          $ref: '#/components/schemas/PlatformCreatedBy'
        created_at:
          example: '2017-07-14T16:53:42Z'
          format: date-time
          type: string
        updated_at:
          example: '2017-07-14T16:53:42Z'
          format: date-time
          type: string
        type:
          $ref: '#/components/schemas/PlatformRoleType'
    PlatformSettings:
      type: object
      description: Platform settings definition
      required:
      - enforce_mfa
      - ai_agent_data_access
      properties:
        enforce_mfa:
          type: boolean
          description: Whether or not to require MFA for all users
          default: false
        ai_agent_data_access:
          type: boolean
          description: Whether AI agents can execute queries against the data warehouse. When false, agents can only explore schemas and generate queries for the user to run manually.
          default: false
    PlatformRBACPermission:
      type: object
      required:
      - id
      - name
      - description
      - query
      - created_by
      - created_at
      - updated_at
      - number_of_affected_roles
      - number_of_affected_users
      properties:
        id:
          $ref: '#/components/schemas/PlatformRBACPermissionID'
        name:
          type: string
        description:
          type: string
        query:
          type: string
        created_by:
          $ref: '#/components/schemas/PlatformCreatedBy'
        created_at:
          example: '2017-07-14T16:53:42Z'
          format: date-time
          type: string
        updated_at:
          example: '2017-07-14T16:53:42Z'
          format: date-time
          type: string
        number_of_affected_roles:
          type: integer
        number_of_affected_users:
          type: integer
    PlatformUserName:
      description: The unique name for the user.
      minLength: 1
      maxLength: 255
      pattern: ^[a-zA-Z\p{L}][a-zA-Z\p{L} \-']*$
      x-pattern-message: can contain only letters, spaces, hyphens, and apostrophes, starting with a letter
      type: string
      example: Sarah O'Connor
    PlatformSAMLConfig:
      title: SAML Configuration
      type: object
      additionalProperties: false
      required:
      - platform_metadata_download_url
      - platform_certificate_download_url
      - platform_sso_url
      - platform_entity_id
      - enabled
      - can_enable
      properties:
        platform_sso_url:
          type: string
          description: SAML service URL.
          format: url
          x-go-name: PlatformSSOURL
        platform_entity_id:
          type: string
          description: SAML Entity ID.
          x-go-name: PlatformEntityID
        platform_metadata_download_url:
          type: string
          description: URL to download platform metadata.
          format: url
          x-go-name: PlatformMetadataDownloadURL
        platform_certificate_download_url:
          type: string
          description: Platform Certificate download URL
          format: url
          x-go-name: PlatformCertificateDownloadURL
        metadata_url:
          type: string
          description: Metadata URL from identity provider. Mutually exclusive with `metadata_xml`
          format: url
          x-go-name: MetadataURL
        metadata_xml:
          type: string
          description: Metadata file contents from identity provider. Mutually exclusive with `metadata_url`
          format: url
          x-go-name: MetadataXML
        logout_url:
          type: string
          description: Logout URL from identity provider
          format: url
          x-go-name: LogoutURL
        role_group_key:
          type: string
          description: Role group key name
          example: groups
        role_mappings:
          type: object
          description: Mapping from IdP group names to roles. Each key is a potential IdP group value for the specified role_group_key, and each value is an array of roles to assign to users in that group.
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/PlatformRole'
          x-go-type-skip-optional-pointer: true
        default_roles:
          type: array
          description: Default roles for new users who are not in any group
          items:
            $ref: '#/components/schemas/PlatformRole'
          x-go-type-skip-optional-pointer: true
          x-omitempty: false
        disable_access_if_no_role_group:
          type: boolean
          description: Whether to disable access if no role group is found in the SAML assertion. If true, users without a role group will not be able to log in.
        enabled:
          type: boolean
          description: Whether SAML is enabled
        can_enable:
          type: boolean
          description: Whether SAML can be enabled
        certificate_fingerprint:
          type: string
          description: Fingerprint of the current SAML certificate
        certificate_expires_at:
          type: string
          format: date-time
          description: Expiration time of the current SAML certificate
        rollover_certificate_fingerprint:
          type: string
          description: Fingerprint of the SAML certificate that will be used after rollover
        rollover_certificate_expires_at:
          type: string
          format: date-time
          description: Expiration time of the SAML certificate that will be used after rollover
    PlatformUserProvider:
      title: LocalUserProvider
      type: string
      enum:
      - local
      - saml
      default: local
    PlatformRoleType:
      type: string
      enum:
      - admin:write
      - admin:read
      - general:read
      - general:write
      - ci
      - schema-only
      - custom
      x-enum-varnames:
      - AdminWrite
      - AdminRead
      - GeneralRead
      - GeneralWrite
      - CI
      - SchemaOnly
      - Custom
    PlatformRoleID:
      description: The unique ID for the role.
      type: string
      format: uuid
      x-go-name: RoleID
    PlatformDataSettings:
      type: object
      description: Platform data settings definition
      required:
      - ownership_tags
      properties:
        ownership_tags:
          type: array
          description: List of tag names for asset ownership
          items:
            type: string
          default: []
    PlatformUserID:
      description: ID of the User
      type: string
      format: uuid
      example: 12345678-1234-1234-1234-1234567890ab
      x-go-name: UserID
    PlatformUser:
      additionalProperties: false
      description: User
      properties:
        created_at:
          example: '2017-07-14T16:53:42Z'
          format: date-time
          type: string
        id:
          description: ID of the User
          type: string
          format: uuid
          example: 12345678-1234-1234-1234-1234567890ab
          x-go-name: ID
        email:
          type: string
          example: user@example.com
        name:
          $ref: '#/components/schemas/PlatformUserName'
        updated_at:
          example: '2017-07-14T16:53:42Z'
          type: string
          format: date-time
        profile_image_url:
          type: string
          description: Profile image URL of user
          x-go-name: ProfileImageURL
        last_login_at:
          type: string
          format: date-time
        provider:
          $ref: '#/components/schemas/PlatformUserProvider'
        tracking_opted_in:
          type: boolean
          description: Whether anonymous user tracking was opted into
        mfa_configured:
          type: boolean
          description: Whether the user has MFA configured
          x-go-name: MFAConfigured
        roles:
          type: array
          items:
            $ref: '#/components/schemas/PlatformRole'
        enabled:
          type: boolean
          description: Whether the user is enabled
      required:
      - id
      - email
      - enabled
      - provider
      - mfa_configured
      - roles
      title: User
      type: object
    PlatformRBACPermissionID:
      description: The unique ID for the data permission.
      type: string
      format: uuid
      x-go-name: RBACPermissionID
    PlatformCreatedBy:
      type: object
      required:
      - id
      - name
      - email
      properties:
        id:
          $ref: '#/components/schemas/PlatformUserID'
        name:
          $ref: '#/components/schemas/PlatformUserName'
        email:
          type: string
    PlatformDataSettingsUpdate:
      type: object
      description: Platform data settings partial update
      properties:
        ownership_tags:
          type: array
          description: List of tag names for asset ownership
          items:
            type: string
    PlatformSAMLConfigUpdate:
      title: SAML Configuration Update
      type: object
      additionalProperties: false
      properties:
        metadata_url:
          type: string
          description: Metadata URL from identity provider. Mutually exclusive with `metadata_xml`
          format: url
          x-go-name: MetadataURL
        metadata_xml:
          type: string
          description: Metadata file contents from identity provider. Mutually exclusive with `metadata_url`
          format: url
          x-go-name: MetadataXML
        logout_url:
          type: string
          description: Logout URL from identity provider
          format: url
          x-go-name: LogoutURL
        role_group_key:
          type: string
          description: Role group key name
        role_mappings:
          type: object
          description: Mapping from IdP group names to roles. Each key is a potential IdP group value for the specified role_group_key, and each value is an array of roles to assign to users in that group.
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/PlatformRoleID'
        default_roles:
          type: array
          description: Default roles for new users who are not in any group
          items:
            $ref: '#/components/schemas/PlatformRoleID'
        disable_access_if_no_role_group:
          type: boolean
          description: Whether to disable access if no role group is found in the SAML assertion. If true, users without a role group will not be able to log in.
        enabled:
          type: boolean
          description: Whether to enable or disable SAML
    PlatformFieldError:
      allOf:
      - $ref: '#/components/schemas/PlatformBasicError'
      - properties:
          errors:
            items:
              type: string
            type: array
          field_errors:
            additionalProperties:
              type: string
            type: object
        type: object
  responses:
    PlatformConflict:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PlatformFieldError'
      description: Conflict
    PlatformRequiresAuthentication:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PlatformBasicError'
      description: Requires authentication
    PlatformNotFound:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PlatformBasicError'
      description: Resource not found
    PlatformUnprocessableEntity:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PlatformFieldError'
      description: UnprocessableEntity
    PlatformForbidden:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PlatformFieldError'
      description: Forbidden
    PlatformInternalError:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PlatformBasicError'
      description: Internal Error
    PlatformBadRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PlatformFieldError'
      description: Bad request
    PlatformMethodNotAllowed:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PlatformBasicError'
      description: Method not allowed
  parameters:
    platform_user_id:
      name: user_id
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/PlatformUserID'
      x-go-name: UserID
  securitySchemes:
    bearerAuth:
      scheme: bearer
      type: http
    basicAuth:
      scheme: basic
      type: http
    cookieAuth:
      scheme: cookie
      type: http