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.
On this page:
add_attachment_to_case
Adds an attachment to a test plan. The maximum allowable upload size is set to 256mb.
Requires TestRail 6.5.2 or later
POST index.php?/api/v2/add_attachment_to_case/:case_id
| :case_id | 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 | int | The ID of the attachment uploaded to TestRail |
Response codes
| 200 | Success, the attachment ID is returned in the response |
| 400 | POST request not formatted properly or invalid case ID |
| 403 | No access to the project or insufficient permissions |
add_attachment_to_plan
Adds an attachment to a test plan. The maximum allowable upload size is set to 256mb.
Requires TestRail 6.3 or later
POST index.php?/api/v2/add_attachment_to_plan/:plan_id
| :plan_id | 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 | int | The ID of the attachment uploaded to TestRail |
Response codes
| 200 | Success, the attachment ID is returned in the response |
| 400 | POST request not formatted properly or invalid plan ID |
| 403 | No access to the project or insufficient permissions |
add_attachment_to_plan_entry
Adds an attachment to a test plan entry. The maximum allowable upload size is set to 256mb.
Requires TestRail 6.3 or later
POST index.php?/api/v2/add_attachment_to_plan_entry/:plan_id/:entry_id
| :plan_id | The ID of the test plan containing the entry |
| :entry_id | 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 | int | The ID of the attachment uploaded to TestRail |
Response codes
| 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 |
add_attachment_to_result
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 attachment to a result based on the result ID. The maximum allowable upload size is set to 256mb.
Requires TestRail 5.7 or later
POST index.php?/api/v2/add_attachment_to_result/:result_id
| :result_id | 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 | int | The ID of the attachment uploaded to TestRail |
Response codes
| 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 |
add_attachment_to_run
Adds attachment to test run. The maximum allowable upload size is set to 256mb.
Requires TestRail 6.3 or later
POST index.php?/api/v2/add_attachment_to_run/:run_id
| :run_id | 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 | int | The ID of the attachment uploaded to TestRail |
Response codes
| 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 |
get_attachments_for_case
Returns a list of attachments for a test case.
Requires TestRail 5.7 or later
GET index.php?/api/v2/get_attachments_for_case/:case_id
| :case_id | The ID of the test case to retrieve attachments from |
Response content
Please see below for a typical response:
[
{
"id": 1773,
"name": "image.jpg",
"size": 21995,
"created_on": 1585560521,
"project_id": 33,
"case_id": 57333,
"user_id": 1,
"result_id": null
}
]
The following system fields are always included in the response:
| Name | Type | Description |
| id | int | The unique ID for the attachment |
| name | string | Name of the attachment |
| Size | int | Size of the attachment in bytes |
| created_on | timestamp | The time/date the attachment was uploaded |
| project_id | int | The ID of the project the attachment was uploaded against |
| case_id | int | The ID of the case the attachment belongs to |
| user_id | int | The ID of the user who uploaded the attachment |
| result_id | int | The test result ID to which the attachment belongs |
Response codes
| 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 |
get_attachments_for_plan
Returns a list of attachments for a test plan.
Requires TestRail 6.3 or later
GET index.php?/api/v2/get_attachments_for_plan/:plan_id
| :plan_id | The ID of the test plan to retrieve attachments from |
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 | int | The unique ID for the attachment |
| name | string | Name of the attachment |
| size | int | Size of the attachment in bytes |
| created_on | timestamp | The time/date the attachment was uploaded |
| project_id | int | The ID of the project the attachment was uploaded against |
| case_id | int | The ID of the case the attachment belongs to |
| user_id | int | The ID of the user who uploaded the attachment |
| entity_attachments_id | int | 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 | int | The test result ID to which the attachment belongs |
Response codes
| 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 |
get_attachments_for_plan_entry
Returns a list of attachments for a test plan entry.
Requires TestRail 6.3 or later
GET index.php?/api/v2/get_attachments_for_plan_entry/:plan_id/:entry_id
| :plan_id | The ID of the test plan containing the entry |
| :entry_id | 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
| 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 |
get_attachments_for_run
Returns a list of attachments for a test run.
Requires TestRail 6.3 or later
GET index.php?/api/v2/get_attachments_for_run/:run_id
| :run_id | The ID of the test run to retrieve attachments from |
The method returns the same response format as get_attachments_for_plan.
Response codes
| 200 | Success, an array of attachment details is returned in the response |
| 400 | Invalid test ID |
| 403 | No access to the project |
get_attachments_for_test
Returns a list of attachments for a test’s results.
Requires TestRail 5.7 or later
GET index.php?/api/v2/get_attachments_for_test/:test_id
| :test_id | The ID of the test to retrieve attachments from |
The method returns the same response format as get_attachments_for_case.
Response codes
| 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 |
get_attachment
Retrieves the requested file identified by :attachment_id.
Requires TestRail 5.7 or later
GET index.php?/api/v2/get_attachment/:attachment_id
| :test_id | The ID of the test to retrieve attachments from |
Response codes
| 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 |
delete_attachment
Deletes the specified attachment identified by :attachment_id.
Requires TestRail 5.7 or later
POST index.php?/api/v2/delete_attachment/:attachment_id
| :attachment_id | The ID of the attachment to to delete |
Response content
A successful delete_attachment POST will return an empty response body with a 200 response code.
Response codes
| 200 | Success, the attachment was deleted |
| 400 | Invalid attachment ID |
| 403 | No access to the project or insufficient permissions |