Honeycomb Environments API

openapi: 3.2.0
info:
  title: Honeycomb Environments API
  version: '1.0'
  description: 'Operations tagged Environments 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: Environments
  description: Manage environments within a Honeycomb team for separating telemetry data across stages.
paths:
  /1/environments:
    get:
      operationId: listEnvironments
      summary: List all environments
      description: Returns a list of all environments within the team.
      tags:
      - Environments
      responses:
        '200':
          description: A list of environments
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Environment'
        '401':
          description: Unauthorized
      security:
      - ApiKeyAuth: []
    post:
      operationId: createEnvironment
      summary: Create an environment
      description: Creates a new environment for separating telemetry data across stages such as development, staging, and production.
      tags:
      - Environments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EnvironmentCreateRequest'
      responses:
        '201':
          description: Environment created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Environment'
        '401':
          description: Unauthorized
      security:
      - ApiKeyAuth: []
    servers:
    - url: https://api.honeycomb.io
      description: Honeycomb Production API
  /1/environments/{environmentId}:
    get:
      operationId: getEnvironment
      summary: Get an environment
      description: Returns a single environment by its ID.
      tags:
      - Environments
      parameters:
      - $ref: '#/components/parameters/environmentId'
      responses:
        '200':
          description: Environment details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Environment'
        '401':
          description: Unauthorized
        '404':
          description: Environment not found
      security:
      - ApiKeyAuth: []
    put:
      operationId: updateEnvironment
      summary: Update an environment
      description: Updates an environment's properties.
      tags:
      - Environments
      parameters:
      - $ref: '#/components/parameters/environmentId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EnvironmentUpdateRequest'
      responses:
        '200':
          description: Environment updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Environment'
        '401':
          description: Unauthorized
        '404':
          description: Environment not found
      security:
      - ApiKeyAuth: []
    delete:
      operationId: deleteEnvironment
      summary: Delete an environment
      description: Deletes an environment.
      tags:
      - Environments
      parameters:
      - $ref: '#/components/parameters/environmentId'
      responses:
        '204':
          description: Environment deleted
        '401':
          description: Unauthorized
        '404':
          description: Environment not found
      security:
      - ApiKeyAuth: []
    servers:
    - url: https://api.honeycomb.io
      description: Honeycomb Production API
  /2/teams/{teamSlug}/environments:
    parameters:
    - $ref: '#/components/parameters/teamSlug'
    get:
      security:
      - bearerAuth:
        - environments:read
      tags:
      - Environments
      summary: List all Environments
      operationId: get2TeamsByTeamSlugEnvironments
      parameters:
      - $ref: '#/components/parameters/PaginationCursor'
      - $ref: '#/components/parameters/PaginationSize'
      responses:
        '200':
          description: Success
          headers:
            Ratelimit:
              $ref: '#/components/headers/RateLimit'
            RateLimitPolicy:
              $ref: '#/components/headers/RateLimitPolicy'
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/EnvironmentListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationFailed'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
      x-operation-id-source: normalized
      x-operation-id-original: listEnvironments
    post:
      security:
      - bearerAuth:
        - environments:write
      tags:
      - Environments
      summary: Create an Environment
      operationId: post2TeamsByTeamSlugEnvironments
      requestBody:
        required: true
        content:
          application/vnd.api+json:
            schema:
              $ref: '#/components/schemas/CreateEnvironmentRequest'
      responses:
        '201':
          description: Created
          headers:
            Ratelimit:
              $ref: '#/components/headers/RateLimit'
            RateLimitPolicy:
              $ref: '#/components/headers/RateLimitPolicy'
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/EnvironmentResponse'
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/ValidationFailed'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
      x-operation-id-source: normalized
      x-operation-id-original: createEnvironment
    servers:
    - url: https://api.honeycomb.io
    - url: https://api.eu1.honeycomb.io
  /2/teams/{teamSlug}/environments/{ID}:
    parameters:
    - $ref: '#/components/parameters/teamSlug'
    - $ref: '#/components/parameters/ID'
    get:
      security:
      - bearerAuth:
        - environments:read
      tags:
      - Environments
      summary: Get an Environment
      operationId: get2TeamsByTeamSlugEnvironmentsByID
      responses:
        '200':
          description: Success
          headers:
            Ratelimit:
              $ref: '#/components/headers/RateLimit'
            RateLimitPolicy:
              $ref: '#/components/headers/RateLimitPolicy'
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/EnvironmentResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
      x-operation-id-source: normalized
      x-operation-id-original: getEnvironment
    patch:
      security:
      - bearerAuth:
        - environments:write
      tags:
      - Environments
      summary: Update an Environment
      operationId: patch2TeamsByTeamSlugEnvironmentsByID
      requestBody:
        required: true
        content:
          application/vnd.api+json:
            schema:
              $ref: '#/components/schemas/UpdateEnvironmentRequest'
      responses:
        '200':
          description: Success
          headers:
            Ratelimit:
              $ref: '#/components/headers/RateLimit'
            RateLimitPolicy:
              $ref: '#/components/headers/RateLimitPolicy'
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/EnvironmentResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/ValidationFailed'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
      x-operation-id-source: normalized
      x-operation-id-original: updateEnvironment
    delete:
      security:
      - bearerAuth:
        - environments:write
      tags:
      - Environments
      summary: Delete an Environment
      description: 'This deletes and immediately deactivates the Environment. This is an irreversible operation.


        Environments with Deletion Protection enabled cannot be deleted. To delete an Environment with Deletion Protection enabled, first disable Deletion Protection by updating the Environment with `settings.delete_protected = false`.'
      operationId: delete2TeamsByTeamSlugEnvironmentsByID
      responses:
        '204':
          description: No Content
          headers:
            Ratelimit:
              $ref: '#/components/headers/RateLimit'
            RateLimitPolicy:
              $ref: '#/components/headers/RateLimitPolicy'
        '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'
        '500':
          $ref: '#/components/responses/InternalError'
      x-operation-id-source: normalized
      x-operation-id-original: deleteEnvironment
    servers:
    - url: https://api.honeycomb.io
    - url: https://api.eu1.honeycomb.io
