# Environments API

> Create, list, get, update, and delete project-scoped test environments over the integrator API.

Environments are project-scoped, named test contexts (for example `staging`, `pre-prod`, `production`) that can be attached to test runs. Each environment has a globally-unique ULID assigned by the server and a human-readable `slug` that must be unique among live environments within a project.

## Create

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

`{projectId}` is the project **code** (for example `ACME`).

### Request body

| Field         | Required | Notes                                                                                                                                              |
| ------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`        | yes      | Non-empty string, max 120 characters                                                                                                               |
| `slug`        | yes      | Lowercase alphanumeric segments joined by single hyphens. No leading, trailing, or doubled hyphens. Examples: `staging`, `pre-prod`, `pre-prod-v2` |
| `description` | no       | Free-text description, max 2000 characters                                                                                                         |
| `url`         | no       | Valid URL, max 2000 characters                                                                                                                     |
| `isDefault`   | no       | `true` to mark as the project default. Atomically demotes any existing default. Defaults to `false`                                                |

Client-supplied `ulid` fields are rejected.

### Response

`201` with the created environment object. See [Response fields](#response-fields).

Duplicate live slug within the project returns `409 conflict`. Invalid slug format or empty `name` return `422 validation_failed`.

### Example

```bash
curl -sS -X POST \
  -H "Authorization: Bearer $PROBARA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Staging","slug":"staging","isDefault":true}' \
  "https://app.probara.net/api/v1/projects/ACME/environments"
```

## List

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

Returns the live (non-deleted) environments for the project, newest first. Page-based pagination.

### Query parameters

| Parameter  | Notes                                    |
| ---------- | ---------------------------------------- |
| `page`     | Page number (1-based, default `1`)       |
| `pageSize` | Items per page (default `50`, max `200`) |

### Response

`200` with `{ items, page, pageSize, total }`. Each item follows the [response shape](#response-fields).

### Example

```bash
curl -sS \
  -H "Authorization: Bearer $PROBARA_API_TOKEN" \
  "https://app.probara.net/api/v1/projects/ACME/environments"
```

## Get

`GET /api/v1/environments/{environmentUlid}`

Returns a single live environment scoped to the active organization.

Returns `404 not_found` when the environment is outside the active organization or has been deleted.

### Example

```bash
curl -sS \
  -H "Authorization: Bearer $PROBARA_API_TOKEN" \
  "https://app.probara.net/api/v1/environments/01JXXXXXXXXXXXXXXXXXXXXXXXXX"
```

## Update

`PATCH /api/v1/environments/{environmentUlid}`

Partial update. At least one field must be provided; an empty body returns `422 validation_failed`.

### Request body

| Field         | Required | Notes                                                                                             |
| ------------- | -------- | ------------------------------------------------------------------------------------------------- |
| `name`        | no       | Non-empty string, max 120 characters                                                              |
| `slug`        | no       | Same slug format rules as create                                                                  |
| `description` | no       | Max 2000 characters, or `null` to clear                                                           |
| `url`         | no       | Valid URL, or `null` to clear                                                                     |
| `isDefault`   | no       | `true` to promote this environment as the project default; atomically demotes the current default |

Duplicate live slug returns `409 conflict`. Returns `404 not_found` when the environment is outside the active organization.

### Example

```bash
curl -sS -X PATCH \
  -H "Authorization: Bearer $PROBARA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Pre-production","isDefault":false}' \
  "https://app.probara.net/api/v1/environments/01JXXXXXXXXXXXXXXXXXXXXXXXXX"
```

## Delete

`DELETE /api/v1/environments/{environmentUlid}`

Soft-deletes the environment. Returns `204` on success. Subsequent `GET` returns `404 not_found` and the environment is excluded from list results.

Returns `404 not_found` when the environment is outside the active organization.

### Example

```bash
curl -sS -X DELETE \
  -H "Authorization: Bearer $PROBARA_API_TOKEN" \
  "https://app.probara.net/api/v1/environments/01JXXXXXXXXXXXXXXXXXXXXXXXXX"
```

## Response fields

All mutating endpoints (`POST`, `PATCH`) and `GET /api/v1/environments/{environmentUlid}` return a single environment object with the following fields.

| Field         | Type           | Notes                                           |
| ------------- | -------------- | ----------------------------------------------- |
| `ulid`        | string (ULID)  | Server-assigned unique identifier               |
| `projectUlid` | string (ULID)  | The project this environment belongs to         |
| `name`        | string         | Display name                                    |
| `slug`        | string         | URL-safe identifier                             |
| `description` | string \| null | Optional description                            |
| `url`         | string \| null | Optional URL                                    |
| `isDefault`   | boolean        | Whether this is the project default environment |
| `createdAt`   | number         | Unix epoch milliseconds                         |
| `updatedAt`   | number         | Unix epoch milliseconds                         |

## Audit events

Environment mutations emit `environment.created`, `environment.updated`, and `environment.deleted` on the organization activity feed. See [Audit events](https://docs.probara.net/en/developers/api/audit-events/).