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.

On this page:

    API Rate Limit

    Please note that the API is rate-limited on TestRail Cloud to ensure optimal performance for all users and may throttle requests. TestRail might also return a 429 Too Many Requests response, which you are expected to handle. Such a response also includes a Retry-After header indicating how many seconds to wait before you are allowed to submit the next request.

    To avoid rate limits on TestRail Cloud, try using bulk API endpoints (e.g. using as add_results_for_cases instead of add_results_for case), build a time delay into your API calls, or upgrade to TestRail Enterprise Cloud.

    Rate limits for TestRail Cloud are as follows:

    • 180 Requests per instance, per minute for TestRail Cloud Professional subscriptions.
    • 300 Requests per instance, per minute for TestRail Cloud Enterprise subscriptions.

    No API rate limits are built into TestRail Server installations.

    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
    limit=:limit
    &offset=:offset
    :case_id The ID of the test case to retrieve attachments from

     

    info Please Note: As of February 26, 2021 the data structure returned by bulk GET API endpoints will change. These bulk endpoints will no longer return an array of all entities, but will instead return an object with additional pagination fields and an array of up to 250 entities.To see the new response structure and test any necessary code changes, include the following header and value in your API requests: x-api-ident: beta.

    New 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
      }
    ]
    }
    

    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

    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

    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
    limit=:limit
    &offset=:offset
    :plan_id The ID of the test plan to retrieve attachments from

     

    info Please Note: As of February 26, 2021 the data structure returned by bulk GET API endpoints will change. These bulk endpoints will no longer return an array of all entities, but will instead return an object with additional pagination fields and an array of up to 250 entities.To see the new response structure and test any necessary code changes, include the following header and value in your API requests: x-api-ident: beta.

    New 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

    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

    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
    limit=:limit
    &offset=:offset
    :run_id The ID of the test run to retrieve attachments from

    The method returns the same response format as get_attachments_for_plan.

    info Please Note: As of February 26, 2021 the data structure returned by bulk GET API endpoints will change. These bulk endpoints will no longer return an array of all entities, but will instead return an object with additional pagination fields and an array of up to 250 entities.To see the new response structure and test any necessary code changes, include the following header and value in your API requests: x-api-ident: beta.

    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

    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
    :attachment_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