CloudQuery Notifications 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 Notifications API
  version: 1.0.0
security:
- bearerAuth: []
- cookieAuth: []
tags:
- name: Notifications
paths:
  /notifications:
    get:
      description: List the notifications rules delivered, suppressed or failed to deliver, and sync failure notifications, newest first
      operationId: PlatformListNotifications
      parameters:
      - $ref: '#/components/parameters/platform_per_page'
      - $ref: '#/components/parameters/platform_page'
      - in: query
        name: severities
        required: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/PlatformPolicySeverity'
        style: form
        explode: true
        description: Filter by policy severities (policy matches any)
      - in: query
        name: policy_group_ids
        required: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/PlatformPolicyGroupID'
        style: form
        explode: true
        description: Filter by policy groups (policy matches any)
      - in: query
        name: sent_only
        required: false
        schema:
          type: boolean
          default: false
        description: Return only notifications that were delivered.
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                required:
                - items
                - metadata
                properties:
                  items:
                    items:
                      $ref: '#/components/schemas/PlatformNotificationDetail'
                    type: array
                  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:
      - Notifications
      summary: Platform list notifications
      x-summary-source: derived
components:
  schemas:
    PlatformNotificationDestinationListItem:
      title: Notification Destination List Item
      type: object
      description: Notification Destination List Item
      additionalProperties: false
      required:
      - id
      - name
      - enabled
      - type
      - url
      - created_at
      - updated_at
      properties:
        id:
          $ref: '#/components/schemas/PlatformNotificationDestinationID'
        name:
          type: string
          example: Send to Slack
        enabled:
          type: boolean
        type:
          type: string
          enum:
          - webhook
          - slack
          - msteams
          - email
          description: Type of notification destination
        url:
          type: string
          example: https://hooks.slack.com/services/REDACTED
          x-go-name: URL
        slack_channels:
          type: array
          items:
            type: string
          description: List of Slack channel names (only for slack type)
          x-go-name: SlackChannels
        last_notification_error_timestamp:
          type: string
          format: date-time
          nullable: true
          description: Timestamp of the last notification error
          x-go-name: LastNotificationErrorTimestamp
        last_notification_error_code:
          type: string
          nullable: true
          description: Error code of the last notification error
          x-go-name: LastNotificationErrorCode
        last_notification_error_message:
          type: string
          nullable: true
          description: Error message of the last notification error
          x-go-name: LastNotificationErrorMessage
        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
    PlatformNotificationDetail:
      title: Notification Detail
      type: object
      description: 'One delivery-log entry: a notification a rule delivered, suppressed or failed to deliver to one destination in one evaluation cycle, or a sync failure notification. `id` is the delivery''s event id, `triggered_at` its cycle, `total_violations` the batch size, and `outcome`, `failed_reason` and `resource_sample` describe the delivery.'
      additionalProperties: false
      required:
      - id
      - message
      - severity
      - state
      - total_violations
      - created_at
      - updated_at
      properties:
        id:
          type: string
          format: uuid
          description: The delivery's event id
          x-go-name: ID
        query_id:
          type: string
          format: uuid
          description: The query of the policy the notification is about
          x-go-name: QueryID
        policy_id:
          type: string
          format: uuid
          description: The policy the notification is about, when its insight is a policy's
          x-go-name: PolicyID
        insight_id:
          type: string
          description: The insight the notification is about (unset for a sync failure)
          x-go-name: InsightID
        insight_title:
          type: string
          description: Title of the insight, when the caller can see it
          x-go-name: InsightTitle
        insight_category:
          type: string
          description: Category of the insight, when the caller can see it
          x-go-name: InsightCategory
        insight_source:
          type: string
          description: Source of the insight, when the caller can see it
          x-go-name: InsightSource
        message:
          type: string
          description: Alert message content
        severity:
          $ref: '#/components/schemas/PlatformAlertSeverity'
        state:
          $ref: '#/components/schemas/PlatformAlertState'
        total_violations:
          type: integer
          format: int64
          description: Number of violations that triggered the alert
        last_evaluated_at:
          type: string
          format: date-time
          description: Timestamp when the alert was last evaluated
        triggered_at:
          type: string
          format: date-time
          description: Timestamp when the alert was triggered
        created_at:
          type: string
          format: date-time
          description: Timestamp when the alert was created
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the alert was last updated
        notification_destination:
          $ref: '#/components/schemas/PlatformNotificationDestinationListItem'
          description: The notification destination for this notification item (null if no destinations configured)
          nullable: true
        outcome:
          $ref: '#/components/schemas/PlatformNotificationDeliveryOutcome'
        rule_id:
          type: string
          format: uuid
          description: The notification rule that produced a delivery-log entry
          x-go-name: RuleID
        failed_reason:
          type: string
          description: Short reason a delivery-log entry ended `failed`
        resource_sample:
          type: array
          description: Up to 10 of the resources in a delivery-log entry's batch, as the rule walk classified them. Omitted for a caller whose role carries an asset permission, so a partial scope never sees resources outside it.
          items:
            type: object
            additionalProperties: true
    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.

            '
    PlatformAlertState:
      type: string
      enum:
      - unknown
      - pending
      - inactive
      - triggered
    PlatformAlertSeverity:
      type: string
      enum:
      - low
      - medium
      - high
      - critical
    PlatformPolicySeverity:
      description: Policy severity
      type: string
      enum:
      - low
      - medium
      - high
      - critical
      x-go-name: PolicySeverity
    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
    PlatformNotificationDestinationID:
      description: The unique ID for the notification destination.
      type: string
      format: uuid
      x-go-name: NotificationDestinationID
    PlatformNotificationDeliveryOutcome:
      title: Notification Delivery Outcome
      type: string
      description: Terminal outcome of a Notifications v2 delivery. `suppressed` is a match a suppress rule deliberately silenced, so it has no destination.
      enum:
      - delivered
      - suppressed
      - failed
    PlatformPolicyGroupID:
      title: Policy Group ID
      type: string
      format: uuid
      x-go-name: PolicyGroupID
  responses:
    PlatformUnprocessableEntity:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PlatformFieldError'
      description: UnprocessableEntity
    PlatformInternalError:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PlatformBasicError'
      description: Internal Error
    PlatformForbidden:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PlatformFieldError'
      description: Forbidden
    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
  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_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)