The Honeycomb Triggers API allows developers to programmatically configure alerting rules that fire when query results meet specified conditions. Triggers work in conjunction with the Recipients API, which manages notification destinations including PagerDuty, Email, Webhook, Microsoft Teams, and Slack. The API supports listing, creating, updating, and deleting triggers, enabling automated setup of alerting workflows for production observability.
openapi: 3.1.0
info:
title: Honeycomb Triggers API
description: >-
The Honeycomb Triggers API allows developers to programmatically configure
alerting rules that fire when query results meet specified conditions.
Triggers work in conjunction with the Recipients API, which manages
notification destinations including PagerDuty, Email, Webhook, Microsoft
Teams, and Slack. The API supports listing, creating, updating, and
deleting triggers, enabling automated setup of alerting workflows for
production observability.
version: '1.0'
contact:
name: Honeycomb Support
url: https://support.honeycomb.io
termsOfService: https://www.honeycomb.io/terms-of-service
externalDocs:
description: Honeycomb Triggers API Documentation
url: https://api-docs.honeycomb.io/api/triggers
servers:
- url: https://api.honeycomb.io
description: Honeycomb Production API
tags:
- name: Triggers
description: >-
Configure alerting rules that fire when query results meet specified
threshold conditions.
- name: Recipients
description: >-
Manage notification destinations for triggers and burn alerts including
PagerDuty, Email, Webhook, Microsoft Teams, and Slack.
security:
- ApiKeyAuth: []
paths:
/1/triggers/{datasetSlug}:
get:
operationId: listTriggers
summary: List all triggers
description: >-
Returns a list of all triggers for the specified dataset.
tags:
- Triggers
parameters:
- $ref: '#/components/parameters/datasetSlug'
responses:
'200':
description: A list of triggers
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Trigger'
'401':
description: Unauthorized
post:
operationId: createTrigger
summary: Create a trigger
description: >-
Creates a new trigger that fires when query results meet specified
threshold conditions. Recipients should be created first via the
Recipients API and referenced by ID.
tags:
- Triggers
parameters:
- $ref: '#/components/parameters/datasetSlug'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TriggerCreateRequest'
responses:
'201':
description: Trigger created
content:
application/json:
schema:
$ref: '#/components/schemas/Trigger'
'400':
description: Bad request - invalid trigger configuration
'401':
description: Unauthorized
/1/triggers/{datasetSlug}/{triggerId}:
get:
operationId: getTrigger
summary: Get a trigger
description: >-
Returns a single trigger by its ID.
tags:
- Triggers
parameters:
- $ref: '#/components/parameters/datasetSlug'
- $ref: '#/components/parameters/triggerId'
responses:
'200':
description: Trigger details
content:
application/json:
schema:
$ref: '#/components/schemas/Trigger'
'401':
description: Unauthorized
'404':
description: Trigger not found
put:
operationId: updateTrigger
summary: Update a trigger
description: >-
Updates a trigger's query, threshold, or notification settings.
tags:
- Triggers
parameters:
- $ref: '#/components/parameters/datasetSlug'
- $ref: '#/components/parameters/triggerId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TriggerUpdateRequest'
responses:
'200':
description: Trigger updated
content:
application/json:
schema:
$ref: '#/components/schemas/Trigger'
'401':
description: Unauthorized
'404':
description: Trigger not found
delete:
operationId: deleteTrigger
summary: Delete a trigger
description: >-
Deletes a trigger from the specified dataset.
tags:
- Triggers
parameters:
- $ref: '#/components/parameters/datasetSlug'
- $ref: '#/components/parameters/triggerId'
responses:
'204':
description: Trigger deleted
'401':
description: Unauthorized
'404':
description: Trigger not found
/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. The API key
must have the Manage Recipients permission.
tags:
- Recipients
responses:
'200':
description: A list of recipients
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Recipient'
'401':
description: Unauthorized
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
/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
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
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
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-Honeycomb-Team
description: >-
Honeycomb Configuration API key with Manage Triggers and Manage
Recipients permissions.
parameters:
datasetSlug:
name: datasetSlug
in: path
required: true
description: >-
The slug identifier for the dataset.
schema:
type: string
triggerId:
name: triggerId
in: path
required: true
description: >-
The unique identifier for the trigger.
schema:
type: string
recipientId:
name: recipientId
in: path
required: true
description: >-
The unique identifier for the recipient.
schema:
type: string
schemas:
Trigger:
type: object
properties:
id:
type: string
description: >-
Unique identifier for the trigger.
name:
type: string
description: >-
The display name of the trigger.
description:
type: string
description: >-
A description of the trigger.
disabled:
type: boolean
description: >-
Whether the trigger is currently disabled.
query:
$ref: '#/components/schemas/QuerySpec'
threshold:
type: object
description: >-
The threshold configuration that determines when the trigger fires.
properties:
op:
type: string
description: >-
The comparison operator.
enum:
- '>'
- '>='
- '<'
- '<='
value:
type: number
description: >-
The threshold value to compare against.
exceeded_limit:
type: integer
description: >-
Number of times threshold must be exceeded before firing.
frequency:
type: integer
description: >-
How frequently in seconds the trigger is evaluated.
recipients:
type: array
description: >-
List of recipients to notify when the trigger fires.
items:
$ref: '#/components/schemas/RecipientRef'
created_at:
type: string
format: date-time
description: >-
ISO8601 formatted time the trigger was created.
updated_at:
type: string
format: date-time
description: >-
ISO8601 formatted time the trigger was last updated.
TriggerCreateRequest:
type: object
required:
- name
- query
- threshold
- recipients
properties:
name:
type: string
description: >-
The display name for the trigger.
description:
type: string
description: >-
An optional description for the trigger.
disabled:
type: boolean
description: >-
Whether the trigger should be disabled upon creation.
query:
$ref: '#/components/schemas/QuerySpec'
threshold:
type: object
required:
- op
- value
properties:
op:
type: string
enum:
- '>'
- '>='
- '<'
- '<='
value:
type: number
frequency:
type: integer
description: >-
How frequently in seconds to evaluate the trigger.
recipients:
type: array
items:
$ref: '#/components/schemas/RecipientRef'
TriggerUpdateRequest:
type: object
properties:
name:
type: string
description:
type: string
disabled:
type: boolean
query:
$ref: '#/components/schemas/QuerySpec'
threshold:
type: object
properties:
op:
type: string
enum:
- '>'
- '>='
- '<'
- '<='
value:
type: number
frequency:
type: integer
recipients:
type: array
items:
$ref: '#/components/schemas/RecipientRef'
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.
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.
RecipientRef:
type: object
properties:
id:
type: string
description: >-
The ID of the recipient to notify.
RecipientCreateRequest:
type: object
required:
- type
- target
properties:
type:
type: string
enum:
- email
- pagerduty
- slack
- webhook
- msteams
target:
type: string
description: >-
The target address or identifier for the recipient.
RecipientUpdateRequest:
type: object
properties:
target:
type: string
description: >-
An updated target address or identifier.
QuerySpec:
type: object
description: >-
A query specification defining the alert condition.
properties:
calculations:
type: array
items:
type: object
properties:
op:
type: string
enum:
- COUNT
- SUM
- AVG
- COUNT_DISTINCT
- MAX
- MIN
- P001
- P01
- P05
- P10
- P25
- P50
- P75
- P90
- P95
- P99
- P999
column:
type: string
filters:
type: array
items:
type: object
properties:
column:
type: string
op:
type: string
value: {}
breakdowns:
type: array
items:
type: string
time_range:
type: integer
description: >-
The time range in seconds for the trigger query.
RecipientRef:
type: object
properties:
id:
type: string
description: >-
The ID of the recipient to notify.