API: Attachments - TestRail

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.

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": 444,
        "name": "What-Testers-Should-Be-Automating.jpg",
        "filename": "444.what_testers_should_be_automating.jpg",
        "size": 166994,
        "created_on": 1554737184,
        "project_id": 14,
        "case_id": 3414,
        "test_change_id": 17899,
        "user_id": 10
    }
]

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
filename string The filename 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
test_change_id int The test change ID to which the attachment belongs to
user_id int The ID of the user who uploaded the attachment

 

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

 

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_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_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_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_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

 

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