Use this API to look up the test environments available in a Jira space. Each environment has a name and an identifier you can use in Vansah API requests, such as filtering execution results by environment.

Before you begin

Create a Vansah API token and use the Vansah URL supplied for your workspace. The token account must be able to access the 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 DEMO with your Jira space key. Keep your token private.

Endpoint and headers

GET /api/v2/properties/environments

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

Send the parameters in the query string. No JSON request body is needed.

Query parameters

Parameter	How to use it
`projectKey`	The Jira space key, for example `DEMO`. Include it to provide space context when using an API token. The API keeps the parameter name `projectKey`.
`startAt`	Optional. Number of records to skip. Defaults to `0`. Use a whole number of zero or greater.
`limit`	The page size is fixed at `50`. You can leave this parameter out; sending a different number does not change the page size.

The list is sorted by environment name. Deleted environments and the - placeholder are excluded. There is no environment-name search parameter on this endpoint.

1. Retrieve the 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 successful response:

{
  "success": true,
  "message": "Environments returned successfully",
  "pagination": {
    "total": 2,
    "startAt": 0,
    "limit": 50
  },
  "data": [
    {
      "identifier": "8cc5aea6-f311-11ef-892e-2e4c1a6a0f74",
      "name": "Staging"
    },
    {
      "identifier": "8cc5c440-f311-11ef-892e-2e4c1a6a0f74",
      "name": "UAT"
    }
  ]
}

Field	Meaning
`success` and `message`	Whether the request succeeded and a summary of the outcome.
`pagination.total`	Total number of active environments returned by this lookup before pagination.
`pagination.startAt`	The record offset used for this page.
`pagination.limit`	The fixed page size, `50`.
`data[].identifier`	The environment’s UUID. Use this value when an API parameter asks for an environment identifier.
`data[].name`	The environment name displayed in Vansah.

2. Retrieve more pages if needed

Request startAt=50 for the second page, then 100, and continue until you have retrieved pagination.total records or receive an empty data array. Keep the same projectKey on every page.

3. Use an environment identifier

Copy the identifier for the environment you need. This example uses the UAT identifier as environmentIdentifier when listing Test Cases and their matching execution results:

curl --request GET --get \
  --url "$VANSAH_URL/api/v2/testCases" \
  --header "Authorization: $VANSAH_TOKEN" \
  --header "Accept: application/json" \
  --data-urlencode "projectKey=DEMO" \
  --data-urlencode "environmentIdentifier=8cc5c440-f311-11ef-892e-2e4c1a6a0f74" \
  --data-urlencode "startAt=0" \
  --data-urlencode "limit=50"

Replace the example UUID with the identifier returned for your environment. See List Test Cases (API) for the response and other filters. An environment filter controls which execution result is considered; Test Cases without a matching execution can still appear as untested.

To rename an environment, use Update an Environment (API).

Troubleshooting

Message or issue	What to check
`Please provide space information`	Include the correct `projectKey`, which is the Jira space key.
`One or more validation errors found.`	Read `data.errors`. Use a numeric `startAt`; if you send `limit`, it must also be numeric even though the page size remains 50.
Authentication or access error	Check the Vansah URL, token, Jira space key, and the token account’s access.
Empty list	Check the space and offset. Retry with `startAt=0`. Deleted environments and the placeholder are not returned.
`Something went wrong while Getting Environments.`	Retry the request. If the issue continues, contact Vansah Support with the endpoint and response, without your token.

Example validation error:

{
  "success": false,
  "message": "One or more validation errors found.",
  "data": {
    "errors": [
      {
        "value": "next",
        "msg": "startAt must be a number.",
        "param": "startAt",
        "location": "query"
      }
    ]
  }
}

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

List Test Environments (API)