Honeycomb Events API

openapi: 3.2.0
info:
  title: Honeycomb Events 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 Pollinators Slack or to Honeycomb Support.'
servers:
- url: https://api.honeycomb.io
- url: https://api.eu1.honeycomb.io
tags:
- name: Events
  description: 'The Events API endpoints are the lowest-level way to send Events to Honeycomb. **This should be your last resort!**


    If unsure where to start when instrumenting an application, read about how to Send Data to Honeycomb.


    If you are building a tracing or metrics library, we recommend using OpenTelemetry.


    ## Authorization


    It is recommended that an Ingest API key is used for sending events.


    A Configuration API key will work, and must have the **Send Events** permission.

    Learn more about API keys here.'
paths:
  /1/batch/{datasetSlug}:
    parameters:
    - $ref: '#/components/parameters/datasetSlug'
    post:
      security:
      - configuration_key: []
      - ingest_key: []
      summary: Create Events
      description: 'Supports batch creation of events.


        Dataset names are case insensitive. `POST` requests to "MyDatasET" will land in the same dataset as "mydataset". Names may contain URL-encoded spaces or other special characters, but not URL-encoded slashes. For example, "My%20Dataset" will show up in the UI as "My Dataset".


        The first event received for a dataset determines the casing of the displayed name. All subsequent variations in casing will use the originally specified case.'
      tags:
      - Events
      operationId: createEvents
      parameters:
      - in: header
        name: Content-Encoding
        description: 'Included when sending events in a file. Size limitations may be addressed by compressing request bodies with gzip or zstd compression. Be sure to set the Content-Encoding to `gzip` or `zstd` when compressing the request body. If sending plaintext, omit this header; "plaintext" is included to simplify the example with curl.

          '
        schema:
          type: string
          enum:
          - gzip
          - zstd
        example: plaintext
      requestBody:
        required: true
        description: "The array should contain one or more JSON objects representing Events. Each Event contains its payload under the `data` key. Values of `time` and/or `samplerate` can be included as well.\n\nThe JSON payload should have the structure:\n\n  `[{ \"data\": { \"key1\": \"value1\", \"key2\": 2.0 } }, ... ]`\n\nSize limitations may be addressed by compressing request bodies with `gzip` or `zstd` compression.\n\nAn empty `202` response indicates that the event has been queued for processing.\n"
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/BatchEvent'
            example:
            - time: '2006-01-02T15:04:05.99Z'
              samplerate: 1
              data:
                method: GET
                endpoint: /foo
                shard: users
                duration_ms: 32
            - time: '2006-01-02T15:04:05.99Z'
              data:
                some_other_key: value
                duration_ms: 40
          application/octet-stream:
            schema:
              type: string
              format: binary
      responses:
        '200':
          description: Enqueued for processing
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    status:
                      type: number
                    error:
                      type: string
              example:
              - status: 202
              - status: 400
                error: Request body should not be empty.
              - status: 400
                error: Event has too many columns.
              - status: 400
                error: Request body is malformed and cannot be read.
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not-empty:
                  description: The body is empty, or blank.
                  value:
                    error: Request body should not be empty.
                dataset-too-many-columns:
                  description: The dataset has reached the maximum number of columns.
                  value:
                    error: Dataset has too many columns.
                malformed-request:
                  description: The API failed to decode the body as JSON.
                  value:
                    error: Request body is malformed and cannot be read.
                too-large:
                  description: The body is too large.
                  value:
                    error: Request body is too large.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Dropped due to administrative throttling
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Event dropped due to administrative throttling
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          description: Dropped due to rate limiting
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                rate-limiting:
                  value:
                    error: Request dropped due to rate limiting.
                deny-list:
                  value:
                    error: Event dropped due to administrative denylist
  /1/events/{datasetSlug}:
    parameters:
    - $ref: '#/components/parameters/datasetSlug'
    post:
      security:
      - configuration_key: []
      - ingest_key: []
      summary: Create an Event
      description: 'Using this endpoint for anything more than testing is highly discouraged.


        Sending events in batches will be much more efficient and should be preferred if at all possible.'
      tags:
      - Events
      operationId: createEvent
      parameters:
      - in: header
        name: X-Honeycomb-Event-Time
        description: The Event's timestamp. Optional. Defaults to server time.
        schema:
          type: integer
      - in: header
        name: X-Honeycomb-Samplerate
        description: Optional. Defaults to 1.
        schema:
          type: integer
      requestBody:
        description: 'The request body is limited to raw (potentially compressed) size of 1MB.


          The maximum number of distinct columns (fields) allowed in an event is `2000`.

          '
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Event'
            example:
              method: GET
              endpoint: /foo
              shard: users
              duration_ms: 32
        required: true
      responses:
        '200':
          description: Enqueued for processing
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not-empty:
                  description: The body is empty, or blank.
                  value:
                    error: Request body should not be empty.
                dataset-too-many-columns:
                  description: The dataset has reached the maximum number of columns.
                  value:
                    error: Dataset has too many columns.
                events-too-many-columns:
                  description: The event has reached the maximum number of columns.
                  value:
                    error: Event has too many columns.
                malformed-request:
                  description: The API failed to decode the body as JSON.
                  value:
                    error: Request body is malformed and cannot be read.
                too-large:
                  description: The body is too large.
                  value:
                    error: Request body is too large.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Dropped due to administrative throttling
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Event dropped due to administrative throttling
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          description: Dropped due to rate limiting
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                rate-limiting:
                  value:
                    error: Request dropped due to rate limiting.
                deny-list:
                  value:
                    error: Event dropped due to administrative denylist
components:
  schemas:
    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
    Event:
      type: object
      minProperties: 1
      maxProperties: 2000
      additionalProperties:
        description: 'A collection of key-value properties that represent the Event. Honeycomb supports basic data types for the values of each Event attribute.


          ### Limits

          - 2,000 fields per event. The entire event must be less than 1 MB of uncompressed JSON.

          - String Fields: Each string field has a maximum length of 64KB.

          - Number Fields: Integers and Floats are both 64-bit.

          '
        type:
        - string
        - number
        - boolean
    Error:
      x-tags:
      - Errors
      type: object
      description: A legacy error, containing only a textual description.
      properties:
        error:
          type: string
          readOnly: true
    BatchEvent:
      type: object
      properties:
        data:
          type: object
          allOf:
          - $ref: '#/components/schemas/Event'
        time:
          type: string
          description: 'Should be in RFC3339 high precision format (for example, YYYY-MM-DDTHH:MM:SS.mmmZ). May be a Unix epoch (seconds since 1970) with second or greater precision (for example, 1452759330927). Optional. If not set, defaults to the time that the API receives the event.

            '
        samplerate:
          type: integer
          description: 'An integer representing the denominator in the fraction 1/n when client-side sampling has been applied. Optional. If not set, defaults to `1`, meaning "not sampled". Refer to [Sampling](https://docs.honeycomb.io/manage-data-volume/sample/sampled-data-in-honeycomb/) for more detail.

            '
  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
  parameters:
    datasetSlug:
      name: datasetSlug
      description: 'The dataset slug.

        '
      in: path
      required: true
      schema:
        type: string
  responses:
    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'
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: unknown API key - check your credentials
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/JSONAPIError'
  securitySchemes:
    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
externalDocs:
  url: https://docs.honeycomb.io