Skip to main content

Create a Test Case (API)

Create a Vansah Test Case with clear JSON examples for steps, BDD, and other scripts, then link it using readable Jira work item keys.

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

/api/v2/category/caseTypes

Create a Test Case

POST

/api/v2/testCase

Find an optional destination Test Folder

GET

/api/v2/testFolders

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

project

key

String

"DEMO"

The Jira space key. It must match the selected type’s space.

Request body

headline

String

"Sign in with a valid account"

Required title, 1–800 characters after trimming.

type

identifier

String (UUID)

"446b5362-a167-11ef-99bc-4a527ec72f78"

Required type value obtained by matching its name in step 1.

Request body

description

String

"Verify that an active user can sign in and access their account."

Optional description. If omitted, the headline is used.

Request body

precondition

String

"An active test account exists."

Optional starting conditions.

Request body

label

Array of strings

["Smoke"]

Optional label names. Reusing an existing label needs no new-label creation. Adding a new label requires permission to add Test Case labels.

issue[]

key

String

"DEMO-123"

Optional Jira work item requirement. Add one object for each work item.

Request body

scriptType

String

"multistep"

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

steps[]

position

Integer

1

Required positive, unique position. Use 1, 2, and so on. Steps are saved in position order.

steps[]

step

String

"Open the sign-in page."

Required instruction for this plain-text workflow.

steps[]

expectedResult

String

"The sign-in form appears."

Optional expected result.

steps[]

testData

String

"Use the test account configured for this environment."

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

scriptType

String

Exact values: multistep, plainText, bdd, or automation. Omit it if you do not want to create script content yet.

bddData

String

BDD script text when scriptType is bdd.

automationData

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

folder[]

identifier

String (UUID)

"675ab256-06c5-4f09-bf96-a6c5c347d057"

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

priority

jiraID

String

"2"

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

400 — One or more validation errors found.

Read JSON path data.errors. Check the headline, required type object, exact scriptType, and step fields.

400 — Invalid Case Type.

Look up the type by name again and use its active identifier.

400 — Provided Space should be same as Case Type's Space

Make the nested project/key match the Jira space containing that type.

400 — Please provide one or more steps

Supply a nonempty steps array for multistep.

400 — Please provide unique step positions

Use different positive integer positions.

400 — Cannot create more than 200 Test Steps.

Keep the script at 200 steps or fewer. Check what was already saved before retrying.

400 — priority, work item, or folder verification failed

Repeat the relevant lookup and confirm access to the intended Jira space and requirement.

401 — authentication failed

Check the base URL, raw API token, expiry, and connected Jira access.

403 — access denied

Check Create Test Cases permission. New labels also need Add Test Case Labels permission. A blocked account is also denied.

503 — permission lookup unavailable

Retry after a short wait. Jira permissions could not be verified.

400 — Something went wrong while creating a test case

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.

Did this answer your question?