openapi: 3.1.0
info:
title: Honeycomb Auth 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>.
'
servers:
- url: https://api.honeycomb.io
- url: https://api.eu1.honeycomb.io
tags:
- 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/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:
responses:
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'
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'
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.
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
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'
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
GenericError:
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
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’s 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
'
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
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
RecipientType:
type: string
description: One of the supported Recipient Types
enum:
- pagerduty
- email
- slack
- webhook
- msteams
- msteams_workflow
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.
**Required Fields:**
- `calculations`: At least one aggregate calculation (e.g., COUNT, AVG, SUM). Cannot use HEATMAP or CONCURRENCY.
- `time_range`: Query duration in seconds. Must be between the trigger `frequency` and the lesser of (4 × `frequency`) or 86400 (24 hours).
**Prohibited Fields:**
- `orders`: Not supported. Trigger queries automatically order results based on the threshold operator.
- `limit`: Not supported. All matching result groups are evaluated.
- `start_time` and `end_time`: Not supported. Use `time_range` instead for relative time windows.
- `usage_mode`: Not supported for triggers.
**Calculation Restrictions:**
- Without formulas: Maximum 1 non-having aggregate allowed.
- With formulas: Maximum 1 formula allowed, with up to 100 aggregates.
- Maximum 1 HAVING clause allowed, which must correspond to an existing calculation.
- Named aggregates cannot be combined with global `filters`.
**Metrics Dataset Specific:**
- `granularity` field is supported and must be within calculated min/max bounds based on time range.
- Nil aggregate values are skipped during trigger evaluation (no error, group is simply not evaluated).
- Requires a non-legacy environment.
**Standard Datasets:**
- `granularity` field is not supported.
Learn more about [Triggers](https://docs.honeycomb.io/notify/alert/triggers/).
'
properties: {}
Error:
x-tags:
- Errors
type: object
description: A legacy error, containing only a textual description.
properties:
error:
type: string
readOnly: true
CreateTriggerRequest:
oneOf:
- $ref: '#/components/schemas/TriggerWithInlineQuery'
- $ref: '#/components/schemas/TriggerWithQueryReference'
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
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
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/).
'
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'
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.
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
headers:
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
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
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
parameters:
recipientId:
name: recipientId
description: Unique identifier (ID) of a Recipient.
in: path
required: true
schema:
type: string
datasetSlugOrAll:
name: datasetSlug
description: 'The dataset slug or use `__all__` for endpoints that support environment-wide operations.
'
in: path
required: true
schema:
type: string
externalDocs:
url: https://docs.honeycomb.io