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 Auth Triggers API
description: The Honeycomb API is a REST API that provides programmatic access to the Honeycomb observability platform. It enables developers to manage datasets and columns, configure SLOs and burn alerts, set up triggers and recipients, manage boards and markers, administer environments, API keys, and access auth, query annotations, calculated fields, marker settings, reporting, dataset definitions, and service maps.
version: '1.0'
contact:
name: Honeycomb Support
url: https://support.honeycomb.io
termsOfService: https://www.honeycomb.io/terms-of-service
servers:
- url: https://api.honeycomb.io
description: Honeycomb Production API
security:
- ApiKeyAuth: []
tags:
- name: Triggers
description: Configure alerting rules that fire when query results meet specified conditions.
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.
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'
'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
components:
schemas:
RecipientRef:
type: object
properties:
id:
type: string
description: The ID of the recipient to notify.
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: An updated display name for the trigger.
description:
type: string
description: An updated description for the trigger.
disabled:
type: boolean
description: Whether the trigger should be disabled.
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'
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.
QuerySpec:
type: object
description: A query specification defining what data to retrieve and how to aggregate it.
properties:
calculations:
type: array
description: The calculations to perform on the query data.
items:
type: object
properties:
op:
type: string
description: The aggregation operation.
enum:
- COUNT
- SUM
- AVG
- COUNT_DISTINCT
- MAX
- MIN
- P001
- P01
- P05
- P10
- P25
- P50
- P75
- P90
- P95
- P99
- P999
- HEATMAP
- RATE_AVG
- RATE_SUM
- RATE_MAX
column:
type: string
description: The column to perform the calculation on.
filters:
type: array
description: Filters to apply to the query.
items:
type: object
properties:
column:
type: string
description: The column to filter on.
op:
type: string
description: The filter operator.
enum:
- '='
- '!='
- '>'
- '>='
- <
- <=
- starts-with
- does-not-start-with
- contains
- does-not-contain
- exists
- does-not-exist
- in
- not-in
value:
description: The value to compare against.
breakdowns:
type: array
description: Columns to group results by.
items:
type: string
orders:
type: array
description: Ordering for the results.
items:
type: object
properties:
column:
type: string
op:
type: string
order:
type: string
enum:
- ascending
- descending
time_range:
type: integer
description: The time range in seconds to query over.
start_time:
type: integer
description: Unix timestamp for the query start time.
end_time:
type: integer
description: Unix timestamp for the query end time.
granularity:
type: integer
description: The granularity of results in seconds.
limit:
type: integer
description: The maximum number of results to return.
parameters:
triggerId:
name: triggerId
in: path
required: true
description: The unique identifier for the trigger.
schema:
type: string
datasetSlug:
name: datasetSlug
in: path
required: true
description: The slug identifier for the dataset. Dataset names are case insensitive.
schema:
type: string
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-Honeycomb-Team
description: Honeycomb Configuration API key. Must have appropriate permissions for the endpoint being called.
externalDocs:
description: Honeycomb API Documentation
url: https://api-docs.honeycomb.io/api