Use this API to retrieve the available Vansah Test Case label names in your workspace. This is useful when preparing Test Case imports, integrations, or label filters.

The list is workspace-wide and sorted by label name. Each item contains a name; this endpoint does not return a label identifier or the Test Cases that use the label. Learn more about using Labels for Test Cases.

Before you begin

Create a Vansah API token and use the Vansah URL supplied for your workspace. The token must be valid for the workspace you want to read.

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/category/labels

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
`startAt`	Optional. Number of records to skip, starting at `0`. Defaults to `0`. Use a whole number of zero or greater.
`limit`	Optional. Number of labels to return per page. Defaults to `1000`. Use a positive whole number, such as `100`.

This endpoint returns active label names for the workspace. It does not offer a label-name search or space-level label filter. If you supply projectKey for authentication context, it does not narrow the label list to that space.

Example: retrieve label names

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

If your workspace requires an enabled space context, add --data-urlencode "projectKey=DEMO" to the command, replacing DEMO with a space you can access.

Example successful response:

{
  "success": true,
  "message": "Labels returned successfully",
  "pagination": {
    "total": 3,
    "startAt": 0,
    "limit": 100
  },
  "data": [
    {
      "name": "Functional"
    },
    {
      "name": "Regression"
    },
    {
      "name": "Smoke"
    }
  ]
}

Understand the response

Field	Meaning
`success`	`true` when the request succeeds.
`message`	A summary of the result, such as `Labels returned successfully`.
`pagination.total`	Total number of active labels matching the workspace.
`pagination.startAt`	The offset used for this page.
`pagination.limit`	The page size used for this request.
`data`	An array of objects, each containing a label’s `name`. An empty array means no labels were returned for that page.

Retrieve the remaining pages

For a page size of 100, request startAt=100 for the next page, then 200, and continue until you have retrieved pagination.total labels or receive an empty data array. Keep the same limit on each page.

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

Troubleshooting

Message or issue	What to check
`One or more validation errors found.`	Read `data.errors`. Both pagination values must be numeric. Use whole-number offsets and page sizes.
Authentication error	Check the Vansah URL and API token. Use a Vansah API token in the `Authorization` header.
`This project is disabled`	If your workspace limits Vansah to selected spaces, supply an enabled space you can access using `projectKey`.
Empty `data` array	Check the workspace and offset. If there are no active labels, or the offset is past the end of the list, an empty array is expected.
`Something went wrong while Getting All Vansah Labels`	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": "many",
        "msg": "limit must be a number.",
        "param": "limit",
        "location": "query"
      }
    ]
  }
}

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

List Test Case Labels (API)