Boards API

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.)

Fields on a Board

A Board consists of a name, description, and a list of zero or more queries.

name: (required) the board’s name displayed in the UI
description: displayed on the board page itself
style: 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 board
- graph_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
- 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 documentation
- dataset: 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.

Notes

All the datasets used in queries on a board must be within the Environment associated with the API key making the request.

In Honeycomb Classic, boards are limited to queries within the Classic section of Honeycomb.

When a board is read from the API, it will also contain its honeycomb-assigned id field. This field is optional when updating the board via PUT.
Currently, all non-limited-access boards are visible and editable via the API. Boards created by the API have no creator and cannot be assigned collaborators, so they can only be edited and deleted via the API.
Limited-access boards are not visible via the API in any form.
Boards created via API will be visible in the “Boards from your Team” list.
Boards created via UI, but modified via API, will retain their original owner and collaborators.
There is a maximum of 1000 boards per team, including limited-access boards.

Authorization and Headers

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.

Create a Board

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.

Create Example Request

Create a Board Using a Query ID

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
      }
    }
  ]
}'

Create a Board Using an Inline Query

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"
    }
  ]
}'

Create 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",
      "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"
}

Retrieve a Board

GETting a board via API should return the same response as upon board creation via POST.

Retrieve Example Request

curl https://api.honeycomb.io/1/boards/2NeeaE9bBLd \
    -H "X-Honeycomb-Team: YOUR_API_KEY"

Retrieve 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",
      "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"
}

Update a Board

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.

Update 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",
      "graph_settings": {
        "utc_xaxis": true,
        "hide_markers": true
      },
      "dataset": "API Test",
      "query_id": "abc3419d",
      "query_annotation_id": "e4c24a35"
    }
  ]
}'

Update 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",
      "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"
}

Delete a Board

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.

Delete Example Request

curl https://api.honeycomb.io/1/boards/2NeeaE9bBLd -X DELETE \
    -H "X-Honeycomb-Team: YOUR_API_KEY"

Delete Example Response

# DELETE returns HTTP 204: No Content

List All Boards

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.