openapi: 3.1.0
info:
  title: Honeycomb Auth Triggers API
  version: 1.0.0
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  contact:
    email: support@honeycomb.io
  description: 'The API allows programmatic management of many resources within Honeycomb.


    Please report any discrepancies with actual API behavior in <a href="https://docs.honeycomb.io/troubleshoot/community/">Pollinators Slack</a> or to <a href="https://support.honeycomb.io/">Honeycomb Support</a>.

    '
servers:
- url: https://api.honeycomb.io
- url: https://api.eu1.honeycomb.io
tags:
- name: Triggers
  description: 'Triggers let you receive notifications when your data in Honeycomb crosses the thresholds that you configure.

    The graph on which to alert is as flexible as a Honeycomb query, which helps reduce false positives due to known errors.


    Triggers support both standard event-based datasets and metrics datasets. Metrics triggers have additional capabilities

    such as granularity control.

    Learn more in the [Triggers documentation](https://docs.honeycomb.io/notify/alert/triggers/).


    This API allows you to list, create, update, and delete Triggers.


    ## Authorization


    The API key must have the **Manage Triggers** permission. Learn more about [API keys here](https://docs.honeycomb.io/configure/environments/manage-api-keys/).

    '
paths:
  /1/triggers/{datasetSlug}:
    parameters:
    - $ref: '#/components/parameters/datasetSlugOrAll'
    get:
      security:
      - configuration_key: []
      summary: List All Triggers
      description: 'List all triggers on the provided dataset or environment.

        '
      tags:
      - Triggers
      operationId: listTriggers
      responses:
        '200':
          description: OK
          headers:
            Ratelimit:
              $ref: '#/components/headers/RateLimit'
            RateLimitPolicy:
              $ref: '#/components/headers/RateLimitPolicy'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TriggerResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        default:
          $ref: '#/components/responses/GenericError'
    post:
      security:
      - configuration_key: []
      summary: Create a Trigger
      description: 'Create a trigger on the provided dataset or environment.

        '
      tags:
      - Triggers
      operationId: createTrigger
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTriggerRequest'
        required: true
      responses:
        '201':
          description: Success - trigger created
          headers:
            Location:
              schema:
                type: string
              description: Relative path to fetch this trigger via API.
            Ratelimit:
              $ref: '#/components/headers/RateLimit'
            RateLimitPolicy:
              $ref: '#/components/headers/RateLimitPolicy'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TriggerResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/RateLimited'
  /1/triggers/{datasetSlug}/{triggerId}:
    parameters:
    - $ref: '#/components/parameters/datasetSlugOrAll'
    - name: triggerId
      description: The unique identifier (ID) of a Trigger.
      in: path
      required: true
      schema:
        type: string
    get:
      security:
      - configuration_key: []
      summary: Get a Trigger
      description: 'Fetch details for a single Trigger by Trigger ID.

        '
      tags:
      - Triggers
      operationId: getTrigger
      responses:
        '200':
          description: Success
          headers:
            Ratelimit:
              $ref: '#/components/headers/RateLimit'
            RateLimitPolicy:
              $ref: '#/components/headers/RateLimitPolicy'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TriggerResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
    put:
      security:
      - configuration_key: []
      summary: Update a Trigger
      description: 'Update a trigger by specifying the trigger ID and the same fields used when creating a new trigger.

        '
      tags:
      - Triggers
      operationId: updateTrigger
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TriggerResponse'
        required: true
      responses:
        '200':
          description: Success
          headers:
            Ratelimit:
              $ref: '#/components/headers/RateLimit'
            RateLimitPolicy:
              $ref: '#/components/headers/RateLimitPolicy'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TriggerResponse'
        '400':
          $ref: '#/components/responses/GenericError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/RateLimited'
    delete:
      security:
      - configuration_key: []
      summary: Delete a Trigger
      description: 'Delete a trigger by specifying the trigger ID. The body of the DELETE request should be empty.

        '
      tags:
      - Triggers
      operationId: deleteTrigger
      responses:
        '204':
          description: Success - no content
          headers:
            Ratelimit:
              $ref: '#/components/headers/RateLimit'
            RateLimitPolicy:
              $ref: '#/components/headers/RateLimitPolicy'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
  /1/recipients/{recipientId}/triggers:
    parameters:
    - $ref: '#/components/parameters/recipientId'
    get:
      security:
      - configuration_key: []
      summary: Get Triggers Associated with a Recipient
      description: 'List all triggers that will alert a given Recipient. **Important:** This request will return all Triggers associated with the specific Recipient across your entire Honeycomb team rather than being scoped to a dataset or environment.

        '
      tags:
      - Triggers
      operationId: listTriggersWithRecipient
      responses:
        '200':
          description: Success
          headers:
            Ratelimit:
              $ref: '#/components/headers/RateLimit'
            RateLimitPolicy:
              $ref: '#/components/headers/RateLimitPolicy'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TriggerResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        default:
          $ref: '#/components/responses/GenericError'
components:
  responses:
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            deny-management-apis:
              description: Team cannot access management APIs.
              value:
                error: Your team has been denied access to Management APIs, please contact support to be unblocked.
        application/problem+json:
          schema:
            $ref: '#/components/schemas/DetailedError'
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/JSONAPIError'
    UnprocessableEntity:
      description: Invalid request
      headers:
        Ratelimit:
          $ref: '#/components/headers/RateLimit'
        RateLimitPolicy:
          $ref: '#/components/headers/RateLimitPolicy'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ValidationError'
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: Rate Limit Exceeded
      headers:
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
        Ratelimit:
          $ref: '#/components/headers/RateLimit'
        RateLimitPolicy:
          $ref: '#/components/headers/RateLimitPolicy'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Rate Limited
        application/problem+json:
          schema:
            $ref: '#/components/schemas/DetailedError'
          example:
            status: 429
            type: https://api.honeycomb.io/problems/rate-limited
            title: You have exceeded your rate limit.
            error: You have exceeded your rate limit.
            detail: Please try again after 2025-02-01T15:23:12Z.
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/JSONAPIError'
          example:
            errors:
            - id: 06dcdd6508ca822f0e7e2bb4121c1f52
              code: rate-limited/may-retry
              title: request rate limit exceeded
              detail: Please try again after 2025-02-01T15:23:12Z.
    PayloadTooLarge:
      description: The provided request body was over the maximum allowed size.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DetailedError'
          example:
            status: 413
            type: https://api.honeycomb.io/problems/payload-too-large
            title: Request body is too large.
            error: Body size is larger than maximum size of 100000 bytes
    NotFound:
      description: Not Found
      headers:
        Ratelimit:
          $ref: '#/components/headers/RateLimit'
        RateLimitPolicy:
          $ref: '#/components/headers/RateLimitPolicy'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: dataset not found
        application/problem+json:
          schema:
            $ref: '#/components/schemas/DetailedError'
          example:
            status: 404
            type: https://api.honeycomb.io/problems/not-found
            title: The requested resource cannot be found.
            error: Dataset not found
            detail: Dataset not found
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/JSONAPIError'
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: unknown API key - check your credentials
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/JSONAPIError'
    BadRequest:
      description: The provided request body was invalid.
      headers:
        Ratelimit:
          $ref: '#/components/headers/RateLimit'
        RateLimitPolicy:
          $ref: '#/components/headers/RateLimitPolicy'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/DetailedError'
          examples:
            DetailedError:
              value:
                status: 400
                type: https://api.honeycomb.io/problems/unparseable
                title: The request body could not be parsed.
                error: invalid gzip data
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            GenericError:
              value:
                error: invalid Query data
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/JSONAPIError'
          examples:
            JSONAPIError:
              value:
                errors:
                - id: 06dcdd6508ca822f0e7e2bb4121c1f52
                  code: invalid
                  title: request body could not be parsed
                  detail: invalid gzip data
    GenericError:
      description: Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    BaseTrigger:
      type: object
      properties:
        id:
          type: string
          readOnly: true
          description: The unique identifier (ID) for this Trigger.
        dataset_slug:
          type: string
          readOnly: true
          description: The slug of the dataset this trigger belongs to. For environment-wide triggers, this will be "__all__".
        name:
          type: string
          description: 'A short, human-readable name for this Trigger, which will be displayed in the UI and when the trigger fires.

            '
          minLength: 1
          maxLength: 120
        description:
          type: string
          description: 'A longer description, displayed on the Trigger''s detail page.

            '
          maxLength: 1023
        tags:
          type: array
          description: A list of key-value pairs to help identify the Trigger.
          maxItems: 10
          items:
            $ref: '#/components/schemas/Tag'
          example:
          - key: team
            value: blue
        threshold:
          type: object
          required:
          - op
          - value
          description: 'The threshold over which the trigger will fire, specified as both an operator and a value.

            '
          properties:
            op:
              type: string
              enum:
              - '>'
              - '>='
              - <
              - <=
            value:
              type: number
            exceeded_limit:
              type: integer
              description: 'The number of times the threshold must be met before an alert is sent.

                '
              default: 1
              minimum: 1
              maximum: 5
        frequency:
          type: integer
          description: 'The interval in seconds in which to check the results of the query’s calculation against the threshold. Cannot be more than 4 times the query''s duration (i.e. `duration <= frequency*4`). See [A Caveat on Time](https://docs.honeycomb.io/investigate/collaborate/share-query/define-query-json/#how-to-specify-an-absolute-time-range) for more information on specifying a query''s duration. minimum: 60 maximum: 86400 multipleOf: 60 default: 900

            '
        alert_type:
          type: string
          description: "How often to fire an alert when a trigger threshold is crossed.\n- `on_change` sends a trigger notification when the result of the specified calculation crosses the threshold.\n  The trigger resolves only when the result of the query no longer satisfies the threshold condition.\n- `on_true` keeps sending a trigger notification at current frequency when and while the threshold is met.\n  (This reflects the same behavior as the \"Send an alert every time a threshold is met\" checkbox in the Honeycomb UI.)\n"
          enum:
          - on_change
          - on_true
          default: on_change
        disabled:
          type: boolean
          default: false
          description: 'If true, the trigger will not be evaluated and alerts will not be sent.

            '
        triggered:
          type: boolean
          readOnly: true
          description: 'If true, the trigger has crossed its specified threshold without resolving.

            '
        recipients:
          type: array
          description: 'A list of [Recipients](/api/recipients/) to notify when the Trigger fires. Using `type`+`target` is deprecated. First, create the Recipient via the Recipients API, and then specify the ID.

            '
          items:
            $ref: '#/components/schemas/NotificationRecipient'
        evaluation_schedule_type:
          type: string
          description: 'The schedule type used by the trigger. The default is frequency, where the trigger runs at the

            specified frequency. The window type means that the trigger will run at the specified frequency,

            but only in the time window specified in the evaluation_schedule field.

            '
          enum:
          - frequency
          - window
        evaluation_schedule:
          type: object
          description: 'A schedule that determines when the trigger is run. When the time is within the scheduled

            window, the trigger will be run at the specified frequency. Outside of the window, the trigger

            will not be run.

            '
          required:
          - window
          properties:
            window:
              type: object
              description: 'Window start/end times and days of the week are calculated in UTC. If the end time is the same as or earlier than the start time, the end time is treated as being in the following day.

                '
              required:
              - days_of_week
              - start_time
              - end_time
              properties:
                days_of_week:
                  type: array
                  minItems: 1
                  maxItems: 7
                  items:
                    type: string
                    enum:
                    - sunday
                    - monday
                    - tuesday
                    - wednesday
                    - thursday
                    - friday
                    - saturday
                start_time:
                  type: string
                  description: A UTC time in HH:mm format (13:00)
                  example: 840
                  pattern: ^([0-1]?[0-9]|2[0-3]):[0-5][0-9]$
                end_time:
                  type: string
                  description: A UTC time in HH:mm format (13:00)
                  example: 1260
                  pattern: ^([0-1]?[0-9]|2[0-3]):[0-5][0-9]$
        created_at:
          type: string
          format: date-time
          readOnly: true
        updated_at:
          type: string
          format: date-time
          readOnly: true
        baseline_details:
          type: object
          oneOf:
          - required:
            - offset_minutes
            - type
            description: 'Additional properties needed to configure this trigger with a dynamic baseline threshold.

              '
            properties:
              offset_minutes:
                type: integer
                enum:
                - 60
                - 1440
                - 10080
                - 40320
                description: 'For a given trigger run, how far back we should look to compare results. Currently only support comparison 1 hour, 24 hours, 7 days, or 28 days in the past.

                  '
              type:
                type: string
                enum:
                - percentage
                - value
                description: 'How to compare the change in the two time periods. Currently supports the difference in values (b-a) or the percentage difference in values (b-a)/b.

                  '
            example:
              offset_minutes: 60
              type: percentage
          - description: Set to an empty object to clear the baseline threshold.
            additionalProperties: false
            example: {}
        auto_investigate:
          x-internal: true
          type: boolean
          description: 'When true, Honeycomb will automatically start an investigation when this Trigger fires.

            '
          default: false
          example: false
    Tag:
      type: object
      required:
      - key
      - value
      properties:
        key:
          type: string
          description: A key to identify the tag, lowercase letters only.
          maxLength: 32
        value:
          type: string
          description: A value for the tag, must begin with a lowercase letter, contain only alphanumeric characters (all letters lowercase) and special characters of `/` and `-` allowed.
          maxLength: 128
    RecipientType:
      type: string
      description: One of the supported Recipient Types
      enum:
      - pagerduty
      - email
      - slack
      - webhook
      - msteams
      - msteams_workflow
    TriggerResponse:
      allOf:
      - $ref: '#/components/schemas/TriggerWithInlineQuery'
      - $ref: '#/components/schemas/TriggerWithQueryReference'
    TriggerWithInlineQuery:
      allOf:
      - $ref: '#/components/schemas/BaseTrigger'
      - type: object
        properties:
          query:
            type: object
            description: 'An inline query specification that is a strict subset of the standard Query Specification.


              **Required Fields:**

              - `calculations`: At least one aggregate calculation (e.g., COUNT, AVG, SUM). Cannot use HEATMAP or CONCURRENCY.

              - `time_range`: Query duration in seconds. Must be between the trigger `frequency` and the lesser of (4 × `frequency`) or 86400 (24 hours).


              **Prohibited Fields:**

              - `orders`: Not supported. Trigger queries automatically order results based on the threshold operator.

              - `limit`: Not supported. All matching result groups are evaluated.

              - `start_time` and `end_time`: Not supported. Use `time_range` instead for relative time windows.

              - `usage_mode`: Not supported for triggers.


              **Calculation Restrictions:**

              - Without formulas: Maximum 1 non-having aggregate allowed.

              - With formulas: Maximum 1 formula allowed, with up to 100 aggregates.

              - Maximum 1 HAVING clause allowed, which must correspond to an existing calculation.

              - Named aggregates cannot be combined with global `filters`.


              **Metrics Dataset Specific:**

              - `granularity` field is supported and must be within calculated min/max bounds based on time range.

              - Nil aggregate values are skipped during trigger evaluation (no error, group is simply not evaluated).

              - Requires a non-legacy environment.


              **Standard Datasets:**

              - `granularity` field is not supported.


              Learn more about [Triggers](https://docs.honeycomb.io/notify/alert/triggers/).

              '
            properties: {}
    Error:
      x-tags:
      - Errors
      type: object
      description: A legacy error, containing only a textual description.
      properties:
        error:
          type: string
          readOnly: true
    CreateTriggerRequest:
      oneOf:
      - $ref: '#/components/schemas/TriggerWithInlineQuery'
      - $ref: '#/components/schemas/TriggerWithQueryReference'
    ValidationError:
      x-tags:
      - Errors
      allOf:
      - $ref: '#/components/schemas/DetailedError'
      - type: object
        properties:
          status:
            type: number
            readOnly: true
            default: 422
          type:
            type: string
            readOnly: true
            default: https://api.honeycomb.io/problems/validation-failed
          title:
            type: string
            readOnly: true
            default: The provided input is invalid.
          type_detail:
            type: array
            items:
              type: object
              properties:
                field:
                  type: string
                  readOnly: true
                code:
                  type: string
                  readOnly: true
                  enum:
                  - invalid
                  - missing
                  - incorrect_type
                  - already_exists
                description:
                  type: string
                  readOnly: true
    NotificationRecipientDetails:
      type: object
      properties:
        pagerduty_severity:
          description: 'When using a Recipient of `type = "pagerduty"`, the severity of the alert can be specified.

            '
          type: string
          default: critical
          enum:
          - critical
          - error
          - warning
          - info
        variables:
          description: 'When using a Recipient of `type = "webhook"`, the alert-level variables can be specified.

            '
          type: array
          items:
            type: object
            required:
            - name
            properties:
              name:
                type: string
                pattern: ^[a-z](?:[a-zA-Z0-9]+$)?$
                maxLength: 64
                example: severity
              value:
                type: string
                maxLength: 256
                example: warning
    TriggerWithQueryReference:
      allOf:
      - $ref: '#/components/schemas/BaseTrigger'
      - type: object
        properties:
          query_id:
            type: string
            description: 'The ID of an existing saved Query that meets the trigger query requirements.


              The referenced query must satisfy the same restrictions as inline trigger queries:

              - Must have at least one aggregate calculation (not HEATMAP or CONCURRENCY)

              - Cannot have `orders`, `limit`, `start_time`, `end_time`, or `usage_mode` fields set

              - Must have appropriate `time_range` relative to trigger frequency

              - Must respect calculation restrictions (max 1 non-having aggregate without formulas, or max 1 formula with up to 100 aggregates)

              - Maximum 1 having clause allowed

              - Named aggregates cannot be combined with global filters

              - For metrics datasets: may include `granularity` field (within calculated bounds)

              - For standard datasets: must not include `granularity` field


              The API will validate the referenced query meets these criteria when creating or updating the trigger.


              See the inline `query` field documentation above for complete trigger query requirements and learn more about [Triggers](https://docs.honeycomb.io/notify/alert/triggers/).

              '
    NotificationRecipient:
      type: object
      properties:
        id:
          type: string
        type:
          deprecated: true
          description: 'One of the allowed Recipient types.

            Deprecated: Use the Recipients API first, then pass the Recipient ID.

            '
          allOf:
          - $ref: '#/components/schemas/RecipientType'
        target:
          type: string
          deprecated: true
          description: 'The target of the notification. For example, the specific Slack channel or email address.

            For Recipients of `type = "webhook"` or `type = "msteams_workflow"`,

            this will be the Name in the UI and `webhook_name` in the Recipients API.

            Deprecated: Use the Recipients API first, then pass the Recipient ID.

            '
        details:
          $ref: '#/components/schemas/NotificationRecipientDetails'
    DetailedError:
      x-tags:
      - Errors
      description: An RFC7807 'Problem Detail' formatted error message.
      type: object
      required:
      - error
      - status
      - type
      - title
      properties:
        error:
          type: string
          readOnly: true
          default: something went wrong!
        status:
          type: number
          readOnly: true
          description: The HTTP status code of the error.
        type:
          type: string
          readOnly: true
          description: Type is a URI used to uniquely identify the type of error.
        title:
          type: string
          readOnly: true
          description: Title is a human-readable summary that explains the `type` of the problem.
        detail:
          type: string
          readOnly: true
          description: The general, human-readable error message.
        instance:
          type: string
          readOnly: true
          description: The unique identifier (ID) for this specific error.
    JSONAPIError:
      x-tags:
      - Errors
      type: object
      description: A JSONAPI-formatted error message.
      properties:
        errors:
          type: array
          items:
            type: object
            readOnly: true
            required:
            - id
            - code
            properties:
              id:
                type: string
                readOnly: true
              status:
                type: string
                readOnly: true
              code:
                type: string
                readOnly: true
              title:
                type: string
                readOnly: true
              detail:
                type: string
                readOnly: true
              source:
                type: object
                readOnly: true
                properties:
                  pointer:
                    type: string
                    readOnly: true
                  header:
                    type: string
                    readOnly: true
                  parameter:
                    type: string
                    readOnly: true
  headers:
    RateLimit:
      description: "The (draft07) recommended header from the IETF on rate limiting.\nThe value of the header is formatted \"limit=X, remaining=Y, reset=Z\".\nWhere:\n  - X is the maximum number of requests allowed in the window\n  - Y is the number of requests remaining in the window\n  - Z is the number of seconds until the limit resets\n"
      schema:
        type: string
      example: limit=100, remaining=50, reset=60
    RetryAfter:
      description: 'The RFC7231 header used to indicate when a client should retry requests.

        '
      schema:
        type: string
      example: Fri, 22 Mar 2024 18:37:53 GMT
    RateLimitPolicy:
      description: "The (draft07) recommended header from the IETF on rate limiting.\nThe value of the header is formatted \"X;w=Y\".\nWhere:\n - X is the maximum number of requests allowed in a window\n - Y is the size of the window in seconds\n"
      schema:
        type: string
      example: 100;w=60
  parameters:
    recipientId:
      name: recipientId
      description: Unique identifier (ID) of a Recipient.
      in: path
      required: true
      schema:
        type: string
    datasetSlugOrAll:
      name: datasetSlug
      description: 'The dataset slug or use `__all__` for endpoints that support environment-wide operations.

        '
      in: path
      required: true
      schema:
        type: string
externalDocs:
  url: https://docs.honeycomb.io