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.)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 boardquery_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
: (required) the dataset to query. Note: This field can take either the name
(“My Dataset”) or slug
(“my-dataset”); the response will always use the name
.query
: (required) a Query Specificationid
field. This field is optional when updating the board via PUT.The only expected header is X-Honeycomb-Team
, which is your Team API key. It is required.
Boards are considered a separate resource from our Events, Markers, or Triggers APIs.
To use this API, you may want to modify an existing key to be able to access Boards or create a new Boards-only key.
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.
Example Request
$ 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": "APITest",
"query":{
"breakdowns": [
"method",
"endpoint"
],
"calculations": [
{"column": "dur_ms", "op": "AVG"},
{"column": "dur_ms", "op": "P99"}
],
"filters": [
{"column": "shard", "op": "=", "value": "users"}
],
"orders": [
{"column": "dur_ms", "op": "P99"},
{"column": "endpoint"}
],
"limit": 10,
"time_range": 3600
}
}
]
}'
Example Response
{
"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":"APITest",
"query":{
"breakdowns":["method","endpoint"],
"calculations":[{"column":"dur_ms","op":"AVG"},{"column":"dur_ms","op":"P99"}],
"filters":[{"column":"shard","op":"=","value":"users"}],
"orders":[{"column":"dur_ms","op":"P99"},{"column":"endpoint"}],
"limit":10,
"time_range":3600
}
}
],
"id":"2NeeaE9bBLd"
}
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.
GET
ting a board via API should return the same response as upon board creation via POST
.
Example Request
$ curl https://api.honeycomb.io/1/boards/2NeeaE9bBLd \
-H "X-Honeycomb-Team: YOUR_API_KEY"
Example Response
{
"name":"My board",
"description":"A board created via the API",
"style":"list",
"queries":[
{
"caption": "context for this query on this board",
"query_style": "table",
"dataset":"APITest",
"query":{
"breakdowns":["method","endpoint"],
"calculations":[{"column":"dur_ms","op":"AVG"},{"column":"dur_ms","op":"P99"}],
"filters":[{"column":"shard","op":"=","value":"users"}],
"orders":[{"column":"dur_ms","op":"P99"},{"column":"endpoint"}],
"limit":10,
"time_range":3600
}
}
],
"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.
Example Request
$ 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",
"dataset": "APITest",
"query":{
"breakdowns": [
"method",
"endpoint"
],
"calculations": [
{"column": "dur_ms", "op": "AVG"},
{"column": "dur_ms", "op": "P99"}
],
"filters": [
{"column": "shard", "op": "=", "value": "users"}
],
"orders": [
{"column": "dur_ms", "op": "P99"},
{"column": "endpoint"}
],
"limit": 10,
"time_range": 3600
}
}
]
}'
Example Response
{
"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",
"dataset":"APITest",
"query":{
"breakdowns":["method","endpoint"],
"calculations":[{"column":"dur_ms","op":"AVG"},{"column":"dur_ms","op":"P99"}],
"filters":[{"column":"shard","op":"=","value":"users"}],
"orders":[{"column":"dur_ms","op":"P99"},{"column":"endpoint"}],
"limit":10,
"time_range":3600
}
}
],
"id":"2NeeaE9bBLd"
}
API permissions around manipulating Boards behave like any other member of your team. (See our Roles and Permissions for more details.) You may delete any public board via API.
Example Request
$ curl https://api.honeycomb.io/1/boards/2NeeaE9bBLd -X DELETE \
-H "X-Honeycomb-Team: YOUR_API_KEY"
Example Response
# DELETE returns HTTP 204: No Content
A successful DELETE
response will a HTTP 204
status code.
All non-secret Boards for a team may be retrieved by sending a GET
request to /1/boards/
Example Request
$ curl https://api.honeycomb.io/1/boards \
-H "X-Honeycomb-Team: YOUR_API_KEY"
A successful response will return HTTP 200
and a JSON list of all Board objects for the team.
Invalid input will result in a HTTP 422
being returned.