CloudQuery filters API

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 filters API
  version: 1.0.0
security:
- bearerAuth: []
- cookieAuth: []
tags:
- name: filters
paths:
  /filters:
    get:
      description: List Filters
      operationId: PlatformListFilters
      parameters:
      - $ref: '#/components/parameters/platform_per_page'
      - $ref: '#/components/parameters/platform_page'
      - $ref: '#/components/parameters/platform_filter_tags'
      - $ref: '#/components/parameters/platform_filter_name_filter'
      - $ref: '#/components/parameters/platform_filter_expression_filter'
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                required:
                - items
                - metadata
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/PlatformFilter'
                  metadata:
                    $ref: '#/components/schemas/PlatformListMetadata'
        '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:
      - filters
  /filters/tags:
    get:
      description: List Filter Tags
      operationId: PlatformListFilterTags
      parameters:
      - $ref: '#/components/parameters/platform_per_page'
      - $ref: '#/components/parameters/platform_page'
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                required:
                - items
                - metadata
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/PlatformFilterTag'
                  metadata:
                    $ref: '#/components/schemas/PlatformListMetadata'
        '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:
      - filters
  /filters/{filter_id}:
    get:
      description: Get a table filter by ID
      operationId: PlatformGetFilterByID
      parameters:
      - $ref: '#/components/parameters/platform_filter_id'
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformFilter'
        '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:
      - filters
    patch:
      description: Update a table filter
      operationId: PlatformUpdateFilter
      parameters:
      - $ref: '#/components/parameters/platform_filter_id'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlatformFilterUpdate'
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformFilter'
        '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:
      - filters
    delete:
      description: Delete a table filter
      operationId: PlatformDeleteFilter
      parameters:
      - $ref: '#/components/parameters/platform_filter_id'
      responses:
        '204':
          description: Deleted
        '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:
      - filters
  /queries/{query_id}/filters:
    get:
      description: List Query Filters
      operationId: PlatformQueryListFilters
      parameters:
      - $ref: '#/components/parameters/platform_query_id'
      - $ref: '#/components/parameters/platform_per_page'
      - $ref: '#/components/parameters/platform_page'
      - $ref: '#/components/parameters/platform_filter_tags'
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                required:
                - items
                - metadata
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/PlatformFilter'
                  metadata:
                    $ref: '#/components/schemas/PlatformListMetadata'
        '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:
      - filters
    post:
      description: Save Query Filter
      operationId: PlatformQuerySaveFilter
      parameters:
      - $ref: '#/components/parameters/platform_query_id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlatformFilterCreate'
      responses:
        '200':
          description: Filter already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformFilter'
        '201':
          description: Filter created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformFilter'
        '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:
      - filters
  /queries/{query_id}/filters/tags:
    get:
      description: List Filter Tags For A Saved Query
      operationId: PlatformQueryListFilterTags
      parameters:
      - $ref: '#/components/parameters/platform_query_id'
      - $ref: '#/components/parameters/platform_per_page'
      - $ref: '#/components/parameters/platform_page'
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                required:
                - items
                - metadata
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/PlatformFilterTag'
                  metadata:
                    $ref: '#/components/schemas/PlatformListMetadata'
        '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:
      - filters
  /tables/{table_name}/filters:
    get:
      description: List Table Filters
      operationId: PlatformTableListFilters
      parameters:
      - $ref: '#/components/parameters/platform_table_name'
      - $ref: '#/components/parameters/platform_per_page'
      - $ref: '#/components/parameters/platform_page'
      - $ref: '#/components/parameters/platform_filter_tags'
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                required:
                - items
                - metadata
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/PlatformFilter'
                  metadata:
                    $ref: '#/components/schemas/PlatformListMetadata'
        '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:
      - filters
    post:
      description: Save Table Filter
      operationId: PlatformTableSaveFilter
      parameters:
      - $ref: '#/components/parameters/platform_table_name'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlatformFilterCreate'
      responses:
        '200':
          description: Filter already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformFilter'
        '201':
          description: Filter created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformFilter'
        '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:
      - filters
  /tables/{table_name}/filters/tags:
    get:
      description: List Filter Tags For A Table
      operationId: PlatformTableListFilterTags
      parameters:
      - $ref: '#/components/parameters/platform_table_name'
      - $ref: '#/components/parameters/platform_per_page'
      - $ref: '#/components/parameters/platform_page'
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                required:
                - items
                - metadata
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/PlatformFilterTag'
                  metadata:
                    $ref: '#/components/schemas/PlatformListMetadata'
        '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:
      - filters
