Attach screenshots, logs, or reports to a step in an existing Test Run. Send the files with the run number, Jira space key, and step number. For Plain Text, BDD, or Automation scripts, select the script type instead of a step number.

Before you begin

Create a Vansah API token with Jira access configured for the workspace containing the run.
Have an existing Test Run and the step or script log you want to attach evidence to. Use the run for the intended Test Case and, where applicable, Test Plan requirement and iteration.
For a run shown as DEMO-TR248, use 248 as the run number and DEMO as the Jira space key. This upload request sends those values in separate fields.
Have the files available on the computer or build agent sending the request.

If you need a run first, follow Create a Test Run. To check or record the step’s result, see Record a Test Step Result.

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 space, run number, step, and local file paths with your own values.

1. Upload files to a step

This complete request attaches two files to step 1 of run DEMO-TR248:

curl --request POST \
  --url "$VANSAH_URL/api/v2/testRun/attachment" \
  --header "Authorization: $VANSAH_TOKEN" \
  --header "Accept: application/json" \
  --form "projectKey=DEMO" \
  --form "testRunKey=248" \
  --form "testStep=1" \
  --form "attachments=@./screenshots/login-failure.png" \
  --form "attachments=@./logs/browser.log"

The @ tells cURL to read a local file. Repeat the exact field name attachments for each file. This example uses multipart form data so the files can be uploaded directly.

Form-data field	Type	Example value	Use
`projectKey`	Text	`DEMO`	Required with the run number. The Jira space key. Keep the API field name projectKey.
`testRunKey`	Numeric text	`248`	Required. The number from the Test Run key, sent separately from the Jira space key.
`testStep`	Integer as text	`1`	Required for a Multi Steps run. The step must already have a log in this run.
`attachments`	File	`login-failure.png`	Required. Send at least one file; repeat this field for additional files.

projectKey refers to the Jira space key. It is a flat form-data field in this request; there is no nested project object.

Include the step number. If both the step number and script type are omitted, the files are attached to the Test Run itself.

2. Upload evidence to a Plain Text, BDD, or Automation script

Use the script type in place of the step number. This complete example uploads a report to the BDD log in run DEMO-TR249:

curl --request POST \
  --url "$VANSAH_URL/api/v2/testRun/attachment" \
  --header "Authorization: $VANSAH_TOKEN" \
  --header "Accept: application/json" \
  --form "projectKey=DEMO" \
  --form "testRunKey=249" \
  --form "scriptType=Bdd" \
  --form "attachments=@./reports/checkout-failure.html"

Script format	Form-data field	Example value
Plain Text	`scriptType`	`plainText`
BDD	`scriptType`	`Bdd`
Automation	`scriptType`	`automation`

Use the value that matches the run’s script format. Send one location selector: a step number for Multi Steps, or a script type for the other formats.

Make sure the script log already exists. If a matching Plain Text, BDD, or Automation run has no log, this endpoint can attach the file at run level. Check the intended log before uploading and verify the attachment location afterward.

Endpoint, headers, and upload limits

POST $VANSAH_URL/api/v2/testRun/attachment

Header	Value
`Authorization`	Your Vansah API token directly, without a Bearer prefix.
`Accept`	`application/json`
`Content-Type`	Let cURL or your HTTP client generate multipart/form-data and its boundary when sending files.

Use the exact file field name attachments, without square brackets. Do not set a JSON content type for the form-data requests above. This upload operation has no pagination or filtering parameters.

Limit	Maximum
Files in one multipart request	20
Each file	25 MiB (26,214,400 bytes)
Complete multipart request, including form fields and boundaries	100 MiB (104,857,600 bytes)

Split large batches into smaller requests. A batch with four files at the per-file maximum exceeds the complete request limit once the multipart overhead is included.

Upload from Postman

Create a POST request to your Vansah base URL followed by /api/v2/testRun/attachment.
Add the Authorization header with your Vansah API token and Accept with application/json.
Under Body, choose form-data. Add projectKey, testRunKey, and either testStep or scriptType as text fields, using the same values as the examples above.
Add attachments, change its type to File, and choose a local file. Repeat attachments for additional files.
Let Postman generate the multipart Content-Type header, then send the request.

See Postman’s form-data instructions for its file-picker options.

Read the response and check the attachment

A successful request returns HTTP 200. The response lists the uploaded file URLs under JSON path data.attachments:

{
  "success": true,
  "message": "Test Run Attachment(s) created successfully.",
  "data": {
    "attachments": [
      "https://attachments.example.com/login-failure.png",
      "https://attachments.example.com/browser.log"
    ]
  }
}

These URLs are synthetic examples. Use the values returned by your own request. Confirm that every expected file has a nonempty URL, then open the Test Run in Vansah and check the intended step or script log.

If any file is missing, has an empty URL, or appears at run level, check the target and saved attachments before retrying. Repeating a request can create duplicate attachments.

Errors and troubleshooting

HTTP status	Meaning
`400`	Invalid form fields, missing run or log, script mismatch, empty upload, multipart limit error, or an attachment-processing failure.
`401`	Missing, invalid, expired, or inactive token, or Jira access is not configured for the API token.
`403`	The account is blocked during authorization.

For example, a step number that does not match an existing log can return HTTP 400:

{
  "success": false,
  "message": "Please provide a valid Test Step Number",
  "data": [],
  "errorCode": 1306
}

Field-validation errors can instead include an array under JSON path data.errors. Check the field name and message; not every error response includes an error code.

Message or issue	What to check
`Please provide one or more attachments.`	Include at least one local file in the attachments field.
`Please provide a valid Test Run key(...)`	Use the numeric run portion with its Jira space key. This form does not accept the full DEMO-TR248 value as the run number.
`Please provide a valid Test Step Number`	Confirm the step number and an existing step log in that run.
`Test Case Script Type is not multi Steps`	Use testStep for a Multi Steps run. Use the matching scriptType for Plain Text, BDD, or Automation.
Script type mismatch	Check the run’s actual script format and the scriptType value.
Too many files, File too large, or an unexpected field	Check the upload limits and repeat the exact attachments field name.
Files appear on the Test Run	Include the intended step number or script type, and confirm the corresponding log already exists.
`Failed to create Test Run Attachments.`	Check for files already uploaded before retrying. If the issue continues, contact Vansah Support with the request and response after removing the token.

Attach Files to a Test Step (API)