CloudQuery Reports 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 Reports API
  version: 1.0.0
security:
- bearerAuth: []
- cookieAuth: []
tags:
- name: Reports
paths:
  /reports:
    get:
      operationId: PlatformListReports
      x-mcp:
        name: list_reports
        description: List saved reports with title, visibility and owner. Reports are YAML documents of widgets backed by warehouse SQL.
      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'
      summary: Platform list reports
      x-summary-source: derived
    post:
      description: Create Report
      operationId: PlatformCreateReport
      x-mcp:
        name: create_report
        readOnly: false
        description: 'Create a report from YAML content. Take the structure from list_report_templates or get_report, and check every widget''s SQL with run_query first. The report is visible to the whole organization unless you pass private: true, and creating a visible one needs an admin role.'
      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'
      summary: Platform create report
      x-summary-source: derived
  /reports/{report_id}:
    get:
      description: Get Report
      operationId: PlatformGetReport
      x-mcp:
        name: get_report
        description: Get one report including its YAML content. Read it before update_report and to copy the shape of a working widget.
      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'
      summary: Platform get report
      x-summary-source: derived
    put:
      description: Update Report
      operationId: PlatformUpdateReport
      x-mcp:
        name: update_report
        readOnly: false
        description: Update a report's title, description, visibility or YAML content. Read it with get_report first.
      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'
      summary: Platform update report
      x-summary-source: derived
    delete:
      description: Delete Report
      operationId: PlatformDeleteReport
      x-mcp:
        name: delete_report
        readOnly: false
        description: Delete a report. Confirm with get_report first.
      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'
      summary: Platform delete report
      x-summary-source: derived
  /reports/templates:
    get:
      operationId: PlatformListReportTemplates
      x-mcp:
        name: list_report_templates
        description: List the built-in report templates. Templates show the report YAML structure and are the starting point for create_report.
      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'
      summary: Platform list report templates
      x-summary-source: derived
    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'
      summary: Platform create report template
      x-summary-source: derived
  /reports/templates/{template_id}:
    get:
      description: Get Report Template
      operationId: PlatformGetReportTemplate
      x-mcp:
        name: get_report_template
        description: Get one report template with its full YAML content.
      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'
      summary: Platform get report template
      x-summary-source: derived
    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'
      summary: Platform update report template
      x-summary-source: derived
    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'
      summary: Platform delete report template
      x-summary-source: derived
components:
  schemas:
    PlatformReportTemplateSortDirection:
      title: ReportTemplateSortDirection
      type: string
      enum:
      - asc
      - desc
      default: asc
    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
    PlatformReportSortDirection:
      title: ReportTemplateSortDirection
      type: string
      enum:
      - asc
      - desc
      default: asc
    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
    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
    PlatformReportTemplateCreateOrUpdate:
      type: object
      properties:
        title:
          type: string
        description:
          type: string
        content:
          type: string
          description: YAML body
        visible:
          type: boolean
    PlatformReportTemplateSortBy:
      title: ReportTemplateSortBy
      type: string
      enum:
      - id
      - title
      - description
      - visible
      - created_at
      - updated_at
    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
    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
    PlatformListMetadata:
      required:
      - page_size
      properties:
        total_count:
          type: integer
        last_page:
          type: integer
        page_size:
          type: integer
        time_ms:
          type: integer
        next_cursor:
          type: string
          description: 'Opaque cursor for the next page when using keyset pagination. Present only

            for keyset-eligible list queries (default order, no group_by); omitted on

            the last page. Pass it back as the `cursor` query parameter.

            '
    PlatformFieldError:
      allOf:
      - $ref: '#/components/schemas/PlatformBasicError'
      - properties:
          errors:
            items:
              type: string
            type: array
          field_errors:
            additionalProperties:
              type: string
            type: object
        type: object
    PlatformBasicError:
      additionalProperties: false
      description: Basic Error
      required:
      - message
      - status
      properties:
        message:
          type: string
        status:
          type: integer
      title: Basic Error
      type: object
    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
  responses:
    PlatformNotFound:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PlatformBasicError'
      description: Resource not found
    PlatformForbidden:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PlatformFieldError'
      description: Forbidden
    PlatformBadRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PlatformFieldError'
      description: Bad request
  parameters:
    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_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_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
    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_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_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
  securitySchemes:
    bearerAuth:
      scheme: bearer
      type: http
    basicAuth:
      scheme: basic
      type: http
    cookieAuth:
      scheme: cookie
      type: http
x-provenance:
  method: harvested
  publisher: CloudQuery
  source: https://platform-multi-tenant-api-docs.cloudquery.io/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)