# Environments

Environment management within projects

Source: https://keyenv.dev/docs/api/environments/

Environment management within projects

## List environments

```http
GET /api/v1/projects/{projectId}/environments
```

Returns all environments in a project

**Operation ID:** `listEnvironments` &middot; **Authentication:** `Authorization: Bearer <token>`

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | `string` | yes | Project UUID or slug (e.g., "my-project") |

### Responses

| Status | Description | Body |
| --- | --- | --- |
| `200` | List of environments | `object` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |
| `404` | Resource not found | `Error` |

### Response body (`200`)

| Field | Type | Description |
| --- | --- | --- |
| `environments` | `object[]` |  |

### Example

```bash
curl -X GET "https://api.keyenv.dev/api/v1/projects/{projectId}/environments" \
  -H "Authorization: Bearer $KEYENV_TOKEN"
```

## Create environment

```http
POST /api/v1/projects/{projectId}/environments
```

Creates a new environment in a project. Can optionally inherit secrets from another environment.

**Operation ID:** `createEnvironment` &middot; **Authentication:** `Authorization: Bearer <token>`

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | `string` | yes | Project UUID or slug (e.g., "my-project") |

### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | `string` | yes |  |
| `inherits_from` | `string (uuid)` | no | Parent environment ID for secret inheritance |

### Responses

| Status | Description | Body |
| --- | --- | --- |
| `201` | Environment created | `Environment` |
| `400` | Invalid request | `Error` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |
| `429` | Plan limit exceeded | `LimitError` |

### Response body (`201`)

| Field | Type | Description |
| --- | --- | --- |
| `id` | `string (uuid)` |  |
| `project_id` | `string (uuid)` |  |
| `name` | `string` |  |
| `inherits_from` | `string (uuid)` |  |
| `created_at` | `string (date-time)` |  |

### Example

```bash
curl -X POST "https://api.keyenv.dev/api/v1/projects/{projectId}/environments" \
  -H "Authorization: Bearer $KEYENV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"string","inherits_from":"00000000-0000-0000-0000-000000000000"}'
```

## Get environment

```http
GET /api/v1/projects/{projectId}/environments/{environmentId}
```

Returns environment details

**Operation ID:** `getEnvironment` &middot; **Authentication:** `Authorization: Bearer <token>`

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | `string` | yes | Project UUID or slug (e.g., "my-project") |
| `environmentId` | `string` | yes | Environment UUID or name (e.g., "development", "staging", "production") |

### Responses

| Status | Description | Body |
| --- | --- | --- |
| `200` | Environment details | `Environment` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |
| `404` | Resource not found | `Error` |

### Response body (`200`)

| Field | Type | Description |
| --- | --- | --- |
| `id` | `string (uuid)` |  |
| `project_id` | `string (uuid)` |  |
| `name` | `string` |  |
| `inherits_from` | `string (uuid)` |  |
| `created_at` | `string (date-time)` |  |

### Example

```bash
curl -X GET "https://api.keyenv.dev/api/v1/projects/{projectId}/environments/{environmentId}" \
  -H "Authorization: Bearer $KEYENV_TOKEN"
```

## Delete environment

```http
DELETE /api/v1/projects/{projectId}/environments/{environmentId}
```

Deletes an environment and all its secrets. Cannot delete default environments (development, staging, production).

**Operation ID:** `deleteEnvironment` &middot; **Authentication:** `Authorization: Bearer <token>`

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | `string` | yes | Project UUID or slug (e.g., "my-project") |
| `environmentId` | `string` | yes | Environment UUID or name (e.g., "development", "staging", "production") |

### Responses

| Status | Description | Body |
| --- | --- | --- |
| `204` | Environment deleted |  |
| `400` | Invalid request | `Error` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |
| `404` | Resource not found | `Error` |

### Example

```bash
curl -X DELETE "https://api.keyenv.dev/api/v1/projects/{projectId}/environments/{environmentId}" \
  -H "Authorization: Bearer $KEYENV_TOKEN"
```