openapi: 3.1.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 reports API
  version: 1.0.0
security:
- bearerAuth: []
- cookieAuth: []
tags:
- name: reports
paths:
  /reports:
    get:
      operationId: PlatformListReports
      description: List reports
      tags:
      - reports
      parameters:
      - name: search_term
        in: query
        schema:
          type: string
        description: Filter reports by title or description.
      - name: visibility
        in: query
        schema:
          type: string
          enum:
          - private
          - public
      - $ref: '#/components/parameters/platform_per_page'
      - $ref: '#/components/parameters/platform_page'
      - $ref: '#/components/parameters/platform_report_sort_bys'
      - $ref: '#/components/parameters/platform_report_sort_dirs'
      responses:
        '200':
          description: List of reports.
          content:
            application/json:
              schema:
                type: object
                required:
                - reports
                - metadata
                properties:
                  reports:
                    type: array
                    items:
                      $ref: '#/components/schemas/PlatformReport'
                  metadata:
                    $ref: '#/components/schemas/PlatformListMetadata'
        '400':
          $ref: '#/components/responses/PlatformBadRequest'
        '403':
          $ref: '#/components/responses/PlatformForbidden'
        '404':
          $ref: '#/components/responses/PlatformNotFound'
    post:
      description: Create Report
      operationId: PlatformCreateReport
      tags:
      - reports
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlatformReportCreate'
      responses:
        '201':
          description: Created report.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    $ref: '#/components/schemas/PlatformReport'
        '400':
          $ref: '#/components/responses/PlatformBadRequest'
        '403':
          $ref: '#/components/responses/PlatformForbidden'
  /reports/{report_id}:
    get:
      description: Get Report
      operationId: PlatformGetReport
      tags:
      - reports
      parameters:
      - name: report_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: ID of the report.
      responses:
        '200':
          description: Retrieved report.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    $ref: '#/components/schemas/PlatformReport'
        '403':
          $ref: '#/components/responses/PlatformForbidden'
        '404':
          $ref: '#/components/responses/PlatformNotFound'
    put:
      description: Update Report
      operationId: PlatformUpdateReport
      tags:
      - reports
      parameters:
      - name: report_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: ID of the report.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlatformReportUpdate'
      responses:
        '200':
          description: Updated report.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    $ref: '#/components/schemas/PlatformReport'
        '400':
          $ref: '#/components/responses/PlatformBadRequest'
        '403':
          $ref: '#/components/responses/PlatformForbidden'
        '404':
          $ref: '#/components/responses/PlatformNotFound'
    delete:
      description: Delete Report
      operationId: PlatformDeleteReport
      tags:
      - reports
      parameters:
      - name: report_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: ID of the report.
      responses:
        '204':
          description: Report deleted.
        '403':
          $ref: '#/components/responses/PlatformForbidden'
        '404':
          $ref: '#/components/responses/PlatformNotFound'
  /reports/templates:
    get:
      operationId: PlatformListReportTemplates
      description: List report templates
      tags:
      - reports
      parameters:
      - name: search_term
        in: query
        schema:
          type: string
        description: Filter report templates by name.
      - $ref: '#/components/parameters/platform_per_page'
      - $ref: '#/components/parameters/platform_page'
      - $ref: '#/components/parameters/platform_report_templates_sort_bys'
      - $ref: '#/components/parameters/platform_report_templates_sort_dirs'
      responses:
        '200':
          description: List of report templates.
          content:
            application/json:
              schema:
                type: object
                required:
                - templates
                - metadata
                properties:
                  templates:
                    type: array
                    items:
                      $ref: '#/components/schemas/PlatformReportTemplate'
                  metadata:
                    $ref: '#/components/schemas/PlatformListMetadata'
        '400':
          $ref: '#/components/responses/PlatformBadRequest'
        '403':
          $ref: '#/components/responses/PlatformForbidden'
        '404':
          $ref: '#/components/responses/PlatformNotFound'
    post:
      description: Create Report Template
      operationId: PlatformCreateReportTemplate
      tags:
      - reports
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlatformReportTemplateCreateOrUpdate'
      responses:
        '201':
          description: Created report template.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    $ref: '#/components/schemas/PlatformReportTemplate'
        '400':
          $ref: '#/components/responses/PlatformBadRequest'
        '403':
          $ref: '#/components/responses/PlatformForbidden'
  /reports/templates/{template_id}:
    get:
      description: Get Report Template
      operationId: PlatformGetReportTemplate
      tags:
      - reports
      parameters:
      - name: template_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: ID of the report template.
      responses:
        '200':
          description: Retrieved report template.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    $ref: '#/components/schemas/PlatformReportTemplate'
        '403':
          $ref: '#/components/responses/PlatformForbidden'
        '404':
          $ref: '#/components/responses/PlatformNotFound'
    put:
      description: Update Report Template
      operationId: PlatformUpdateReportTemplate
      tags:
      - reports
      parameters:
      - name: template_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: ID of the report template.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlatformReportTemplateCreateOrUpdate'
      responses:
        '200':
          description: Updated report template.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    $ref: '#/components/schemas/PlatformReportTemplate'
        '400':
          $ref: '#/components/responses/PlatformBadRequest'
        '403':
          $ref: '#/components/responses/PlatformForbidden'
        '404':
          $ref: '#/components/responses/PlatformNotFound'
    delete:
      description: Delete Report Template
      operationId: PlatformDeleteReportTemplate
      tags:
      - reports
      parameters:
      - name: template_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: ID of the report template.
      responses:
        '204':
          description: Report template deleted.
        '403':
          $ref: '#/components/responses/PlatformForbidden'
        '404':
          $ref: '#/components/responses/PlatformNotFound'
