Create a Test Run to record one execution of a Test Case against a Jira work item, Test Folder, or Test Plan iteration. Send the outcome from your automation tool, or create an Untested run before reporting individual step outcomes.

Before you begin

Create a Vansah API token with Jira access configured, and 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 applies the configured execution permission groups, or Jira’s browse permission when no groups are configured.
The Test Case must already be linked to the selected work item, folder, or plan requirement. It must not be blocked.
For a Test Plan, the plan and selected iteration must already exist.
Check whether the Jira space requires an environment, sprint, or version for Test Runs.

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. Keep your token private. Replace sample keys, paths, names, and property values 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.

Request tables separate the parent object from the exact JSON key. Sample data appears under Example value. The complete JSON examples show how the objects fit together.

Example: Jira work item

Save this as run.json. It records a Passed execution of DEMO-C46 against DEMO-123:

{
  "asset": {
    "type": "issue",
    "key": "DEMO-123"
  },
  "case": {
    "key": "DEMO-C46"
  },
  "project": {
    "key": "DEMO"
  },
  "result": {
    "name": "passed"
  }
}

Example: Test Folder

Use the Test Folder path and the Jira space key. Copy the folder path from Vansah, including its slashes. Replace the example path, space key, and Test Case key, then save this complete request as run.json:

{
  "asset": {
    "type": "folder",
    "folderPath": "Regression/Checkout/"
  },
  "case": {
    "key": "DEMO-C46"
  },
  "project": {
    "key": "DEMO"
  },
  "result": {
    "name": "passed"
  }
}

See Copying a Test Folder Path for how to get the path.

Example: Standard Test Plan

This example creates an Untested run in iteration 1. Keep iteration nested inside asset:

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

1. Choose where to record the execution

Send one asset object and one case object per request. The asset identifies the execution context.

Parent object	JSON field	Type	Example value	Use
`asset`	`type`	String	`"folder"`	Required. Use issue for a Jira work item, folder for a Test Folder, or plannedRun for a Test Plan.
`asset`	`key`	String	`"DEMO-123"`	The Jira work item key when type is issue.
`asset`	`key`	String	`"DEMO-P13"`	The Test Plan key when type is plannedRun. Test Plans use the P prefix.
`asset`	`folderPath`	String	`"Regression/Checkout/"`	Required when type is folder. Copy the exact path and include the Jira space key in the project object.
`asset`	`iteration`	Positive integer	`1`	Required for a Test Plan. The existing iteration number in the selected plan.

Parent object	JSON field	Type	Example value	Use
`case`	`key`	String	`"DEMO-C46"`	Required. The linked Test Case key shown in Vansah.
`project`	`key`	String	`"DEMO"`	The Jira space key. Required for a folder path and included in the examples.
`result`	`name`	String	`"passed"`	Send explicitly. Use the current configured result name; use Untested before reporting individual steps.

The API field names JSON path project.key and projectKey refer to the Jira space key.

For Test Plans, use "asset": {"type":"plannedRun","key":"DEMO-P13","iteration":1}. A top-level iteration field is not used. An iteration number must be a JSON number, such as 1, rather than "1".

When selecting a folder by path, also include "project":{"key":"DEMO"} and copy the exact path, including slashes. See Copying a Test Folder Path.

For an Advanced Test Plan, also select its requirement. Use the Advanced Test Plan request guide.

2. 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.

3. 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; for Test Plan executions, this request does not automatically copy the iteration’s property selections.

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

{
  "asset": {
    "type": "issue",
    "key": "DEMO-123"
  },
  "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

This complete example groups the execution under a CI build label and chooses a reporting timezone:

{
  "asset": {
    "type": "issue",
    "key": "DEMO-123"
  },
  "case": {
    "key": "DEMO-C46"
  },
  "project": {
    "key": "DEMO"
  },
  "result": {
    "name": "passed"
  },
  "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; Test Plan executions use the selected iteration’s captured fingerprint. You do not need to send a fingerprint value.

4. Send the request

Run this command from the directory containing run.json. Add any mandatory properties to the file first:

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.json

Each successful POST creates a new run. If the request times out or returns a creation failure, check whether Vansah created the run before sending it again. An execution-group label does not prevent duplicate requests.

5. Read the response

A successful request returns HTTP 200. This example shows selected fields for the Passed work item or folder request with the default result name. The complete response includes additional property, execution context, and log details. The Untested plan example returns result ID 3 instead.

{
  "success": true,
  "message": "A new Test Run created.",
  "data": {
    "run": {
      "identifier": "a3043da4-e54b-4bee-aa9b-556e442d49f1",
      "key": 248,
      "projectKey": "DEMO",
      "overallResult": {
        "id": 2,
        "name": "PASSED"
      }
    }
  }
}

Response JSON path	Meaning
`data.run.identifier`	The new run’s UUID. Save it for later result and attachment requests.
`data.run.key`	The numeric run key within the Jira space.
`data.run.projectKey`	The Jira space key.
`data.run.asset`	The execution context. For a Test Plan, this includes `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. Save log identifiers to report individual step results. A log is not guaranteed for a script with no applicable content.

Vansah uses the active Test Case version linked to the selected execution context. If no matching active mapping is found, it falls back to the Test Case’s current version.

Record step results and attach evidence

Sending a result at creation initializes the applicable logs with the same outcome. For different outcomes or actual results per step, use the returned log identifiers in subsequent requests. Send {"result":{"name":"untested"}} when creating the run if you want to start Untested.

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 work item, folder, or plan selector. For plans, also check the 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 work item, folder, or plan requirement.
`Please make sure a Test Case is not Blocked.`	Check the blocked state in the execution context and, for Advanced Test Plans, 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.

Create a Test Run (API)