Boards API

Using the Boards API for the Kubernetes Starter Pack

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.)
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
- dataset: (required) the dataset to query
- query: (required) a Query Specification

Notes

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.

Headers

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.

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.

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",
      "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",
      "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.

Retrieve a Board

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

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.

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

Delete a Board

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.

List all Boards

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.