openapi: 3.1.0
info:
  title: Honeycomb 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>.

    '
externalDocs:
  url: https://docs.honeycomb.io
servers:
- url: https://api.honeycomb.io
- url: https://api.eu1.honeycomb.io
tags:
- name: Recipients
  description: 'Honeycomb Recipients allow you to define and manage the Recipients that will get notified by a Trigger or Burn Alert.


    The types of Recipients supported are: PagerDuty, Email, Webhook, Microsoft Teams, and Slack.


    ## Authorization


    The API key must have the **Manage Recipients** permission. Recipients are team-wide and NOT environment-specific.

    API Keys with the **Manage Recipients** permission can modify recipients used by ALL environments for a given team.


    Learn more about [API keys here](https://docs.honeycomb.io/configure/environments/manage-api-keys/).

    '
- 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/recipients:
    post:
      security:
      - configuration_key: []
      summary: Create a Recipient
      description: 'Unlike many resources, Recipients are not linked to a specific Environment or Dataset. The Recipient will be created for the Team associated with your API key.

        The `details` fields will vary depending on the `type` of Recipient. Use the drop-down to view the specific fields for each `type` value.

        Before Slack Recipients can be created, the Slack OAuth flow in the Integration Center must be completed.

        '
      tags:
      - Recipients
      operationId: createRecipient
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Recipient'
        required: true
      responses:
        '201':
          description: Success
          headers:
            Ratelimit:
              $ref: '#/components/headers/RateLimit'
            RateLimitPolicy:
              $ref: '#/components/headers/RateLimitPolicy'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Recipient'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/ValidationFailed'
    get:
      security:
      - configuration_key: []
      summary: List all Recipients
      description: 'Retrieve all recipients for a team.

        '
      tags:
      - Recipients
      operationId: listRecipients
      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/Recipient'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: unknown API key - check your credentials
  /1/recipients/{recipientId}:
    parameters:
    - $ref: '#/components/parameters/recipientId'
    get:
      security:
      - configuration_key: []
      summary: Get a single Recipient
      description: 'Retrieve a Recipient by recipient ID.

        '
      tags:
      - Recipients
      operationId: getRecipient
      responses:
        '200':
          description: Success
          headers:
            Ratelimit:
              $ref: '#/components/headers/RateLimit'
            RateLimitPolicy:
              $ref: '#/components/headers/RateLimitPolicy'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Recipient'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      security:
      - configuration_key: []
      summary: Update a Recipient
      description: 'Update a Recipient by specifying the recipient ID and full recipient details. (Partial PUT is not supported.)

        Updates to the Recipient Type is not supported. For example, changing an existing Recipient from PagerDuty to Email is not allowed.

        **Important**: Modifying an existing recipient will change the destination of all triggers/burn alerts that use that recipient.

        '
      tags:
      - Recipients
      operationId: updateRecipient
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Recipient'
        required: true
      responses:
        '200':
          description: Success
          headers:
            Ratelimit:
              $ref: '#/components/headers/RateLimit'
            RateLimitPolicy:
              $ref: '#/components/headers/RateLimitPolicy'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Recipient'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/ValidationFailed'
    delete:
      security:
      - configuration_key: []
      summary: Delete a Recipient
      description: 'Delete a recipient by specifying the recipient ID.

        A Recipient can only be deleted if it is NOT in use by any Triggers or Burn Alerts associated to the team.

        '
      tags:
      - Recipients
      operationId: deleteRecipient
      responses:
        '204':
          description: Success - no content
          headers:
            Ratelimit:
              $ref: '#/components/headers/RateLimit'
            RateLimitPolicy:
              $ref: '#/components/headers/RateLimitPolicy'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: unknown API key - check your credentials
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
  /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:
  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\u2019s 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\n"
        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
    EmailRecipient:
      allOf:
      - $ref: '#/components/schemas/RecipientProperties'
      - type: object
        properties:
          type:
            type: string
            enum:
            - email
      - type: object
        properties:
          details:
            type: object
            required:
            - email_address
            description: Specific schema for the Email Recipient Type
            properties:
              email_address:
                type: string
                description: Email address to notify.
                example: notify-me@example-email.com
    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
    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/).

              '
    RecipientProperties:
      type: object
      properties:
        id:
          type: string
          readOnly: true
          example: yUheCUmgZ8p
        created_at:
          type: string
          format: date-time
          description: ISO8601 formatted time the Recipient was created.
          example: '2022-07-26T22:38:04Z'
          readOnly: true
        updated_at:
          type: string
          format: date-time
          description: ISO8601 formatted time the Recipient was updated.
          example: '2022-07-26T22:38:04Z'
          readOnly: true
        type:
          $ref: '#/components/schemas/RecipientType'
    MSTeamsWorkflowRecipient:
      allOf:
      - $ref: '#/components/schemas/RecipientProperties'
      - type: object
        properties:
          type:
            type: string
            enum:
            - msteams_workflow
      - type: object
        properties:
          details:
            type: object
            required:
            - webhook_name
            - webhook_url
            description: Specific schema for the MS Teams Workflow Recipient Type.
            properties:
              webhook_name:
                type: string
                maxLength: 255
                description: A name for this recipient.
                example: My Teams Channel
              webhook_url:
                type: string
                maxLength: 2048
                description: Incoming webhook URL of an Teams instance.
                example: https://test-123.westus.logic.azure.com:443/workflows/54321/triggers/manual/paths/invoke
    CreateTriggerRequest:
      oneOf:
      - $ref: '#/components/schemas/TriggerWithInlineQuery'
      - $ref: '#/components/schemas/TriggerWithQueryReference'
    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
    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.\n\n**Required Fields:**\n- `calculations`: At least one aggregate calculation (e.g.,\
              \ COUNT, AVG, SUM). Cannot use HEATMAP or CONCURRENCY.\n- `time_range`: Query duration in seconds. Must be between the trigger `frequency` and the lesser of (4 \xD7 `frequency`) or 86400 (24\
              \ hours).\n\n**Prohibited Fields:**\n- `orders`: Not supported. Trigger queries automatically order results based on the threshold operator.\n- `limit`: Not supported. All matching result\
              \ groups are evaluated.\n- `start_time` and `end_time`: Not supported. Use `time_range` instead for relative time windows.\n- `usage_mode`: Not supported for triggers.\n\n**Calculation Restrictions:**\n\
              - Without formulas: Maximum 1 non-having aggregate allowed.\n- With formulas: Maximum 1 formula allowed, with up to 100 aggregates.\n- Maximum 1 HAVING clause allowed, which must correspond\
              \ to an existing calculation.\n- Named aggregates cannot be combined with global `filters`.\n\n**Metrics Dataset Specific:**\n- `granularity` field is supported and must be within calculated\
              \ min/max bounds based on time range.\n- Nil aggregate values are skipped during trigger evaluation (no error, group is simply not evaluated).\n- Requires a non-legacy environment.\n\n**Standard\
              \ Datasets:**\n- `granularity` field is not supported.\n\nLearn more about [Triggers](https://docs.honeycomb.io/notify/alert/triggers/).\n"
            properties: {}
    WebhookHeader:
      type: object
      required:
      - header
      properties:
        header:
          type: string
          maxLength: 64
        value:
          type: string
          maxLength: 750
    MSTeamsRecipient:
      allOf:
      - $ref: '#/components/schemas/RecipientProperties'
      - type: object
        properties:
          type:
            type: string
            enum:
            - msteams
      - type: object
        deprecated: true
        properties:
          details:
            type: object
            required:
            - webhook_name
            - webhook_url
            description: Specific schema for the MS Teams Recipient Type. Now deprecated, please use the `msteams_workflow` type instead.
            properties:
              webhook_name:
                type: string
                description: A name for this recipient.
                example: My Teams Channel
              webhook_url:
                type: string
                description: Incoming webhook URL of an Teams instance.
                example: https://yourco.webhook.office.com/webhook/xxxx
    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
    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.
    RecipientType:
      type: string
      description: One of the supported Recipient Types
      enum:
      - pagerduty
      - email
      - slack
      - webhook
      - msteams
      - msteams_workflow
    PagerDutyRecipient:
      allOf:
      - $ref: '#/components/schemas/RecipientProperties'
      - type: object
        properties:
          type:
            type: string
            enum:
            - pagerduty
      - type: object
        properties:
          details:
            type: object
            required:
            - pagerduty_integration_name
            - pagerduty_integration_key
            description: Specific schema for the Pagerduty Recipient Type
            properties:
              pagerduty_integration_name:
                type: string
                description: A name for this Integration.
                example: Example PagerDuty Service
              pagerduty_integration_key:
                type: string
                description: Pagerduty Integration Key.
                example: 7zOwh1edS8xHGcwfb2bA4sqY8E6PJzSK
                minLength: 32
                maxLength: 32
    WebhookRecipient:
      allOf:
      - $ref: '#/components/schemas/RecipientProperties'
      - type: object
        properties:
          type:
            type: string
            enum:
            - webhook
      - type: object
        properties:
          details:
            type: object
            required:
            - webhook_name
            - webhook_url
            description: Specific schema for the Webhook Recipient Type
            properties:
              webhook_headers:
                type: array
                maxItems: 5
                description: Custom headers for this webhook
                items:
                  $ref: '#/components/schemas/WebhookHeader'
                example:
                - header: Authorization
                  value: Bearer xyz123
              webhook_name:
                type: string
                maxLength: 255
                description: A name for this Integration.
                example: Example webhook
              webhook_url:
                type: string
                description: Webhook URL.
                maxLength: 2048
                example: https://webhook.example.com
              webhook_secret:
                type: string
                description: Webhook secret.
                maxLength: 255
                example: secret
              webhook_payloads:
                type: object
                description: Specify a custom webhook payload.
                properties:
                  template_variables:
                    type: array
                    maxItems: 10
                    description: Custom variable definitions for this webhook
                    items:
                      $ref: '#/components/schemas/TemplateVariableDefinition'
                    example:
                    - name: severity
                      default_value: CRITICAL
                  payload_templates:
                    type: object
                    properties:
                      trigger:
                        $ref: '#/components/schemas/PayloadTemplate'
                      budget_rate:
                        $ref: '#/components/schemas/PayloadTemplate'
                      exhaustion_time:
                        $ref: '#/components/schemas/PayloadTemplate'
    SlackRecipient:
      allOf:
      - $ref: '#/components/schemas/RecipientProperties'
      - type: object
        properties:
          type:
            type: string
            enum:
            - slack
      - type: object
        properties:
          details:
            type: object
            required:
            - slack_channel
            description: Specific schema for the Slack Recipient Type.
            properties:
              slack_channel:
                type: string
                description: Slack channel to notify.
                example: '#alerts-channel'
    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
    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'
    PayloadTemplate:
      type: object
      properties:
        body:
          type: string
          example: '{ \"alert\": \"{{.Alert.Description}}\" }'
    Recipient:
      type: object
      required:
      - type
      properties:
        type:
          type: string
      discriminator:
        propertyName: type
        mapping:
          pagerduty: '#/components/schemas/PagerDutyRecipient'
          email: '#/components/schemas/EmailRecipient'
          slack: '#/components/schemas/SlackRecipient'
          webhook: '#/components/schemas/WebhookRecipient'
          msteams: '#/components/schemas/MSTeamsRecipient'
          msteams_workflow: '#/components/schemas/MSTeamsWorkflowRecipient'
      oneOf:
      - $ref: '#/components/schemas/PagerDutyRecipient'
      - $ref: '#/components/schemas/EmailRecipient'
      - $ref: '#/components/schemas/SlackRecipient'
      - $ref: '#/components/schemas/WebhookRecipient'
      - $ref: '#/components/schemas/MSTeamsRecipient'
      - $ref: '#/components/schemas/MSTeamsWorkflowRecipient'
    Error:
      x-tags:
      - Errors
      type: object
      description: A legacy error, containing only a textual description.
      properties:
        error:
          type: string
          readOnly: true
    TemplateVariableDefinition:
      type: object
      required:
      - name
      properties:
        name:
          type: string
          pattern: ^[a-z](?:[a-zA-Z0-9]+$)?$
          maxLength: 64
          example: severity
        default_value:
          type: string
          maxLength: 256
          example: CRITICAL
  parameters:
    datasetSlugOrAll:
      name: datasetSlug
      description: 'The dataset slug or use `__all__` for endpoints that support environment-wide operations.

        '
      in: path
      required: true
      schema:
        type: string
    recipientId:
      name: recipientId
      description: Unique identifier (ID) of a Recipient.
      in: path
      required: true
      schema:
        type: string
  responses:
    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'
    ValidationFailed:
      description: Validation Failed
      headers:
        Ratelimit:
          $ref: '#/components/headers/RateLimit'
        RateLimitPolicy:
          $ref: '#/components/headers/RateLimitPolicy'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ValidationError'
          example:
            status: 422
            type: https://api.honeycomb.io/problems/validation-failed
            error: The provided input is invalid.
            title: The provided input is invalid
            type_detail:
            - field: type
              code: invalid
              description: 'type: must be a valid value'
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/JSONAPIError'
    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'
    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'
    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
    GenericError:
      description: Error
      content:
        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.
    Conflict:
      description: Conflict
      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: 409
            type: https://api.honeycomb.io/problems/conflict
            title: Request could not be completed due to a conflict with the current state of the target resource.
            error: A resource by that name already exists.
        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
  headers:
    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
    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
    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