The Boards API is for creating, reading, modifying, or deleting public Honeycomb Boards via API. All requests should be made via HTTPS to api.honeycomb.io
.
The API is permitted to manipulate Boards as if it was any other member of your team. (See our Roles and Permissions documentation for more details.)
A Board consists of a name
, description
, and a list of zero or more queries
.
name
: (required) the board’s name displayed in the UIdescription
: displayed on the board page itselfstyle
: how the board should be displayed in the UI; one of "list"
(the default) or "visual"
. (See our Boards documentation for more details.)column_layout
: the number of columns to layout on the board; one of "multi"
(the default) or "single"
.queries
: a list of queries to display on the board, in the order of appearance:
caption
: descriptive text to contextualize the query’s value within this boardgraph_settings
: a map of boolean toggles to control the display settings for this query on the board.
If a value is unspecified, it is assumed to be false
(the default).
The currently supported toggles are:
hide_markers
log_scale
omit_missing_values
stacked_graphs
utc_xaxis
overlaid_charts
query_style
: how the query should be displayed on the board; one of "graph"
(the default), "table"
or "combo"
meaning table and graph together. See more about query styles in our Boards documentationdataset
: the dataset to query. Required when using the deprecated query
. Note: This field can take either the name
(“My Dataset”) or slug
(“my-dataset”); the response will always use the name
.query_id
- the ID of a query object. Cannot be used with query
. Query IDs can be retrieved from the UI or from the Query API.query
- (deprecated) an inline Query Specification. Cannot be used with query_id
.query_annotation_id
: The ID of a query annotation object that provides a name and description for the query. The query annotation must apply to the query_id
or query
specified.Environment-wide queries work only with queries specified by query_id
.
In Honeycomb Classic, boards are limited to queries within the Classic section of Honeycomb.
id
field. This field is optional when updating the board via PUT.
The only expected header is X-Honeycomb-Team
, which is your API key, and it is required.
The API key must have the Manage Public Boards permission.
Learn more about API keys.
POST
a single board definition to Honeycomb, and receive the created board definition, including its new "id"
, as a response.
The body of the POST
should be a JSON encoded object containing key/value pairs. ID may not be set during creation.
A successful response will return HTTP 201
and the Location
header will contain the URL to the new Board resource.
Invalid input will result in a HTTP 422
being returned.
curl https://api.honeycomb.io/1/boards -X POST \
-H "X-Honeycomb-Team: YOUR_API_KEY" \
-d '
{
"name": "My board",
"description": "A board created via the API",
"style": "visual",
"queries": [
{
"caption": "context for this query on this board",
"query_style": "table",
"query_id": "abc1234e",
"query_annotation_id": "e4c24a35",
"graph_settings": {
"utc_xaxis": true,
"hide_markers": true
}
}
]
}'
Note: this method is deprecated.
curl https://api.honeycomb.io/1/boards -X POST \
-H "X-Honeycomb-Team: YOUR_API_KEY" \
-d '
{
"name": "My board",
"description": "A board created via the API",
"style": "visual",
"queries": [
{
"caption": "context for this query on this board",
"query_style": "table",
"dataset": "API Test",
"graph_settings": {
"stacked_graphs": true,
"utc_xaxis": true
},
"query":{
"breakdowns": [
"method",
"endpoint"
],
"calculations": [
{"column": "duration_ms", "op": "AVG"},
{"column": "duration_ms", "op": "P99"}
],
"filters": [
{"column": "shard", "op": "=", "value": "users"}
],
"orders": [
{"column": "duration_ms", "op": "P99"},
{"column": "endpoint"}
],
"limit": 10,
"time_range": 3600
},
"query_annotation_id": "e4c24a35"
}
]
}'
{
"name": "My board",
"description": "A board created via the API",
"style": "visual",
"queries": [
{
"caption": "context for this query on this board",
"query_style": "table",
"graph_settings": {
"stacked_graphs": true,
"utc_xaxis": true
},
"dataset": "API Test",
"query_id": "abc3419d",
"query_annotation_id": "e4c24a35"
}
],
"links": {
"board_url": "https://ui.honeycomb.io/myteam/environments/myenvironment/board/2NeeaE9bBLd"
},
"id": "2NeeaE9bBLd"
}
GET
ting a board via API should return the same response as upon board creation via POST
.
curl https://api.honeycomb.io/1/boards/2NeeaE9bBLd \
-H "X-Honeycomb-Team: YOUR_API_KEY"
{
"name": "My board",
"description": "A board created via the API",
"style": "list",
"queries": [
{
"caption": "context for this query on this board",
"query_style": "table",
"graph_settings": {
"hide_markers": true,
"utc_xaxis": true
},
"dataset": "API Test",
"query_id": "abc3419d",
"query_annotation_id": "e4c24a35"
}
],
"links": {
"board_url": "https://ui.honeycomb.io/myteam/environments/myenvironment/board/2NeeaE9bBLd"
},
"id": "2NeeaE9bBLd"
}
Queries can be added to, removed from, and re-ordered within a board by updating the board itself. It is not possible to reference individual queries via the API.
curl https://api.honeycomb.io/1/boards/2NeeaE9bBLd -X PUT \
-H "X-Honeycomb-Team: YOUR_API_KEY" \
-d '
{
"name":"Updated board",
"description":"A board created via the API",
"style":"visual",
"queries": [
{
"caption": "updated context for this query on this board",
"query_style": "combo",
"graph_settings": {
"utc_xaxis": true,
"hide_markers": true
},
"dataset": "API Test",
"query_id": "abc3419d",
"query_annotation_id": "e4c24a35"
}
]
}'
{
"name": "Updated board",
"description": "A board created via the API",
"style": "visual",
"queries": [
{
"caption": "updated context for this query on this board",
"query_style": "combo",
"graph_settings": {
"hide_markers": true,
"utc_xaxis": true
},
"dataset": "API Test",
"query_id": "abc3419d",
"query_annotation_id": "e4c24a35"
}
],
"links": {
"board_url": "https://ui.honeycomb.io/myteam/environments/myenvironment/board/2NeeaE9bBLd"
},
"id": "2NeeaE9bBLd"
}
You may delete any public board via API. API permissions around manipulating Boards behave like any other member of your team. (See our Roles and Permissions for more details.)
A successful DELETE
response will a HTTP 204
status code.
curl https://api.honeycomb.io/1/boards/2NeeaE9bBLd -X DELETE \
-H "X-Honeycomb-Team: YOUR_API_KEY"
# DELETE returns HTTP 204: No Content
All non-secret Boards within an environment may be retrieved by sending a GET
request to /1/boards/
.
A successful response will return HTTP 200
and a JSON list of all Board objects for the environment.
In Honeycomb Classic, all boards within Classic will be returned.
Invalid input will result in a HTTP 422
being returned.
curl https://api.honeycomb.io/1/boards \
-H "X-Honeycomb-Team: YOUR_API_KEY"
Did you find what you were looking for?