Create a test environment, such as UAT or Staging, in a Jira space. Use the environment when recording test execution or filtering results in Vansah.

Before you begin

Create a Vansah API token and use the Vansah URL supplied for your workspace.
The token account must be a Jira administrator or a space administrator for the destination Jira space.
Choose a name not already used by another 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 your token private.

Endpoint and headers

POST /api/v2/properties/environment

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

1. Prepare the request

Body field	What to send
`name`	Required string, 1–255 characters. Use a plain-text environment name, for example `UAT`.
`project.key`	The Jira space key, for example `DEMO`. Include it to identify the destination space. The API field name remains `project.key`.

The space context can also be supplied using the projectKey query parameter. This create endpoint allows up to 50 active environment records per Jira space.

Example JSON body:

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

2. Create the environment

curl --request POST \
  --url "$VANSAH_URL/api/v2/properties/environment" \
  --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-41ed-bdf2-ae827922bf87",
    "name": "UAT"
  }
}

Response field	Meaning
`success`	`true` when the request succeeds.
`message`	A summary of the outcome.
`data.identifier`	The new environment’s UUID. Save it for API requests that require an environment identifier.
`data.name`	The saved environment name.

3. Confirm the environment

List the environments in the same Jira space:

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"

Find the new name and identifier in data. See List Test Environments (API) for pagination and result-filter examples. To change the name later, use Update an Environment (API).

Troubleshooting

Message or issue	What to check
`One or more validation errors found.`	Inspect `data.errors`. The name must be a nonempty string of 1–255 characters.
`Duplicate environment(UAT)`	List the space’s environments and reuse the existing environment, or choose a different name.
`Cannot create more than 50 Case Environments per space.`	Review the existing environments before adding another.
`Please provide space information`	Include the correct `project.key` or `projectKey`. Both refer to the Jira space key.
Authentication or permission error	Check the Vansah URL, token, Jira space key, and the token account’s administrator permissions.
`Something went wrong while Creating Environment.`	Check the environment list before retrying. If the issue continues, contact Vansah Support with the request and response, 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.

Create a Test Environment (API)