Use a Test Log to record a step’s outcome and what actually happened during a Test Run. Find the existing log and update it with PUT. Use POST only when that step does not yet have a log.

Before you begin

Create a Vansah API token with Jira access configured, and use your workspace’s Vansah base URL.
The token account needs access to the Jira space. Creating or updating logs requires permission to execute Test Cases.
Have an existing Test Run for the intended work item, folder, or Test Plan iteration. Use the steps captured for that run, which may differ from the Test Case’s current script.
When creating the run for later step reporting, use {"result":{"name":"untested"}} with your configured Untested name to initialize applicable logs. See Create a Test Run.

The examples use Bash and cURL. Set VANSAH_URL to the Vansah base URL without a trailing slash and VANSAH_TOKEN to your API token. Replace the sample UUIDs, keys, and values with your own. No example credentials are provided.

Endpoints and headers

Method and route	Purpose
`GET /api/v2/run/{identifierOrKey}/logs`	Return the existing logs for a Test Run.
`PUT /api/v2/logs/{identifier}`	Update an existing log’s outcome or actual result.
`POST /api/v2/logs`	Create a missing log for a step in an existing run.

Header	Value
`Authorization`	Your Vansah API token directly, without a `Bearer` prefix.
`Accept`	`application/json`
`Content-Type`	`application/json` for the JSON POST and PUT requests below.

Successful requests return HTTP 200. Each route uses a different request shape; use the fields listed for that operation.

1. Find the existing step logs

Use the Test Run’s readable key in the URL. Combine the Jira space key, -TR, and the numeric run key returned when the run was created. For example, space DEMO and run 248 give DEMO-TR248. Replace that sample key below with your own:

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

The response contains JSON path data.logs, an array of existing logs. This route returns all logs without pagination and does not create missing logs. Do not depend on the array order; match the log to the intended step.

Example response showing selected fields for a standard Passed step:

{
  "success": true,
  "message": "Test Log returned successfully",
  "data": {
    "logs": [
      {
        "identifier": "fc63828a-e54c-4b6f-bf2e-aa9b556e442d",
        "result": {
          "name": "PASSED"
        },
        "actualResult": "The user signed in and the account page appeared.",
        "step": {
          "order": 1
        }
      }
    ]
  }
}

Find the entry whose step order matches the step you are reporting. Copy that entry’s identifier from the response and set the Bash variable LOG_IDENTIFIER to that value. This required identifier comes from the response; you do not need to find it in the UI.

LOG_IDENTIFIER='fc63828a-e54c-4b6f-bf2e-aa9b556e442d'

The value above matches the sample response. Replace it with the identifier returned for your own step. Logs without a step can have step: null. The response can also contain actual-result rich text, attachments, and linked work items.

This list is not a view of one test-data iteration. Do not use an iteration query to assume the returned log results are limited to that iteration.

2. Update an existing step result

Save this JSON as update-step.json. It records Passed and the actual outcome:

{
  "result": {
    "name": "passed"
  },
  "actualResult": "The user signed in and the account page appeared."
}

curl --request PUT \
  --url "$VANSAH_URL/api/v2/logs/$LOG_IDENTIFIER" \
  --header "Authorization: $VANSAH_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data-binary @update-step.json

Parent object	JSON field	Type	Example value	Use
`result`	`name`	String	`"passed"`	Optional. Current workspace result name, matched case-insensitively. Omit the result object to leave the outcome unchanged.
Request body	`actualResult`	String	`"The user signed in and the account page appeared."`	Optional. Omit to preserve the saved actual result; send an empty string to clear it.
Request body	`iterationNum`	Positive integer	`2`	Optional existing test-data iteration. Without it, the update applies to every existing test-data iteration for this log.
Request body	`timezone`	String	`"America/New_York"`	Optional reporting timezone. Missing or unrecognized values fall back to Australia/Sydney.

When a result is supplied, Vansah checks the Test Run’s existing mandatory environment, sprint, and version selections. Set required properties on the run first. This PUT request does not set those properties. A blocked Test Case cannot be updated through this log operation.

The response includes success: true, the message Updated Test Log., and JSON path data.log containing the log identifier, actual result, and a run summary in JSON path data.log.run. The run’s overall outcome is recalculated when the result changes.

Keep the actual result focused on what happened. To add screenshots, logs, or reports, see Attach Files to a Test Step.