components:
  schemas:
    PlatformListMetadata:
      required:
      - page_size
      properties:
        total_count:
          type: integer
        last_page:
          type: integer
        page_size:
          type: integer
        time_ms:
          type: integer
    PlatformFieldError:
      allOf:
      - $ref: '#/components/schemas/PlatformBasicError'
      - properties:
          errors:
            items:
              type: string
            type: array
          field_errors:
            additionalProperties:
              type: string
            type: object
        type: object
    PlatformReportTemplate:
      type: object
      required:
      - id
      - title
      - description
      - content
      - visible
      properties:
        id:
          type: string
          format: uuid
          x-go-name: ID
        title:
          type: string
        description:
          type: string
        content:
          description: YAML body
          type: string
        visible:
          type: boolean
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    PlatformReportTemplateSortBy:
      title: ReportTemplateSortBy
      type: string
      enum:
      - id
      - title
      - description
      - visible
      - created_at
      - updated_at
    PlatformReport:
      type: object
      required:
      - id
      - title
      - description
      - content
      - private
      properties:
        id:
          type: string
          format: uuid
          x-go-name: ID
        title:
          type: string
        description:
          type: string
        content:
          description: YAML body
          type: string
        private:
          type: boolean
        created_by:
          $ref: '#/components/schemas/PlatformCreatedBy'
        updated_by:
          $ref: '#/components/schemas/PlatformCreatedBy'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    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
    PlatformReportUpdate:
      type: object
      properties:
        title:
          type: string
        description:
          type: string
        content:
          type: string
          description: YAML body
        private:
          type: boolean
        template_id:
          type: string
          format: uuid
          x-go-name: TemplateID
          description: Template ID, if report is being created from a template
    PlatformReportCreate:
      type: object
      properties:
        title:
          type: string
        description:
          type: string
        content:
          type: string
          description: YAML body
        private:
          type: boolean
        template_id:
          type: string
          format: uuid
          x-go-name: TemplateID
          description: Template ID, if report is being created from a template
      required:
      - title
      - content
    PlatformReportTemplateSortDirection:
      title: ReportTemplateSortDirection
      type: string
      enum:
      - asc
      - desc
      default: asc
    PlatformReportSortDirection:
      title: ReportTemplateSortDirection
      type: string
      enum:
      - asc
      - desc
      default: asc
    PlatformBasicError:
      additionalProperties: false
      description: Basic Error
      required:
      - message
      - status
      properties:
        message:
          type: string
        status:
          type: integer
      title: Basic Error
      type: object
    PlatformReportTemplateCreateOrUpdate:
      type: object
      properties:
        title:
          type: string
        description:
          type: string
        content:
          type: string
          description: YAML body
        visible:
          type: boolean
    PlatformReportSortBy:
      title: ReportSortBy
      type: string
      enum:
      - id
      - title
      - description
      - private
      - created_at
      - updated_at
    PlatformUserID:
      description: ID of the User
      type: string
      format: uuid
      example: 12345678-1234-1234-1234-1234567890ab
      x-go-name: UserID
    PlatformCreatedBy:
      type: object
      required:
      - id
      - name
      - email
      properties:
        id:
          $ref: '#/components/schemas/PlatformUserID'
        name:
          $ref: '#/components/schemas/PlatformUserName'
        email:
          type: string
  responses:
    PlatformBadRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PlatformFieldError'
      description: Bad request
    PlatformNotFound:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PlatformBasicError'
      description: Resource not found
    PlatformForbidden:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PlatformFieldError'
      description: Forbidden
  parameters:
    platform_report_templates_sort_dirs:
      name: sort_dir
      in: query
      description: Report template sort direction options
      allowEmptyValue: true
      explode: true
      schema:
        type: array
        items:
          $ref: '#/components/schemas/PlatformReportTemplateSortDirection'
      x-go-type-skip-optional-pointer: true
      x-go-name: ReportTemplateSortDirections
    platform_page:
      description: Page number of the results to fetch
      in: query
      name: page
      required: false
      schema:
        default: 1
        minimum: 1
        type: integer
        format: int64
    platform_per_page:
      description: The number of results per page (max 1000).
      in: query
      name: per_page
      required: false
      schema:
        default: 100
        maximum: 1000
        minimum: 1
        type: integer
        format: int64
    platform_report_sort_bys:
      name: sort_by
      in: query
      description: Sort by options
      allowEmptyValue: true
      explode: true
      schema:
        type: array
        items:
          $ref: '#/components/schemas/PlatformReportSortBy'
      x-go-type-skip-optional-pointer: true
      x-go-name: ReportSortBys
    platform_report_templates_sort_bys:
      name: sort_by
      in: query
      description: Sort by options
      allowEmptyValue: true
      explode: true
      schema:
        type: array
        items:
          $ref: '#/components/schemas/PlatformReportTemplateSortBy'
      x-go-type-skip-optional-pointer: true
      x-go-name: ReportTemplateSortBys
    platform_report_sort_dirs:
      name: sort_dir
      in: query
      description: Report sort direction options
      allowEmptyValue: true
      explode: true
      schema:
        type: array
        items:
          $ref: '#/components/schemas/PlatformReportSortDirection'
      x-go-type-skip-optional-pointer: true
      x-go-name: ReportSortDirections
  securitySchemes:
    bearerAuth:
      scheme: bearer
      type: http
    basicAuth:
      scheme: basic
      type: http
    cookieAuth:
      scheme: cookie
      type: http