Working with Environments (v2)

Environments help organize your Honeycomb data and API keys by deployment stage (production, staging, etc.). This v2 API requires Management Key authentication.

Management Key Required

The Environments API requires a Management Key (not a regular API key). See Authentication for setup.

Automatic Pagination

The list() and list_async() methods automatically paginate through all results. For teams with many environments, this may result in multiple API requests. The default rate limit is 100 requests per minute per operation. If you need higher limits, contact Honeycomb support.

Basic Environment Operations

List Environments

async def list_environments(client: HoneycombClient) -> list[Environment]:
    """List all environments in a team.

    Args:
        client: HoneycombClient with management key

    Returns:
        List of environments
    """
    environments = await client.environments.list_async()
    for env in environments:
        color = f" ({env.color.value})" if env.color else ""
        print(f"{env.name}{color}: {env.slug}")
    return environments

Get a Specific Environment

async def get_environment(client: HoneycombClient, env_id: str) -> Environment:
    """Get a specific environment by ID.

    Args:
        client: HoneycombClient with management key
        env_id: Environment ID

    Returns:
        The environment object
    """
    env = await client.environments.get_async(env_id)
    print(f"Name: {env.name}")
    print(f"Slug: {env.slug}")
    print(f"Description: {env.description}")
    print(f"Delete Protected: {env.delete_protected}")
    return env

Create an Environment

async def create_environment(client: HoneycombClient) -> str:
    """Create a new environment.

    Args:
        client: HoneycombClient with management key

    Returns:
        The created environment ID
    """
    env = await client.environments.create_async(
        name="Staging",
        description="Staging environment for testing",
        color="blue",
    )
    return env.id

Update an Environment

async def update_environment(client: HoneycombClient, env_id: str) -> Environment:
    """Update an environment's properties.

    Args:
        client: HoneycombClient with management key
        env_id: Environment ID to update

    Returns:
        The updated environment
    """
    updated = await client.environments.update_async(
        env_id,
        description="Updated: Staging environment for pre-production testing",
        color="green",
        delete_protected=True,  # Prevent accidental deletion
    )
    return updated

Delete an Environment

Warning

Deleting an environment cannot be undone. Enable delete protection for critical environments.

async def delete_environment(client: HoneycombClient, env_id: str) -> None:
    """Delete an environment.

    Args:
        client: HoneycombClient with management key
        env_id: Environment ID to delete

    Note: If the environment is delete_protected, this will fail with a 409 error.
    """
    await client.environments.delete_async(env_id)

Environment Colors

Available colors: BLUE, GREEN, GOLD, RED, PURPLE, LIGHT_BLUE, LIGHT_GREEN, LIGHT_GOLD, LIGHT_RED, LIGHT_PURPLE

Note: CLASSIC is a special read-only color for auto-created Classic environments.

Sync Usage

All environment operations have sync equivalents:

with HoneycombClient(
    management_key="hcamk_xxx",
    management_secret="xxx",
    sync=True
) as client:
    envs = client.environments.list("my-team")
    env = client.environments.get("my-team", env_id)
    env = client.environments.create("my-team", EnvironmentCreate(...))
    updated = client.environments.update("my-team", env_id, EnvironmentUpdate(...))
    client.environments.delete("my-team", env_id)

Delete Protection

Use delete_protected=True in EnvironmentUpdate to prevent accidental deletion of critical environments. To delete a protected environment, first disable protection via update.