Use the following API methods to upload, retrieve and delete attachments.
The following headers must be used when uploading attachments via the TestRail API using POST requests:
Content-Type: multipart/form-data
The attachment should be submitted as form data in the body of the request. Please review our Accessing the API documentation or TestRail’s bindings for examples of submitting an attachment.
After TestRail 7.1 release (cloud), the attachment management system slightly changed. A new format for attachment ID has been introduced. Please check here: Introduction to the TestRail API
add_attachment_to_case
This endpoint requires TestRail 6.5.2 or later.
Adds an attachment to a test plan. The maximum allowable upload size is set to 256MB.
POST index.php?/api/v2/add_attachment_to_case/{case_id}
Parameters
Name | Type | Required | Description |
---|---|---|---|
case_id | integer | true | The ID of the test case the attachment should be added to. |
Response content
Please see below for a typical response:
{
"attachment_id": 443
}
The following system fields are always included in the response:
Name | Type | Description |
---|---|---|
attachment_id | integer | The ID of the attachment uploaded to TestRail |
Response codes
Status Code | Description |
---|---|
200 | Success (the attachment ID is returned in the response) |
400 | Invalid or unknown test case |
403 | No access to the project |
429 | TestRail Cloud only—Too many requests (see API rate limit) |
add_attachment_to_plan
This endpoint requires TestRail 6.3 or later.
Adds an attachment to a test plan. The maximum allowable upload size is set to 256MB.
POST index.php?/api/v2/add_attachment_to_plan/{plan_id}
Parameters
Name | Type | Required | Description |
---|---|---|---|
plan_id | integer | true | The ID of the test plan the attachment should be added to. |
Response content
Please see below for a typical response:
{
"attachment_id": 443
}
The following system fields are always included in the response:
Name | Type | Description |
---|---|---|
attachment_id | integer | The ID of the attachment uploaded to TestRail |
Response codes
Status Code | Description |
---|---|
200 | Success (the attachment ID is returned in the response) |
400 | Invalid or unknown test plan |
403 | No access to the project |
429 | TestRail Cloud only—Too many requests (see API rate limit) |
add_attachment_to_plan_entry
This endpoint requires TestRail 6.3 or later.
Adds an attachment to a test plan. The maximum allowable upload size is set to 256MB.
POST index.php?/api/v2/add_attachment_to_plan_entry/{plan_id}/{entry_id}
Parameters
Name | Type | Required | Description |
---|---|---|---|
plan_id | integer | true | The ID of the test plan containing the entry |
entry_id | integer | true | The ID of the test plan entry the attachment should be added to |
Response content
Please see below for a typical response:
{
"attachment_id": 443
}
The following system fields are always included in the response:
Name | Type | Description |
---|---|---|
attachment_id | integer | The ID of the attachment uploaded to TestRail |
Response codes
Status Code | Description |
---|---|
200 | Success (the attachment ID is returned in the response) |
400 | POST request not formatted properly or invalid ID parameter(s) |
403 | No access to the project or insufficient permissions |
429 | TestRail Cloud only—Too many requests (see API rate limit) |
add_attachment_to_result
This endpoint requires TestRail 5.7 or later.
The ability to edit test results must be enabled under ‘Site Settings’ in order for add_attachment_to_result endpoints to work.
Adds an attachment to a result based on the result ID. The maximum allowable upload size is set to 256MB.
POST index.php?/api/v2/add_attachment_to_result/{result_id}
Parameters
Name | Type | Required | Description |
---|---|---|---|
result_id | integer | true | The ID of the test result the attachment should be added to |
See the Results API documentation for details of how to obtain:result_id’s.
Response content
Please see below for a typical response:
{
"attachment_id": 443
}
The following system fields are always included in the response:
Name | Type | Description |
---|---|---|
attachment_id | integer | The ID of the attachment uploaded to TestRail |
Response codes
Status Code | Description |
---|---|
200 | Success (the attachment ID is returned in the response) |
400 | POST request not formatted properly or invalid result ID |
403 | No access to the project or insufficient permissions |
429 | TestRail Cloud only—Too many requests (see API rate limit) |
add_attachment_to_run
This endpoint requires TestRail 6.3 or later.
Adds an attachment to test run. The maximum allowable upload size is set to 256MB.
POST index.php?/api/v2/add_attachment_to_run/{run_id}
Parameters
Name | Type | Required | Description |
---|---|---|---|
run_id | integer | true | The ID of the test run the attachment should be added to |
Response content
Please see below for a typical response:
{
"attachment_id": 443
}
The following system fields are always included in the response:
Name | Type | Description |
---|---|---|
attachment_id | integer | The ID of the attachment uploaded to TestRail |
Response codes
Status Code | Description |
---|---|
200 | Success (the attachment ID is returned in the response) |
400 | POST request not formatted properly or invalid run ID |
403 | No access to the project or insufficient permissions |
429 | TestRail Cloud only—Too many requests (see API rate limit) |
get_attachments_for_case
This endpoint requires TestRail 5.7 or later.
Returns a list of attachments for a test case.
GET index.php?/api/v2/get_attachments_for_case/{case_id}&limit={limit}&offset={offset}
Parameters
Name | Type | Required | Description |
---|---|---|---|
case_id | integer | true | The ID of the test case to retrieve attachments from |
Request filters
The following filters can be applied:
Name | Type | Description |
---|---|---|
limit | integer | The number of attachments the response should return (The response size is 250 by default) –requires TestRail 6.7 or later |
offset | integer | Where to start counting the attachments from (the offset) – requires TestRail 6.7 or later |
Response Content
Please see below for a typical response:
{
"offset": 0,
"limit": 250,
"size": 0,
"_link": {
"next": null,
"prev": null,
},
"attachments": [
{
"id": 1773,
"name": "image.jpg",
"size": 21995,
"created_on": 1585560521,
"project_id": 33,
"case_id": 57333,
"user_id": 1,
"result_id": null
}
]
}
After TestRail 7.1 release (cloud), the attachment management system slightly changed. A new format for attachment ID has been introduced. Please check here: API – Getting Started
{
"offset": 0,
"limit": 250,
"size": 4,
"_links": {
"next": null,
"prev": null
},
"attachments": [
{
"client_id": 614308,
"project_id": 2,
"entity_type": "case",
"id": "2ec27be4-812f-4806-9a5d-d39130d1691a",
"created_on": 1631722975,
"data_id": "63c82867-526d-43be-b1a5-9ddfcf581cf5",
"entity_id": "3",
"filename": "msdia80.dll",
"filetype": "dll",
"legacy_id": 0,
"name": "msdia80.dll",
"size": 904704,
"user_id": 1,
"is_image": false,
"icon": "other"
}
]
}
The following system fields are always included in the response:
Name | Type | Description |
---|---|---|
id | integer | The unique ID for the attachment |
name | string | Name of the attachment |
size | integer | Size of the attachment in bytes |
created_on | timestamp | The time/date the attachment was uploaded |
project_id | integer | The ID of the project the attachment was uploaded against |
case_id | integer | The ID of the case the attachment belongs to |
user_id | integer | The ID of the user who uploaded the attachment |
result_id | integer | The test result ID to which the attachment belongs |
Response codes
Status Code | Description |
---|---|
200 | Success(an array of attachment details is returned in the response) |
400 | Invalid test case ID |
403 | No access to the project or insufficient permissions |
429 | TestRail Cloud only—Too many requests (see API rate limit) |
get_attachments_for_plan
This endpoint requires TestRail 6.3 or later.
Returns a list of attachments for a test plan.
GET index.php?/api/v2/get_attachments_for_plan/{plan_id}&limit={limit}&offset={offset}
Parameters
Name | Type | Required | Description |
---|---|---|---|
plan_id | integer | true | The ID of the test plan to retrieve attachments from |
Request filters
The following filters can be applied:
Name | Type | Description |
---|---|---|
limit | integer | The number of attachments the response should return (The response size is 250 by default) –requires TestRail 6.7 or later |
offset | integer | Where to start counting the attachments from (the offset) – requires TestRail 6.7 or later |
Response Content
Please see below for a typical response:
[
{
"id": 1900,
"name": "TR-2104.gif",
"size": 3838070,
"created_on": 1602178189,
"project_id": 15,
"case_id": null,
"user_id": 1,
"entity_attachments_id": 360,
"icon_name": "Gif Image",
"result_id": null
}
]
The following system fields are always included in the response:
Name | Type | Description |
---|---|---|
id | integer | The unique ID for the attachment |
name | string | Name of the attachment |
size | integer | Size of the attachment in bytes |
created_on | timestamp | The time/date the attachment was uploaded |
project_id | integer | The ID of the project the attachment was uploaded against |
case_id | integer | The ID of the case the attachment belongs to |
user_id | integer | The ID of the user who uploaded the attachment |
entity_attachments_id | integer | The ID of the attachment record (not the ID of the attachment itself) |
icon_name | string | The name of the icon used within the TestRail UI |
result_id | integer | The test result ID to which the attachment belongs |
Response codes
Status Code | Description |
---|---|
200 | Success (an array of attachment details is returned in the response) |
400 | Invalid test ID |
403 | No access to the project or insufficient permissions |
429 | TestRail Cloud only—Too many requests (see API rate limit) |
get_attachments_for_plan_entry
This endpoint requires TestRail 6.3 or later.
Returns a list of attachments for a test plan entry.
GET index.php?/api/v2/get_attachments_for_plan_entry/{plan_id}/{entry_id}
Parameters
Name | Type | Required | Description |
---|---|---|---|
plan_id | integer | true | The ID of the test plan containing the entry |
entry_id | integer | true | The ID of the test plan entry to retrieve attachments from |
The method returns the same response format as get_attachments_for_plan.
Response codes
Status Code | Description |
---|---|
200 | Success (an array of attachment details is returned in the response) |
400 | Invalid test ID |
403 | No access to the project or insufficient permissions |
429 | TestRail Cloud only—Too many requests (see API rate limit) |
get_attachments_for_run
This endpoint requires TestRail 6.3 or later.
Returns a list of attachments for a test run.
GET index.php?/api/v2/get_attachments_for_run/{run_id}?limit={limit}&offset={offset}
Parameters
Name | Type | Required | Description |
---|---|---|---|
run_id | integer | true | The ID of the test run to retrieve attachments from |
The method returns the same response format as get_attachments_for_plan.
Request filters
The following filters can be applied:
Name | Type | Description |
---|---|---|
limit | integer | The number of attachments the response should return (The response size is 250 by default) –requires TestRail 6.7 or later |
offset | integer | Where to start counting the attachments from (the offset) – requires TestRail 6.7 or later |
Response codes
Status Code | Description |
---|---|
200 | Success (an array of attachment details is returned in the response) |
400 | Invalid test ID |
403 | No access to the project or insufficient permissions |
429 | TestRail Cloud only—Too many requests (see API rate limit) |
get_attachments_for_test
This endpoint requires TestRail 5.7 or later.
Returns a list of attachments for a test’s results.
GET index.php?/api/v2/get_attachments_for_test/{test_id}
Parameters
Name | Type | Required | Description |
---|---|---|---|
test_id | integer | true | The ID of the test to retrieve attachments from |
The method returns the same response format as get_attachments_for_case.
Response codes
Status Code | Description |
---|---|
200 | Success (an array of attachment details is returned in the response) |
400 | Invalid test ID |
403 | No access to the project or insufficient permissions |
429 | TestRail Cloud only—Too many requests (see API rate limit) |
get_attachment
This endpoint requires TestRail 5.7 or later.
Retrieves the requested file identified by attachment_id
.
GET index.php?/api/v2/get_attachment/{attachment_id}
Parameters
Name | Type | Required | Description |
---|---|---|---|
attachment_id | integer | true | The ID of the test to retrieve attachments from |
Response codes
Status Code | Description |
---|---|
200 | Success (the attachment is returned in the body of the response) |
400 | Invalid attachment ID |
403 | No access to the project or insufficient permissions |
429 | TestRail Cloud only—Too many requests (see API rate limit) |
delete_attachment
This endpoint requires TestRail 5.7 or later.
Deletes the specified attachment identified by attachment_id
.
POST index.php?/api/v2/delete_attachment/{attachment_id}
Parameters
Name | Type | Required | Description |
---|---|---|---|
attachment_id | integer | true | The ID of the attachment to delete |
Response content
A successful delete_attachment POST will return an empty response body with a 200 response code.
Response codes
Status Code | Description |
---|---|
200 | Success (the attachment was deleted) |
400 | Invalid attachment ID |
403 | No access to the project or insufficient permissions |
429 | TestRail Cloud only—Too many requests (see API rate limit) |