openapi: 3.1.0
info:
title: Honeycomb Columns 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.
'
externalDocs:
url: https://docs.honeycomb.io
servers:
- url: https://api.honeycomb.io
- url: https://api.eu1.honeycomb.io
tags:
- name: Calculated Fields
description: 'Calculated Fields (also called Derived Columns) allow you to run queries based on the value of an expression that is calculated from the fields in an event.
This API allows you to list, create, update, and delete Calculated Fields in a dataset or across a whole environment, paralleling the behavior of the Schema tab within a Dataset''s or Environment''s
Settings UI.
## 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/).
'
- name: Columns
description: 'Columns are fields in the events you send to Honeycomb.
This API allows you to list, create, update, and delete columns in a dataset.
## 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/derived_columns/{datasetSlug}:
parameters:
- $ref: '#/components/parameters/datasetSlugOrAll'
post:
security:
- configuration_key: []
summary: Create a Calculated Field
description: 'Create a Calculated Field (also called a Derived Column). Calculated Fields allow you to run queries based on the value of an expression that is calculated from the fields in an event.
'
tags:
- Calculated Fields
operationId: createCalculatedField
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CalculatedField'
required: true
responses:
'201':
description: Success
headers:
Ratelimit:
$ref: '#/components/headers/RateLimit'
RateLimitPolicy:
$ref: '#/components/headers/RateLimitPolicy'
content:
application/json:
schema:
$ref: '#/components/schemas/CalculatedField'
example:
id: yUheCUmgZ8p
alias: one
description: just one
expression: INT(1)
created_at: '2022-07-26T22:38:04Z'
updated_at: '2022-11-16T17:34:01Z'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/Conflict'
'429':
$ref: '#/components/responses/RateLimited'
get:
security:
- configuration_key: []
summary: List all Calculated Fields
description: Get all the Calculated Fields (also called Derived Columns) in a dataset or environment. With the `?alias=X` query parameter, can return a single Calculated Field by its `alias`.
tags:
- Calculated Fields
operationId: listCalculatedFields
parameters:
- name: alias
description: The Calculated Field `alias`.
in: query
schema:
type: string
responses:
'200':
description: 'When listing all columns, an array of CalculatedField objects will be returned. When using `key_name`, will return a single CalculatedField object if found.
'
headers:
Ratelimit:
$ref: '#/components/headers/RateLimit'
RateLimitPolicy:
$ref: '#/components/headers/RateLimitPolicy'
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/CalculatedFieldList'
- $ref: '#/components/schemas/CalculatedField'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/RateLimited'
/1/derived_columns/{datasetSlug}/{derivedColumnId}:
parameters:
- $ref: '#/components/parameters/datasetSlugOrAll'
- name: derivedColumnId
description: Unique identifier (ID) of a Calculated Field (also called a Derived Column).
in: path
required: true
schema:
type: string
get:
security:
- configuration_key: []
summary: Get a Calculated Field
tags:
- Calculated Fields
operationId: getCalculatedField
responses:
'200':
description: Success
headers:
Ratelimit:
$ref: '#/components/headers/RateLimit'
RateLimitPolicy:
$ref: '#/components/headers/RateLimitPolicy'
content:
application/json:
schema:
$ref: '#/components/schemas/CalculatedField'
example:
id: yUheCUmgZ8p
alias: one
description: just one
expression: INT(1)
created_at: '2022-07-26T22:38:04Z'
updated_at: '2022-11-16T17:34:01Z'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/RateLimited'
put:
security:
- configuration_key: []
summary: Update a Calculated Field
description: 'Update a Calculated Field (also called a Derived Column).
'
tags:
- Calculated Fields
operationId: updateCalculatedField
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CalculatedField'
required: true
responses:
'200':
description: Success
headers:
Ratelimit:
$ref: '#/components/headers/RateLimit'
RateLimitPolicy:
$ref: '#/components/headers/RateLimitPolicy'
content:
application/json:
schema:
$ref: '#/components/schemas/CalculatedField'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/Conflict'
'429':
$ref: '#/components/responses/RateLimited'
delete:
security:
- configuration_key: []
summary: Delete a Calculated Field
description: 'Delete a Calculated Field (also called a Derived Column). **Note**: A Calculated Field used by a SLO, Trigger, or Board cannot be deleted without removing or modifying the SLO, Trigger,
or Board first.
'
tags:
- Calculated Fields
operationId: deleteCalculatedField
responses:
'204':
description: Success - no content
headers:
Ratelimit:
$ref: '#/components/headers/RateLimit'
RateLimitPolicy:
$ref: '#/components/headers/RateLimitPolicy'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/Conflict'
'429':
$ref: '#/components/responses/RateLimited'
/1/columns/{datasetSlug}:
parameters:
- $ref: '#/components/parameters/datasetSlugOrAll'
post:
security:
- configuration_key: []
summary: Create a Column
description: 'Create a column by providing corresponding details for that type.
'
tags:
- Columns
operationId: createColumn
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateColumn'
required: true
responses:
'201':
description: Success
headers:
Ratelimit:
$ref: '#/components/headers/RateLimit'
RateLimitPolicy:
$ref: '#/components/headers/RateLimitPolicy'
content:
application/json:
schema:
$ref: '#/components/schemas/Column'
example:
id: yUheCUmgZ8p
key_name: my_column
hidden: false
description: An integer column
type: integer
last_written: '2022-07-26T22:38:05Z'
created_at: '2022-07-26T22:38:04Z'
updated_at: '2022-07-26T22:38:04Z'
'400':
description: Bad Request
headers:
Ratelimit:
$ref: '#/components/headers/RateLimit'
RateLimitPolicy:
$ref: '#/components/headers/RateLimitPolicy'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: Key name cannot be blank
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/Conflict'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/RateLimited'
get:
security:
- configuration_key: []
summary: List all Columns
description: 'Get all the Columns in a dataset or environment.
Use `__all__` as the dataset slug to retrieve all Columns across all datasets in the environment (not available for classic environments).
'
tags:
- Columns
operationId: listColumns
parameters:
- name: key_name
description: the column key name
in: query
schema:
type: string
responses:
'200':
description: 'When listing all columns, an array of Column objects will be returned. When using `key_name`, will return a single Column object if found.
'
headers:
Ratelimit:
$ref: '#/components/headers/RateLimit'
RateLimitPolicy:
$ref: '#/components/headers/RateLimitPolicy'
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ColumnList'
- $ref: '#/components/schemas/Column'
examples:
list-of-columns:
description: Lists all columns.
value:
- id: yUheCUmgZ8p
key_name: my_column
hidden: false
description: ''
type: integer
last_written: '2022-07-26T22:38:05Z'
created_at: '2022-07-26T22:38:04Z'
updated_at: '2022-07-26T22:38:04Z'
- id: yUheCUmgZ8q
key_name: other_column
hidden: false
description: ''
type: string
last_written: '2022-07-26T22:38:05Z'
created_at: '2022-07-26T22:38:04Z'
updated_at: '2022-07-26T22:38:04Z'
get-column-by-key-name:
description: Get back column details for a key name
value:
id: yUheCUmgZ8p
key_name: my_column
hidden: false
description: ''
type: integer
last_written: '2022-07-26T22:38:05Z'
created_at: '2022-07-26T22:38:04Z'
updated_at: '2022-07-26T22:38:04Z'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/RateLimited'
/1/columns/{datasetSlug}/{columnId}:
parameters:
- $ref: '#/components/parameters/datasetSlug'
- name: columnId
description: Unique identifier (ID) of a column.
in: path
required: true
schema:
type: string
get:
security:
- configuration_key: []
summary: Get a Column
tags:
- Columns
operationId: getColumn
responses:
'200':
description: Success
headers:
Ratelimit:
$ref: '#/components/headers/RateLimit'
RateLimitPolicy:
$ref: '#/components/headers/RateLimitPolicy'
content:
application/json:
schema:
$ref: '#/components/schemas/Column'
example:
id: yUheCUmgZ8p
key_name: my_column
hidden: false
description: ''
type: integer
last_written: '2022-07-26T22:38:05Z'
created_at: '2022-07-26T22:38:04Z'
updated_at: '2022-07-26T22:38:04Z'
'400':
description: Bad Request
headers:
Ratelimit:
$ref: '#/components/headers/RateLimit'
RateLimitPolicy:
$ref: '#/components/headers/RateLimitPolicy'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: The id provided in the URL is malformed - we expected a 12-char base58-safe string.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/RateLimited'
put:
security:
- configuration_key: []
summary: Update a Column
description: 'Update a column
'
tags:
- Columns
operationId: updateColumn
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Column'
required: true
responses:
'200':
description: Success
headers:
Ratelimit:
$ref: '#/components/headers/RateLimit'
RateLimitPolicy:
$ref: '#/components/headers/RateLimitPolicy'
content:
application/json:
schema:
$ref: '#/components/schemas/Column'
example:
id: yUheCUmgZ8p
key_name: my_column
hidden: false
description: ''
type: string
last_written: '2022-07-26T22:38:05Z'
created_at: '2022-07-26T22:38:04Z'
updated_at: '2022-07-26T22:38:04Z'
'400':
description: Bad Request
headers:
Ratelimit:
$ref: '#/components/headers/RateLimit'
RateLimitPolicy:
$ref: '#/components/headers/RateLimitPolicy'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: Key name cannot be blank
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'422':
$ref: '#/components/responses/ValidationFailed'
'429':
$ref: '#/components/responses/RateLimited'
delete:
security:
- configuration_key: []
summary: Delete a Column
description: 'Delete a column. **Note**: Deleted columns are no longer queryable, but data in existing permalinks (query results and trace views) will remain stored and available at those links.
'
tags:
- Columns
operationId: deleteColumn
responses:
'204':
description: Success - no content
headers:
Ratelimit:
$ref: '#/components/headers/RateLimit'
RateLimitPolicy:
$ref: '#/components/headers/RateLimitPolicy'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/Conflict'
'429':
$ref: '#/components/responses/RateLimited'
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
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
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
datasetSlug:
name: datasetSlug
description: 'The dataset slug.
'
in: path
required: true
schema:
type: string
schemas:
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
Column:
allOf:
- $ref: '#/components/schemas/CreateColumn'
properties:
key_name:
readOnly: true
ValidationError:
x-tags:
- Errors
allOf:
- $ref: '#/components/schemas/DetailedError'
- type: object
properties:
status:
type: number
readOnly: true
default: 422
type:
type: string
readOnly: true
default: https://api.honeycomb.io/problems/validation-failed
title:
type: string
readOnly: true
default: The provided input is invalid.
type_detail:
type: array
items:
type: object
properties:
field:
type: string
readOnly: true
code:
type: string
readOnly: true
enum:
- invalid
- missing
- incorrect_type
- already_exists
description:
type: string
readOnly: true
ColumnList:
type: array
items:
$ref: '#/components/schemas/Column'
CalculatedField:
type: object
required:
- id
- alias
- expression
- created_at
- updated_at
properties:
id:
type: string
readOnly: true
description: Unique identifier (ID), returned in response bodies.
alias:
type: string
description: The human-readable name of the Calculated Field (also called Derived Column), as it will be referenced when building queries.
minLength: 1
maxLength: 255
expression:
type: string
description: 'The expression to evaluate to construct this Calculated Field''s value. (Calculated Field is also called Derived Column.) Refer to the [Calculated Field Reference](https://docs.honeycomb.io/reference/derived-column-formula/).
'
minLength: 1
maxLength: 4095
description:
type: string
description: A human-readable description for the Calculated Field that displays in the UI.
default: ''
maxLength: 255
created_at:
type: string
readOnly: true
description: ISO8601 formatted time when the field was created.
updated_at:
type: string
readOnly: true
description: ISO8601 formatted time when the field was 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.
CalculatedFieldList:
type: array
items:
$ref: '#/components/schemas/CalculatedField'
CreateColumn:
type: object
required:
- key_name
properties:
key_name:
type: string
description: Name of the Column.
example: my_column
minLength: 1
maxLength: 255
type:
type: string
default: string
enum:
- string
- float
- integer
- boolean
- histogram
description: Type of data that the Column will contain. Histogram is in beta and only works in your Metrics dataset.
example: integer
description:
type: string
description: Column description.
maxLength: 255
example: An integer column
hidden:
type: boolean
default: false
description: If `true`, the column is excluded from autocomplete and raw data field lists.
id:
type: string
readOnly: true
description: Unique identifier (ID), returned in response bodies.
last_written:
type: string
readOnly: true
description: ISO8601 formatted time the column was last written to (received event data).
created_at:
type: string
readOnly: true
description: ISO8601 formatted time the column was created.
updated_at:
type: string
readOnly: true
description: ISO8601 formatted time the column was updated.
Error:
x-tags:
- Errors
type: object
description: A legacy error, containing only a textual description.
properties:
error:
type: string
readOnly: true
responses:
UnprocessableEntity:
description: Invalid request
headers:
Ratelimit:
$ref: '#/components/headers/RateLimit'
RateLimitPolicy:
$ref: '#/components/headers/RateLimitPolicy'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ValidationError'
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'
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'
ValidationFailed:
description: Validation Failed
headers:
Ratelimit:
$ref: '#/components/headers/RateLimit'
RateLimitPolicy:
$ref: '#/components/headers/RateLimitPolicy'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ValidationError'
example:
status: 422
type: https://api.honeycomb.io/problems/validation-failed
error: The provided input is invalid.
title: The provided input is invalid
type_detail:
- field: type
code: invalid
description: 'type: must be a valid value'
application/json:
schema:
$ref: '#/components/schemas/Error'
application/vnd.api+json:
schema:
$ref: '#/components/schemas/JSONAPIError'
Conflict:
description: Conflict
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: 409
type: https://api.honeycomb.io/problems/conflict
title: Request could not be completed due to a conflict with the current state of the target resource.
error: A resource by that name already exists.
application/vnd.api+json:
schema:
$ref: '#/components/schemas/JSONAPIError'
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.
BadRequest:
description: The provided request body was invalid.
headers:
Ratelimit:
$ref: '#/components/headers/RateLimit'
RateLimitPolicy:
$ref: '#/components/headers/RateLimitPolicy'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/DetailedError'
examples:
DetailedError:
value:
status: 400
type: https://api.honeycomb.io/problems/unparseable
title: The request body could not be parsed.
error: invalid gzip data
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
GenericError:
value:
error: invalid Query data
application/vnd.api+json:
schema:
$ref: '#/components/schemas/JSONAPIError'
examples:
JSONAPIError:
value:
errors:
- id: 06dcdd6508ca822f0e7e2bb4121c1f52
code: invalid
title: request body could not be parsed
detail: invalid gzip data