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! This API can be used to interact with the CloudQuery platform. As a user, the API allows you to search the CloudQuery asset inventory, run SQL queries against the data warehouse, save and load searches, and much more. As an administrator, it allows you to manage your teams, syncs, and other objects.

    ### Authentication

    The API is secured using bearer tokens. To get started, you can generate an API key for your Platform deployment from your platform dashboard. For a step-by-step guide, see: https://www.cloudquery.io/docs/cli/managing-cloudquery/deployments/generate-api-key.

    The base URL for the API depends on where your CloudQuery Platform is hosted. If running locally, this is usually http://localhost:3000/api. In a production deployment it should be an HTTPS URL. For purposes of illustration, we will assume the platform instance is available at https://cloudquery.mycompany.com. In this case, the base API endpoint will be https://cloudquery.mycompany.com/api.

    ### Example Request

    To test your connection to the API, we can use the `/plugins` endpoint. For example:

    `curl -v -H "Authorization: Bearer $CLOUDQUERY_API_KEY" \ https://cloudquery.mycompany.com/api/plugins`

    '
  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
servers:
- url: https://api.cloudquery.io
  description: Base URL declared by the provider in apis.yml (roadmap#122).
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
  /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
    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
    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
  /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
    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
  /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
    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
  /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
  /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
    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
  /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
    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
components:
  responses:
    PlatformInternalError:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PlatformBasicError'
      description: Internal Error
    PlatformConflict:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PlatformFieldError'
      description: Conflict
    PlatformUnprocessableEntity:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PlatformFieldError'
      description: UnprocessableEntity
    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
    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
    PlatformForbidden:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PlatformFieldError'
      description: Forbidden
  schemas:
    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
    PlatformCreatedBy:
      type: object
      required:
      - id
      - name
      - email
      properties:
        id:
          $ref: '#/components/schemas/PlatformUserID'
        name:
          $ref: '#/components/schemas/PlatformUserName'
        email:
          type: string
    PlatformRBACPermissionID:
      description: The unique ID for the data permission.
      type: string
      format: uuid
      x-go-name: RBACPermissionID
    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: []
    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'
    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
    PlatformRoleID:
      description: The unique ID for the role.
      type: string
      format: uuid
      x-go-name: RoleID
    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
    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
    PlatformUserID:
      description: ID of the User
      type: string
      format: uuid
      example: 12345678-1234-1234-1234-1234567890ab
      x-go-name: UserID
    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
    PlatformFieldError:
      allOf:
      - $ref: '#/components/schemas/PlatformBasicError'
      - properties:
          errors:
            items:
              type: string
            type: array
          field_errors:
            additionalProperties:
              type: string
            type: object
        type: object
    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
    PlatformBasicError:
      additionalProperties: false
      description: Basic Error
      required:
      - message
      - status
      properties:
        message:
          type: string
        status:
          type: integer
      title: Basic Error
      type: object
    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
    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
    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
    PlatformUserProvider:
      title: LocalUserProvider
      type: string
      enum:
      - local
      - saml
      default: local
  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