components:
  parameters:
    environmentId:
      name: environmentId
      in: path
      required: true
      description: The unique identifier for the environment.
      schema:
        type: string
    PaginationSize:
      name: page[size]
      description: The number of entries to include per response. Maximum value is 100.
      in: query
      schema:
        type: number
        minimum: 1
        maximum: 100
        default: 20
      example: 10
    PaginationCursor:
      name: page[after]
      description: 'The string value of the `next` attribute from a previous result page.

        The cursor value must be empty or omitted for the first request of a cursor-paginated query.

        '
      in: query
      schema:
        type: string
      example: eyxJjcmAVhdGVkX
    ID:
      name: ID
      description: A unique identifier
      in: path
      required: true
      schema:
        type: string
    teamSlug:
      name: teamSlug
      description: The slug of the Team
      in: path
      required: true
      schema:
        type: string
  schemas:
    EnvironmentUpdateRequest:
      type: object
      properties:
        name:
          type: string
          description: An updated display name for the environment.
        description:
          type: string
          description: An updated description for the environment.
        color:
          type: string
          description: An updated color for the environment.
    EnvironmentCreateRequest:
      type: object
      required:
      - name
      properties:
        name:
          type: string
          description: The display name for the environment.
        description:
          type: string
          description: An optional description for the environment.
        color:
          type: string
          description: An optional color for the environment.
    Environment:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the environment.
        name:
          type: string
          description: The display name of the environment.
        slug:
          type: string
          description: The URL-safe slug identifier for the environment.
        description:
          type: string
          description: A description of the environment.
        color:
          type: string
          description: A color associated with the environment for UI display.
        created_at:
          type: string
          format: date-time
          description: ISO8601 formatted time the environment was created.
        updated_at:
          type: string
          format: date-time
          description: ISO8601 formatted time the environment 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.
    Error:
      x-tags:
      - Errors
      type: object
      description: A legacy error, containing only a textual description.
      properties:
        error:
          type: string
          readOnly: true
    EnvironmentListResponse:
      type: object
      required:
      - data
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Environment_2'
        links:
          $ref: '#/components/schemas/PaginationLinks'
    CreateEnvironmentRequest:
      type: object
      required:
      - data
      properties:
        data:
          type: object
          required:
          - type
          - attributes
          properties:
            type:
              type: string
              enum:
              - environments
            attributes:
              type: object
              required:
              - name
              properties:
                name:
                  type: string
                  maxLength: 255
                description:
                  type: string
                  maxLength: 255
                color:
                  $ref: '#/components/schemas/EnvironmentColor'
    Environment_2:
      type: object
      required:
      - id
      - type
      - links
      - attributes
      properties:
        id:
          type: string
        type:
          type: string
          enum:
          - environments
        links:
          type: object
          required:
          - self
          properties:
            self:
              type: string
        attributes:
          type: object
          required:
          - name
          - description
          - color
          - slug
          - settings
          properties:
            name:
              type: string
            description:
              type: string
            color:
              description: '''classic'' color is used only for auto-created Classic environments and cannot be set on any other environment. Classic environments cannot be set to any other color.

                '
              oneOf:
              - $ref: '#/components/schemas/EnvironmentColor'
              - type: string
                enum:
                - classic
            slug:
              type: string
            settings:
              type: object
              required:
              - delete_protected
              properties:
                delete_protected:
                  type: boolean
                  description: If true, the environment cannot be deleted.
    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
    EnvironmentColor:
      type: string
      enum:
      - blue
      - green
      - gold
      - red
      - purple
      - lightBlue
      - lightGreen
      - lightGold
      - lightRed
      - lightPurple
    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
    PaginationLinks:
      type: object
      description: Links to iterate through the pages of results.
      required:
      - next
      properties:
        next:
          type:
          - string
          - 'null'
          description: The URL for the next page of results.
          readOnly: true
          example: /2/teams/my-team/api-keys?page[after]=3025fa645ad1100d&page[size]=10
    EnvironmentResponse:
      type: object
      required:
      - data
      properties:
        data:
          $ref: '#/components/schemas/Environment_2'
    UpdateEnvironmentRequest:
      type: object
      required:
      - data
      properties:
        data:
          type: object
          required:
          - id
          - type
          - attributes
          properties:
            id:
              type: string
            type:
              type: string
              enum:
              - environments
            attributes:
              type: object
              properties:
                description:
                  type: string
                  maxLength: 255
                color:
                  $ref: '#/components/schemas/EnvironmentColor'
                settings:
                  type: object
                  properties:
                    delete_protected:
                      type: boolean
                      description: If true, the environment cannot be deleted.
  responses:
    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'
    PayloadTooLarge:
      description: The provided request body was over the maximum allowed size.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DetailedError'
          example:
            status: 413
            type: https://api.honeycomb.io/problems/payload-too-large
            title: Request body is too large.
            error: Body size is larger than maximum size of 100000 bytes
    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.
    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'
    InternalError:
      description: InternalError
      content:
        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
    UnsupportedMediaType:
      description: The provided request body had an invalid Content-Type.
      content:
        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'
  headers:
    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
    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
  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