Use the Vansah REST API to connect automated tests, CI/CD pipelines, and development tools to your testing data. You can create and find test cases, record test runs and step results, attach evidence, and retrieve data for reporting.

Set up API access

In Jira, open Apps → Vansah, select the settings gear, and open Vansah API Tokens.
Create a token and copy the API Connect URL shown for your workspace. Follow Creating a Vansah API Token and Finding Your Vansah API Connect URL.
Use an account that can access the Jira space and has the permissions needed for the operation. For example, recording a run or a step result requires permission to execute test cases.

The examples use Bash and cURL. Set VANSAH_URL to the API Connect URL without a trailing slash and VANSAH_TOKEN to your token. Store the token in your tool’s secret or credential settings.

Request headers and Jira space fields

Header	Value
Authorization	Your complete Vansah API token, without a `Bearer` prefix.
Accept	`application/json`
Content-Type	`application/json` for JSON requests. For file uploads, use the format required by the attachment endpoint.

API field names such as projectKey and project.key refer to the Jira space key. Preserve those field names in requests. Replace sample values with values from your own Jira space:

Value	Example
Jira space key	`DEMO`
Jira work item key	`DEMO-123`
Vansah test case key	`DEMO-C46`
Vansah Test Plan key	`DEMO-P13`
Identifier	A UUID returned by Vansah. A case, run, and step log each have a different identifier.

Common requests

Append the paths below to your API Connect URL. Each linked guide gives the request fields, permissions, examples, and response details for that task.

Task	Method and path
Find test cases	`GET /api/v2/testCases`
Create a test case	`POST /api/v2/testCase`
Create a Test Run	`POST /api/v2/run`
Retrieve a Test Run	`GET /api/v2/run/{identifierOrKey}`
Find the step logs in a run	`GET /api/v2/run/{identifierOrKey}/logs`
Update a step result	`PUT /api/v2/logs/{identifier}`
Create a missing step log	`POST /api/v2/logs`
Attach evidence to a step log	`POST /api/v2/logs/{identifier}/attachments`
List Standard Test Plan cases or Advanced Test Plan cases	`GET /api/v2/testplan/testCases`
Create Advanced Test Plans in bulk	`POST /api/v2/advancedTestPlan/bulk`
Create Test Folders in bulk	`POST /api/v2/testFolder/bulk`
List test environments	`GET /api/v2/properties/environments`
List test case types	`GET /api/v2/category/caseTypes`

Example: report an automated test result

This example records a passing execution of DEMO-C46 against Jira work item DEMO-123. The test case must already be linked to that work item and must not be blocked.

1. Find the test case

curl --request GET --get \
  --url "$VANSAH_URL/api/v2/testCases" \
  --header "Authorization: $VANSAH_TOKEN" \
  --header "Accept: application/json" \
  --data-urlencode "projectKey=DEMO" \
  --data-urlencode "caseKey=DEMO-C46" \
  --data-urlencode "startAt=0" \
  --data-urlencode "limit=50"

Confirm that the response identifies the case you intended to test. To create a case first, use the Create a Test Case API.

2. Create the Test Run

Save this JSON as run.json:

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

Send the file from the directory where you saved it:

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

If the Jira space makes an environment, release, or sprint mandatory, include the required properties values. See Create a Test Run for the complete field options.

3. Save the run identifier

Example successful response, showing selected fields:

{
  "success": true,
  "message": "A new Test Run created.",
  "data": {
    "run": {
      "identifier": "8f3d15c4-7a1b-426c-b1cb-683d83dd6988",
      "key": 246,
      "projectKey": "DEMO",
      "overallResult": {
        "id": 2,
        "name": "PASSED"
      }
    }
  }
}

Save data.run.identifier for later requests. The numeric data.run.key is the run number; its readable key in this example is DEMO-TR246.

4. Record individual step results when needed

Supplying a result when creating a run applies that starting outcome to its initial step logs. If your automation reports a separate outcome for each step, create the run without result, retrieve its logs, and update the matching logs.

Set VANSAH_RUN_ID to the returned run identifier, then retrieve the logs:

curl --request GET \
  --url "$VANSAH_URL/api/v2/run/$VANSAH_RUN_ID/logs" \
  --header "Authorization: $VANSAH_TOKEN" \
  --header "Accept: application/json"

Find the step in data.logs and use its log identifier for PUT /api/v2/logs/{identifier}. Use POST /api/v2/logs only for a step that does not already have a log. Follow Record a Test Step Result and Attach Files to a Test Step.

Test Plans, results, and pagination

For a Test Plan execution, use an existing iteration. An Advanced Test Plan also needs its work item or folder requirement. See Create a Test Run in an Advanced Test Plan.
Check the result format for the endpoint. Creating a run accepts a result object such as {"name":"passed"}; list filters such as resultID use documented numeric codes. These formats are not interchangeable in every request.
List endpoints commonly use startAt and limit, but defaults and response nesting vary. Test case lists use data.pagination; environment lists return pagination at the top level.
Keep the same filters and sort order while requesting additional pages. Use the endpoint’s pagination.total and returned page size to decide when to stop.
Use exact folder paths, including the required slashes. Encode query values with --data-urlencode.

Handle errors and retries

Check success, message, and any data.errors before continuing. An empty matching list can still be a successful response.
For authentication failures, verify the API URL and token. For access errors, verify the account’s Jira space access and the operation’s permissions.
Each successful POST /api/v2/run creates a new run. After a timeout, check whether the original request succeeded before sending another create request.
For a log that already exists, update it with PUT using its log UUID. Do not treat a repeated POST as an update.
When contacting Support, share the method, endpoint, and response without your token or other credentials.

Postman and integration guides

Explore requests in the Vansah Postman collection. For tool setup and examples, use the Java integration guide, C# integration guide, or CI/CD integration guide.

Vansah REST API Quick Reference