Skip to content
Plune Plune Plune Docs

Rename an environment

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

The project owner’s. The past runs of the old name in any spelling, the ones in the Bin too, take the new name, so they do not fall into seen; the entry of the feed says how many (runsRenamed). The active saved widgets of the project follow (#2119): a filter or a segment by environment on the old name in any spelling takes the new one, in the same transaction (widgetsRewritten and widgetIds in the entry). A run reported later under the old name is a seen value. A name another environment has is a 409; the same name in another case is a rename. A name runs already report outside the list, the ones in the Bin too, would make those runs and these one environment: without merge: true that is a 409 saying how many runs have it (mergeRuns), and nothing is written; with it the rename goes ahead and the entry says merged. A rename that would rewrite more than 50000 runs is a 413, before anything is written.

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters ”
id
required
string

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
merge

Confirms a rename onto a name runs already report outside the list, the ones in the Bin too (#2119): those runs and the runs of this environment become one environment, which cannot be split again. Without it that rename is a 409 with mergeRuns.

boolean
Examples

Rename

{
  "name": "stage"
}

Responses

Section titled “ Responses ”

200

Section titled “200 ”

The environment under its new name

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": "stage",
  "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"
}

404

Section titled “404 ”

No such environment in the project

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

409

Section titled “409 ”

Another environment has the name (no mergeRuns), or runs already report it outside the list and merge was not sent

Media type application/json
object
error
required
string
mergeRuns

The runs that already report the new name outside the list, the ones in the Bin too (error says how many of them are there): the ones the rename would merge with this environment.

integer
>= 1
Examples
{
  "error": "an environment named 'production' is already in the list (an archived one counts)"
}

413

Section titled “413 ”

The rename would rewrite more than 50000 runs

Media type application/json
object
error
required
string
Example 
{
  "error": "the rename would rewrite 61204 runs of 'staging', and one rename of an environment rewrites at most 50000"
}

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