Skip to content
Plune Plune Plune Docs

Add an environment to the list

POST
/v1/environments
 
curl --request POST \
  --url https://beta-api.plune.ai/v1/environments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "staging" }'

The project owner’s. The first one makes the project’s system field. «Add to list» of a seen value is this call with its name. A name the list already has by the same rule, an archived one too, is a 409, and so is the 101st environment (the archived ones count). An entry of the feed about the field.

Authorizations

Section titled “Authorizations ”

Request Body required

Section titled “Request Body required ”
Media type application/json
object
name
required

Trimmed of spaces, tabs, carriage returns and line feeds at either end (a no-break space stays). The value a run is written with.

string
>= 1 characters <= 64 characters
Example 
{
  "name": "staging"
}

Responses

Section titled “ Responses ”

201

Section titled “201 ”

Added, at the end of the list, with its runs counted

Media type application/json

An environment of the project’s list (#1252, ADR 0071): an option of its system field, whose name is the value a run carries in environment.

object
id
required

The option’s id: never changes and is never reused.

string
name
required
string
>= 1 characters <= 64 characters
archivedAt
required

Set while archived: one not to offer for new runs. The runs keep it, and a run that reports it is still taken.

string format: date-time
nullable
runs
required

The live runs of the project whose environment is this name lower-cased and trimmed of spaces, tabs, carriage returns and line feeds: «Staging» and «staging » count as one.

integer
lastRunAt
required

When the newest of those runs started.

string format: date-time
nullable
Example 
{
  "id": "opt_5e1a9c07d2",
  "name": "staging",
  "archivedAt": null,
  "runs": 48,
  "lastRunAt": "2026-09-16T09:12:04.151Z"
}

400

Section titled “400 ”

Invalid body: a name of 1 to 64 characters

Media type application/json
object
error
required
string
Example 
{
  "error": "validation failed — name: an environment needs a name"
}

401

Section titled “401 ”

No / invalid token or session

403

Section titled “403 ”

You are in the project, but not as its owner

Media type application/json
object
error
required
string
Example 
{
  "error": "project owner only"
}

409

Section titled “409 ”

The name is in the list already, or the list holds 100

Media type application/json
object
error
required
string
Example 
{
  "error": "an environment named 'staging' is already in the list (an archived one counts)"
}

429

Section titled “429 ”

Rate-limited: the per-route throttle, or the per-minute request limit of the plan an API token counts by (#1442; the body names the plan, #2092). Retry-After carries the seconds until the window rolls over.

Media type application/json
object
error
required
string
Example generated
{
  "error": "example"
}

Headers

Section titled “Headers ”
Retry-After
integer

Seconds until the window rolls over