Create a Test Run for a Test Case linked to a Test Folder or Jira work item in an Advanced Test Plan. Specify the plan, an existing iteration, and the requirement being tested. Save the returned run identifier to record results or attach evidence later.

Before you begin

Create a Vansah API token with Jira access configured. Use the Vansah base URL supplied for your workspace.
The token account needs access to the Jira space and permission to execute Test Cases. Vansah checks the Execute Test Cases permission; configured Jira groups apply, or Jira’s browse permission applies when no groups are configured.
The plan and iteration must already exist. The Test Case must be linked to the selected requirement in the plan and must not be blocked in either context.
Check whether the Jira space makes an environment, sprint, or version mandatory for Test Runs.

The examples use Bash and cURL. Set VANSAH_URL to your workspace’s Vansah base URL without a trailing slash, and VANSAH_TOKEN to your API token. Replace every sample key, UUID, path, and property value with your own values.

Endpoint and authentication

POST $VANSAH_URL/api/v2/run

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

Send a JSON object in the request body. This create request has no pagination or filtering parameters.

1. Select the plan, iteration, and Test Case

Body field	Type and requirement	How to use it
`asset.type`	String · Required	Use the exact value `plannedRun`.
`asset.key` or `asset.identifier`	String · One required	Use the plan key, such as `DEMO-P13`, or its UUID. Send one selector.
`asset.iteration`	Positive integer or object · Required	Use an existing iteration number, such as `1`, or `{"identifier":"YOUR_ITERATION_UUID"}`. Keep it inside `asset`.
`case.key` or `case.identifier`	String · One required	Use the linked Test Case key, such as `DEMO-C46`, or its UUID. Send one selector.
`project.key`	String · Optional context	The Jira space key, such as `DEMO`. Use the space containing the plan. The API field name remains `project.key`; the plan determines the run’s space.

An iteration number must be a JSON number: use 1, rather than "1". The endpoint does not create an iteration.

2. Select the requirement in the Advanced Test Plan

Identify the requirement whose linked Test Case you are executing. Use either a testPlanAsset object or the top-level testPlanAssetIdentifier string.

Requirement	Fields to send
Test Folder	Set `testPlanAsset.type` to `folder`. Add one string selector: `identifier` (folder UUID), `key` (for example, `DEMO-F3`), or `folderPath`. This object resolves folders in the plan’s Jira space.
Jira work item	Set `testPlanAsset.type` to `issue` and `testPlanAsset.key` to the work item key, such as `DEMO-123`. The account must be able to access the work item.
Requirement UUID	Instead of the object, set `testPlanAssetIdentifier` to the existing requirement’s Vansah UUID. For a work item, this is the Vansah requirement identifier, not the Jira work item’s numeric ID.

The Test Case must be linked to this requirement within the selected plan. For a folder path, copy the exact stored path, including slashes. See Copying a Test Folder Path. Send one requirement selector. If both forms are supplied, testPlanAssetIdentifier takes precedence.

3. Set the initial result

Send result explicitly. Use {"id":3} to create an Untested run before recording individual outcomes, or {"id":2} to record Passed when that result is enabled for the Jira space.

Field	Type	Behavior
`result.id`	Integer	The result ID configured in your Vansah workspace. Built-in IDs include `3` for Untested, `2` for Passed, and `1` for Failed.
`result.name`	String	Alternative to the ID. Use the current result name in your workspace; matching is case-insensitive. If both ID and name are supplied, the ID takes precedence.

Results other than the built-in Untested result must be enabled and available for the Jira space. Supplying a result also initializes the run’s applicable test logs with that result. For step-based tests, it applies to every created step log.

Although result is optional in the request schema, send it explicitly to avoid relying on the default result lookup. Use result.id: 3 when you plan to update individual steps afterward.

4. Add execution properties when needed

The properties object is optional unless the Jira space enables a property and makes it mandatory under Test Run Properties. Supply the values you want on the new run; this request does not automatically copy the iteration’s property selections.

Body field	Type	Behavior
`properties.environment.name`	String	Environment name, such as `UAT`. An unknown name creates a Vansah environment in the plan’s Jira space, so check the spelling.
`properties.release.jiraID` or `properties.release.name`	Jira version ID or string name	Select an existing Jira version in the plan’s Jira space. Use the exact name when selecting by name. The ID takes precedence if both are supplied.
`properties.sprint.jiraID` or `properties.sprint.name`	Jira sprint ID or string name	Select an existing accessible sprint. Name lookup uses sprints from boards in the plan’s Jira space and matches the exact name. Prefer the ID when names are duplicated. The ID takes precedence if both are supplied.

For example, merge this properties object into the complete request body. The fragment alone is not a create request. Replace the sample Jira IDs and name with values from your own Jira space:

{
  "properties": {
    "environment": {
      "name": "UAT"
    },
    "release": {
      "jiraID": "10001"
    },
    "sprint": {
      "jiraID": 42
    }
  }
}

Omit an optional property to leave it unselected. A value of -1 for a sprint or version jiraID also means no selection. A name of - means no selection when no ID is used. These empty selections do not satisfy a mandatory property.

Other optional fields