Report one test-data iteration

A test-data iteration is a row of test data used by the run. It is separate from the Test Plan iteration selected when the run was created.

For a run with existing test-data iteration logs, add iterationNum to the PUT body:

{
  "result": {
    "name": "passed"
  },
  "actualResult": "The user signed in and the account page appeared.",
  "iterationNum": 2
}

The number must be a positive integer and refer to an existing iteration for this log. It can also be supplied as a query parameter, such as ?iterationNum=2; the body value takes precedence. The parent log’s outcome is then recalculated across its iterations.

Omitting iterationNum updates all existing test-data iterations for the log. Supply it when your automation reports each data row separately. POST does not create a new test-data iteration.

3. Create a missing log only when needed

If no log exists for the step, save this as step-result.json:

{
  "run": {
    "key": "DEMO-TR248"
  },
  "step": {
    "number": 1
  },
  "result": {
    "name": "passed"
  },
  "actualResult": "The user signed in and the account page appeared."
}

Parent object	JSON field	Type	Example value	Use
`run`	`key`	String	`"DEMO-TR248"`	Required. The readable key of the existing Test Run.
`step`	`number`	Integer	`1`	Required. The captured step order in that run. Use 0 only when the run has no captured steps.
`result`	`name`	String	`"passed"`	Send explicitly. Use one of the fixed lowercase POST names listed below.
Request body	`actualResult`	String	`"The user signed in and the account page appeared."`	Optional description of what happened. Starts empty when omitted.

The run supplies the Jira space context. API fields named projectKey or project.key refer to the Jira space key.

POST result name	Meaning
`passed`	Passed
`failed`	Failed
`n/a`	Not applicable
`untested`	Untested
`n/a in progress`	Not applicable so far; still in progress
`failed in progress`	Failed so far; still in progress
`passed in progress`	Passed so far; still in progress

Use these exact lowercase names for POST. Blocked and custom result names are not accepted by its validator. PUT uses the workspace’s configured result names.

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

Example successful response:

{
  "success": true,
  "message": "A new Test Log created.",
  "data": {
    "log": {
      "identifier": "fc63828a-e54c-4b6f-bf2e-aa9b556e442d",
      "actualResultAdf": {
        "version": 1,
        "type": "doc",
        "content": [
          {
            "type": "paragraph",
            "content": [
              {
                "type": "text",
                "text": "The user signed in and the account page appeared."
              }
            ]
          }
        ]
      },
      "actualResult": "The user signed in and the account page appeared."
    }
  }
}

Save JSON path data.log.identifier. If a log already exists for that run and step, POST returns HTTP 400 with A Test Log already exists for provided Step. and the existing log in JSON path data.log. Use PUT with its identifier.

Errors and troubleshooting

HTTP status	Meaning
`400`	Invalid fields, missing run/log/step, duplicate POST, invalid result, blocked Test Case, missing mandatory run properties, rich-text validation failure, or a create/update failure.
`401`	Missing, invalid, expired, or inactive token, or the API token is not configured for Jira access.
`403`	The account is blocked or permission is denied. Jira permission lookups can also return a denial.
`503`	Jira permission lookup is temporarily unavailable during a create or update request. This error uses `errorCode: 1400`.

Example error for an invalid POST result:

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

Field-validation failures can instead include JSON path data.errors, with entries containing a field name and message. ADF validation uses errorCode: 1400; an error code is not present on every error response.

Message or issue	What to check
`A Test Log already exists for provided Step.`	Use PUT with the existing `data.log.identifier`, or list the run’s logs.
`Test Run not found.`	Check the run UUID or full key and the token’s workspace.
`Test log not found. Please provide correct log identifier`	Use the log UUID in the PUT URL.
`Invalid Step provided.`	Use the captured step order for that run, rather than the current Test Case script.
`Invalid result provided.`	Check the separate POST and PUT result rules.
`Test Log Iteration not found.`	Use an existing test-data iteration for that log.
`Invalid Issues provided.`	Check the linked work item IDs, keys, and the account’s access.
Environment, Sprint, or Version is required	Set the required properties on the Test Run before updating its result.
`Failed to create Log.` or `Failed to update Log.`	Read the saved logs before retrying. If the failure continues, contact Vansah Support with the request and response after removing your token.

Record a Test Step Result (API)