Send arbitrary JSON events into Honeycomb datasets via single-event POST, high-throughput batch POST, and Kinesis-style ingest. Events are the lowest-level ingest primitive; OpenTelemetry traces, metrics, and logs all land here. Each event becomes a row in a columnar dataset that you can query, trigger on, or derive SLOs from.
openapi: 3.1.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 <a href="https://docs.honeycomb.io/troubleshoot/community/">Pollinators Slack</a> or to <a href="https://support.honeycomb.io/">Honeycomb
Support</a>.
'
externalDocs:
url: https://docs.honeycomb.io
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](https://docs.honeycomb.io/send-data/).
If you are building a tracing or metrics library, we recommend using [OpenTelemetry](https://docs.honeycomb.io/send-data/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](https://docs.honeycomb.io/configure/environments/manage-api-keys/).
'
- name: Kinesis Events
description: 'The Kinesis Events API endpoints allow Honeycomb to process streaming events from Amazon Kinesis.
Refer to the [Honeycomb AWS integrations](https://docs.honeycomb.io/integrations/aws/how-aws-integrations-work/) documentation for more information.
## 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](https://docs.honeycomb.io/configure/environments/manage-api-keys/).
'
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
/1/kinesis_events/{datasetSlug}:
parameters:
- in: header
name: X-Amz-Firehose-Request-Id
description: 'AWS Request ID associated with the Kinesis Firehose.
'
schema:
type: string
required: true
example: 33658b45-a8f1-4007-92e8-f601ae33db14
- $ref: '#/components/parameters/datasetSlug'
post:
summary: Create Kinesis Events
description: 'This endpoint processes events and metrics coming from AWS through Kinesis Firehose.
'
tags:
- Kinesis Events
operationId: createKinesisEvents
security:
- firehose_access_key: []
requestBody:
description: 'The request body expected from Amazon Kinesis Firehose. Events and metrics have the same shape but the base64 encoded data blob for metrics is expected to be Protowire-encoded as well.
CloudWatch Logs data coming through Amazon Kinesis Firehose is expected to have a gzip Content-Encoding.
'
content:
application/json:
schema:
$ref: '#/components/schemas/KinesisEvent'
required: true
responses:
'200':
description: Events queued for processing
content:
application/json:
schema:
$ref: '#/components/schemas/KinesisResponse'
'401':
$ref: '#/components/responses/Unauthorized'
default:
$ref: '#/components/responses/GenericError'
components:
responses:
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'
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'
headers:
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
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
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
KinesisEvent:
type: object
properties:
requestId:
type: string
timestamp:
type: integer
records:
type: array
items:
$ref: '#/components/schemas/KinesisEventRecord'
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.
'
KinesisResponse:
type: object
properties:
requestId:
type: string
timestamp:
type: integer
errorMessage:
type: string
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
KinesisEventRecord:
type: object
properties:
data:
type: string
description: Base64 encoded Kinesis record from AWS
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
description: 'The dataset slug.
'
in: path
required: true
schema:
type: string