Honeycomb Datasets API

openapi: 3.1.0
info:
  title: Honeycomb Auth Datasets 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>.

    '
servers:
- url: https://api.honeycomb.io
- url: https://api.eu1.honeycomb.io
tags:
- name: Datasets
  description: 'A Dataset represents a collection of related events that come from the same source, or are related to the same source.


    This API allows you to list, create, and update datasets.


    ## Authorization


    The API key must have the **Create Datasets** permission. Learn more about [API keys here](https://docs.honeycomb.io/configure/environments/manage-api-keys/).

    '
paths:
  /1/datasets:
    post:
      security:
      - configuration_key: []
      summary: Create a Dataset
      description: 'Create a Dataset in the environment associated with your API key.

        If a Dataset already exists by that name (or slug), then the existing dataset will be returned.

        '
      tags:
      - Datasets
      operationId: createDataset
      requestBody:
        description: 'The dataset will be created within the environment associated with your API key.

          '
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DatasetCreationPayload'
        required: true
      responses:
        '200':
          description: OK - Dataset already exists
          headers:
            Ratelimit:
              $ref: '#/components/headers/RateLimit'
            RateLimitPolicy:
              $ref: '#/components/headers/RateLimitPolicy'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Dataset'
        '201':
          description: Created
          headers:
            Ratelimit:
              $ref: '#/components/headers/RateLimit'
            RateLimitPolicy:
              $ref: '#/components/headers/RateLimitPolicy'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Dataset'
              example:
                name: MyDataset!
                slug: mydataset-
                description: A nice description of my dataset
                expand_json_depth: 3
                created_at: 2022-07-21 18:39:23+00:00
                last_written_at: null
                regular_columns_count: 0
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          description: Conflict
          headers:
            Ratelimit:
              $ref: '#/components/headers/RateLimit'
            RateLimitPolicy:
              $ref: '#/components/headers/RateLimitPolicy'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: we could not create a dataset with that name
            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.
                detail: environment has reached the maximum number of datasets allowed
                error: environment has reached the maximum number of datasets allowed
        '422':
          $ref: '#/components/responses/ValidationFailed'
        '429':
          $ref: '#/components/responses/RateLimited'
        default:
          $ref: '#/components/responses/GenericError'
    get:
      security:
      - configuration_key: []
      summary: List All Datasets
      description: 'Lists all Datasets for an environment.

        **Note**: For Honeycomb Classic users, all datasets in Classic are returned.

        '
      tags:
      - Datasets
      operationId: listDatasets
      responses:
        '200':
          description: Success
          headers:
            Ratelimit:
              $ref: '#/components/headers/RateLimit'
            RateLimitPolicy:
              $ref: '#/components/headers/RateLimitPolicy'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Dataset'
              example:
              - name: my dataset!
                description: my dataset described!
                slug: my-dataset-
                expand_json_depth: 2
                created_at: '2022-07-21T18:39:23Z'
                last_written_at: '2022-07-22T19:52:00Z'
                regular_columns_count: 12
              - name: another dataset
                description: ''
                slug: another-dataset
                expand_json_depth: 0
                created_at: '2022-07-21T18:39:23Z'
                last_written_at: '2022-07-22T19:52:00Z'
                regular_columns_count: 98
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
        default:
          $ref: '#/components/responses/GenericError'
  /1/datasets/{datasetSlug}:
    parameters:
    - $ref: '#/components/parameters/datasetSlug'
    get:
      security:
      - configuration_key: []
      summary: Get a Dataset
      description: 'Get a single Dataset by slug.

        '
      tags:
      - Datasets
      operationId: getDataset
      responses:
        '200':
          description: Success
          headers:
            Ratelimit:
              $ref: '#/components/headers/RateLimit'
            RateLimitPolicy:
              $ref: '#/components/headers/RateLimitPolicy'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Dataset'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        default:
          $ref: '#/components/responses/GenericError'
    delete:
      security:
      - configuration_key: []
      summary: Delete a Dataset
      description: 'Deletes the Dataset. This is an irreversible operation.

        It may take several minutes for the deletion process to complete.



        **WARNING**: This endpoint will allow anyone with an API key that has the

        manage dataset permission to delete any dataset in the environment (or

        any dataset in the whole team for Classic customers).



        Datasets with Deletion Protection enabled cannot be deleted.


        To delete a Dataset with Deletion Protection enabled, first disable Deletion Protection by updating the Dataset with `settings.delete_protected = false`.

        '
      tags:
      - Datasets
      operationId: deleteDataset
      responses:
        '202':
          description: Deleted
          headers:
            Ratelimit:
              $ref: '#/components/headers/RateLimit'
            RateLimitPolicy:
              $ref: '#/components/headers/RateLimitPolicy'
          content:
            application/json: {}
        '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'
        default:
          $ref: '#/components/responses/GenericError'
    put:
      security:
      - configuration_key: []
      summary: Update a Dataset
      description: 'Update a Dataset''s settings.

        '
      tags:
      - Datasets
      operationId: updateDataset
      requestBody:
        description: 'Update a Dataset''s settings.

          All fields must be specified, as omitting one will have the effect of reverting the setting to the default.

          '
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DatasetUpdatePayload'
            example:
              expand_json_depth: 3
              description: my updated description
              settings:
                delete_protected: false
      responses:
        '200':
          description: Updated
          headers:
            Ratelimit:
              $ref: '#/components/headers/RateLimit'
            RateLimitPolicy:
              $ref: '#/components/headers/RateLimitPolicy'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Dataset'
              example:
                name: My Dataset!
                slug: my-dataset-
                description: my updated description
                settings:
                  delete_protected: false
                expand_json_depth: 3
                created_at: '2022-07-21T18:39:23Z'
                last_written_at: '2022-09-22T17:32:03Z'
                regular_columns_count: 100
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '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
    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
    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
  responses:
    GenericError:
      description: Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    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'
    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.
    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'
    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'
    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'
  parameters:
    datasetSlug:
      name: datasetSlug
      description: 'The dataset slug.

        '
      in: path
      required: true
      schema:
        type: string
  schemas:
    Dataset:
      type: object
      description: 'Datasets are a collection of events from a specific source or related source.

        '
      required:
      - name
      properties:
        name:
          type: string
          description: The name of the dataset.
          example: My Dataset!
          minLength: 1
          maxLength: 255
        description:
          type: string
          default: ''
          description: A description for the dataset.
          example: A nice description of my dataset
          minLength: 0
          maxLength: 1024
        settings:
          type: object
          properties:
            delete_protected:
              type: boolean
              description: If true, the dataset cannot be deleted.
        expand_json_depth:
          type: integer
          description: The maximum unpacking depth of nested JSON fields.
          example: 3
          default: 0
          minimum: 0
          maximum: 10
        slug:
          type: string
          example: my-dataset-
          description: The 'slug' of the dataset to be used in URLs.
          readOnly: true
        regular_columns_count:
          type:
          - 'null'
          - integer
          description: 'The total number of unique fields for this Dataset. The value will be null if the dataset does not contain any fields yet.

            '
          example: 100
          readOnly: true
        last_written_at:
          type:
          - 'null'
          - string
          description: 'The ISO8601-formatted time when the dataset last received event data. The value will be null if no data has been received yet.

            '
          example: '2022-07-21T18:39:23Z'
          readOnly: true
        created_at:
          type: string
          description: The ISO8601-formatted time when the dataset was created.
          example: '2022-09-22T17:32:11Z'
          readOnly: true
        dataset_type:
          type: string
          description: 'The type of data contained in the dataset. Only present for time-series metrics datasets.

            '
          enum:
          - metrics
          example: metrics
          readOnly: true
    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.
    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
    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
    DatasetUpdatePayload:
      type: object
      description: an object to send to the Dataset API via PUT
      required:
      - description
      - expand_json_depth
      properties:
        description:
          type: string
          default: ''
          description: A description for the dataset.
          example: A nice description of my dataset
          minLength: 0
          maxLength: 1024
        expand_json_depth:
          type: integer
          description: The maximum unpacking depth of nested JSON fields.
          example: 3
          default: 0
          minimum: 0
          maximum: 10
        settings:
          type: object
          properties:
            delete_protected:
              type: boolean
              description: If true, the dataset cannot be deleted.
    DatasetCreationPayload:
      type: object
      description: an object to send to the Dataset API via PUT
      required:
      - name
      properties:
        name:
          type: string
          description: The name of the dataset.
          minLength: 1
          maxLength: 255
        description:
          type: string
          default: ''
          description: A description for the dataset.
          example: A nice description of my dataset
          minLength: 0
          maxLength: 1024
        expand_json_depth:
          type: integer
          description: The maximum unpacking depth of nested JSON fields.
          example: 3
          default: 0
          minimum: 0
          maximum: 10
    Error:
      x-tags:
      - Errors
      type: object
      description: A legacy error, containing only a textual description.
      properties:
        error:
          type: string
          readOnly: true
externalDocs:
  url: https://docs.honeycomb.io