Logz.io Alerts API

openapi: 3.2.0
info:
  description: '# Introduction

    This API is documented using the **OpenAPI 2.0** specification.'
  title: Logz.io Alerts API
  termsOfService: https://logz.io/about-us/terms-of-use/
  contact:
    email: help@logz.io
    url: https://docs.logz.io/
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://api.logz.io/
security:
- X-API-TOKEN: []
tags:
- name: Alerts
  description: Logz.io alerts use a Kibana search query to continuously scan your logs and alert you when a certain set of conditions is met.
paths:
  /v2/alerts:
    get:
      operationId: getAllAlerts
      summary: Retrieve all alerts
      description: 'Returns the complete list of all alerts configured for the account.

        Please ensure to change the region in the URL to match your account''s region.'
      tags:
      - Alerts
      responses:
        '200':
          description: successful operation
          headers: {}
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AlertV2Response'
      requestBody:
        content:
          application/json:
            schema: {}
    post:
      summary: Create an alert
      description: 'Configures and activates a new alert.

        Please ensure to change the region in the URL to match your account''s region.'
      tags:
      - Alerts
      operationId: createAlert
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlertV2Response'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AlertV2Request'
  /v2/alerts/<<alertId>>:
    get:
      summary: Retrieve alert by ID
      description: 'Returns alert details by alert ID.

        Please ensure to change the region in the URL to match your account''s region.'
      tags:
      - Alerts
      operationId: getAlert
      parameters:
      - in: path
        name: alertId
        required: true
        description: Unique identifier of the alert in Logz.io.
        example: 563412
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: successful operation
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlertV2Response'
    put:
      summary: Update an alert
      description: 'Applies changes to an alert, identified by its ID. Can be used to enable or disable the alert.

        Please ensure to change the region in the URL to match your account''s region.'
      tags:
      - Alerts
      operationId: updateAlert
      parameters:
      - name: alertId
        in: path
        required: true
        description: Unique identifier of the alert in Logz.io.
        example: 563412
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlertV2Response'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AlertV2Request'
    delete:
      operationId: deleteAlert
      summary: Delete an alert
      description: 'Deletes an alert identified by its ID.

        Please ensure to change the region in the URL to match your account''s region.'
      tags:
      - Alerts
      parameters:
      - name: alertId
        in: path
        required: true
        description: Unique identifier of the alert in Logz.io.
        example: 563412
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: successful operation
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlertV2Response'
  /v2/alerts/{id}/enable:
    post:
      summary: Enable alert by ID
      description: 'Enables an alert by its alert ID. This is reversible. The alert can be disabled again at any time.

        Please ensure to change the region in the URL to match your account''s region.'
      operationId: enableAlert
      tags:
      - Alerts
      parameters:
      - name: id
        description: Alert ID
        in: path
        required: true
        example: 654312
        schema:
          type: integer
          format: int32
      responses:
        default:
          description: successful operation
  /v2/alerts/{id}/disable:
    post:
      operationId: disableAlert
      summary: Disable alert by ID
      description: 'Disables an alert by its alert ID. This is reversible. The alert can be enabled again at any time.

        Please ensure to change the region in the URL to match your account''s region.'
      tags:
      - Alerts
      parameters:
      - name: id
        description: Alert ID
        in: path
        required: true
        example: 654321
        schema:
          type: integer
          format: int32
      responses:
        default:
          description: successful operation
  /v1/alerts/triggered-alerts:
    post:
      operationId: TriggeredAlerts
      summary: Retrieve triggered alerts
      description: 'Returns a paged filtered list of triggered alerts for your accounts.

        Please ensure to change the region in the URL to match your account''s region.'
      tags:
      - Alerts
      parameters:
      - name: from
        in: query
        description: Of the results found, the first result to return.
        example: 0
        schema:
          type: integer
          default: 0
          minimum: 0
      - name: size
        in: query
        description: Size of page to return.
        example: 15
        schema:
          type: integer
      - name: search
        in: query
        description: Part of the alert name to filter by name (ignore case).
        example: test
        schema:
          type: string
      - name: severities
        in: query
        description: Filter results by severity of triggered alerts.
        schema:
          type: array
          items:
            type: string
            enum:
            - - SEVERE
              - HIGH
              - MEDIUM
              - LOW
              - INFO
            example: '["SEVERE", "HIGH"]'
      - name: sortBy
        in: query
        description: Sort alerts by date or severity.
        schema:
          type: string
          enum:
          - DATE
          - SEVERITY
      - name: sortOrder
        in: query
        description: Sort order of alerts retrieved.
        schema:
          type: string
          enum:
          - ASC
          - DESC
      - name: tags
        in: query
        description: List of tags the alert is related to.
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          description: successful operation
          headers: {}
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TriggeredAlertsResponse'
components:
  schemas:
    AlertOutput:
      type: object
      description: Automatically sends out notifications with sample results when the alert triggers.
      properties:
        recipients:
          $ref: '#/components/schemas/AlertRecipients'
        suppressNotificationsMinutes:
          type: integer
          format: int32
          minimum: 5
          maximum: 1440
          description: Add a waiting period in minutes to space out notifications. (The alert will still trigger but will not send out notifications during the waiting period.)
          example: 60
        type:
          type: string
          description: Selects the output format for the alert notification. If the alert has no aggregations/group by fields, `JSON` offers the option to send full sample logs without selecting specific fields.
          enum:
          - JSON
          - TABLE
    TriggeredAlertsResponse:
      type: object
      properties:
        pageSize:
          type: integer
          description: Size of page returned.
          example: 2
        from:
          type: integer
          description: Of the results found, the first result to return.
          example: 1
        total:
          type: integer
          description: Total number of alerts retrieved.
          example: 2
        results:
          type: array
          description: Array of alerts retrieved by the search.
          items:
            type: object
            properties:
              alertId:
                type: integer
                description: Alert ID.
                example: 1
              name:
                type: string
                description: Alert name.
                example: test
              eventDate:
                type: number
                description: Alert date.
                example: 1523970558.657
              severity:
                type: string
                description: Alert severity
                example: HIGH
    SubAlertOutput:
      type: object
      description: Selects the data output to be sent in the notification when the alert triggers. Not applicable, when grouping by fields or aggregating results, as the output is auto-selected.
      properties:
        columns:
          type: array
          items:
            $ref: '#/components/schemas/ColumnConfig'
        shouldUseAllFields:
          type: boolean
          description: If `true`, the notification output will include entire logs with all of their fields in the sample data.
          default: true
    SubAlert:
      type: object
      properties:
        queryDefinition:
          $ref: '#/components/schemas/AlertQuery'
        trigger:
          $ref: '#/components/schemas/AlertTrigger'
        output:
          $ref: '#/components/schemas/SubAlertOutput'
    AlertV2Request:
      type: object
      required:
      - title
      - subComponents
      properties:
        title:
          type: string
          description: Alert title
          example: Excessive WARN levels in PROD
        description:
          type: string
          description: A description of the event, its significance, and suggested next steps or instructions for the team.
          example: Steps to remediate...
        tags:
          type: array
          items:
            type: string
            example: network
          maxItems: 10
          minItems: 0
          description: Tags for filtering alerts and triggered alerts. Can be used in Kibana Discover, dashboards, and more.
        output:
          $ref: '#/components/schemas/AlertOutput'
        searchTimeFrameMinutes:
          type: integer
          minimum: 5
          maximum: 1440
          format: int32
          description: 'The time frame for evaluating the log data is a sliding window, with 1 minute granularity.


            The recommended minimum and maximum values are not validated, but needed to guarantee the alert''s accuracy.


            The minimum recommended time frame is 5 minutes, as anything shorter will be less reliable and unnecessarily resource-heavy.


            The maximum recommended time frame is 1440 minutes (24 hours). The alert runs on the index from today and yesterday (in UTC) and the maximum time frame increases throughout the day, reaching 48 hours exactly before midnight UTC.


            The default value is 5. '
          example: 20
        subComponents:
          type: array
          description: Sets the search criteria using a search query, filters, group by aggregations, accounts to search, and trigger conditions.
          items:
            $ref: '#/components/schemas/SubAlert'
        correlations:
          $ref: '#/components/schemas/SubAlertCorrelation'
        schedule:
          $ref: '#/components/schemas/AlertSchedule'
        enabled:
          type: boolean
          description: If `true`, the alert is enabled and active. Default value is `true`.
        sendToAll:
          type: boolean
          default: false
          description: If `true`, a single email will be sent to all email addresses.
    AlertSchedule:
      type: object
      description: Defines the frequency and the time frame in which an alert will be evaluated.
      properties:
        cronExpression:
          type: string
          description: Cron job for the intervals schedule.
          example: 0 0/60 9-17 ? * * *
        timezone:
          type: string
          description: Time zone for the cron job. If no time zone is selected, UTC will be used by default.
          example: America/Sao_Paulo
    AlertTrigger:
      type: object
      description: Sets the triggering threshold and severity tab to label the event when the alert triggers.
      properties:
        operator:
          type: string
          enum:
          - LESS_THAN
          - GREATER_THAN
          - LESS_THAN_OR_EQUALS
          - GREATER_THAN_OR_EQUALS
          - EQUALS
          - NOT_EQUALS
          example: GREATER_THAN_OR_EQUALS
          description: Specifies the operator for evaluating the results.
        severityThresholdTiers:
          type: object
          description: 'Sets a severity label per trigger threshold as a key:value pair.


            If using more than one sub-component, only 1 severityThresholdTiers is allowed. Otherwise, 1 per `enum` are allowed (for a total of 5 thresholds of increasing severities).


            Increasing severity must adhere to the logic of the operator.'
          enum:
          - INFO
          - LOW
          - MEDIUM
          - HIGH
          - SEVERE
          additionalProperties: null
          default:
            MEDIUM: 10.0
          example:
            MEDIUM: 10.0
            HIGH: 100.0
            SEVERE: 300.0
    AlertQuery:
      type: object
      description: Determines when the alert should trigger using any combination of a search query, filters, group by aggregations, accounts to search, and trigger conditions.
      properties:
        query:
          type: string
          description: 'Provide a Kibana search query written in Lucene syntax. The search query together with the filters select for the relevant logs.


            Cannot be null - send an asterisk wildcard `*` if not using a search query.'
          default: '*'
          example: type:apache_access
        filters:
          $ref: '#/components/schemas/BoolFilter'
        groupBy:
          type:
          - array
          - 'null'
          description: Specify 1-3 fields by which to group the results and count them. If you apply a group by operation, the alert returns a count of the results aggregated by unique values.
          items:
            type: string
          maxItems: 3
          minItems: 0
        aggregation:
          $ref: '#/components/schemas/Aggregation'
        shouldQueryOnAllAccounts:
          type: boolean
          default: true
          example: false
          description: Only applicable when the alert is run from the main account. If `true`, the alert runs on the main account and all associated searchable sub accounts. If `false`, specify relevant account IDs for the alert to monitor using the `accountIdsToQueryOn` field.
        accountIdsToQueryOn:
          type: array
          description: Specify Account IDs to select which accounts the alert should monitor. The alert will be checked only on these accounts.
          items:
            type: integer
            format: int32
            example: 2321
    ColumnConfig:
      type: object
      description: Customize the alert output to be sent out in notifications when the alert triggers.
      properties:
        fieldName:
          type: string
          description: Specify the fields to be included in the notification.
        regex:
          type: string
          description: Trims the data using regex filters. [Learn more](https://docs.logz.io/user-guide/alerts/regex-filters.html)
        sort:
          type: string
          description: Specify a single field to sort by. The field cannot be an analyzed field (a field that supports free text search or searching by part of a message, such as the 'message' field).
          enum:
          - DESC
          - ASC
    AlertRecipients:
      type: object
      description: Add email addresses and/or endpoint channels to automatically receive notifications with sample data when the alert triggers.
      properties:
        emails:
          type: array
          description: Array of email addresses to be notified when the alert triggers.
          items:
            type: string
            example: tom.a@logz.io
        notificationEndpointIds:
          type: array
          description: Array of IDs of pre-configured endpoint channels to notify when the alert triggers.
          items:
            type: integer
            format: int32
    SubAlertCorrelation:
      type: object
      description: 'Only applicable when multiple sub-components are in use. Selects a logic for correlating the alert’s sub-components.


        `AND` is currently the only supported operator. When `AND` is the `correlationOperator`, both sub-components must meet their triggering criteria for the alert to trigger.'
      properties:
        correlationOperators:
          type: array
          items:
            type: string
            enum:
            - AND
        joins:
          type: array
          description: 'Specifies which group by fields must have the same values to trigger the alert.


            Joins the group by fields from the first and second sub-components. The key represents the index of the sub component in the array (See the example - the index of the first sub-component is 0, the second is 1).


            The fields must be ordered pairs of the group by fields already in use in the `queryDefinition`.'
          items:
            type: object
            additionalProperties: null
            example:
              0: region
              1: region
          default: false
    BoolFilter:
      type: object
      description: Apply `must` and `must_not` filters to the monitoring alert. Filters are more efficient compared to a query, so it's recommended to opt for a filter over a query, where possible. See [Elasticsearch Bool-Query](https://www.elastic.co/guide/en/elasticsearch/reference/6.8/query-dsl-bool-query.html) for more detail.
      properties:
        bool:
          $ref: '#/components/schemas/FilterLists'
    Aggregation:
      type: object
      description: Specifies a trigger condition that acts as a threshold.
      properties:
        aggregationType:
          type: string
          description: 'Specifies the aggregation operator.


            * If `COUNT`, `fieldToAggregateOn` must be null, and `groupBy` fields must not be empty.

            * If `NONE`, `fieldToAggregateOn` must be null, and `groupBy` field must not be empty (or null).

            * If `PERCENTAGE`, `valueToAggregateOn` must be specified.


            * If any other operator type (other than `NONE` or `COUNT`), `fieldToAggregateOn` must not be null.'
          enum:
          - SUM
          - MIN
          - MAX
          - AVG
          - COUNT
          - UNIQUE_COUNT
          - NONE
          - PERCENTAGE
          - PERCENTILE
        fieldToAggregateOn:
          type: string
          description: 'Selects the field on which to run the aggregation for the trigger condition.


            * Cannot be a field already in use for `groupBy`.'
        valueToAggregateOn:
          type: string
          description: 'Used by the `PERCENTAGE` aggregation to select the field’s value. This value is used to determine if its ratio out of the total amount of logs in the query satisfies the trigger condition.

            * Only relevant for the `PERCENTAGE` aggregation.'
    FilterLists:
      type: object
      description: Runs Elasticsearch [Bool Query](https://www.elastic.co/guide/en/elasticsearch/reference/6.8/query-dsl-bool-query.html) filters on the data (before the search query is applied). The most efficient way to grab the logs you are looking for.
      properties:
        must:
          type: array
          items:
            type: object
            properties:
              match_phrase:
                type: object
                properties:
                  Field:
                    type: object
                    properties:
                      query:
                        type: string
                        example: value
        must_not:
          type: array
          items:
            type: object
            properties:
              match_phrase:
                type: object
                properties:
                  Field:
                    type: object
                    properties:
                      query:
                        type: string
                        example: value
    AlertV2Response:
      type: object
      properties:
        id:
          type: integer
          format: int32
          description: Logz.io alert ID.
          example: 627816
        updatedAt:
          type: string
          description: Date and time in UTC when the alert was last updated.
          example: 2020-04-02 18:58:16+00:00
        updatedBy:
          type: string
          description: Email of the user who last updated the alert.
          example: tomer@logz.io
        createdAt:
          type: string
          description: Date and time in UTC when the alert was first created.
          example: 2020-02-02 18:58:16+00:00
        createdBy:
          type: string
          description: Email of the user who first created the alert.
          example: tomer@logz.io
        enabled:
          type: boolean
          description: If `true`, the alert is currently active.
          exampe: true
        title:
          type: string
          description: Alert title.
          example: Excessive WARN levels in PROD
        description:
          type: string
          description: A description of the event, its significance, and suggested next steps or instructions for the team.
          example: Steps to remediate...
        tags:
          type: array
          items:
            type: string
          description: Tags for filtering alerts and triggered alerts. Can be used in Kibana Discover, dashboards, and more.
          example:
          - network
          - aws
        output:
          $ref: '#/components/schemas/AlertOutput'
        searchTimeFrameMinutes:
          type: integer
          minimum: 5
          maximum: 1440
          format: int32
          description: 'The time frame for evaluating the log data is a sliding window, with 1 minute granularity.


            The recommended minimum and maximum values are not validated, but needed to guarantee the alert''s accuracy.


            The minimum recommended time frame is 5 minutes, as anything shorter will be less reliable and unnecessarily resource-heavy.


            The maximum recommended time frame is 1440 minutes (24 hours). The alert runs on the index from today and yesterday (in UTC) and the maximum time frame increases throughout the day, reaching 48 hours exactly before midnight UTC.'
        subComponents:
          type: array
          description: Determines when the alert should trigger using any combination of a search query, filters, group by aggregations, accounts to search, and trigger conditions.
          items:
            $ref: '#/components/schemas/SubAlert'
        correlations:
          $ref: '#/components/schemas/SubAlertCorrelation'
        schedule:
          type: object
          description: Defines the intervals in which an alert will be evaluated. This feature is still in production, but the payload already contains the data.
          properties:
            cronExpression:
              type: string
              description: Cron job for the intervals schedule.
            timezone:
              type: string
              description: Time zone for the cron job. If no time zone is selected, UTC will be used by default.
        sendToAll:
          type: boolean
          default: false
          description: If `true`, a single email will be sent to all email addresses.
  securitySchemes:
    X-API-TOKEN:
      description: 'You can manage your API tokens from the [Logz.io API tokens](https://app.logz.io/#/dashboard/settings/manage-tokens/api) page.


        API tokens are account-specific. You will need to be logged into the relevant Log Management or SIEM account to view the API tokens associated with it.


        To manage your API tokens, log into the relevant account in your Logz.io platform, click the gear in the top-right menu, and select [**Tools > Manage tokens > API tokens**](https://app.logz.io/#/dashboard/settings/manage-tokens/api).


        It''s important to keep your tokens secure. API tokens carry privileges to make changes to users and accounts, so if you believe an API token has been compromised, delete it, and replace it with a new token in your integrations.'
      type: apiKey
      in: header
      name: X-API-TOKEN
x-servers:
- url: https://api.logz.io
  description: US East (Northern Virginia)
- url: https://api-au.logz.io
  description: Asia Pacific (Sydney)
- url: https://api-ca.logz.io
  description: Canada (Central)
- url: https://api-eu.logz.io
  description: Europe (Frankfurt)
- url: https://api-uk.logz.io
  description: Europe (London)
x-tagGroups:
- name: Log Monitoring
  tags:
  - Search logs
  - Alerts
  - Deployments
  - Insights
  - Logz.io snapshots
- name: Cloud SIEM
  tags:
  - Security account
  - Security rules
  - Security events
  - Lookup lists
- name: Account administration
  tags:
  - Manage users
  - Manage metrics account
  - Associated accounts
  - Authentication groups
  - Who am I
  - Manage time-based log accounts
  - Manage shared tokens
  - Manage API tokens
  - Manage notification endpoints
  - Import or export Kibana objects
- name: Manage data shipping
  tags:
  - Manage log shipping tokens
  - Drop filters
  - Archive logs
  - Restore logs
  - Parsing
  - Delete object API
- name: Data security
  tags:
  - Retrieve audit trail
- name: Connect to AWS resources
  tags:
  - Connect to CloudTrail
  - Connect to S3 Buckets
- name: Metrics API Gateway
  tags:
  - Grafana contact points
  - Grafana data source
  - Grafana alerting provisioning
  - Grafana silence management
  - Grafana annotations
  - Grafana dashboards
  - Grafana dashboard search
  - Grafana snapshots
  - Grafana get all folders
  description: Metrics API Gateway to supported endpoints.