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.

In the request tables, Parent object shows where the field belongs, JSON field is the exact key to send, and Example value contains sample data. The JSON examples show the actual nesting.

1. Select the plan, iteration, and Test Case

Use the readable Test Plan and Test Case keys shown in Vansah, plus the iteration number you want to execute. Replace the example values with your own.

Save this complete request as run-folder.json. It creates an Untested run for a Test Folder requirement:

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

Parent object	JSON field	Type	Example value	Use
`asset`	`type`	String	`"plannedRun"`	Required. Creates a Test Run in a Test Plan.
`asset`	`key`	String	`"DEMO-P13"`	Required. The existing Test Plan key.
`asset`	`iteration`	Positive integer	`1`	Required. The existing iteration number in that plan.
`case`	`key`	String	`"DEMO-C46"`	Required. The Test Case key linked to the selected requirement in the plan.
`project`	`key`	String	`"DEMO"`	The Jira space key for the plan. Included in the examples.

Keep the iteration number inside the asset object. Use a JSON number without quotation marks. This request uses an existing iteration; it does not create one.

2. Select the requirement in the Advanced Test Plan

The Test Plan is selected by the key in the asset object, using the P prefix shown in the examples. The testPlanAsset object selects the requirement inside that plan: a Test Folder path or a Jira work item key.

For a Jira work item requirement, save this complete request as run-issue.json:

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

Parent object	JSON field	Type	Example value	Use
`testPlanAsset`	`type`	String	`"folder"`	Use folder for a Test Folder or issue for a Jira work item.
`testPlanAsset`	`folderPath`	String	`"Regression/Checkout/"`	For a folder, use its exact stored path in the plan’s Jira space.
`testPlanAsset`	`key`	String	`"DEMO-123"`	For a Jira work item, use its work item key when type is issue.

The Test Case must be linked to this requirement within the plan. For a folder requirement, use its path. See Copying a Test Folder Path to get the path, including its slashes.

3. Set the initial result

Use the result name configured in your Vansah workspace. To start Untested before recording individual steps, include this field in the complete request:

{
  "result": {
    "name": "untested"
  }
}

Parent object	JSON field	Type	Example value	Use
`result`	`name`	String	`"untested"`	Send explicitly. Use the configured name for Untested, Passed, Failed, or another result available in your workspace. Matching is case-insensitive.

If your workspace renamed a result, use its current name. Results other than the built-in Untested result must be enabled and available for the Jira space.

Supplying a result also initializes the applicable logs with that outcome. Use Untested when your automation will report individual steps afterward. Send the result explicitly; omitting it relies on inconsistent default handling.

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.

This complete example records a Passed execution with an environment, version, and sprint. Replace the sample names with names from your own Jira space:

{
  "asset": {
    "type": "plannedRun",
    "key": "DEMO-P13",
    "iteration": 1
  },
  "testPlanAsset": {
    "type": "folder",
    "folderPath": "Regression/Checkout/"
  },
  "case": {
    "key": "DEMO-C46"
  },
  "project": {
    "key": "DEMO"
  },
  "result": {
    "name": "passed"
  },
  "properties": {
    "environment": {
      "name": "UAT"
    },
    "release": {
      "name": "Release 1.0"
    },
    "sprint": {
      "name": "Sprint 1"
    }
  }
}

Parent object	JSON field	Type	Example value	Use
`properties.environment`	`name`	String	`"UAT"`	Optional unless mandatory. Uses the named environment in this Jira space; an unknown name creates an environment. Check spelling.
`properties.release`	`name`	String	`"Release 1.0"`	Optional unless mandatory. Exact existing Jira version name in the execution context’s Jira space.
`properties.sprint`	`name`	String	`"Sprint 1"`	Optional unless mandatory. Exact existing sprint name from boards in the execution context’s Jira space.

Omit an optional property to leave it unselected. An empty selection does not satisfy a mandatory property.

Other optional fields

To group executions under a CI build label and choose a reporting timezone, add these fields to the request:

{
  "asset": {
    "type": "plannedRun",
    "key": "DEMO-P13",
    "iteration": 1
  },
  "testPlanAsset": {
    "type": "folder",
    "folderPath": "Regression/Checkout/"
  },
  "case": {
    "key": "DEMO-C46"
  },
  "project": {
    "key": "DEMO"
  },
  "result": {
    "name": "untested"
  },
  "executionGroupIdentifier": "checkout-build-42",
  "timezone": "America/New_York"
}

Parent object	JSON field	Type	Example value	Use
Request body	`executionGroupIdentifier`	String	`"checkout-build-42"`	Optional label for related executions, such as a CI build. Use 1–255 characters after trimming.
Request body	`timezone`	String	`"America/New_York"`	Optional recognized timezone name. Missing or unrecognized values fall back to Australia/Sydney.

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

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": {
        "type": "plannedRun",
        "plannedRunIteration": {
          "key": 1
        }
      }
    }
  }
}

Response JSON path	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. Use the iteration’s returned key to confirm the iteration number.
`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 JSON path 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)