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