components:
  schemas:
    PlatformFilterUpdate:
      title: Filter definition for updating a filter
      description: Filter Update Definition
      type: object
      properties:
        name:
          type: string
          example: t2.micro EC2 instances
        description:
          type: string
        expression:
          $ref: '#/components/schemas/PlatformFilterExpression'
        tags:
          type: array
          items:
            $ref: '#/components/schemas/PlatformFilterTag'
    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
    PlatformFilterID:
      description: The unique ID for the filter.
      type: string
      format: uuid
      x-go-name: FilterID
    PlatformQueryID:
      description: The unique ID for the query.
      type: string
      format: uuid
      x-go-name: QueryID
    PlatformFilterTag:
      description: A table column filter tag.
      type: string
    PlatformFilterExpression:
      description: A table column filter.
      type: string
      example: resource_type=aws_s3_buckets
    PlatformFilter:
      title: Filter
      type: object
      description: Saved filter
      additionalProperties: false
      required:
      - id
      - name
      - expression
      - created_at
      properties:
        id:
          description: ID of the Filter
          type: string
          format: uuid
          example: 12345678-1234-1234-1234-1234567890ab
          x-go-name: ID
        name:
          type: string
          example: t2.micro EC2 instances
        expression:
          $ref: '#/components/schemas/PlatformFilterExpression'
        description:
          type: string
          example: Filter to find all EC2 instances of type t2.micro from the aws_ec2_instance raw table
        table:
          $ref: '#/components/schemas/PlatformTableName'
        query_id:
          $ref: '#/components/schemas/PlatformQueryID'
        user_id:
          $ref: '#/components/schemas/PlatformUserID'
        tags:
          type: array
          items:
            $ref: '#/components/schemas/PlatformFilterTag'
          x-go-type-skip-optional-pointer: true
        created_at:
          example: '2017-07-14T16:53:42Z'
          format: date-time
          type: string
    PlatformFilterCreate:
      title: Filter definition for creating a filter
      type: object
      description: Saved filter
      additionalProperties: false
      required:
      - name
      - expression
      properties:
        name:
          type: string
          example: t2.micro EC2 instances
        expression:
          $ref: '#/components/schemas/PlatformFilterExpression'
        public:
          type: boolean
          default: true
          x-omitempty: false
          x-go-type-skip-optional-pointer: true
          description: Whether the filter is visible to all users, or only to the user who created it
        tags:
          type: array
          items:
            $ref: '#/components/schemas/PlatformFilterTag'
          x-go-type-skip-optional-pointer: true
        description:
          type: string
          example: Filter to find all EC2 instances of type t2.micro from the aws_ec2_instance raw table
    PlatformBasicError:
      additionalProperties: false
      description: Basic Error
      required:
      - message
      - status
      properties:
        message:
          type: string
        status:
          type: integer
      title: Basic Error
      type: object
    PlatformTableName:
      description: The name of the table.
      type: string
      example: cloud_assets
    PlatformUserID:
      description: ID of the User
      type: string
      format: uuid
      example: 12345678-1234-1234-1234-1234567890ab
      x-go-name: UserID
  parameters:
    platform_filter_name_filter:
      name: name_filter
      in: query
      required: false
      schema:
        description: Filter by filter name
        type: string
    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_filter_id:
      in: path
      name: filter_id
      required: true
      schema:
        $ref: '#/components/schemas/PlatformFilterID'
      x-go-name: FilterID
    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_table_name:
      in: path
      name: table_name
      required: true
      schema:
        $ref: '#/components/schemas/PlatformTableName'
    platform_filter_tags:
      name: tag
      in: query
      description: Filter tags
      allowEmptyValue: true
      explode: true
      schema:
        type: array
        items:
          $ref: '#/components/schemas/PlatformFilterTag'
      x-go-name: FilterTags
    platform_filter_expression_filter:
      name: expression_filter
      in: query
      required: false
      schema:
        description: Filter by filter expression
        type: string
    platform_query_id:
      in: path
      name: query_id
      required: true
      schema:
        $ref: '#/components/schemas/PlatformQueryID'
      x-go-name: QueryID
  responses:
    PlatformBadRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PlatformFieldError'
      description: Bad request
    PlatformInternalError:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PlatformBasicError'
      description: Internal Error
    PlatformNotFound:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PlatformBasicError'
      description: Resource not found
    PlatformForbidden:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PlatformFieldError'
      description: Forbidden
    PlatformUnprocessableEntity:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PlatformFieldError'
      description: UnprocessableEntity
    PlatformRequiresAuthentication:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PlatformBasicError'
      description: Requires authentication
  securitySchemes:
    bearerAuth:
      scheme: bearer
      type: http
    basicAuth:
      scheme: basic
      type: http
    cookieAuth:
      scheme: cookie
      type: http