Use this API to find the Jira spaces available to your Vansah account. Copy a returned space key when configuring other Vansah API requests for your automation or development environment.

The list contains active spaces available in Vansah and associated with the account used by your API token. You can filter for one space by its key or retrieve its saved description.

Before you begin

Create a Vansah API token and use the Vansah URL supplied for your workspace. The token must belong to the account whose spaces you want to retrieve.

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. Keep your token private.

Endpoint and headers

GET /api/v2/projects

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
`key`	Optional. Filter by one exact Jira space key, for example `DEMO`. Leave it out to list the spaces available to your account.
`startAt`	Optional record offset for the list. Defaults to `0`. Use a whole number of zero or greater.
`limit`	Optional list page size. Defaults to `50`. Use a positive whole number.
`type`	Optional. Set to `description` to retrieve one space with its saved description. Include `key` to select the space. This response is a single object without pagination.

The list is sorted by space name. The key filter is an exact match; there is no name-search parameter.

1. List the available Jira spaces

curl --request GET --get \
  --url "$VANSAH_URL/api/v2/projects" \
  --header "Authorization: $VANSAH_TOKEN" \
  --header "Accept: application/json" \
  --data-urlencode "startAt=0" \
  --data-urlencode "limit=50"

Example successful response:

{
  "success": true,
  "message": "Spaces returned successfully",
  "pagination": {
    "total": 1,
    "startAt": 0,
    "limit": 50
  },
  "data": [
    {
      "identifier": "5602ff61-de35-11ef-9c82-56bd4ac65cf0",
      "name": "Demo Testing",
      "key": "DEMO",
      "status": 1
    }
  ]
}

Field	Meaning
`success` and `message`	Whether the request succeeded and a summary of the outcome.
`pagination`	The total matching count, page offset, and page size.
`data[].identifier`	The space record’s Vansah UUID.
`data[].name`	The space name stored in Vansah.
`data[].key`	The Jira space key, such as `DEMO`.
`data[].status`	The active status, `1`, for returned spaces.

Filter for one space

Add --data-urlencode "key=DEMO" to the request, replacing DEMO with your Jira space key. The list response still contains a data array.

Retrieve more pages

With a page size of 50, request startAt=50 for the second page, then 100, and continue until you have retrieved pagination.total records or receive an empty array. Keep limit and any key filter unchanged.

2. Retrieve a space’s description

Use type=description and select a space with key:

curl --request GET --get \
  --url "$VANSAH_URL/api/v2/projects" \
  --header "Authorization: $VANSAH_TOKEN" \
  --header "Accept: application/json" \
  --data-urlencode "key=DEMO" \
  --data-urlencode "type=description"

Example response:

{
  "success": true,
  "message": "Space returned successfully",
  "data": {
    "identifier": "5602ff61-de35-11ef-9c82-56bd4ac65cf0",
    "name": "Demo Testing",
    "key": "DEMO",
    "status": 1,
    "description": "Test management for the demo application."
  }
}

Here, data is one space object with a description field. startAt and limit do not paginate this response.

3. Use the space key in other API requests

Use the returned key value, such as DEMO, wherever another endpoint asks for projectKey or project.key. Both refer to the Jira space key. Keep those parameter names exactly as documented.

For example, this request retrieves Test Cases in that Jira space:

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

See List Test Cases (API) for filters and response details.

Troubleshooting

Message or issue	What to check
`One or more validation errors found.`	Read `data.errors`. Pagination values must be numeric. The only supported `type` value is `description`.
Authentication error	Check the Vansah URL and token, and confirm that the token account can still access Jira.
A space is missing or the list is empty	Check the token account, workspace, exact `key` filter, and page offset. Confirm Vansah is enabled for that space. Open Vansah in the space using the same account, then retry.
`No available Space`	The description lookup did not find an active space available to the account. Check the `key` value and account access.
`Failed to get Space(s) List` or `Failed to get Space Properties`	Retry the request. If the error 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": "details",
        "msg": "Please provide a valid type",
        "param": "type",
        "location": "query"
      }
    ]
  }
}

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

List Jira Spaces (API)