honeycomb Recipients API

openapi: 3.2.0
info:
  title: Honeycomb Recipients API
  version: '1.0'
  description: 'Operations tagged Recipients across 2 of this provider''s published API definitions: honeycomb-api-openapi.yml, honeycomb-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.honeycomb.io
  description: Honeycomb Production API
- url: https://api.eu1.honeycomb.io
tags:
- name: Recipients
  description: Manage notification destinations for triggers and burn alerts including PagerDuty, Email, Webhook, Microsoft Teams, and Slack.
paths:
  /1/recipients:
    get:
      operationId: listRecipients
      summary: List all recipients
      description: Returns a list of all notification recipients configured for the team. Recipients are team-wide and not environment-specific.
      tags:
      - Recipients
      responses:
        '200':
          description: A list of recipients
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Recipient'
        '401':
          description: Unauthorized
      security:
      - ApiKeyAuth: []
    post:
      operationId: createRecipient
      summary: Create a recipient
      description: Creates a new notification recipient. Supported types include PagerDuty, Email, Webhook, Microsoft Teams, and Slack.
      tags:
      - Recipients
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RecipientCreateRequest'
      responses:
        '201':
          description: Recipient created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Recipient'
        '401':
          description: Unauthorized
      security:
      - ApiKeyAuth: []
    servers:
    - url: https://api.honeycomb.io
      description: Honeycomb Production API
  /1/recipients/{recipientId}:
    get:
      operationId: getRecipient
      summary: Get a recipient
      description: Returns a single recipient by its ID.
      tags:
      - Recipients
      parameters:
      - $ref: '#/components/parameters/recipientId'
      responses:
        '200':
          description: Recipient details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Recipient'
        '401':
          description: Unauthorized
        '404':
          description: Recipient not found
      security:
      - ApiKeyAuth: []
    put:
      operationId: updateRecipient
      summary: Update a recipient
      description: Updates a recipient's notification target or configuration.
      tags:
      - Recipients
      parameters:
      - $ref: '#/components/parameters/recipientId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RecipientUpdateRequest'
      responses:
        '200':
          description: Recipient updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Recipient'
        '401':
          description: Unauthorized
        '404':
          description: Recipient not found
      security:
      - ApiKeyAuth: []
    delete:
      operationId: deleteRecipient
      summary: Delete a recipient
      description: Deletes a notification recipient.
      tags:
      - Recipients
      parameters:
      - $ref: '#/components/parameters/recipientId'
      responses:
        '204':
          description: Recipient deleted
        '401':
          description: Unauthorized
        '404':
          description: Recipient not found
      security:
      - ApiKeyAuth: []
    parameters:
    - $ref: '#/components/parameters/recipientId_2'
    servers:
    - url: https://api.honeycomb.io
      description: Honeycomb Production API
components:
  schemas:
    RecipientCreateRequest:
      type: object
      required:
      - type
      - target
      properties:
        type:
          type: string
          description: The notification channel type.
          enum:
          - email
          - pagerduty
          - slack
          - webhook
          - msteams
        target:
          type: string
          description: The target address or identifier for the recipient.
    Recipient:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the recipient.
        type:
          type: string
          description: The notification channel type.
          enum:
          - email
          - pagerduty
          - slack
          - webhook
          - msteams
        target:
          type: string
          description: The target address or identifier for the recipient, such as an email address or webhook URL.
        created_at:
          type: string
          format: date-time
          description: ISO8601 formatted time the recipient was created.
        updated_at:
          type: string
          format: date-time
          description: ISO8601 formatted time the recipient was last updated.
    RecipientUpdateRequest:
      type: object
      properties:
        target:
          type: string
          description: An updated target address or identifier for the recipient.
    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.
    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'
                      anomaly:
                        $ref: '#/components/schemas/PayloadTemplate'
    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
    Error:
      x-tags:
      - Errors
      type: object
      description: A legacy error, containing only a textual description.
      properties:
        error:
          type: string
          readOnly: true
    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
    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
    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'
    Recipient_2:
      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'
    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
    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'
    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
    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
    RecipientType:
      type: string
      description: One of the supported Recipient Types
      enum:
      - pagerduty
      - email
      - slack
      - webhook
      - msteams
      - msteams_workflow
    WebhookHeader:
      type: object
      required:
      - header
      properties:
        header:
          type: string
          maxLength: 64
        value:
          type: string
          maxLength: 750
    PayloadTemplate:
      type: object
      properties:
        body:
          type: string
          example: '{ \"alert\": \"{{.Alert.Description}}\" }'
    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:
    recipientId:
      name: recipientId
      in: path
      required: true
      description: The unique identifier for the recipient.
      schema:
        type: string
    recipientId_2:
      name: recipientId
      description: Unique identifier (ID) of a Recipient.
      in: path
      required: true
      schema:
        type: string
  responses:
    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'
    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'
    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'
    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'
    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
    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'
  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
    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
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Honeycomb-Team
      description: Honeycomb Configuration API key. Must have appropriate permissions for the endpoint being called.
    configuration_key:
      type: apiKey
      name: X-Honeycomb-Team
      in: header
      description: 'Authenticate using a Honeycomb Configuration Key.


        Pass the **Token** in the `X-Honeycomb-Team` header:

        ```http

        X-Honeycomb-Team: 1234567890123456789012

        ```


        If you created your key using the API, use `data.attributes.secret`; this is the same value as the **Token** in the UI.


        To learn how to create a Configuration Key, visit [Manage Environment API Keys](/configure/environments/manage-api-keys). To learn more about authenticating requests, visit [API Authentication](/api/authentication).

        '
    ingest_key:
      type: apiKey
      name: X-Honeycomb-Team
      in: header
      description: 'Authenticate using a Honeycomb Ingest Key.


        Pass the Ingest Key in the `X-Honeycomb-Team` header:

        ```http

        X-Honeycomb-Team: hc[x]ik_1234567890123456789012345612345678901234567890123456789012

        ```


        The key value is the key ID and key secret concatenated with no separator:

        - If you created your key through the UI, Honeycomb provides the complete value as the **Ingest Key**.

        - If you created your key using the API, construct the key value by concatenating `data.id` and `data.attributes.secret` with no separator.


        To learn how to create an Ingest Key, visit [Manage Environment API Keys](/configure/environments/manage-api-keys). To learn more about authenticating requests, visit [API Authentication](/api/authentication).

        '
    firehose_access_key:
      type: apiKey
      name: X-Amz-Firehose-Access-Key
      in: header
      description: 'We recommend using a Honeycomb Ingest Key to authenticate, though a Configuration Key will work.


        To learn more about authenticating requests, visit [API Authentication](/api/authentication).

        '
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Authenticate using a Honeycomb Management Key.


        Pass the Management Key as a Bearer token in the `Authorization` header:

        ```http

        Authorization: Bearer hcxmk_12345678901234567890123456:12345678901234567890123456789012

        ```


        Construct the key value by joining the **Key ID** and **Secret** with a colon (`:`).


        To learn how to create a Management Key, visit [Manage Team API Keys](/configure/teams/manage-api-keys). To learn more about authenticating requests, visit [API Authentication](/api/authentication).

        '
      bearerFormat: HONEYCOMB_KEY_ID:HONEYCOMB_KEY_SECRET
x-refined-from:
- honeycomb-api-openapi.yml
- honeycomb-openapi.yml