honeycomb Calculated Fields API

openapi: 3.2.0
info:
  title: Honeycomb Calculated Fields API
  version: '1.0'
  description: 'Operations tagged Calculated Fields 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: Calculated Fields
  description: Manage calculated fields (derived columns) that compute values from expressions applied to event fields.
paths:
  /1/calculated_fields/{datasetSlug}:
    get:
      operationId: listCalculatedFields
      summary: List calculated fields
      description: Returns a list of all calculated fields (derived columns) in the specified dataset.
      tags:
      - Calculated Fields
      parameters:
      - $ref: '#/components/parameters/datasetSlug'
      responses:
        '200':
          description: A list of calculated fields
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CalculatedField'
        '401':
          description: Unauthorized
      security:
      - ApiKeyAuth: []
    post:
      operationId: createCalculatedField
      summary: Create a calculated field
      description: Creates a new calculated field (derived column) in the specified dataset or across the environment.
      tags:
      - Calculated Fields
      parameters:
      - $ref: '#/components/parameters/datasetSlug'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CalculatedFieldCreateRequest'
      responses:
        '201':
          description: Calculated field created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CalculatedField'
        '401':
          description: Unauthorized
      security:
      - ApiKeyAuth: []
    servers:
    - url: https://api.honeycomb.io
      description: Honeycomb Production API
  /1/calculated_fields/{datasetSlug}/{calculatedFieldId}:
    get:
      operationId: getCalculatedField
      summary: Get a calculated field
      description: Returns a single calculated field by its ID.
      tags:
      - Calculated Fields
      parameters:
      - $ref: '#/components/parameters/datasetSlug'
      - $ref: '#/components/parameters/calculatedFieldId'
      responses:
        '200':
          description: Calculated field details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CalculatedField'
        '401':
          description: Unauthorized
        '404':
          description: Calculated field not found
      security:
      - ApiKeyAuth: []
    put:
      operationId: updateCalculatedField
      summary: Update a calculated field
      description: Updates the expression or properties of a calculated field.
      tags:
      - Calculated Fields
      parameters:
      - $ref: '#/components/parameters/datasetSlug'
      - $ref: '#/components/parameters/calculatedFieldId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CalculatedFieldUpdateRequest'
      responses:
        '200':
          description: Calculated field updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CalculatedField'
        '401':
          description: Unauthorized
        '404':
          description: Calculated field not found
      security:
      - ApiKeyAuth: []
    delete:
      operationId: deleteCalculatedField
      summary: Delete a calculated field
      description: Deletes a calculated field from the specified dataset.
      tags:
      - Calculated Fields
      parameters:
      - $ref: '#/components/parameters/datasetSlug'
      - $ref: '#/components/parameters/calculatedFieldId'
      responses:
        '204':
          description: Calculated field deleted
        '401':
          description: Unauthorized
        '404':
          description: Calculated field not found
      security:
      - ApiKeyAuth: []
    servers:
    - url: https://api.honeycomb.io
      description: Honeycomb Production API
  /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: post1DerivedColumnsByDatasetSlug
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CalculatedField_2'
        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_2'
              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'
      x-operation-id-source: normalized
      x-operation-id-original: createCalculatedField
    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: get1DerivedColumnsByDatasetSlug
      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_2'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
      x-operation-id-source: normalized
      x-operation-id-original: listCalculatedFields
    servers:
    - url: https://api.honeycomb.io
    - url: https://api.eu1.honeycomb.io
  /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: get1DerivedColumnsByDatasetSlugByDerivedColumnId
      responses:
        '200':
          description: Success
          headers:
            Ratelimit:
              $ref: '#/components/headers/RateLimit'
            RateLimitPolicy:
              $ref: '#/components/headers/RateLimitPolicy'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CalculatedField_2'
              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'
      x-operation-id-source: normalized
      x-operation-id-original: getCalculatedField
    put:
      security:
      - configuration_key: []
      summary: Update a Calculated Field
      description: Update a Calculated Field (also called a Derived Column).
      tags:
      - Calculated Fields
      operationId: put1DerivedColumnsByDatasetSlugByDerivedColumnId
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CalculatedField_2'
        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_2'
        '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'
      x-operation-id-source: normalized
      x-operation-id-original: updateCalculatedField
    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: delete1DerivedColumnsByDatasetSlugByDerivedColumnId
      responses:
        '204':
          description: Success - no content
          headers:
            Ratelimit:
              $ref: '#/components/headers/RateLimit'
            RateLimitPolicy:
              $ref: '#/components/headers/RateLimitPolicy'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '409':
          $ref: '#/components/responses/Conflict'
        '429':
          $ref: '#/components/responses/RateLimited'
      x-operation-id-source: normalized
      x-operation-id-original: deleteCalculatedField
    servers:
    - url: https://api.honeycomb.io
    - url: https://api.eu1.honeycomb.io
components:
  parameters:
    calculatedFieldId:
      name: calculatedFieldId
      in: path
      required: true
      description: The unique identifier for the calculated field.
      schema:
        type: string
    datasetSlug:
      name: datasetSlug
      in: path
      required: true
      description: The slug identifier for the dataset. Dataset names are case insensitive.
      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
  schemas:
    CalculatedFieldCreateRequest:
      type: object
      required:
      - alias
      - expression
      properties:
        alias:
          type: string
          description: The alias name for the calculated field.
        expression:
          type: string
          description: The expression to compute the field value.
        description:
          type: string
          description: An optional description for the calculated field.
    CalculatedFieldUpdateRequest:
      type: object
      properties:
        expression:
          type: string
          description: An updated expression for the calculated field.
        description:
          type: string
          description: An updated description for the calculated field.
    CalculatedField:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the calculated field.
        alias:
          type: string
          description: The alias name used to reference this calculated field in queries.
        expression:
          type: string
          description: The expression used to compute the calculated field value.
        description:
          type: string
          description: A description of the calculated field.
        created_at:
          type: string
          format: date-time
          description: ISO8601 formatted time the calculated field was created.
        updated_at:
          type: string
          format: date-time
          description: ISO8601 formatted time the calculated field 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.
    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
    CalculatedField_2:
      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.
    CalculatedFieldList:
      type: array
      items:
        $ref: '#/components/schemas/CalculatedField_2'
  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:
    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'
    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
    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'
    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