API: Attachments
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.
info Please Note: After TestRail 7.1 release (cloud), the attachment management system has slightly changed. A new format for attachment ID has been introduced.
Please check here: Introduction to the TestRail API
On this page:
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 entry. 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.
info Please Note: 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 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 result 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
}
]
}
info Please Note: After TestRail 7.1 release (cloud), the attachment management system has 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 |
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) |