Create a Test Case in your Jira space, add its script, and link it to Jira work items in one request. The examples use plain text for the title, description, steps, and expected results.
Endpoints
Action | Method | Endpoint |
Find the Test Case type by name | GET |
|
Create a Test Case | POST |
|
Find an optional destination Test Folder | GET |
|
Add the endpoint path to your Vansah base URL.
Before you begin
These examples use Bash and cURL. Set VANSAH_URL to your Vansah base URL without a trailing slash and VANSAH_TOKEN to your Vansah API token. Send the token directly in the Authorization header, without a Bearer prefix. Keep it private.
The token account needs access to the Jira space and Vansah permission to create Test Cases. If no Jira groups are configured for that permission, Jira Browse permission is used.
Replace DEMO with your Jira space key. JSON path project.key means the Jira space key.
1. Find your Test Case type by name
Endpoint: GET /api/v2/category/caseTypes
Creating a Test Case requires a type identifier. Look up the type name you recognize in Vansah:
curl --request GET --get \
--url "$VANSAH_URL/api/v2/category/caseTypes" \
--header "Authorization: $VANSAH_TOKEN" \
--header "Accept: application/json" \
--data-urlencode "projectKey=DEMO" \
--data-urlencode "startAt=0" \
--data-urlencode "limit=100"
Example HTTP 200 response:
{
"success": true,
"message": "CaseTypes returned successfully",
"pagination": {
"total": 1,
"startAt": 0,
"limit": 100
},
"data": [
{
"identifier": "446b5362-a167-11ef-99bc-4a527ec72f78",
"name": "Functional"
}
]
}
Find Functional and copy its identifier from your response into the type object in the examples below. The synthetic value is only an example. See List Test Case Types (API) for paging.
The type must be active and belong to the Jira space in project. This endpoint does not accept a type name instead of the required identifier.
2. Prepare a Test Case with steps
Endpoint: POST /api/v2/testCase
Save this complete body as test-case.json. Replace the type value with the one you just obtained and the Jira work item key with your requirement:
{
"project": {
"key": "DEMO"
},
"headline": "Sign in with a valid account",
"type": {
"identifier": "446b5362-a167-11ef-99bc-4a527ec72f78"
},
"description": "Verify that an active user can sign in and access their account.",
"precondition": "An active test account exists. The sign-in page is available.",
"label": [
"Smoke"
],
"issue": [
{
"key": "DEMO-123"
}
],
"scriptType": "multistep",
"steps": [
{
"position": 1,
"step": "Open the sign-in page.",
"expectedResult": "The sign-in form appears."
},
{
"position": 2,
"step": "Enter valid credentials and select Sign in.",
"testData": "Use the test account configured for this environment.",
"expectedResult": "The account page appears."
}
]
}
Parent object | JSON field | Type | Example value | Use |
|
| String |
| The Jira space key. It must match the selected type’s space. |
Request body |
| String |
| Required title, 1–800 characters after trimming. |
|
| String (UUID) |
| Required type value obtained by matching its name in step 1. |
Request body |
| String |
| Optional description. If omitted, the headline is used. |
Request body |
| String |
| Optional starting conditions. |
Request body |
| Array of strings |
| Optional label names. Reusing an existing label needs no new-label creation. Adding a new label requires permission to add Test Case labels. |
|
| String |
| Optional Jira work item requirement. Add one object for each work item. |
Request body |
| String |
| Creates a Multi Steps script using the steps array. |
Use the exact JSON keys and nesting shown. Omit optional arrays you do not need. To reuse existing labels, see List Test Case Labels (API).
Step fields
Endpoint: POST /api/v2/testCase
The complete request above includes two step objects. Each object uses these fields:
Parent object | JSON field | Type | Example value | Use |
|
| Integer |
| Required positive, unique position. Use 1, 2, and so on. Steps are saved in position order. |
|
| String |
| Required instruction for this plain-text workflow. |
|
| String |
| Optional expected result. |
|
| String |
| Optional data or instructions for the step. |
A Multi Steps script must contain at least one step. The step handler allows up to 200 steps. Keep positions unique and use JSON numbers.
3. Create the Test Case
Endpoint: POST /api/v2/testCase
curl --request POST \
--url "$VANSAH_URL/api/v2/testCase" \
--header "Authorization: $VANSAH_TOKEN" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data-binary @test-case.json
Example HTTP 200 response excerpt, showing selected fields and one of the returned steps:
{
"success": true,
"message": "Test Case created successfully.",
"data": {
"identifier": "460f1562-1a80-41f0-b619-a6332c493f52",
"key": "DEMO-C335",
"testCaseVersion": 1,
"headline": "Sign in with a valid account",
"type": {
"identifier": "446b5362-a167-11ef-99bc-4a527ec72f78",
"name": "Functional"
},
"script": {
"type": "multistep",
"data": [
{
"identifier": "15df09b4-177c-447f-934d-255b7125cc67",
"position": 1,
"stepOrder": 1,
"plainStep": "Open the sign-in page.",
"plainExpectedResult": "The sign-in form appears."
}
]
}
}
}
Keep the readable key, such as DEMO-C335, for later requests that accept a Test Case key. JSON path data.testCaseVersion is 1 for the new case. The response also includes its identifier and saved details; JSON path data.script contains the script you created.
Open the Test Case in Vansah and verify its script and requirement links. You can also find it by key with List Test Cases (API).
After a timeout or error, check whether the Test Case, script, or links were saved before retrying. Creation is not rolled back as one operation, and repeating the request can create another Test Case.
Other complete script examples
Endpoint: POST /api/v2/testCase
Save any complete example below as test-case.json and use the POST command above. Replace the type identifier with the value you obtained in step 1.
BDD: Use scriptType: "bdd" and a bddData string:
{
"project": {
"key": "DEMO"
},
"headline": "Sign in with a valid account using BDD",
"type": {
"identifier": "446b5362-a167-11ef-99bc-4a527ec72f78"
},
"scriptType": "bdd",
"bddData": "Feature: Account access\n Scenario: Valid sign-in\n Given an active user is on the sign-in page\n When the user signs in with valid credentials\n Then the account page is displayed"
}
Automation: Use scriptType: "automation" and an automationData string. This saves the script; it does not run it:
{
"project": {
"key": "DEMO"
},
"headline": "Record the account access automation script",
"type": {
"identifier": "446b5362-a167-11ef-99bc-4a527ec72f78"
},
"scriptType": "automation",
"automationData": "console.log(\"Run the account access test in your configured test environment.\");"
}
No script yet: Omit scriptType and the script fields:
{
"project": {
"key": "DEMO"
},
"headline": "Sign in with a valid account",
"type": {
"identifier": "446b5362-a167-11ef-99bc-4a527ec72f78"
}
}
JSON field at the request root | Type | Use |
| String | Exact values: multistep, plainText, bdd, or automation. Omit it if you do not want to create script content yet. |
| String | BDD script text when scriptType is bdd. |
| String | Automation script text when scriptType is automation. |
Plain Text script
Endpoint: POST /api/v2/testCase
For a Plain Text script, send plainTextDataAdf as the structured document below. ADF means Atlassian Document Format. This form is accepted by the create endpoint:
{
"project": {
"key": "DEMO"
},
"headline": "Sign in with a valid account",
"type": {
"identifier": "446b5362-a167-11ef-99bc-4a527ec72f78"
},
"scriptType": "plainText",
"plainTextDataAdf": {
"version": 1,
"type": "doc",
"content": [
{
"type": "paragraph",
"content": [
{
"type": "text",
"text": "Sign in with an active test account and confirm the account page appears."
}
]
}
]
}
}
Change the text value to your script. Keep version, type, and content in the structure shown. Save the complete request to test-case.json and use the same POST command.
ADF request documents are limited to 2,000,000 serialized bytes, 10,000 nodes, and 200,000 text characters. Use ordinary strings in the main Multi Steps and BDD workflows unless you need rich formatting.
Optional: link a Test Folder
Endpoint: GET /api/v2/testFolders
This create endpoint requires a folder identifier for the folder array. First find the folder by name and check its path:
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 "testFolderName=Checkout" \
--data-urlencode "startAt=0" \
--data-urlencode "limit=100"
Match name and folderPath in the response’s data array. Copy its identifier, and replace the synthetic value in this complete request:
Endpoint: POST /api/v2/testCase
{
"project": {
"key": "DEMO"
},
"headline": "Sign in with a valid account",
"type": {
"identifier": "446b5362-a167-11ef-99bc-4a527ec72f78"
},
"folder": [
{
"identifier": "675ab256-06c5-4f09-bf96-a6c5c347d057"
}
]
}
Parent object | JSON field | Type | Example value | Use |
|
| String (UUID) |
| Existing Test Repository folder from the lookup. Include only when linking a folder. |
For later lookup pages, increase startAt by 100 until you reach JSON path pagination.total. This create endpoint does not accept a folder path or folder key in this array. Use the lookup to identify the right folder rather than guessing an identifier.
Optional: choose a priority
Endpoint: POST /api/v2/testCase
Use List Test Case Priorities (API), match the familiar priority name, and copy its id. This create endpoint requires that Jira priority ID when you supply priority.
For example, if your response maps High to "2", this is a complete request:
{
"project": {
"key": "DEMO"
},
"headline": "Sign in with a valid account",
"type": {
"identifier": "446b5362-a167-11ef-99bc-4a527ec72f78"
},
"priority": {
"jiraID": "2"
}
}
Parent object | JSON field | Type | Example value | Use |
|
| String |
| Jira priority ID obtained by matching the name in the priority response. Omit the priority object if you do not need to choose one. |
When a default Test Case status is configured for your Jira space, it is applied during creation. The estimatedTime field is not saved by this create endpoint; set estimated time in Vansah after creation.
Troubleshooting
HTTP status or message | What to check |
| Read JSON path data.errors. Check the headline, required type object, exact scriptType, and step fields. |
| Look up the type by name again and use its active identifier. |
| Make the nested project/key match the Jira space containing that type. |
| Supply a nonempty steps array for multistep. |
| Use different positive integer positions. |
| Keep the script at 200 steps or fewer. Check what was already saved before retrying. |
| Repeat the relevant lookup and confirm access to the intended Jira space and requirement. |
| Check the base URL, raw API token, expiry, and connected Jira access. |
| Check Create Test Cases permission. New labels also need Add Test Case Labels permission. A blocked account is also denied. |
| Retry after a short wait. Jira permissions could not be verified. |
| Check Vansah for a partially created case before retrying. Contact Vansah Support if it continues, without sharing your token. |
Example HTTP 400 controller failure:
{
"success": false,
"errorCode": 1390,
"message": "Something went wrong while creating a test case",
"data": []
}
Type and requirement lookup errors use error code 1306. Permission and ADF validation failures use 1400. Field-validation errors contain JSON path data.errors; script-validation items can use path to identify a field.
