Use a Test Log to record a step’s result and what actually happened during a Test Run. Update an existing step log with PUT /api/v2/logs/{identifier}, or create a missing log with POST /api/v2/logs.

Check for an existing log first. Creating a Test Run normally prepares its step logs. Sending POST again for the same run and step returns A Test Log already exists for provided Step. Use that log’s identifier to update it.

Before you begin

Create a Vansah API token and use the Vansah URL supplied for your workspace.
Make sure the token account can access the Jira space and execute Test Cases in Vansah.
Have an existing Test Run and the step number from that run’s script. Use the run for the intended requirement and iteration.

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. Replace the sample UUIDs with identifiers from your own Test Run. Keep your token private.

Endpoints and headers

Method and endpoint	Use it to
`GET /api/v2/run/{identifierOrKey}/logs`	Find the step logs in a Test Run.
`PUT /api/v2/logs/{identifier}`	Update an existing log’s result or actual outcome.
`POST /api/v2/logs`	Create a log for a step that does not already have one.

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

1. Find the existing step logs

Use the Test Run UUID returned when the run was created:

curl --request GET \
  --url "$VANSAH_URL/api/v2/run/a3043da4-e54b-4bee-aa9b-556e442d49f1/logs" \
  --header "Authorization: $VANSAH_TOKEN" \
  --header "Accept: application/json"

The response contains a data.logs array. Find the intended step and copy that log’s identifier. This is the log UUID, which is different from the run UUID. The response includes the existing result, actual outcome, step information, and attachments.

2. Update a step’s result

Use the log UUID from step 1. This request records a Passed result and the actual outcome:

curl --request PUT \
  --url "$VANSAH_URL/api/v2/logs/fc63828a-e54c-4b6f-bf2e-aa9b556e442d" \
  --header "Authorization: $VANSAH_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{"result":{"name":"passed"},"actualResult":"The user signed in and the account page appeared."}'

A successful update returns success: true, the message Updated Test Log., and the log details in data.log. The run’s overall result is recalculated. If your Jira space requires Test Run properties, supply those on the run before recording its result.

3. Create a missing step log

Use POST only if no log exists for the step in that run. Save this JSON as step-result.json:

{
  "run": {
    "identifier": "a3043da4-e54b-4bee-aa9b-556e442d49f1"
  },
  "step": {
    "number": 1
  },
  "result": {
    "name": "passed"
  },
  "actualResult": "The user signed in and the account page appeared."
}

Body field	What to send
`run.identifier`	The existing Test Run UUID. As an alternative, use `run.key` with the full readable key, such as `DEMO-TR246`.
`step.number`	Required integer identifying the step in the run, starting at `1`. Use `0` only for a run that has no script steps.
`result.name`	The result to record. Use one of the exact lowercase names listed below.
`actualResult`	Optional text explaining what happened. Omit it if there is no comment to record.
`actualResultAdf`	Optional structured rich-text document instead of `actualResult`. If both are present, this field takes precedence.
`linkedIssues`	Optional array of Jira work items to link to the log. Each item needs its numeric `id` and readable `key`. The account must be able to access the work items.

The run identifies the Jira space, so a separate projectKey is not needed in this example.

Send the file:

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 data.log.identifier for subsequent updates or attachments. Read it back with GET /api/v2/logs/{identifier} to confirm the saved result.

Accepted result names

For the POST request, use one of these values in result.name:

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

Use the exact lowercase values above for creating a log. A custom display label is not a supported POST result name.

Add actual outcomes and evidence

For plain text, use actualResult. For a structured rich-text outcome, use actualResultAdf with an Atlassian Document Format (ADF) document. For example, add this field to the request:

{
  "actualResultAdf": {
    "version": 1,
    "type": "doc",
    "content": [
      {
        "type": "paragraph",
        "content": [
          {
            "type": "text",
            "text": "The user signed in and the account page appeared."
          }
        ]
      }
    ]
  }
}

Rich-text requests are limited to 2,000,000 serialized bytes, 10,000 nodes, and 200,000 text characters. Saved-field capacity can impose a smaller limit. Keep long logs or reports as attachments and use the actual outcome to summarize the result.

To attach screenshots or files after saving the result, see Attach Files to a Test Step (API).

Troubleshooting

Message or issue	What to check
`A Test Log already exists for provided Step.`	Use the existing log UUID returned in `data.log.identifier`, or list the run’s logs. Update it with PUT rather than repeating POST.
`Test Run not found.`	Check the run UUID or full run key and the token’s workspace.
`Invalid Step provided.`	Use the step number in that Test Run. A Test Case’s current script can differ from the script used by an older run.
`One or more validation errors found.`	Inspect `data.errors`. Check the run and step objects, UUID, integer step number, and exact result name.
`Invalid result provided.`	Use a supported result name.
`Invalid Issues provided.`	Check linked work item keys and the account’s access. Include each work item’s ID and key.
Authentication or permission error	Check the Vansah URL, token, Jira space access, and permission to execute Test Cases.
`Failed to create Log.`	Read the run’s logs before retrying. If a log exists, update it. If the issue continues, contact Vansah Support with the request and response, without your token.

Example validation error:

{
  "success": false,
  "message": "One or more validation errors found.",
  "data": {
    "errors": [
      {
        "value": "first",
        "msg": "Please provide valid Step number",
        "param": "step.number",
        "location": "body"
      }
    ]
  }
}

You can also view the create request in the Vansah API collection in Postman.

Record a Test Step Result (API)