Define thresholded alerts on top of saved queries — Triggers — and route their firings to Recipients (PagerDuty, Slack, MS Teams, webhooks, email, OpsGenie). Trigger frequency, thresholds, and evaluation schedule are fully configurable per dataset.
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:
# --- truncated at 32 KB (47 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/honeycomb-io/refs/heads/main/openapi/honeycomb-triggers-api-openapi.yml