Query Annotations API | Honeycomb

Honeycomb.io Documentation
  1. Docs
  2. API
  3. Query Annotations API

Query Annotations API

In Honeycomb, users can associate names and descriptions to queries to add additional information in collaboration features. For the purposes of the API, these are called Query Annotations. See Collaborating with your teammates for more on collaboration features.

You can list, create, update, and delete query annotation objects.

In the API, annotations are also used in the Boards API.

Fields on a Query Annotation 

Query Annotation objects have the following assignable fields.

  • name: The name of the query.
  • description: A description of the query.
  • query_id: The query ID for the query that the annotation is describing. Note: Once created, it is NOT possible to change the query ID associated with an annotation. It is possible to have multiple annotations associated with a query.

When a Query Annotation is created or updated, the following fields are assigned. They may not be modified.

  • id: The 6 character hexadecimal ID string is assigned on query annotation creation.
  • created_at: The time the query annotation was created.
  • updated_at: The time of the most recent modification to the query annotation. It is updated every time the query annotation is changed.

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 Queries and Columns permission. Learn more about API keys.

Create a Query Annotation 

Annotations are created by sending a POST request to /1/query_annotations/<DATASET_NAME>.

The annotation body should be a JSON encoded object including as many of the annotation fields as desired. The ID may not be set during creation. name and query_id are required fields for query annotation creation.

When a query annotation is successfully created, the API will respond with HTTP status 201 and will return a JSON object representing that query annotation.

Create Example Request 

An example, creating a query annotation on the TestViaCurl dataset:

curl https://api.honeycomb.io/1/query_annotations/test-via-curl -X POST  \
    -H "X-Honeycomb-Team: YOUR_API_KEY"  \
    -d '{"name":"a named query", "description":"a query description", "query_id":"e4c24a35"}'

Create Example Response  

{
  "created_at": "2016-08-13T05:39:42Z",
  "updated_at": "2016-08-13T05:39:42Z",
  "name": "a named query",
  "description": "a query description",
  "id": "abc3419d",
  "query_id": "e4c24a35"
}

Get a Query Annotation 

A query annotation can be retrieved by sending a GET request to /1/query_annotations/<dataset>/<query_annotation_id>.

Get Example Request 

As an example, this curl request will retrieve the query annotation:

curl https://api.honeycomb.io/1/query_annotations/test-via-curl/abc3419d -X GET  \
    -H "X-Honeycomb-Team: YOUR_API_KEY"

Get Example Response  

{
  "created_at": "2016-08-13T05:39:42Z",
  "updated_at": "2016-08-13T05:39:42Z",
  "name": "a named query",
  "description": "a query description",
  "id": "abc3419d"
}

Update a Query Annotation 

Any of the modifiable fields in a query annotation can be updated by sending a PUT request to /1/query_annotations/<dataset>/<query_annotation_id>.

The PUT request should have as its body a JSON object containing all the user-settable fields for this query annotation, including any updated values. If you do not include an existing field in the payload, it will be erased.

When a query annotation has been successfully updated, the API returns code 200 and the updated query annotation as the body of the response.

Update Example Request 

As an example, this curl request will change the name and description of the query annotation created above:

curl https://api.honeycomb.io/1/query_annotations/test-via-curl/abc3419d -X PUT  \
    -H "X-Honeycomb-Team: YOUR_API_KEY"  \
    -d '{"name":"new name", "description":"new description"}'

Update Example Response  

{
  "created_at": "2016-08-13T05:39:42Z",
  "updated_at": "2016-08-13T05:39:42Z",
  "name": "new name",
  "description": "new description",
  "id": "abc3419d"
}

Delete a Query Annotation 

Query Annotations may be deleted by sending a DELETE request to /1/query_annotations/<dataset>/<annotation_id>.

The body of the DELETE request should be empty.

When the query annotation has been successfully deleted, the API will respond with 200.

Delete Example Request 

As an example, this curl request will delete the query annotation that we created and modified in the previous sections:

curl https://api.honeycomb.io/1/query_annotations/test-via-curl/abc3419d -X DELETE  \
    -H "X-Honeycomb-Team: YOUR_API_KEY"

List All Query Annotations 

All the Query Annotations in a dataset may be retrieved by sending a GET request to /1/query_annotations/<DATASET_NAME>.

A successful response will return HTTP 200 and a JSON list of all query annotation objects for the dataset.

Invalid input will result in a HTTP 422 being returned.

List All Example Request  

curl https://api.honeycomb.io/1/query_annotations/DATASET_NAME \
    -X GET -H "X-Honeycomb-Team: YOUR_API_KEY"

Did you find what you were looking for?

Table of Contents