We use cookies or similar technologies to personalize your online experience and tailor marketing to you. Many of our product features require cookies to function properly. Your use of this site and online product constitutes your consent to these personalization technologies. Read our Privacy Policy to find out more.

X

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.

Notes

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.