openapi: 3.1.0
info:
  title: Honeycomb Environments API
  description: >-
    The Honeycomb Environments API provides administrative capabilities for
    managing environments within a Honeycomb team. Environments allow
    organizations to separate telemetry data across different stages such
    as development, staging, and production. The API supports listing,
    creating, updating, and deleting environments, along with the Auth API
    for validating API keys and determining their associated team and
    environment permissions. The Key Management API enables listing,
    creating, updating, and deleting API keys for a team.
  version: '1.0'
  contact:
    name: Honeycomb Support
    url: https://support.honeycomb.io
  termsOfService: https://www.honeycomb.io/terms-of-service
externalDocs:
  description: Honeycomb Environments API Documentation
  url: https://api-docs.honeycomb.io/api/environments
servers:
  - url: https://api.honeycomb.io
    description: Honeycomb Production API
tags:
  - name: Auth
    description: >-
      Validate API key authentication and determine associated team and
      environment permissions.
  - name: Environments
    description: >-
      Manage environments within a Honeycomb team for separating telemetry data
      across stages.
  - name: Key Management
    description: >-
      Manage API keys for a team, including listing, creating, updating, and
      deleting keys.
security:
  - ApiKeyAuth: []
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
    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
  /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
    put:
      operationId: updateEnvironment
      summary: Update an environment
      description: >-
        Updates an environment's name, description, or color.
      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
    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
  /1/auth:
    get:
      operationId: getAuth
      summary: Authenticate API key
      description: >-
        Validates authentication for a key and returns the team and environment
        that the key belongs to.
      tags:
        - Auth
      responses:
        '200':
          description: Successful authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthInfo'
        '401':
          description: Unauthorized - invalid API key
  /1/auth/permissions:
    get:
      operationId: listAuthorizations
      summary: List authorizations
      description: >-
        Determines what authorizations have been granted to the API key.
      tags:
        - Auth
      responses:
        '200':
          description: List of authorizations for the key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthPermissions'
        '401':
          description: Unauthorized - invalid API key
  /1/api_keys:
    get:
      operationId: listApiKeys
      summary: List all API keys
      description: >-
        Returns a list of all API keys for the team.
      tags:
        - Key Management
      responses:
        '200':
          description: A list of API keys
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ApiKey'
        '401':
          description: Unauthorized
    post:
      operationId: createApiKey
      summary: Create an API key
      description: >-
        Creates a new API key for the team with specified permissions and
        environment scope.
      tags:
        - Key Management
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiKeyCreateRequest'
      responses:
        '201':
          description: API key created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKey'
        '401':
          description: Unauthorized
  /1/api_keys/{keyId}:
    get:
      operationId: getApiKey
      summary: Get an API key
      description: >-
        Returns a single API key by its ID.
      tags:
        - Key Management
      parameters:
        - $ref: '#/components/parameters/keyId'
      responses:
        '200':
          description: API key details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKey'
        '401':
          description: Unauthorized
        '404':
          description: API key not found
    put:
      operationId: updateApiKey
      summary: Update an API key
      description: >-
        Updates an API key's name, permissions, or disabled status.
      tags:
        - Key Management
      parameters:
        - $ref: '#/components/parameters/keyId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiKeyUpdateRequest'
      responses:
        '200':
          description: API key updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKey'
        '401':
          description: Unauthorized
        '404':
          description: API key not found
    delete:
      operationId: deleteApiKey
      summary: Delete an API key
      description: >-
        Deletes an API key.
      tags:
        - Key Management
      parameters:
        - $ref: '#/components/parameters/keyId'
      responses:
        '204':
          description: API key deleted
        '401':
          description: Unauthorized
        '404':
          description: API key not found
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Honeycomb-Team
      description: >-
        Honeycomb Configuration API key with appropriate administrative
        permissions.
  parameters:
    environmentId:
      name: environmentId
      in: path
      required: true
      description: >-
        The unique identifier for the environment.
      schema:
        type: string
    keyId:
      name: keyId
      in: path
      required: true
      description: >-
        The unique identifier for the API key.
      schema:
        type: string
  schemas:
    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.
    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.
    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.
    AuthInfo:
      type: object
      properties:
        team:
          type: object
          description: >-
            The team associated with the API key.
          properties:
            slug:
              type: string
              description: >-
                The slug identifier for the team.
            name:
              type: string
              description: >-
                The display name of the team.
        environment:
          type: object
          description: >-
            The environment associated with the API key, if applicable.
          properties:
            slug:
              type: string
              description: >-
                The slug identifier for the environment.
            name:
              type: string
              description: >-
                The display name of the environment.
    AuthPermissions:
      type: object
      properties:
        api_key_access:
          type: object
          description: >-
            The permissions and access levels granted to the API key.
          additionalProperties:
            type: boolean
    ApiKey:
      type: object
      properties:
        id:
          type: string
          description: >-
            Unique identifier for the API key.
        name:
          type: string
          description: >-
            The display name of the API key.
        type:
          type: string
          description: >-
            The type of API key.
          enum:
            - configuration
            - ingest
        disabled:
          type: boolean
          description: >-
            Whether the API key is disabled.
        permissions:
          type: object
          description: >-
            The permissions granted to this API key.
          additionalProperties:
            type: boolean
        environment_id:
          type: string
          description: >-
            The environment this key is scoped to, if applicable.
        secret:
          type: string
          description: >-
            The API key secret, only returned upon creation.
        created_at:
          type: string
          format: date-time
          description: >-
            ISO8601 formatted time the API key was created.
    ApiKeyCreateRequest:
      type: object
      required:
        - name
        - type
      properties:
        name:
          type: string
          description: >-
            The display name for the API key.
        type:
          type: string
          enum:
            - configuration
            - ingest
        permissions:
          type: object
          description: >-
            The permissions to grant to this API key.
          additionalProperties:
            type: boolean
        environment_id:
          type: string
          description: >-
            The environment to scope this key to.
    ApiKeyUpdateRequest:
      type: object
      properties:
        name:
          type: string
          description: >-
            An updated display name for the API key.
        disabled:
          type: boolean
          description: >-
            Whether to disable the API key.
        permissions:
          type: object
          description: >-
            Updated permissions for the API key.
          additionalProperties:
            type: boolean