Use this API to rename an existing Vansah test environment, such as changing Staging to UAT. The environment keeps its existing identifier.

Before you begin

Create a Vansah API token and use the Vansah URL supplied for your workspace.
Use an account with Jira administrator or space administrator permissions for the space you want to update.
Have the Jira space key and the identifier of an active environment in that 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 DEMO with your Jira space key. Keep the token private.

Endpoint and headers

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

Replace {environmentIdentifier} with the environment’s UUID. Use the identifier returned by the list endpoint below, rather than the environment name.

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

1. Find the environment identifier

List the space’s active environments:

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

Example response:

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

Find the environment you want to rename and copy its identifier. The list is sorted by name and excludes deleted environments and the - placeholder.

This endpoint returns up to 50 environments per page. startAt is the number of records to skip and defaults to 0. To continue, use startAt=50, then 100, until you have retrieved pagination.total records. Use whole numbers of zero or greater. The page size is fixed at 50; sending a different limit does not change it. There is no name-search parameter on this endpoint.

2. Prepare the new name

Field	Requirements
`environmentIdentifier` in the path	Required. A valid UUID for an active environment in the selected space.
`name` in the JSON body	Required string, 1–255 characters. Choose a name that is not used by another active environment in the same space. Use plain text; the backend sanitizes HTML content.
`project.key` in the JSON body	The Jira space key, for example `DEMO`. Include it to identify the space in this example.

The space context can also be supplied through the projectKey query parameter. Use one space for this update. Other environments are unchanged.

Example request body:

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

3. Update the environment

Replace the example UUID in this command with the identifier from step 1:

curl --request PUT \
  --url "$VANSAH_URL/api/v2/properties/environment/f94d0e7d-1edb-11ed-bdf2-ae827922bf87" \
  --header "Authorization: $VANSAH_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{"name":"UAT","project":{"key":"DEMO"}}'

Example successful response:

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

success: true confirms the update. data.identifier is the environment’s existing identifier, and data.name is the saved name. List the environments again to confirm the result.

Troubleshooting

Message or issue	How to resolve it
`One or more validation errors found.`	Read `data.errors`. Check that `name` is a nonempty string of 1–255 characters and the path identifier is a valid UUID.
`Invalid environment identifier(...)`	List environments in the same space. The identifier must belong to an active environment in that space. A deleted environment cannot be renamed through this endpoint.
`Duplicate environment(UAT)`	Choose a name not already used by another active environment in the space.
Authentication or permission error	Check the Vansah URL, token, Jira space key, and the token account’s Jira or space administrator permissions.
`Something went wrong while Updating Environment`	Read the current environment list before retrying. If the issue continues, contact Vansah Support with the response and endpoint, without your token.

Example duplicate-name response:

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

You can also view this request in the Vansah API collection in Postman.

Update an Environment (API)