Use this API to create several Test Folders in a Jira space in one request. You can create empty folders or link existing Test Cases as the folders are created.

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 and have permission to create Test Folders in Vansah.
For subfolders, have the existing parent Test Folder’s UUID.
For optional Test Case links, have the readable case keys, such as DEMO-C1.

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/testFolder/bulk?projectKey=DEMO

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

The query parameter projectKey is the Jira space key. All new folders are created in that space.

1. Prepare the folder list

Send a JSON object with a data array. Each item describes a folder:

Field	What to send
`data[].name`	Required string, 1–255 characters. Choose a name that is unique under the intended parent.
`data[].parentIdentifier`	Include a string for every folder. Use an existing parent Test Folder UUID for a subfolder, or `""` for the repository root. Do not omit the field or send `null`.
`data[].linkedTestCases`	Optional array of Test Case keys, for example `["DEMO-C1","DEMO-C2"]`. Use keys rather than UUIDs. Omit it for an empty folder.

Parent folders must already exist when the request is validated. To build a hierarchy, create the parent first, then use its returned identifier in a later request for the children.

Find a parent folder UUID

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

Find the intended parent and copy its identifier. Use a Test Folder in the same Jira space, rather than a Test Plan Folder.

Example: create folders under an existing parent

Save this as test-folders.json. Replace the sample parent UUID and Test Case keys with your own values:

{
  "data": [
    {
      "name": "Unit Testing",
      "parentIdentifier": "7829d1ab-008a-41f0-b619-a6332c493f52",
      "linkedTestCases": [
        "DEMO-C1",
        "DEMO-C2"
      ]
    },
    {
      "name": "System Testing",
      "parentIdentifier": "7829d1ab-008a-41f0-b619-a6332c493f52"
    }
  ]
}

Example: create a folder at the repository root

Use an empty string for parentIdentifier:

{
  "data": [
    {
      "name": "Release 3.2",
      "parentIdentifier": ""
    }
  ]
}

Test Case version: The optional links created by this bulk request use version 1. Check that this is the version you intend to link. If you need another version, create the folders without linkedTestCases and link the required version separately.

2. Create the folders

curl --request POST \
  --url "$VANSAH_URL/api/v2/testFolder/bulk?projectKey=DEMO" \
  --header "Authorization: $VANSAH_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data-binary @test-folders.json

Do not repeat the same parent-and-name combination in a batch. Existing folders with the same name under a supplied parent are rejected as duplicates.

3. Save the returned identifiers

Example successful response:

{
  "success": true,
  "message": "Bulk Test Folder/s created successfully",
  "data": [
    {
      "name": "Unit Testing",
      "identifier": "18843677-037b-41f0-b619-a6332c493f52"
    },
    {
      "name": "System Testing",
      "identifier": "187a5cc8-037b-41f0-b619-a6332c493f52"
    }
  ]
}

Response field	Meaning
`success` and `message`	Whether the request succeeded and a summary of the outcome.
`data`	The array of created folders.
`data[].name`	The saved folder name.
`data[].identifier`	The new folder’s UUID. Save it for later folder or Test Case requests.

Open the Test Repository in Vansah and check the folder locations and Test Case links. You can also repeat the folder lookup request to confirm the new records.

If a request times out or returns an error, check which folders were created before retrying. Folder creation and Test Case linking can fail at different points, so a failed request may leave some folders already created.

Troubleshooting

Message or issue	What to check
Name validation error	Use a nonempty string of 1–255 characters. Inspect `data.errors` for the affected array item.
`Duplicate Test Folders found: ...`	Remove duplicate names under the same parent from the request, or choose a different name if the folder already exists.
`Invalid parentIdentifier(s): ...`	Use existing parent Test Folder UUIDs from the destination Jira space. Use `""` for the root.
`Invalid test cases found: ...`	Use existing readable keys such as `DEMO-C1`, not Test Case UUIDs.
Error when the parent is omitted	Include `parentIdentifier` as a string on every item, including `""` for a root folder.
Authentication or permission error	Check the Vansah URL, token, Jira space key, and permission to create Test Folders.
`Something went wrong whileCreating bulk Test Folders.`	Check the Test Repository before retrying. If the error continues, contact Vansah Support with the request and response, without your token.

Example name validation response:

{
  "success": false,
  "message": "Please provide name, Name should be min 1 character and max 255 characters long.",
  "data": {
    "errors": [
      {
        "value": "",
        "msg": "Please provide name",
        "param": "data[0].name",
        "location": "body"
      },
      {
        "value": "",
        "msg": "Name should be min 1 character and max 255 characters long.",
        "param": "data[0].name",
        "location": "body"
      }
    ]
  }
}

Create Test Folders in Bulk (API)