Honeycomb Query Annotations API

openapi: 3.1.0
info:
  title: Honeycomb Auth Query Annotations API
  version: 1.0.0
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  contact:
    email: support@honeycomb.io
  description: 'The API allows programmatic management of many resources within Honeycomb.


    Please report any discrepancies with actual API behavior in <a href="https://docs.honeycomb.io/troubleshoot/community/">Pollinators Slack</a> or to <a href="https://support.honeycomb.io/">Honeycomb Support</a>.

    '
servers:
- url: https://api.honeycomb.io
- url: https://api.eu1.honeycomb.io
tags:
- name: Query Annotations
  description: 'Query Annotations in Honeycomb allow you to associate names and descriptions to queries to add additional information in collaboration features.


    This API allows you to list, create, update, and delete Query Annotations.


    ## Authorization


    The API key must have the **Manage Queries and Columns** permission. Learn more about [API keys here](https://docs.honeycomb.io/configure/environments/manage-api-keys/).

    '
paths:
  /1/query_annotations/{datasetSlug}:
    parameters:
    - $ref: '#/components/parameters/datasetSlugOrAll'
    post:
      security:
      - configuration_key: []
      summary: Create a Query Annotation
      description: 'Create a Query Annotation for the specified query ID.

        '
      tags:
      - Query Annotations
      operationId: createQueryAnnotation
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QueryAnnotation'
        required: true
      responses:
        '201':
          description: Created
          headers:
            Ratelimit:
              $ref: '#/components/headers/RateLimit'
            RateLimitPolicy:
              $ref: '#/components/headers/RateLimitPolicy'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryAnnotation'
        '400':
          description: Bad Request
          headers:
            Ratelimit:
              $ref: '#/components/headers/RateLimit'
            RateLimitPolicy:
              $ref: '#/components/headers/RateLimitPolicy'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid-query-id:
                  description: The query ID is invalid.
                  value:
                    error: Query ID included in body is invalid
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        default:
          $ref: '#/components/responses/GenericError'
    get:
      security:
      - configuration_key: []
      summary: List Query Annotations
      description: 'List all Query Annotations in the specified dataset.

        '
      tags:
      - Query Annotations
      operationId: listQueryAnnotations
      parameters:
      - name: include_board_annotations
        in: query
        description: 'Whether to include Query Annotations that were created from boards. By default, only Query Annotations created directly from queries are returned.

          '
        schema:
          type: boolean
          default: false
        required: false
      responses:
        '200':
          description: Success
          headers:
            Ratelimit:
              $ref: '#/components/headers/RateLimit'
            RateLimitPolicy:
              $ref: '#/components/headers/RateLimitPolicy'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/QueryAnnotation'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        default:
          $ref: '#/components/responses/GenericError'
  /1/query_annotations/{datasetSlug}/{queryAnnotationId}:
    parameters:
    - $ref: '#/components/parameters/datasetSlugOrAll'
    - name: queryAnnotationId
      description: The unique identifier (ID) of the annotation.
      in: path
      required: true
      schema:
        type: string
    get:
      security:
      - configuration_key: []
      summary: Get a Query Annotation
      description: 'Get a Query Annotation by its ID.

        '
      tags:
      - Query Annotations
      operationId: getQueryAnnotation
      responses:
        '200':
          description: Success
          headers:
            Ratelimit:
              $ref: '#/components/headers/RateLimit'
            RateLimitPolicy:
              $ref: '#/components/headers/RateLimitPolicy'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryAnnotation'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        default:
          $ref: '#/components/responses/GenericError'
    put:
      security:
      - configuration_key: []
      summary: Update a Query Annotation
      description: 'Update a Query Annotation by specifying its ID. The Query ID associated with the Query Annotation cannot be updated. Partial updates are not supported.

        '
      tags:
      - Query Annotations
      operationId: updateQueryAnnotation
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QueryAnnotation'
            example:
              name: My Updated Annotation
              description: A nice description of My Update Annotation
              query_id: mabAMpSPDjH
              id: sGUnkBHgRFN
              created_at: '2022-10-26T21:36:04Z'
              updated_at: '2022-12-16T10:44:08Z'
        required: true
      responses:
        '200':
          description: Success
          headers:
            Ratelimit:
              $ref: '#/components/headers/RateLimit'
            RateLimitPolicy:
              $ref: '#/components/headers/RateLimitPolicy'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryAnnotation'
              example:
                name: My Updated Annotation
                description: A nice description of My Update Annotation
                query_id: mabAMpSPDjH
        '400':
          description: Bad Request
          headers:
            Ratelimit:
              $ref: '#/components/headers/RateLimit'
            RateLimitPolicy:
              $ref: '#/components/headers/RateLimitPolicy'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                update-includes-bad-id:
                  description: The ID in the URL and the ID in the request body do not match.
                  value:
                    error: Query annotation id included in body does not match URL
                invalid-query-id:
                  description: The query ID is invalid.
                  value:
                    error: Query id included in body is invalid
                cannot-update-query-id:
                  description: The query ID cannot be updated.
                  value:
                    error: queries in annotations cannot be changed
                query-not-in-dataset:
                  description: The query ID does not exist in the specified dataset.
                  value:
                    error: Query is not in the dataset
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        default:
          $ref: '#/components/responses/GenericError'
    delete:
      security:
      - configuration_key: []
      summary: Delete a Query Annotation
      description: 'Delete a Query Annotation by specifying its ID.

        '
      tags:
      - Query Annotations
      operationId: deleteQueryAnnotation
      responses:
        '204':
          description: Success - no content
          headers:
            Ratelimit:
              $ref: '#/components/headers/RateLimit'
            RateLimitPolicy:
              $ref: '#/components/headers/RateLimitPolicy'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        default:
          $ref: '#/components/responses/GenericError'
components:
  headers:
    RateLimitPolicy:
      description: "The (draft07) recommended header from the IETF on rate limiting.\nThe value of the header is formatted \"X;w=Y\".\nWhere:\n - X is the maximum number of requests allowed in a window\n - Y is the size of the window in seconds\n"
      schema:
        type: string
      example: 100;w=60
    RateLimit:
      description: "The (draft07) recommended header from the IETF on rate limiting.\nThe value of the header is formatted \"limit=X, remaining=Y, reset=Z\".\nWhere:\n  - X is the maximum number of requests allowed in the window\n  - Y is the number of requests remaining in the window\n  - Z is the number of seconds until the limit resets\n"
      schema:
        type: string
      example: limit=100, remaining=50, reset=60
    RetryAfter:
      description: 'The RFC7231 header used to indicate when a client should retry requests.

        '
      schema:
        type: string
      example: Fri, 22 Mar 2024 18:37:53 GMT
  responses:
    GenericError:
      description: Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            deny-management-apis:
              description: Team cannot access management APIs.
              value:
                error: Your team has been denied access to Management APIs, please contact support to be unblocked.
        application/problem+json:
          schema:
            $ref: '#/components/schemas/DetailedError'
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/JSONAPIError'
    RateLimited:
      description: Rate Limit Exceeded
      headers:
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
        Ratelimit:
          $ref: '#/components/headers/RateLimit'
        RateLimitPolicy:
          $ref: '#/components/headers/RateLimitPolicy'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Rate Limited
        application/problem+json:
          schema:
            $ref: '#/components/schemas/DetailedError'
          example:
            status: 429
            type: https://api.honeycomb.io/problems/rate-limited
            title: You have exceeded your rate limit.
            error: You have exceeded your rate limit.
            detail: Please try again after 2025-02-01T15:23:12Z.
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/JSONAPIError'
          example:
            errors:
            - id: 06dcdd6508ca822f0e7e2bb4121c1f52
              code: rate-limited/may-retry
              title: request rate limit exceeded
              detail: Please try again after 2025-02-01T15:23:12Z.
    NotFound:
      description: Not Found
      headers:
        Ratelimit:
          $ref: '#/components/headers/RateLimit'
        RateLimitPolicy:
          $ref: '#/components/headers/RateLimitPolicy'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: dataset not found
        application/problem+json:
          schema:
            $ref: '#/components/schemas/DetailedError'
          example:
            status: 404
            type: https://api.honeycomb.io/problems/not-found
            title: The requested resource cannot be found.
            error: Dataset not found
            detail: Dataset not found
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/JSONAPIError'
  parameters:
    datasetSlugOrAll:
      name: datasetSlug
      description: 'The dataset slug or use `__all__` for endpoints that support environment-wide operations.

        '
      in: path
      required: true
      schema:
        type: string
  schemas:
    QueryAnnotation:
      type: object
      description: A Query Annotation consists of a name and description associated with a query to add context when collaborating.
      required:
      - name
      - query_id
      properties:
        name:
          type: string
          description: A name for the Query.
          example: My Named Query
          minLength: 1
          maxLength: 320
        description:
          type: string
          description: A description of the Query.
          example: A nice description of My Named Query
          maxLength: 1023
        query_id:
          type: string
          description: 'The ID of the Query that the annotation describes. **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.

            '
          example: mabAMpSPDjH
        id:
          type: string
          description: The unique identifier (ID) of a Query Annotation.
          readOnly: true
          example: sGUnkBHgRFN
        created_at:
          type: string
          format: date-time
          description: ISO8601 formatted time when the Query Annotation was created.
          example: '2022-10-26T21:36:04Z'
          readOnly: true
        updated_at:
          type: string
          format: date-time
          description: ISO8601 formatted time when the Query Annotation was updated.
          example: '2022-12-04T08:14:26Z'
          readOnly: true
        source:
          type: string
          description: The source of the Query Annotation.
          example: query
          enum:
          - query
          - board
          readOnly: true
    DetailedError:
      x-tags:
      - Errors
      description: An RFC7807 'Problem Detail' formatted error message.
      type: object
      required:
      - error
      - status
      - type
      - title
      properties:
        error:
          type: string
          readOnly: true
          default: something went wrong!
        status:
          type: number
          readOnly: true
          description: The HTTP status code of the error.
        type:
          type: string
          readOnly: true
          description: Type is a URI used to uniquely identify the type of error.
        title:
          type: string
          readOnly: true
          description: Title is a human-readable summary that explains the `type` of the problem.
        detail:
          type: string
          readOnly: true
          description: The general, human-readable error message.
        instance:
          type: string
          readOnly: true
          description: The unique identifier (ID) for this specific error.
    JSONAPIError:
      x-tags:
      - Errors
      type: object
      description: A JSONAPI-formatted error message.
      properties:
        errors:
          type: array
          items:
            type: object
            readOnly: true
            required:
            - id
            - code
            properties:
              id:
                type: string
                readOnly: true
              status:
                type: string
                readOnly: true
              code:
                type: string
                readOnly: true
              title:
                type: string
                readOnly: true
              detail:
                type: string
                readOnly: true
              source:
                type: object
                readOnly: true
                properties:
                  pointer:
                    type: string
                    readOnly: true
                  header:
                    type: string
                    readOnly: true
                  parameter:
                    type: string
                    readOnly: true
    Error:
      x-tags:
      - Errors
      type: object
      description: A legacy error, containing only a textual description.
      properties:
        error:
          type: string
          readOnly: true
externalDocs:
  url: https://docs.honeycomb.io