> ## Documentation Index
> Fetch the complete documentation index at: https://docs.korve.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# environments

> Named per-project environments. Every project has implicit production and preview environments; create more to give env vars, databases, storage, and deploys an isolated scope.

Named per-project environments. Every project has implicit production and preview environments; create more to give env vars, databases, storage, and deploys an isolated scope.

## environments.list

List the project's environments — the implicit production and preview ones plus any custom environments.

```text theme={null}
GET /v1/orgs/{orgId}/projects/{projectId}/environments
```

* **Auth:** Organization API key (`Authorization: Bearer korve_...`) or dashboard session.
* **Minimum role:** `member`
* **Risk:** `read`

### Example

```bash theme={null}
curl "https://api.korve.dev/v1/orgs/$ORG_ID/projects/$PROJECT_ID/environments" \
  -H "Authorization: Bearer korve_..."
```

### Responses

| Status | Description                           |
| ------ | ------------------------------------- |
| `200`  | Environments, implicit ones first.    |
| `404`  | No such project in this organization. |

### Response body (200)

An array of objects with these fields:

| Field       | Type   | Description                                                                                                                                 |
| ----------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`        | string | —                                                                                                                                           |
| `name`      | string | —                                                                                                                                           |
| `slug`      | string | Environment address — unique per project. Pattern: `^[a-z][a-z0-9-]{0,38}$`.                                                                |
| `kind`      | string | The implicit environments carry kind "production"/"preview"; customer-created ones are "custom". One of: `production`, `preview`, `custom`. |
| `createdAt` | string | Format: `date-time`.                                                                                                                        |

## environments.create

Create a custom environment. The slug is derived from the name when omitted; "production" and "preview" are reserved for the implicit environments.

```text theme={null}
POST /v1/orgs/{orgId}/projects/{projectId}/environments
```

* **Auth:** Organization API key (`Authorization: Bearer korve_...`) or dashboard session.
* **Minimum role:** `admin`
* **Billing:** requires active organization billing — returns `402` otherwise.
* **Risk:** `write`

### Request body

| Field  | Type   | Required | Description                                                                                                     |
| ------ | ------ | -------- | --------------------------------------------------------------------------------------------------------------- |
| `name` | string | Yes      | Display name, 1-100 characters.                                                                                 |
| `slug` | string | No       | Environment address, unique per project. Derived from the name when omitted. Pattern: `^[a-z][a-z0-9-]{0,38}$`. |

### Example

```bash theme={null}
curl -X POST "https://api.korve.dev/v1/orgs/$ORG_ID/projects/$PROJECT_ID/environments" \
  -H "Authorization: Bearer korve_..." \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Storefront",
  "slug": "storefront"
}'
```

### Responses

| Status | Description                                                         |
| ------ | ------------------------------------------------------------------- |
| `201`  | Environment created.                                                |
| `402`  | Organization billing is not active.                                 |
| `404`  | No such project in this organization.                               |
| `409`  | An environment with that slug already exists on this project.       |
| `422`  | Invalid name or slug — or a reserved slug ("production"/"preview"). |

### Response body (201)

| Field       | Type   | Description                                                                                                                                 |
| ----------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`        | string | —                                                                                                                                           |
| `name`      | string | —                                                                                                                                           |
| `slug`      | string | Environment address — unique per project. Pattern: `^[a-z][a-z0-9-]{0,38}$`.                                                                |
| `kind`      | string | The implicit environments carry kind "production"/"preview"; customer-created ones are "custom". One of: `production`, `preview`, `custom`. |
| `createdAt` | string | Format: `date-time`.                                                                                                                        |

## environments.delete

Delete a custom environment with its env vars, database, storage objects, and deployment history. The implicit production and preview environments cannot be deleted. This cannot be undone.

```text theme={null}
DELETE /v1/orgs/{orgId}/projects/{projectId}/environments/{environmentId}
```

* **Auth:** Organization API key (`Authorization: Bearer korve_...`) or dashboard session.
* **Minimum role:** `admin`
* **Risk:** `destructive` · sensitive (elevated blast radius)

### Example

```bash theme={null}
curl -X DELETE "https://api.korve.dev/v1/orgs/$ORG_ID/projects/$PROJECT_ID/environments/$ENVIRONMENT_ID" \
  -H "Authorization: Bearer korve_..."
```

### Responses

| Status | Description                              |
| ------ | ---------------------------------------- |
| `200`  | Environment deleted.                     |
| `404`  | No such environment in this project.     |
| `422`  | Implicit environments cannot be deleted. |