The Honeycomb API is a REST API that provides programmatic access to the Honeycomb observability platform. It enables developers to send events, manage datasets and columns, create and run queries, configure SLOs and burn alerts, set up triggers and recipients, manage boards and markers, and administer environments and API keys.
openapi: 3.1.0
info:
title: Honeycomb 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
externalDocs:
description: Honeycomb API Documentation
url: https://api-docs.honeycomb.io/api
servers:
- url: https://api.honeycomb.io
description: Honeycomb Production API
tags:
- name: Auth
description: >-
Validate authentication for a key, determine what authorizations have been
granted to a key, and determine the Team and Environment it belongs to.
- name: Boards
description: >-
Manage boards, which are collections of queries, SLO panels, and text
panels displayed together.
- name: Burn Alerts
description: >-
Manage burn alerts that notify you when issues impact your SLO budget.
- name: Calculated Fields
description: >-
Manage calculated fields (derived columns) that compute values from
expressions applied to event fields.
- name: Columns
description: >-
Manage columns (fields) in the events you send to Honeycomb datasets.
- name: Dataset Definitions
description: >-
Manage dataset definitions that configure how columns are interpreted and
displayed.
- name: Datasets
description: >-
Manage datasets, which represent collections of related events from the
same source.
- name: Environments
description: >-
Manage environments within a Honeycomb team for separating telemetry data
across stages.
- name: Key Management
description: >-
Manage API keys for a team, including listing, creating, updating, and
deleting keys.
- name: Marker Settings
description: >-
Manage marker settings that group similar markers together with consistent
visual styling.
- name: Markers
description: >-
Manage markers that indicate points in time on graphs where notable events
occurred such as deploys or outages.
- name: Query Annotations
description: >-
Associate names and descriptions to queries for collaboration features.
- name: Recipients
description: >-
Manage notification destinations for triggers and burn alerts including
PagerDuty, Email, Webhook, Microsoft Teams, and Slack.
- name: Reporting
description: >-
Access historical SLO performance reporting data.
- name: Service Maps
description: >-
Visualize relationships between services using dependency requests.
- name: SLOs
description: >-
Define and monitor Service Level Objectives for your organization.
- name: Triggers
description: >-
Configure alerting rules that fire when query results meet specified
conditions.
security:
- ApiKeyAuth: []
paths:
/1/auth:
get:
operationId: getAuth
summary: Authenticate API key
description: >-
Validates authentication for a key and returns the team and environment
that the key belongs to.
tags:
- Auth
responses:
'200':
description: Successful authentication
content:
application/json:
schema:
$ref: '#/components/schemas/AuthInfo'
'401':
description: Unauthorized - invalid API key
/1/auth/permissions:
get:
operationId: listAuthorizations
summary: List authorizations
description: >-
Determines what authorizations have been granted to the API key.
tags:
- Auth
responses:
'200':
description: List of authorizations for the key
content:
application/json:
schema:
$ref: '#/components/schemas/AuthPermissions'
'401':
description: Unauthorized - invalid API key
/1/datasets:
get:
operationId: listDatasets
summary: List all datasets
description: >-
Returns a list of all datasets in the environment associated with the
API key.
tags:
- Datasets
responses:
'200':
description: A list of datasets
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Dataset'
'401':
description: Unauthorized
post:
operationId: createDataset
summary: Create a dataset
description: >-
Creates a dataset in the environment associated with the API key. If a
dataset already exists with that name or slug, the existing dataset is
returned.
tags:
- Datasets
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetCreateRequest'
responses:
'201':
description: Dataset created
content:
application/json:
schema:
$ref: '#/components/schemas/Dataset'
'200':
description: Existing dataset returned
content:
application/json:
schema:
$ref: '#/components/schemas/Dataset'
'401':
description: Unauthorized
/1/datasets/{datasetSlug}:
get:
operationId: getDataset
summary: Get a dataset
description: >-
Returns a single dataset by its slug.
tags:
- Datasets
parameters:
- $ref: '#/components/parameters/datasetSlug'
responses:
'200':
description: Dataset details
content:
application/json:
schema:
$ref: '#/components/schemas/Dataset'
'401':
description: Unauthorized
'404':
description: Dataset not found
put:
operationId: updateDataset
summary: Update a dataset
description: >-
Updates a dataset's properties.
tags:
- Datasets
parameters:
- $ref: '#/components/parameters/datasetSlug'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetUpdateRequest'
responses:
'200':
description: Dataset updated
content:
application/json:
schema:
$ref: '#/components/schemas/Dataset'
'401':
description: Unauthorized
'404':
description: Dataset not found
/1/columns/{datasetSlug}:
get:
operationId: listColumns
summary: List all columns
description: >-
Returns a list of all columns in the specified dataset.
tags:
- Columns
parameters:
- $ref: '#/components/parameters/datasetSlug'
responses:
'200':
description: A list of columns
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Column'
'401':
description: Unauthorized
'404':
description: Dataset not found
post:
operationId: createColumn
summary: Create a column
description: >-
Creates a new column in the specified dataset.
tags:
- Columns
parameters:
- $ref: '#/components/parameters/datasetSlug'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ColumnCreateRequest'
responses:
'201':
description: Column created
content:
application/json:
schema:
$ref: '#/components/schemas/Column'
'401':
description: Unauthorized
'404':
description: Dataset not found
/1/columns/{datasetSlug}/{columnId}:
get:
operationId: getColumn
summary: Get a column
description: >-
Returns a single column by its ID.
tags:
- Columns
parameters:
- $ref: '#/components/parameters/datasetSlug'
- $ref: '#/components/parameters/columnId'
responses:
'200':
description: Column details
content:
application/json:
schema:
$ref: '#/components/schemas/Column'
'401':
description: Unauthorized
'404':
description: Column not found
put:
operationId: updateColumn
summary: Update a column
description: >-
Updates the properties of a column in the specified dataset.
tags:
- Columns
parameters:
- $ref: '#/components/parameters/datasetSlug'
- $ref: '#/components/parameters/columnId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ColumnUpdateRequest'
responses:
'200':
description: Column updated
content:
application/json:
schema:
$ref: '#/components/schemas/Column'
'401':
description: Unauthorized
'404':
description: Column not found
delete:
operationId: deleteColumn
summary: Delete a column
description: >-
Deletes a column from the specified dataset.
tags:
- Columns
parameters:
- $ref: '#/components/parameters/datasetSlug'
- $ref: '#/components/parameters/columnId'
responses:
'204':
description: Column deleted
'401':
description: Unauthorized
'404':
description: Column not found
/1/dataset_definitions/{datasetSlug}:
get:
operationId: getDatasetDefinition
summary: Get dataset definition
description: >-
Returns the dataset definition for the specified dataset, which
configures how columns are interpreted and displayed.
tags:
- Dataset Definitions
parameters:
- $ref: '#/components/parameters/datasetSlug'
responses:
'200':
description: Dataset definition details
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetDefinition'
'401':
description: Unauthorized
'404':
description: Dataset not found
put:
operationId: updateDatasetDefinition
summary: Update dataset definition
description: >-
Updates the dataset definition for the specified dataset.
tags:
- Dataset Definitions
parameters:
- $ref: '#/components/parameters/datasetSlug'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetDefinition'
responses:
'200':
description: Dataset definition updated
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetDefinition'
'401':
description: Unauthorized
'404':
description: Dataset not found
/1/calculated_fields/{datasetSlug}:
get:
operationId: listCalculatedFields
summary: List calculated fields
description: >-
Returns a list of all calculated fields (derived columns) in the
specified dataset.
tags:
- Calculated Fields
parameters:
- $ref: '#/components/parameters/datasetSlug'
responses:
'200':
description: A list of calculated fields
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/CalculatedField'
'401':
description: Unauthorized
post:
operationId: createCalculatedField
summary: Create a calculated field
description: >-
Creates a new calculated field (derived column) in the specified dataset
or across the environment.
tags:
- Calculated Fields
parameters:
- $ref: '#/components/parameters/datasetSlug'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CalculatedFieldCreateRequest'
responses:
'201':
description: Calculated field created
content:
application/json:
schema:
$ref: '#/components/schemas/CalculatedField'
'401':
description: Unauthorized
/1/calculated_fields/{datasetSlug}/{calculatedFieldId}:
get:
operationId: getCalculatedField
summary: Get a calculated field
description: >-
Returns a single calculated field by its ID.
tags:
- Calculated Fields
parameters:
- $ref: '#/components/parameters/datasetSlug'
- $ref: '#/components/parameters/calculatedFieldId'
responses:
'200':
description: Calculated field details
content:
application/json:
schema:
$ref: '#/components/schemas/CalculatedField'
'401':
description: Unauthorized
'404':
description: Calculated field not found
put:
operationId: updateCalculatedField
summary: Update a calculated field
description: >-
Updates the expression or properties of a calculated field.
tags:
- Calculated Fields
parameters:
- $ref: '#/components/parameters/datasetSlug'
- $ref: '#/components/parameters/calculatedFieldId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CalculatedFieldUpdateRequest'
responses:
'200':
description: Calculated field updated
content:
application/json:
schema:
$ref: '#/components/schemas/CalculatedField'
'401':
description: Unauthorized
'404':
description: Calculated field not found
delete:
operationId: deleteCalculatedField
summary: Delete a calculated field
description: >-
Deletes a calculated field from the specified dataset.
tags:
- Calculated Fields
parameters:
- $ref: '#/components/parameters/datasetSlug'
- $ref: '#/components/parameters/calculatedFieldId'
responses:
'204':
description: Calculated field deleted
'401':
description: Unauthorized
'404':
description: Calculated field not found
/1/boards:
get:
operationId: listBoards
summary: List all boards
description: >-
Returns a list of all boards accessible in the current environment.
tags:
- Boards
responses:
'200':
description: A list of boards
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Board'
'401':
description: Unauthorized
post:
operationId: createBoard
summary: Create a board
description: >-
Creates a new board for organizing queries, SLO panels, and text panels.
tags:
- Boards
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BoardCreateRequest'
responses:
'201':
description: Board created
content:
application/json:
schema:
$ref: '#/components/schemas/Board'
'401':
description: Unauthorized
/1/boards/{boardId}:
get:
operationId: getBoard
summary: Get a board
description: >-
Returns a single board by its ID, including all queries and panels.
tags:
- Boards
parameters:
- $ref: '#/components/parameters/boardId'
responses:
'200':
description: Board details
content:
application/json:
schema:
$ref: '#/components/schemas/Board'
'401':
description: Unauthorized
'404':
description: Board not found
put:
operationId: updateBoard
summary: Update a board
description: >-
Updates a board's properties, queries, and panels.
tags:
- Boards
parameters:
- $ref: '#/components/parameters/boardId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BoardUpdateRequest'
responses:
'200':
description: Board updated
content:
application/json:
schema:
$ref: '#/components/schemas/Board'
'401':
description: Unauthorized
'404':
description: Board not found
delete:
operationId: deleteBoard
summary: Delete a board
description: >-
Deletes a board.
tags:
- Boards
parameters:
- $ref: '#/components/parameters/boardId'
responses:
'204':
description: Board deleted
'401':
description: Unauthorized
'404':
description: Board not found
/1/markers/{datasetSlug}:
get:
operationId: listMarkers
summary: List all markers
description: >-
Returns a list of all markers for the specified dataset.
tags:
- Markers
parameters:
- $ref: '#/components/parameters/datasetSlug'
responses:
'200':
description: A list of markers
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Marker'
'401':
description: Unauthorized
post:
operationId: createMarker
summary: Create a marker
description: >-
Creates a new marker on the specified dataset to indicate a point in
time where a notable event occurred.
tags:
- Markers
parameters:
- $ref: '#/components/parameters/datasetSlug'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/MarkerCreateRequest'
responses:
'201':
description: Marker created
content:
application/json:
schema:
$ref: '#/components/schemas/Marker'
'401':
description: Unauthorized
/1/markers/{datasetSlug}/{markerId}:
put:
operationId: updateMarker
summary: Update a marker
description: >-
Updates a marker's properties.
tags:
- Markers
parameters:
- $ref: '#/components/parameters/datasetSlug'
- $ref: '#/components/parameters/markerId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/MarkerUpdateRequest'
responses:
'200':
description: Marker updated
content:
application/json:
schema:
$ref: '#/components/schemas/Marker'
'401':
description: Unauthorized
'404':
description: Marker not found
delete:
operationId: deleteMarker
summary: Delete a marker
description: >-
Deletes a marker from the specified dataset.
tags:
- Markers
parameters:
- $ref: '#/components/parameters/datasetSlug'
- $ref: '#/components/parameters/markerId'
responses:
'204':
description: Marker deleted
'401':
description: Unauthorized
'404':
description: Marker not found
/1/marker_settings/{datasetSlug}:
get:
operationId: listMarkerSettings
summary: List all marker settings
description: >-
Returns a list of all marker settings for the specified dataset.
tags:
- Marker Settings
parameters:
- $ref: '#/components/parameters/datasetSlug'
responses:
'200':
description: A list of marker settings
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/MarkerSetting'
'401':
description: Unauthorized
post:
operationId: createMarkerSetting
summary: Create a marker setting
description: >-
Creates a new marker setting that groups similar markers together with
consistent visual styling.
tags:
- Marker Settings
parameters:
- $ref: '#/components/parameters/datasetSlug'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/MarkerSettingCreateRequest'
responses:
'201':
description: Marker setting created
content:
application/json:
schema:
$ref: '#/components/schemas/MarkerSetting'
'401':
description: Unauthorized
/1/marker_settings/{datasetSlug}/{markerSettingId}:
put:
operationId: updateMarkerSetting
summary: Update a marker setting
description: >-
Updates a marker setting's properties.
tags:
- Marker Settings
parameters:
- $ref: '#/components/parameters/datasetSlug'
- $ref: '#/components/parameters/markerSettingId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/MarkerSettingUpdateRequest'
responses:
'200':
description: Marker setting updated
content:
application/json:
schema:
$ref: '#/components/schemas/MarkerSetting'
'401':
description: Unauthorized
'404':
description: Marker setting not found
delete:
operationId: deleteMarkerSetting
summary: Delete a marker setting
description: >-
Deletes a marker setting from the specified dataset.
tags:
- Marker Settings
parameters:
- $ref: '#/components/parameters/datasetSlug'
- $ref: '#/components/parameters/markerSettingId'
responses:
'204':
description: Marker setting deleted
'401':
description: Unauthorized
'404':
description: Marker setting not found
/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
/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
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
/1/slos/{datasetSlug}:
get:
operationId: listSLOs
summary: List all SLOs
description: >-
Returns a list of all Service Level Objectives for the specified dataset.
tags:
- SLOs
parameters:
- $ref: '#/components/parameters/datasetSlug'
responses:
'200':
description: A list of SLOs
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/SLO'
'401':
description: Unauthorized
post:
operationId: createSLO
summary: Create an SLO
description: >-
Creates a new Service Level Objective for the specified dataset.
tags:
- SLOs
parameters:
- $ref: '#/components/parameters/datasetSlug'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SLOCreateRequest'
responses:
'201':
description: SLO created
content:
application/json:
schema:
$ref: '#/components/schemas/SLO'
'401':
description: Unauthorized
/1/slos/{datasetSlug}/{sloId}:
get:
operationId: getSLO
summary: Get an SLO
description: >-
Returns a single SLO by its ID.
tags:
- SLOs
parameters:
- $ref: '#/components/parameters/datasetSlug'
- $ref: '#/components/parameters/sloId'
responses:
'200':
description: SLO details
content:
application/json:
schema:
$ref: '#/components/schemas/SLO'
'401':
description: Unauthorized
'404':
description: SLO not found
put:
operationId: updateSLO
summary: Update an SLO
description: >-
Updates an SLO's target percentage, time period, or associated query.
tags:
- SLOs
parameters:
- $ref: '#/components/parameters/datasetSlug'
- $ref: '#/components/parameters/sloId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SLOUpdateRequest'
responses:
'200':
description: SLO updated
content:
application/json:
schema:
$ref: '#/components/schemas/SLO'
'401':
description: Unauthorized
'404':
description: SLO not found
delete:
operationId: deleteSLO
summary: Delete an SLO
description: >-
Deletes a Service Level Objective.
tags:
- SLOs
parameters:
- $ref: '#/components/parameters/datasetSlug'
- $ref: '#/components/paramete
# --- truncated at 32 KB (85 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/honeycomb/refs/heads/main/openapi/honeycomb-api-openapi.yml