Environments 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.

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

Example

curl -sS -X POST \
  -H "Authorization: Bearer $PROBARA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Staging","slug":"staging","isDefault":true}' \
  "https://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.

Example

curl -sS \
  -H "Authorization: Bearer $PROBARA_API_TOKEN" \
  "https://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

curl -sS \
  -H "Authorization: Bearer $PROBARA_API_TOKEN" \
  "https://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

curl -sS -X PATCH \
  -H "Authorization: Bearer $PROBARA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Pre-production","isDefault":false}' \
  "https://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

curl -sS -X DELETE \
  -H "Authorization: Bearer $PROBARA_API_TOKEN" \
  "https://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.