Create a Vansah Test Case in a Jira space using this API. You can include the description, preconditions, labels, requirement links, and a Test Script in the same request.

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 Cases in Vansah.
Find the UUID of an existing Test Case type in that space using List Test Case Types.
For optional links, have the Jira work item keys and Test Folder UUIDs you want to use.

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 the example space key, UUIDs, and other values with your own. Keep your token private.

Endpoint and headers

POST /api/v2/testCase

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

1. Provide the Test Case details

Field	What to send
`project.key`	The Jira space key, for example `DEMO`. It must match the space containing the selected Test Case type. The API field name remains `project.key`.
`headline`	Required title, 1–800 characters after trimming.
`type.identifier`	Required UUID of an active Test Case type. Supply a `type` object, rather than a type-name string.
`description`	Optional text explaining what the case verifies. If omitted, the headline is used as the description.
`precondition`	Optional text describing the starting conditions.
`descriptionAdf` and `preconditionAdf`	Optional rich-text documents in Atlassian Document Format (ADF). Each takes precedence over the corresponding text field.
`priority.jiraID`	Optional Jira priority ID. Look up the ID with List Test Case Priorities.
`assignee.jiraAccountID`	Optional Jira account ID as a string. Use the account ID, rather than an email address or display name.
`label`	Optional array of label names, such as `["Smoke","Regression"]`. Creating a label that does not exist requires permission to add Test Case labels.
`component`	Optional array of objects containing Jira component IDs, such as `[{"jiraID":10001}]`. Use components available in the Jira space.
`issue`	Optional array of Jira work item objects, such as `[{"key":"DEMO-123"}]`, to link as requirements.
`folder`	Optional array of existing Test Folder objects, such as `[{"identifier":"YOUR_FOLDER_UUID"}]`.

Omit optional objects you do not need. If you supply priority or assignee, include its nested ID field.

Minimal request

This creates the Test Case without an inline script:

{
  "project": {
    "key": "DEMO"
  },
  "headline": "Sign in with a valid account",
  "type": {
    "identifier": "446b5362-a167-41ef-99bc-4a527ec72f78"
  }
}

2. Add a Test Script

Include scriptType to create the script with the Test Case. Use the exact values below:

`scriptType`	Script fields
`multistep`	A nonempty `steps` array. Each step needs a positive integer `position` and `step` text. Positions must be unique. `expectedResult` and `testData` are optional strings.
`plainText`	Use `plainTextDataAdf` for the script’s rich-text document, as shown below.
`bdd`	Use `bddData` for the BDD script text.
`automation`	Use `automationData` for automation script text.

For rich-text step content, use stepDataAdf, resultDataAdf, and testDataAdf instead of the corresponding text fields. Rich-text documents are limited to 2,000,000 serialized bytes, 10,000 nodes, and 200,000 text characters; saved-field capacity can impose a smaller limit.

Example: Test Case with two steps

Save this as test-case.json. Replace the type UUID, folder UUID, Jira work item key, and priority ID with values from your own Jira space:

{
  "project": {
    "key": "DEMO"
  },
  "headline": "Sign in with a valid account",
  "type": {
    "identifier": "446b5362-a167-41ef-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.",
  "priority": {
    "jiraID": 2
  },
  "label": [
    "Smoke"
  ],
  "folder": [
    {
      "identifier": "675ab256-06c5-4f09-bf96-a6c5c347d057"
    }
  ],
  "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."
    }
  ]
}

Example: BDD script

Use the same Test Case fields with scriptType: "bdd" and bddData:

{
  "project": {
    "key": "DEMO"
  },
  "headline": "Sign in with a valid account using BDD",
  "type": {
    "identifier": "446b5362-a167-41ef-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"
}

Example: Plain Text script

{
  "project": {
    "key": "DEMO"
  },
  "headline": "Sign in with a valid account",
  "type": {
    "identifier": "446b5362-a167-41ef-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."
          }
        ]
      }
    ]
  }
}

3. Create the Test Case

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

Each successful request creates a new Test Case. If the request times out or fails after processing starts, check Vansah before resending it to avoid duplicates.

4. Save the Test Case identifier

Example successful response showing selected fields and one returned step:

{
  "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-41ef-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."
        }
      ]
    }
  }
}

Response field	Meaning
`data.identifier`	The new Test Case UUID. Save it for later API calls.
`data.key`	The readable Test Case key, such as `DEMO-C335`.
`data.testCaseVersion`	The created version, `1`.
`data.type`	The saved Test Case type.
`data.descriptionAdf` and `data.preconditionAdf`	The saved rich-text description and preconditions.
`data.script`	The created script when you supplied `scriptType`. A Multi Steps script returns its created steps in `data.script.data`.

Open the Test Case in Vansah to confirm the script and requirement links. You can also find it by key with List Test Cases (API).

Other creation details

Estimated time: This create request does not save estimatedTime. Set it after creation in Vansah or with the Test Case update API.
Script evidence: Step objects can include an attachments array. For Plain Text, BDD, or Automation scripts, use a top-level attachments array. Each attachment needs a name, an extension, and one source: Base64 file data or an HTTPS url. These attach evidence to the script, rather than recording a Test Run result.
Advanced Test Plan links: The request also accepts testPlanAssetIdentifier for a plan requirement and eprIdentifier for an existing iteration when creating a case in a plan context. Use identifiers from the intended plan and requirement.

Troubleshooting

Message or issue	What to check
`One or more validation errors found.`	Inspect `data.errors`. Check the headline length, required type object, UUIDs, array structures, and nested fields.
`Invalid Case Type.`	Use an active type UUID returned for the intended Jira space.
`Provided Space should be same as Case Type's Space`	Make `project.key` match the Jira space containing that type.
`Please provide one or more steps`	For `scriptType: "multistep"`, supply a nonempty `steps` array.
`Please provide unique step positions`	Give every step a different positive integer `position`.
`Failed to verify Priority...` or `Failed to verify Assignee...`	Check the Jira priority ID or account ID.
`Invalid Issues provided: ...` or a folder verification error	Check the Jira work item keys, folder UUIDs, workspace, and account access.
Authentication or permission error	Check the token and permission to create Test Cases. New labels also need permission to add labels.
`Something went wrong while creating a test case`	Check whether the case or its links were created before retrying. If the problem continues, contact Vansah Support with the request and response, without your token.

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

Create a Test Case (API)