honeycomb Query Annotations API

openapi: 3.2.0
info:
  title: Honeycomb Query Annotations API
  version: '1.0'
  description: 'Operations tagged Query Annotations across 2 of this provider''s published API definitions: honeycomb-api-openapi.yml, honeycomb-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.honeycomb.io
  description: Honeycomb Production API
- url: https://api.eu1.honeycomb.io
tags:
- name: Query Annotations
  description: Associate names and descriptions to queries for collaboration features.
paths:
  /1/query_annotations/{datasetSlug}:
    get:
      operationId: listQueryAnnotations
      summary: List query annotations
      description: Returns a list of all query annotations for the specified dataset.
      tags:
      - Query Annotations
      parameters:
      - $ref: '#/components/parameters/datasetSlug'
      responses:
        '200':
          description: A list of query annotations
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/QueryAnnotation'
        '401':
          description: Unauthorized
      security:
      - ApiKeyAuth: []
    post:
      operationId: createQueryAnnotation
      summary: Create a query annotation
      description: Creates a new query annotation to associate a name and description to a query for collaboration.
      tags:
      - Query Annotations
      parameters:
      - $ref: '#/components/parameters/datasetSlug'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QueryAnnotationCreateRequest'
      responses:
        '201':
          description: Query annotation created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryAnnotation'
        '401':
          description: Unauthorized
      security:
      - ApiKeyAuth: []
    parameters:
    - $ref: '#/components/parameters/datasetSlugOrAll'
    servers:
    - url: https://api.honeycomb.io
      description: Honeycomb Production API
  /1/query_annotations/{datasetSlug}/{queryAnnotationId}:
    get:
      operationId: getQueryAnnotation
      summary: Get a query annotation
      description: Returns a single query annotation by its ID.
      tags:
      - Query Annotations
      parameters:
      - $ref: '#/components/parameters/datasetSlug'
      - $ref: '#/components/parameters/queryAnnotationId'
      responses:
        '200':
          description: Query annotation details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryAnnotation'
        '401':
          description: Unauthorized
        '404':
          description: Query annotation not found
      security:
      - ApiKeyAuth: []
    put:
      operationId: updateQueryAnnotation
      summary: Update a query annotation
      description: Updates a query annotation's name or description.
      tags:
      - Query Annotations
      parameters:
      - $ref: '#/components/parameters/datasetSlug'
      - $ref: '#/components/parameters/queryAnnotationId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QueryAnnotationUpdateRequest'
      responses:
        '200':
          description: Query annotation updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryAnnotation'
        '401':
          description: Unauthorized
        '404':
          description: Query annotation not found
      security:
      - ApiKeyAuth: []
    delete:
      operationId: deleteQueryAnnotation
      summary: Delete a query annotation
      description: Deletes a query annotation.
      tags:
      - Query Annotations
      parameters:
      - $ref: '#/components/parameters/datasetSlug'
      - $ref: '#/components/parameters/queryAnnotationId'
      responses:
        '204':
          description: Query annotation deleted
        '401':
          description: Unauthorized
        '404':
          description: Query annotation not found
      security:
      - ApiKeyAuth: []
    parameters:
    - $ref: '#/components/parameters/datasetSlugOrAll'
    - name: queryAnnotationId
      description: The unique identifier (ID) of the annotation.
      in: path
      required: true
      schema:
        type: string
    servers:
    - url: https://api.honeycomb.io
      description: Honeycomb Production API
components:
  schemas:
    QueryAnnotationUpdateRequest:
      type: object
      properties:
        name:
          type: string
          description: An updated name for the query annotation.
        description:
          type: string
          description: An updated description for the annotation.
    QueryAnnotationCreateRequest:
      type: object
      required:
      - name
      - query_id
      properties:
        name:
          type: string
          description: The name for the query annotation.
        description:
          type: string
          description: An optional description for the annotation.
        query_id:
          type: string
          description: The ID of the query to annotate.
    QueryAnnotation:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the query annotation.
        name:
          type: string
          description: The name of the query annotation.
        description:
          type: string
          description: A description associated with the query.
        query_id:
          type: string
          description: The ID of the query this annotation is associated with.
        created_at:
          type: string
          format: date-time
          description: ISO8601 formatted time the query annotation was created.
        updated_at:
          type: string
          format: date-time
          description: ISO8601 formatted time the query annotation was last updated.
    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.
    QueryAnnotation_2:
      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
    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
  parameters:
    datasetSlug:
      name: datasetSlug
      in: path
      required: true
      description: The slug identifier for the dataset. Dataset names are case insensitive.
      schema:
        type: string
    queryAnnotationId:
      name: queryAnnotationId
      in: path
      required: true
      description: The unique identifier for the query annotation.
      schema:
        type: string
    datasetSlugOrAll:
      name: datasetSlug
      description: 'The dataset slug or use `__all__` for endpoints that support environment-wide operations.

        '
      in: path
      required: true
      schema:
        type: string
  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
    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
    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
  responses:
    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'
    GenericError:
      description: Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    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'
    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.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Honeycomb-Team
      description: Honeycomb Configuration API key. Must have appropriate permissions for the endpoint being called.
    configuration_key:
      type: apiKey
      name: X-Honeycomb-Team
      in: header
      description: 'Authenticate using a Honeycomb Configuration Key.


        Pass the **Token** in the `X-Honeycomb-Team` header:

        ```http

        X-Honeycomb-Team: 1234567890123456789012

        ```


        If you created your key using the API, use `data.attributes.secret`; this is the same value as the **Token** in the UI.


        To learn how to create a Configuration Key, visit [Manage Environment API Keys](/configure/environments/manage-api-keys). To learn more about authenticating requests, visit [API Authentication](/api/authentication).

        '
    ingest_key:
      type: apiKey
      name: X-Honeycomb-Team
      in: header
      description: 'Authenticate using a Honeycomb Ingest Key.


        Pass the Ingest Key in the `X-Honeycomb-Team` header:

        ```http

        X-Honeycomb-Team: hc[x]ik_1234567890123456789012345612345678901234567890123456789012

        ```


        The key value is the key ID and key secret concatenated with no separator:

        - If you created your key through the UI, Honeycomb provides the complete value as the **Ingest Key**.

        - If you created your key using the API, construct the key value by concatenating `data.id` and `data.attributes.secret` with no separator.


        To learn how to create an Ingest Key, visit [Manage Environment API Keys](/configure/environments/manage-api-keys). To learn more about authenticating requests, visit [API Authentication](/api/authentication).

        '
    firehose_access_key:
      type: apiKey
      name: X-Amz-Firehose-Access-Key
      in: header
      description: 'We recommend using a Honeycomb Ingest Key to authenticate, though a Configuration Key will work.


        To learn more about authenticating requests, visit [API Authentication](/api/authentication).

        '
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Authenticate using a Honeycomb Management Key.


        Pass the Management Key as a Bearer token in the `Authorization` header:

        ```http

        Authorization: Bearer hcxmk_12345678901234567890123456:12345678901234567890123456789012

        ```


        Construct the key value by joining the **Key ID** and **Secret** with a colon (`:`).


        To learn how to create a Management Key, visit [Manage Team API Keys](/configure/teams/manage-api-keys). To learn more about authenticating requests, visit [API Authentication](/api/authentication).

        '
      bearerFormat: HONEYCOMB_KEY_ID:HONEYCOMB_KEY_SECRET
x-refined-from:
- honeycomb-api-openapi.yml
- honeycomb-openapi.yml