Rename an existing test environment, such as changing Staging to UAT. Start by finding the environment by name, then use its returned identifier for the update. The environment keeps that identifier after it is renamed.

Endpoints

Action	Method	Endpoint
Find the environment by name	GET	`/api/v2/properties/environments`
Rename the selected environment	PUT	`/api/v2/properties/environment/{environmentIdentifier}`

Add the endpoint path to your Vansah base URL. Any value in braces, such as {identifier}, is a placeholder; the steps below show how to obtain and supply it.

Before you begin

Create a Vansah API token with Jira access configured. The token account needs Jira administrator or Jira space administrator permission. Choose a new name not used by another active environment in the same Jira space.

The examples use Bash and cURL. Set VANSAH_URL to your Vansah base URL without a trailing slash and VANSAH_TOKEN to your API token. Replace the sample Jira space key and names with your values.

1. Find the environment by name

Endpoint: GET /api/v2/properties/environments

curl --request GET --get \
  --url "$VANSAH_URL/api/v2/properties/environments" \
  --header "Authorization: $VANSAH_TOKEN" \
  --header "Accept: application/json" \
  --data-urlencode "projectKey=DEMO" \
  --data-urlencode "startAt=0"

Example response for a Jira space with one active environment:

{
  "success": true,
  "message": "Environments returned successfully",
  "pagination": {
    "total": 1,
    "startAt": 0,
    "limit": 50
  },
  "data": [
    {
      "identifier": "f94d0e7d-1edb-41ed-bdf2-ae827922bf87",
      "name": "Staging"
    }
  ]
}

Find the row named Staging, or the environment you want to rename. Copy that row’s identifier into this Bash variable:

ENVIRONMENT_IDENTIFIER='f94d0e7d-1edb-41ed-bdf2-ae827922bf87'

The example value matches the sample response. Replace it with the value returned for your environment. The rename URL requires this identifier; this endpoint does not accept an environment name or readable key in that URL.

The list returns 50 records per page. If needed, use offsets of 50, 100, and so on to find the desired name. See List Test Environments.

2. Prepare the new name

Endpoint: PUT /api/v2/properties/environment/{environmentIdentifier}

Save this complete body as rename-environment.json:

{
  "name": "UAT",
  "project": {
    "key": "DEMO"
  }
}

Parent object	JSON field	Type	Example value	Use
Request body	`name`	String	`"UAT"`	Required. The new nonempty name, 1–255 characters. Use plain text.
`project`	`key`	String	`"DEMO"`	The Jira space key containing the environment. Use the same space as the lookup.

JSON path project.key refers to the Jira space key. The identifier from step 1 goes in the URL, not in this request body.

3. Send the rename request

Endpoint: PUT /api/v2/properties/environment/{environmentIdentifier}

curl --request PUT \
  --url "$VANSAH_URL/api/v2/properties/environment/$ENVIRONMENT_IDENTIFIER" \
  --header "Authorization: $VANSAH_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data-binary @rename-environment.json

Header	Value
`Authorization`	Your Vansah API token directly, without a Bearer prefix.
`Content-Type`	`application/json`
`Accept`	`application/json`

Run the command from the directory containing rename-environment.json, after setting the variable in step 1. This update does not use pagination or filtering parameters.

4. Confirm the new name

Endpoint: GET /api/v2/properties/environments

A successful update returns HTTP 200:

{
  "success": true,
  "message": "Updated successfully",
  "data": {
    "identifier": "f94d0e7d-1edb-41ed-bdf2-ae827922bf87",
    "name": "UAT"
  }
}

The response keeps the same identifier and returns the saved name in JSON path data.name. List the environments again and confirm the new name appears.

Update your automation configuration to use the new environment name. A Test Run request using the old name can create another environment with that old name. Follow Create a Test Run for the name-based request format.

Errors and troubleshooting

A name already used by another active environment returns HTTP 400, for example:

{
  "success": false,
  "errorCode": 1390,
  "message": "Duplicate environment(UAT)",
  "data": []
}

HTTP status	Meaning
`400`	Invalid name or identifier, wrong Jira space, deleted or missing environment, duplicate name, or an update failure.
`401`	Missing, invalid, expired, or inactive token, missing Jira authorization, or rejected authentication during permission lookup.
`403`	The account is blocked or lacks administrator permission.
`503`	Jira permission lookup is temporarily unavailable; errorCode 1400.

Message or issue	What to check
`One or more validation errors found.`	Read JSON path `data.errors`. Check the new name and copy the identifier from the list response.
`Invalid environment identifier(...)`	Repeat the lookup in the same Jira space. The environment must be active; deleted environments cannot be renamed here.
`Duplicate environment(UAT)`	Choose a name not already used by another active environment in that space.
`Something went wrong while Updating Environment`	Read the environment list before retrying. If the issue continues, contact Vansah Support with the endpoint and response after removing your token.

Missing-environment, duplicate-name, and controller failures use errorCode 1390. Field-validation errors can include an errors array without an error code.

Rename a Test Environment (API)