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, UUIDs, paths, 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.

1. Choose where to record the execution

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

Context	Required fields
Jira work item	`asset.type: "issue"` and the work item’s string key in `asset.key`, such as `DEMO-123`.
Test Folder	`asset.type: "folder"` and one string selector: `asset.identifier` (folder UUID), `asset.key` (such as `DEMO-F3`), or `asset.folderPath` (exact stored path).
Standard Test Plan	`asset.type: "plannedRun"`, the plan’s string `asset.key` (such as `DEMO-P13`) or UUID `asset.identifier`, and `asset.iteration`.
Advanced Test Plan	Use the same plan and iteration fields, plus the selected requirement. Follow Create a Test Run in an Advanced Test Plan for the requirement fields and complete examples.

Body field	Type and requirement	How to use it
`case.key` or `case.identifier`	String · One required	The linked Test Case key, such as `DEMO-C46`, or its UUID. Send one selector.
`asset.iteration`	Positive integer or object · Required for a Test Plan	Use an existing iteration number, such as `1`, or `{"identifier":"YOUR_ITERATION_UUID"}`. It belongs inside `asset`.
`project.key`	String · Required for a folder path; otherwise optional context	The Jira space key, such as `DEMO`. For a key or UUID selector, use the space containing that execution context. The asset determines the run’s space.
`result`	Object · Send explicitly	Use `{"id":2}` for Passed when enabled for the space, or `{"id":3}` for Untested before recording step outcomes. See the result rules below.

The API field names 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.

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": {
    "id": 2
  }
}

Example: Test Folder

Use the existing folder’s UUID in asset.identifier. Replace the sample UUID and save the complete body as run.json:

{
  "asset": {
    "type": "folder",
    "identifier": "7a2ba77a-244e-4c08-8386-6e4d0176b851"
  },
  "case": {
    "key": "DEMO-C46"
  },
  "project": {
    "key": "DEMO"
  },
  "result": {
    "id": 2
  }
}

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": {
    "id": 3
  }
}

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

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.

Body field	Type	Behavior
`properties.environment.name`	String	Environment name, such as `UAT`. An unknown name creates a Vansah environment in the execution context’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 execution context’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 execution context’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; 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. Retry and execution-group identifiers associate runs; they do 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 field	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.id: 3 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 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)