Body field	Type and limits	Behavior
`retryOfRunIdentifier`	UUID string	Associate the new run with an existing, undeleted run for the same Test Case in the same Jira space. It still creates a new run.
`executionGroupIdentifier`	String · 1–255 characters after trimming	Group related executions under your own label, such as `checkout-build-42`.
`timezone`	Timezone name string	Use a recognized name, such as `America/New_York`. An omitted or unrecognized name falls back to `Australia/Sydney`.

Vansah captures the requirement fingerprint automatically for the selected plan iteration. You do not need to send a fingerprint value.

Example: Test Folder requirement

Save this JSON as run-folder.json. It creates an Untested run for a Test Case under a folder requirement:

{
  "asset": {
    "type": "plannedRun",
    "key": "DEMO-P13",
    "iteration": 1
  },
  "testPlanAsset": {
    "type": "folder",
    "folderPath": "Regression/Checkout/"
  },
  "case": {
    "key": "DEMO-C46"
  },
  "project": {
    "key": "DEMO"
  },
  "result": {
    "id": 3
  }
}

Example: Jira work item requirement

Save this JSON as run-issue.json when the requirement is a Jira work item:

{
  "asset": {
    "type": "plannedRun",
    "key": "DEMO-P13",
    "iteration": 1
  },
  "testPlanAsset": {
    "type": "issue",
    "key": "DEMO-123"
  },
  "case": {
    "key": "DEMO-C46"
  },
  "project": {
    "key": "DEMO"
  },
  "result": {
    "id": 3
  }
}

5. Send the request

curl --request POST \
  --url "$VANSAH_URL/api/v2/run" \
  --header "Authorization: $VANSAH_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data-binary @run-folder.json

For the work item example, replace @run-folder.json with @run-issue.json. Add any mandatory properties to the file before sending it.

Each successful request creates a new Test Run. If a request times out or reports a creation failure, check whether the run was created before retrying to avoid duplicates.

6. Read the response

A successful request returns HTTP 200. This example shows selected fields for an Untested run with the default result name. The full response contains additional run, iteration, property, and log details.

{
  "success": true,
  "message": "A new Test Run created.",
  "data": {
    "run": {
      "identifier": "a3043da4-e54b-4bee-aa9b-556e442d49f1",
      "key": 248,
      "projectKey": "DEMO",
      "overallResult": {
        "id": 3,
        "name": "UNTESTED"
      },
      "asset": {
        "identifier": "4e8dd56a-4328-478c-88f4-22a721a1c8fa",
        "type": "plannedRun",
        "plannedRunIteration": {
          "identifier": "efd5133b-f648-4b7b-a6a0-09399af421bd",
          "key": 1
        }
      }
    }
  }
}

Response field	How to use it
`data.run.identifier`	The run’s UUID. Save it for later result and attachment requests.
`data.run.key`	The run’s numeric key within the Jira space.
`data.run.projectKey`	The Jira space key. The response field name remains `projectKey`.
`data.run.asset`	The Test Plan and selected iteration details, including the plan `identifier` and `plannedRunIteration`.
`data.run.overallResult`	The built-in overall outcome. Its name can reflect workspace customization; a custom input result ID is not necessarily returned here.
`data.run.logs`	The created logs as an array. Use the returned log identifiers when recording step results. Do not assume a log exists for a script with no applicable content.

When the plan has an active linked Test Case version for the selected requirement, the run uses that version. If that mapping is missing, the implementation falls back to the Test Case’s current version. Check the plan’s version selection before starting an execution.

Errors and troubleshooting

HTTP status	Meaning and next step
`400`	Invalid request, unresolved plan/iteration/requirement, unlinked or blocked Test Case, invalid result, missing mandatory property, or a creation failure. Read `message` and any `data.errors`.
`401`	Missing, invalid, expired, or inactive token, or Jira access is not configured for the API token. Check the token and authorization setup.
`403`	The account is blocked or lacks permission. Jira permission lookups can also return a denial. Review Jira space access and Vansah execution permissions.
`503`	The Jira permission lookup is temporarily unavailable. This response uses `errorCode: 1400`; try again when Jira access is available.

For example, an unresolved result returns HTTP 400 with this error structure:

{
  "success": false,
  "message": "Invalid result provided.",
  "data": [],
  "errorCode": 1306
}

Validation errors can instead return data.errors as an array. An errorCode is not present on every error response.

Message	What to check
`Asset not found.`	Check the plan selector and existing `asset.iteration`.
`Case not found.`	Check the Test Case key or UUID and its workspace.
`Test Case not linked with Asset.`	Link the Test Case to the selected requirement in the plan.
`Please make sure a Test Case is not Blocked.`	Check the blocked state in the plan and its requirement.
`Please provide a valid Test Folder Info` or `Please provide a valid issue key`	Check the requirement selector and the account’s access.
Environment, Sprint, or Version is required	Include the required `properties` selections.
`Failed to create run.`	Check whether a run was created before retrying. If the failure continues, contact Vansah Support with the request and response after removing the token.

Next, record step results or attach evidence to a test step. You can also open this request in the Vansah API collection in Postman.

Create a Test Run in an Advanced Test Plan (API)