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.

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)