# Honeycomb API
The API allows programmatic management of many resources within Honeycomb.
Please report any discrepancies with actual API behavior in Pollinators Slack or to Honeycomb Support.
Version: 1.0.0
License: Apache 2.0
## Servers
```
https://api.honeycomb.io
```
```
https://api.eu1.honeycomb.io
```
## Security
### configuration_key
A Honeycomb Configuration Key is required to use this API.
A Configuration Key can be found in the API Keys section of the environment configuration,
which can be found under Environment Settings -> API Keys -> Configuration tab.
Check out our documentation to [find your API Keys](https://docs.honeycomb.io/configure/environments/manage-api-keys/#find-api-keys).
More information can be found in [Manage Environments](https://docs.honeycomb.io/configure/environments/manage-api-keys/).
Type: apiKey
In: header
Name: X-Honeycomb-Team
### ingest_key
A Honeycomb Ingest Key is required to use this API. The Ingest Key is the concatenation of the Ingest Key ID and the Ingest Key Secret.
For security reasons the Ingest Key Secret will only be available during creation of the Ingest Key while the Ingest Key ID will always be available.
More information can be found in [Manage Environments](https://docs.honeycomb.io/configure/environments/manage-api-keys/).
Type: apiKey
In: header
Name: X-Honeycomb-Team
### firehose_access_key
A Honeycomb Ingest Key is recommended for use with this API, though a Configuration key will work.
More information can be found in [Manage Environments](https://docs.honeycomb.io/configure/environments/manage-api-keys/).
Type: apiKey
In: header
Name: X-Amz-Firehose-Access-Key
### bearerAuth
A Honeycomb Management Key is required to use this API.
The token should be passed in the "Authorization" header,
and the secret should be prefixed with "Bearer " followed by the API Key's ID and secret, separated by a colon.
For example, `Authorization: Bearer hcxmk_12345678901234567890123456:12345678901234567890123456789012`
More information can be found in the [Manage API Keys documentation](https://docs.honeycomb.io/configure/teams/manage-api-keys/).
Type: http
Scheme: bearer
Bearer Format: HONEYCOMB_KEY_ID:HONEYCOMB_KEY_SECRET
## Download OpenAPI description
[Honeycomb API](https://api-docs.honeycomb.io/_spec/api.yaml)
## Auth
API Keys have various scopes permissions and belong to a specific Team or Environment.
Any valid Honeycomb ingest or configuration API Key will work with this endpoint. Learn more about [API keys](https://docs.honeycomb.io/get-started/best-practices/api-keys).
These endpoints can be used to validate authentication for a key, to determine what authorizations have been granted
to a key, and to determine the Team and Environment that a key belongs to.
### List Authorizations
- [GET /1/auth](https://api-docs.honeycomb.io/api/auth/getauth.md): Returns metadata about the API Key used to call the API.
Note: a Honeycomb Classic API key will return an empty string for both of the values.
### List Authorizations V2
- [GET /2/auth](https://api-docs.honeycomb.io/api/auth/getv2auth.md): Returns metadata about the Management API Key used to call the API.
## Boards
Boards are a place to pin and save useful queries and graphs you want to retain for later reuse and reference.
This API allows you to list, create, update, and delete Boards.
## Authorization
The API key must have the **Manage Public Boards** permission. Learn more about [API keys here](https://docs.honeycomb.io/configure/environments/manage-api-keys/).
### Create a Board
- [POST /1/boards](https://api-docs.honeycomb.io/api/boards/createboard.md): Create a Board comprised of one or more Queries.
### List All Boards
- [GET /1/boards](https://api-docs.honeycomb.io/api/boards/listboards.md): Retrieves a list of all non-secret Boards within an environment. : For Honeycomb Classic users, all boards within Classic will be returned.
### Get a Board
- [GET /1/boards/{boardId}](https://api-docs.honeycomb.io/api/boards/getboard.md): Get a single Board by ID.
### Update a Board
- [PUT /1/boards/{boardId}](https://api-docs.honeycomb.io/api/boards/updateboard.md): Update a Board by specifying its ID and full details.
: Queries can be added to, removed from, and re-ordered by updating the board itself. It is not possible to reference individual queries via the API.
### Delete a Board
- [DELETE /1/boards/{boardId}](https://api-docs.honeycomb.io/api/boards/deleteboard.md): Delete a public Board by specifying its ID.
## Burn Alerts
This feature is available as part of the [Honeycomb Pro and Enterprise plans](https://www.honeycomb.io/pricing/).
Burn Alerts notify you when issues impact your SLO budget. Learn more about [Burn Alerts here](https://docs.honeycomb.io/notify/alert/slos/monitor/).
This API allows you to list, create, update, and delete burn alerts.
## Authorization
The API key must have the **Manage SLOs** permission. Learn more about [API keys here](https://docs.honeycomb.io/configure/environments/manage-api-keys/).
### Create a Burn Alert
- [POST /1/burn_alerts/{datasetSlug}](https://api-docs.honeycomb.io/api/burn-alerts/createburnalert.md): Create a Burn Alert against a specified SLO.
### List All Burn Alerts for an SLO
- [GET /1/burn_alerts/{datasetSlug}](https://api-docs.honeycomb.io/api/burn-alerts/listburnalertsbyslo.md): Get all burn alerts associated with the SLO specified in the query param. It is not currently possible to retrieve all burn alerts for a dataset, environment, or team.
### Get a Burn Alert
- [GET /1/burn_alerts/{datasetSlug}/{burnAlertId}](https://api-docs.honeycomb.io/api/burn-alerts/getburnalert.md): Get a single Burn Alert by ID.
### Update a Burn Alert
- [PUT /1/burn_alerts/{datasetSlug}/{burnAlertId}](https://api-docs.honeycomb.io/api/burn-alerts/updateburnalert.md): Update a Burn Alert by specifying its ID and full details.
### Delete a Burn Alert
- [DELETE /1/burn_alerts/{datasetSlug}/{burnAlertId}](https://api-docs.honeycomb.io/api/burn-alerts/deleteburnalert.md): Delete a Burn Alert by specifying its ID.
## Columns
Columns are fields in the events you send to Honeycomb.
This API allows you to list, create, update, and delete columns in a dataset.
## Authorization
The API key must have the **Manage Queries and Columns** permission. Learn more about [API keys here](https://docs.honeycomb.io/configure/environments/manage-api-keys/).
### Create a Column
- [POST /1/columns/{datasetSlug}](https://api-docs.honeycomb.io/api/columns/createcolumn.md): Create a column by providing corresponding details for that type.
### List all Columns
- [GET /1/columns/{datasetSlug}](https://api-docs.honeycomb.io/api/columns/listcolumns.md): Get all the Columns in a dataset
### Get a Column
- [GET /1/columns/{datasetSlug}/{columnId}](https://api-docs.honeycomb.io/api/columns/getcolumn.md)
### Update a Column
- [PUT /1/columns/{datasetSlug}/{columnId}](https://api-docs.honeycomb.io/api/columns/updatecolumn.md): Update a column
### Delete a Column
- [DELETE /1/columns/{datasetSlug}/{columnId}](https://api-docs.honeycomb.io/api/columns/deletecolumn.md): Delete a column. : Deleted columns are no longer queryable, but data in existing permalinks (query results and trace views) will remain stored and available at those links.
## Datasets
A Dataset represents a collection of related events that come from the same source, or are related to the same source.
This API allows you to list, create, and update datasets.
## Authorization
The API key must have the **Create Datasets** permission. Learn more about [API keys here](https://docs.honeycomb.io/configure/environments/manage-api-keys/).
### Create a Dataset
- [POST /1/datasets](https://api-docs.honeycomb.io/api/datasets/createdataset.md): Create a Dataset in the environment associated with your API key.
If a Dataset already exists by that name (or slug), then the existing dataset will be returned.
### List All Datasets
- [GET /1/datasets](https://api-docs.honeycomb.io/api/datasets/listdatasets.md): Lists all Datasets for an environment.
: For Honeycomb Classic users, all datasets in Classic are returned.
### Get a Dataset
- [GET /1/datasets/{datasetSlug}](https://api-docs.honeycomb.io/api/datasets/getdataset.md): Get a single Dataset by slug.
### Delete a Dataset
- [DELETE /1/datasets/{datasetSlug}](https://api-docs.honeycomb.io/api/datasets/deletedataset.md): Deletes the Dataset. This is an irreversible operation.
It may take several minutes for the deletion process to complete.
: This endpoint will allow anyone with an API key that has the
manage dataset permission to delete any dataset in the environment (or
any dataset in the whole team for Classic customers).
Datasets with Deletion Protection enabled cannot be deleted.
To delete a Dataset with Deletion Protection enabled, first disable Deletion Protection by updating the Dataset with .
### Update a Dataset
- [PUT /1/datasets/{datasetSlug}](https://api-docs.honeycomb.io/api/datasets/updatedataset.md): Update a Dataset's settings.
## Dataset Definitions
Dataset definitions describe the fields with special meaning in the Dataset.
Refer to the [Dataset Definitions](https://docs.honeycomb.io/configure/datasets/definitions/) documentation for more information.
**Honeycomb automatically creates these Dataset definition fields when the Dataset is created.** Manual creation of Dataset definitions is **not** needed.
## Authorization
The API key must have the **Create Datasets** permission. Learn more about [API keys here](https://docs.honeycomb.io/configure/environments/manage-api-keys/).
### Set or Update Dataset Definitions
- [PATCH /1/dataset_definitions/{datasetSlug}](https://api-docs.honeycomb.io/api/dataset-definitions/patchdatasetdefinitions.md): Set or update one or more definitions for a Dataset.
: While the PATCH payload can include the , Honeycomb does not use this field when updating Dataset Definitions.
### Get all Dataset Definitions
- [GET /1/dataset_definitions/{datasetSlug}](https://api-docs.honeycomb.io/api/dataset-definitions/listdatasetdefinitions.md): Get all definitions for a Dataset.
The response returns an object with a Dataset Definition for each set Dataset Definition type.
## Derived Columns
Calculated Fields (also called Derived Columns) allow you to run queries based on the value of an expression that is derived from the fields in an event.
This API allows you to list, create, update, and delete Calculated Fields in a dataset or across a whole environment, paralleling the behavior of the Schema tab within a Dataset's or Environment's Settings UI.
## Authorization
The API key must have the **Manage Queries and Columns** permission. Learn more about [API keys here](https://docs.honeycomb.io/configure/environments/manage-api-keys/).
### Create a Derived Column
- [POST /1/derived_columns/{datasetSlug}](https://api-docs.honeycomb.io/api/derived-columns/createderivedcolumn.md): Create a Calculated Field (also called a Derived Column). Calculated Fields allow you to run queries based on the value of an expression that is derived from the columns in an event.
### List all Derived Columns
- [GET /1/derived_columns/{datasetSlug}](https://api-docs.honeycomb.io/api/derived-columns/listderivedcolumns.md): Get all the Calculated Fields (also called Derived Columns) in a dataset or environment. With the query parameter, can return a single Calculated Field by its .
### Get a Derived Column
- [GET /1/derived_columns/{datasetSlug}/{derivedColumnId}](https://api-docs.honeycomb.io/api/derived-columns/getderivedcolumn.md)
### Update a Derived Column
- [PUT /1/derived_columns/{datasetSlug}/{derivedColumnId}](https://api-docs.honeycomb.io/api/derived-columns/updatederivedcolumn.md): Update a Calculated Field (also called a Derived Column).
### Delete a Derived Column
- [DELETE /1/derived_columns/{datasetSlug}/{derivedColumnId}](https://api-docs.honeycomb.io/api/derived-columns/deletederivedcolumn.md): Delete a Calculated Field (also called a Derived Column). : A Calculated Field used by a SLO, Trigger, or Board cannot be deleted without removing or modifying the SLO, Trigger, or Board first.
## Events
The Events API endpoints are the lowest-level way to send Events to Honeycomb. **This should be your last resort!**
If unsure where to start when instrumenting an application, read about how to [Send Data to Honeycomb](https://docs.honeycomb.io/send-data/).
If you are building a tracing or metrics library, we recommend using [OpenTelemetry](https://docs.honeycomb.io/send-data/opentelemetry/).
## Authorization
It is recommended that an Ingest API key is used for sending events.
A Configuration API key will work, and must have the **Send Events** permission.
Learn more about [API keys here](https://docs.honeycomb.io/configure/environments/manage-api-keys/).
### Create Events
- [POST /1/batch/{datasetSlug}](https://api-docs.honeycomb.io/api/events/createevents.md): Supports batch creation of events.
Dataset names are case insensitive. requests to "MyDatasET" will land in the same dataset as "mydataset". Names may contain URL-encoded spaces or other special characters, but not URL-encoded slashes. For example, "My%20Dataset" will show up in the UI as "My Dataset".
The first event received for a dataset determines the casing of the displayed name. All subsequent variations in casing will use the originally specified case.
### Create an Event
- [POST /1/events/{datasetSlug}](https://api-docs.honeycomb.io/api/events/createevent.md): Using this endpoint for anything more than testing is highly discouraged.
Sending events in batches will be much more efficient and should be preferred if at all possible.
## Environments
This API allows you to list, create, and update, and delete Environments.
## Authorization
This API requires a Management Key passed via the HTTP Authorization header. Join the key ID and secret with a colon, like this: `Authorization: Bearer :`.
### List all Environments
- [GET /2/teams/{teamSlug}/environments](https://api-docs.honeycomb.io/api/environments/listenvironments.md)
### Create an Environment
- [POST /2/teams/{teamSlug}/environments](https://api-docs.honeycomb.io/api/environments/createenvironment.md)
### Get an Environment
- [GET /2/teams/{teamSlug}/environments/{ID}](https://api-docs.honeycomb.io/api/environments/getenvironment.md)
### Update an Environment
- [PATCH /2/teams/{teamSlug}/environments/{ID}](https://api-docs.honeycomb.io/api/environments/updateenvironment.md)
### Delete an Environment
- [DELETE /2/teams/{teamSlug}/environments/{ID}](https://api-docs.honeycomb.io/api/environments/deleteenvironment.md): This deletes and immediately deactivates the Environment. This is an irreversible operation.
Environments with Deletion Protection enabled cannot be deleted. To delete an Environment with Deletion Protection enabled, first disable Deletion Protection by updating the Environment with .
## Key Management
This API allows you to list, create, update, and delete API Keys for a Team.
Learn more about [API keys here](https://docs.honeycomb.io/configure/environments/manage-api-keys/).
**Note**: currently only Ingest Keys are supported.
## Authorization
This API requires a Management Key passed via the HTTP Authorization header. Join the key ID and secret with a colon, like this: `Authorization: Bearer :`.
### List all API Keys
- [GET /2/teams/{teamSlug}/api-keys](https://api-docs.honeycomb.io/api/key-management/listapikeys.md): List all API Keys for a Team.
: currently only keys of type will be returned.
### Create an API Key
- [POST /2/teams/{teamSlug}/api-keys](https://api-docs.honeycomb.io/api/key-management/createapikey.md): This creates an API Key, which will return the API Key components in the response. The Key ID will be found at and
the Key Secret will be found at . For security reasons the Key Secret will only be available during creation so make sure to save it.
To use a newly-created Ingest Key it should be passed in the header with the API Key's ID and secret
concatenated (and with no separator). For example,
Check out our best practices for API Keys.
### Get an API Key
- [GET /2/teams/{teamSlug}/api-keys/{ID}](https://api-docs.honeycomb.io/api/key-management/getapikey.md): Fetches an API Key.
: currently only keys of type are supported.
### Update an API Key
- [PATCH /2/teams/{teamSlug}/api-keys/{ID}](https://api-docs.honeycomb.io/api/key-management/updateapikey.md): Updates an API Key.
: currently only keys of type are supported.
### Delete an API Key
- [DELETE /2/teams/{teamSlug}/api-keys/{ID}](https://api-docs.honeycomb.io/api/key-management/deleteapikey.md): This deletes and immediately deactivates the API Key. This is an irreversible operation.
: currently only keys of type are supported.
## Kinesis Events
The Kinesis Events API endpoints allow Honeycomb to process streaming events from Amazon Kinesis.
Refer to the [Honeycomb AWS integrations](https://docs.honeycomb.io/integrations/aws/how-aws-integrations-work/) documentation for more information.
## Authorization
It is recommended that an Ingest API key is used for sending events.
A Configuration API key will work, and must have the **Send Events** permission.
Learn more about [API keys here](https://docs.honeycomb.io/configure/environments/manage-api-keys/).
### Create Kinesis Events
- [POST /1/kinesis_events/{datasetSlug}](https://api-docs.honeycomb.io/api/kinesis-events/createkinesisevents.md): This endpoint processes events and metrics coming from AWS through Kinesis Firehose.
## Markers
Markers indicate points in time on graphs where interesting things happen, such as deploys or outages.
This API allows you to list, create, update, and delete Markers.
## Authorization
The API key must have the **Manage Markers** permission. Learn more about [API keys here](https://docs.honeycomb.io/configure/environments/manage-api-keys/).
### Create a Marker
- [POST /1/markers/{datasetSlug}](https://api-docs.honeycomb.io/api/markers/createmarker.md): Create a Marker in the specified dataset. To create an environment marker, use the keyword and an API key associated with the desired environment.
### List All Markers
- [GET /1/markers/{datasetSlug}](https://api-docs.honeycomb.io/api/markers/getmarker.md): Lists all Markers for a dataset.
### Update a Marker
- [PUT /1/markers/{datasetSlug}/{markerId}](https://api-docs.honeycomb.io/api/markers/updatemarker.md): Update a Marker in the specified dataset. To update an environment marker, use the keyword and an API key associated with the desired environment.
### Delete a Marker
- [DELETE /1/markers/{datasetSlug}/{markerId}](https://api-docs.honeycomb.io/api/markers/deletemarker.md)
## Marker Settings
Marker Settings apply to groups of similar Markers.
For example, "deploys" markers appear with the same color on a graph.
This API allows you to list, create, update, and delete Marker Settings.
## Authorization
The API key must have the **Manage Markers** permission. Learn more about [API keys here](https://docs.honeycomb.io/configure/environments/manage-api-keys/).
### Create a Marker Setting
- [POST /1/marker_settings/{datasetSlug}](https://api-docs.honeycomb.io/api/marker-settings/createmarkersetting.md)
### Get a Marker Setting
- [GET /1/marker_settings/{datasetSlug}](https://api-docs.honeycomb.io/api/marker-settings/listmarkersettings.md)
### Update a Marker Setting
- [PUT /1/marker_settings/{datasetSlug}/{markerSettingId}](https://api-docs.honeycomb.io/api/marker-settings/updatemarkersettings.md): A marker setting's may not be changed after creation.
### Delete a Marker Setting
- [DELETE /1/marker_settings/{datasetSlug}/{markerSettingId}](https://api-docs.honeycomb.io/api/marker-settings/deletemarkersettings.md)
## Queries
Queries in Honeycomb are specifications for queries, and are used to identify queries in other parts of the API - in particular: boards, triggers, and query annotations.
This API allows you to create and get query objects.
## Authorization
The API key must have the **Manage Queries and Columns** permission. Learn more about [API keys here](https://docs.honeycomb.io/configure/environments/manage-api-keys/).
### Create a Query
- [POST /1/queries/{datasetSlug}](https://api-docs.honeycomb.io/api/queries/createquery.md): Create a query from a specification. DOES NOT run the query to retrieve results.
### Get a Query
- [GET /1/queries/{datasetSlug}/{queryId}](https://api-docs.honeycomb.io/api/queries/getquery.md): Retrieve a query by its ID.
## Query Annotations
Query Annotations in Honeycomb allow you to associate names and descriptions to queries to add additional information in collaboration features.
This API allows you to list, create, update, and delete Query Annotations.
## Authorization
The API key must have the **Manage Queries and Columns** permission. Learn more about [API keys here](https://docs.honeycomb.io/configure/environments/manage-api-keys/).
### Create a Query Annotation
- [POST /1/query_annotations/{datasetSlug}](https://api-docs.honeycomb.io/api/query-annotations/createqueryannotation.md): Create a Query Annotation for the specified query ID.
### List Query Annotations
- [GET /1/query_annotations/{datasetSlug}](https://api-docs.honeycomb.io/api/query-annotations/listqueryannotations.md): List all Query Annotations in the specified dataset.
### Get a Query Annotation
- [GET /1/query_annotations/{datasetSlug}/{queryAnnotationId}](https://api-docs.honeycomb.io/api/query-annotations/getqueryannotation.md): Get a Query Annotation by its ID.
### Update a Query Annotation
- [PUT /1/query_annotations/{datasetSlug}/{queryAnnotationId}](https://api-docs.honeycomb.io/api/query-annotations/updatequeryannotation.md): Update a Query Annotation by specifying its ID. The Query ID associated with the Query Annotation cannot be updated. Partial updates are not supported.
### Delete a Query Annotation
- [DELETE /1/query_annotations/{datasetSlug}/{queryAnnotationId}](https://api-docs.honeycomb.io/api/query-annotations/deletequeryannotation.md): Delete a Query Annotation by specifying its ID.
## Query Data
This feature is available as part of the [Honeycomb Enterprise plan](https://www.honeycomb.io/pricing/).
Query Results are the aggregated data from a Query, similar to what is displayed in graphs or heatmaps within the Honeycomb UI. Receiving results from a Query is a three-step process:
Create the Query (or Query Spec), which validates that the query parameters are valid. Creating a query does not actually run the query to get results.
Run the query asynchronously by creating a Query Result referencing the Query’s ID. This returns a Query Result ID.
Poll the query result endpoint (with the Query Result ID) until the data is ready.
Note that many Query Results can be created from a single Query. This is particularly useful when using a relative time_range parameter in the Query.
For example, a Query with `time_range: 7200` and no explicit `start_time` or `end_time` can be re-run over and over, with each resulting Query Result containing the most recent 2 hours of data.
This is conceptually similar to clicking Run Query in the Honeycomb UI without changing any query parameters.
**IMPORTANT API RESTRICTIONS:**
To ensure the stability of Honeycomb systems, we have enabled the following API restrictions. These restrictions may change over time.
* Query Results can only be created for events with timestamps within the past 7 days.
* When creating a Query Result, the time ranges from the Query are truncated according to the following rules. For queries with a time range of:
* less than or equal to 6 hours, results are truncated to the nearest 1 minute. For example, a start/end time of 2021-04-22T05:28:12Z will be truncated to 2021-04-22T05:28:00Z.
* greater than 6 hours and less than or equal to 2 days, results are truncated to the nearest 5 minutes. For example, a start/end time of 2021-04-22T05:28:12Z will be truncated to 2021-04-22T05:25:00Z.
* greater than 2 days and less than or equal to 7 days, results are truncated to the nearest 30 minutes. For example, a start/end time of 2021-04-22T05:28:12Z will be truncated to 2021-04-22T05:00:00Z.
* Creating a Query Result is rate limited to 10 requests per minute. Status code 429 will be returned when rate limited.
* Query Results cannot take longer than 10 seconds to run.
## Authorization
The API key must have the **Manage Queries and Columns** and **Run Queries** permission. Learn more about [API keys here](https://docs.honeycomb.io/configure/environments/manage-api-keys/).
### Create a Query Result
- [POST /1/query_results/{datasetSlug}](https://api-docs.honeycomb.io/api/query-data/createqueryresult.md): Kick off processing of a Query to then get back the Query Results.
Once the Query Result has been created, the query will be run asynchronously, allowing the result data to be fetched from the GET query result endpoint.
Only the last 7 days of data can be queried. Any queries with a , , or older than last 7 days will result in a error response.
### Get Query Result
- [GET /1/query_results/{datasetSlug}/{queryResultId}](https://api-docs.honeycomb.io/api/query-data/getqueryresult.md): Get the Query Result details for a specific Query Result ID.
This endpoint is used to fetch the results of a query that had previously been created. It is recommended to follow the Location header included in the Create Query Result output, but the URL can also be constructed manually with the <query-result-id>.
## Recipients
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/).
### Create a Recipient
- [POST /1/recipients](https://api-docs.honeycomb.io/api/recipients/createrecipient.md): 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 fields will vary depending on the of Recipient. Use the drop-down to view the specific fields for each value.
Before Slack Recipients can be created, the Slack OAuth flow in the Integration Center must be completed.
### List all Recipients
- [GET /1/recipients](https://api-docs.honeycomb.io/api/recipients/listrecipients.md): Retrieve all recipients for a team.
### Get a single Recipient
- [GET /1/recipients/{recipientId}](https://api-docs.honeycomb.io/api/recipients/getrecipient.md): Retrieve a Recipient by recipient ID.
### Update a Recipient
- [PUT /1/recipients/{recipientId}](https://api-docs.honeycomb.io/api/recipients/updaterecipient.md): 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.
: Modifying an existing recipient will change the destination of all triggers/burn alerts that use that recipient.
### Delete a Recipient
- [DELETE /1/recipients/{recipientId}](https://api-docs.honeycomb.io/api/recipients/deleterecipient.md): 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.
## Reporting
The Reporting API provides access to historical performance data.
## Authorization
The API key must have the **Manage SLOs** permission. Learn more about [API keys here](https://docs.honeycomb.io/configure/environments/manage-api-keys/).
### Get SLO History
- [POST /1/reporting/slos/historical](https://api-docs.honeycomb.io/api/reporting/getslohistory.md): Get a weekly breakdown of historical data for a list of SLOs for a given time range.
## Service Maps
The Service Maps API endpoints allow you to visualize the relationships between your services in Honeycomb.
This API allows you to create and retrieve service Dependency Requests, which are used to generate maps of dependencies between services.
## Authorization
The API key must have the **Read Service Maps** permission. Learn more about [API keys here](https://docs.honeycomb.io/configure/environments/manage-api-keys/).
### Create a Map Dependency Request
- [POST /1/maps/dependencies/requests](https://api-docs.honeycomb.io/api/service-maps/createmapdependencyrequest.md): Create a Map Dependency Request.
### Get Map Dependencies
- [GET /1/maps/dependencies/requests/{requestId}](https://api-docs.honeycomb.io/api/service-maps/getmapdependencies.md): Get the dependencies for a previously created Map Dependencies Request.
## SLOs
This feature is available as part of the [Honeycomb Pro and Enterprise plans](https://www.honeycomb.io/pricing).
Honeycomb SLOs allow you to define and monitor Service Level Objectives (SLOs) for your organization.
This API allows you to list, create, update, and delete SLO objects.
You can also access historical reporting for your SLOs to analyze long-term performance trends. For more information, see [Get SLO History](https://api-docs.honeycomb.io/api/reporting/getslohistory)
## Authorization
The API key must have the **Manage SLOs** permission. Learn more about [API keys here](https://docs.honeycomb.io/configure/environments/manage-api-keys/).
### Create an SLO
- [POST /1/slos/{datasetSlug}](https://api-docs.honeycomb.io/api/slos/createslo.md): Create an SLO on the provided dataset.
### Get all SLOs
- [GET /1/slos/{datasetSlug}](https://api-docs.honeycomb.io/api/slos/listslos.md): Get all SLOs for a dataset or environment (using ). This action returns any SLOs, including those applied with multiple datasets.
### Get an SLO
- [GET /1/slos/{datasetSlug}/{sloId}](https://api-docs.honeycomb.io/api/slos/getslo.md): Get an SLO by ID.
### Update an SLO
- [PUT /1/slos/{datasetSlug}/{sloId}](https://api-docs.honeycomb.io/api/slos/updateslo.md): Update an SLO by specifying its ID and full SLO details.
### Delete an SLO
- [DELETE /1/slos/{datasetSlug}/{sloId}](https://api-docs.honeycomb.io/api/slos/deleteslo.md): Delete an SLO by specifying its ID.
## Triggers
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.
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/).
### List All Triggers
- [GET /1/triggers/{datasetSlug}](https://api-docs.honeycomb.io/api/triggers/listtriggers.md): List all triggers on the provided dataset or environment.
### Create a Trigger
- [POST /1/triggers/{datasetSlug}](https://api-docs.honeycomb.io/api/triggers/createtrigger.md): Create a trigger on the provided dataset or environment.
### Get a Trigger
- [GET /1/triggers/{datasetSlug}/{triggerId}](https://api-docs.honeycomb.io/api/triggers/gettrigger.md): Fetch details for a single Trigger by Trigger ID.
### Update a Trigger
- [PUT /1/triggers/{datasetSlug}/{triggerId}](https://api-docs.honeycomb.io/api/triggers/updatetrigger.md): Update a trigger by specifying the trigger ID and the same fields used when creating a new trigger.
### Delete a Trigger
- [DELETE /1/triggers/{datasetSlug}/{triggerId}](https://api-docs.honeycomb.io/api/triggers/deletetrigger.md): Delete a trigger by specifying the trigger ID. The body of the DELETE request should be empty.
### Get Triggers Associated with a Recipient
- [GET /1/recipients/{recipientId}/triggers](https://api-docs.honeycomb.io/api/triggers/listtriggerswithrecipient.md): List all triggers that will alert a given Recipient. 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.