Help

Attachment API

Attachments

Using the Mingle Attachment API files can be uploaded to cards and wiki pages as attachments. Existing attachments can also be accessed or deleted from cards or wiki pages. Card attachment resources are located by issuing a GET request to the server with the card's number as a parameter. Wiki page attachment resources are located by issuing a GET to a server with a wiki page's identifier.

Please keep in mind that in many other parts of the system, the system assigned identifier, id, is used to identify a card. Attachments identify cards by number rather than by id. If you specify a card id rather than a card number, you may end up updating the wrong card, and damage your data.

Structure of an attachment resource

Please note that all the API resources and examples refer to v2 of the API. If you would like information on v1 of the API please refer to older versions of the help that can be found at the ThoughtWorks Studios website.

The structure of the attachment resource, and its attributes are described below, along with their data type. Also included with each attribute is whether you are allowed to update the value.

attachment resource xml - attributes
  • file_name: String; read only, file name of the attachment
  • url: String; read only, system defined location of an attachment

Get all attachments for a card

Reference

        Request Method: GET
        URL: /api/v2/projects/project_identifier/cards/card_number/attachments.xml
        Parameters: NA

Example

        GET
      
        http://yourname:password@your.mingle.server:8080/api/v2/projects/test_project/cards/42/attachments.xml

Explanation

The above is an example of a GET request to a Mingle server running at your.mingle.server, port 8080. The request is made with the authorization credentials of yourname/password. The URL of api/v2/projects/test_project/cards/42/attachments.xml represents the attachment resource for the card numbered 42 in project with identifier test_project.

Result

If you were authorized to perform the operation, and the resource was available, you should get an xml document that looks something like the following: 
    <?xml version="1.0" encoding="UTF-8"?>
    <attachments type="array">
      <attachment>
        <url>/attachments/b4a15f3dcbebe1cc641f8c5a08f78394/811/notes.txt</url>
        <file_name>notes.txt</file_name>
      </attachment>
      <attachment>
        <url>/attachments/ecd1a5d278ac586a5b7d6be6edbb1747/812/picture_1.png</url>
        <file_name>picture_1.png</file_name>
      </attachment>
    </attachments>

Get all attachments for a wiki page

Reference

        Request Method: GET
        URL: /api/v2/projects/project_identifier/wiki/page_identifier/attachments.xml
        Parameters: NA

Example

        GET
        
        http://yourname:password@your.mingle.server:8080/api/v2/projects/test_project/wiki/overview_page/attachments.xml

Explanation

The above is an example of a GET request to a Mingle server running at your.mingle.server, port 8080. The request is made with the authorization credentials of yourname/password. The URL of api/v2/projects/test_project/wiki/overview_page/attachments.xml represents the attachment resource for the Overview page in project with identifier test_project.

Result

If you were authorized to perform the operation, and the resource was available, you should get an xml document that looks something like the following: 
    <?xml version="1.0" encoding="UTF-8"?>
    <attachments type="array">
      <attachment>
        <url>/attachments/b4a15f3dcbebe1cc641f8c5a08f78394/811/notes.txt</url>
        <file_name>notes.txt</file_name>
      </attachment>
      <attachment>
        <url>/attachments/ecd1a5d278ac586a5b7d6be6edbb1747/812/picture_1.png</url>
        <file_name>picture_1.png</file_name>
      </attachment>
    </attachments>

Get an attachment for a wiki page or card

Reference

        Request Method: GET
        URL: attachment url returned in the attachment resource when requesting all attachments for a wiki page or card (see above)
        Parameters: NA

Example

        GET
        
        http://yourname:password@your.mingle.server:8080/api/v2/attachments/b4a15f3dcbebe1cc641f8c5a08f78394/811/notes.txt

Explanation

The above is an example of a GET request to a Mingle server running at your.mingle.server, port 8080. The request is made with the authorization credentials of yourname/password. The URL of /attachments/b4a15f3dcbebe1cc641f8c5a08f78394/811/notes.txt represents the attachment you want to access.

Result

If you were authorized to perform the operation, and the resource was available, you should be able to access the attachment.

Deleting an attachment on a card

Reference

        Request Method: DELETE
        URL: /api/v2/projects/project_identifier/cards/card_number/attachments/file_name
        Parameters: NA

Example

        DELETE

        http://yourname:password@your.mingle.server:8080/api/v2projects/test_project/cards/42/attachments/picture_1.png

Explanation

The above is an example of a DELETE request to a Mingle server running at your.mingle.server, port 8080. The request is made with the authorization credentials of yourname/password. The URL of projects/test_project/cards/42/attachments/picture_1.png represents the attachment picture_1.png for the card numbered 42 in project with identifier test_project.

Result

If you were authorized to perform the operation, and the resource was available, the attachment you specified should have been deleted.

Deleting an attachment on a wiki page

Reference

        Request Method: DELETE
        URL: /api/v2/projects/project_identifier/wiki/wiki_page/attachments/file_name
        Parameters: NA

Example

        DELETE

        http://yourname:password@your.mingle.server:8080/api/v2/projects/test_project/wiki/overview_page/attachments/picture_1.png

Explanation

The above is an example of a DELETE request to a Mingle server running at your.mingle.server, port 8080. The request is made with the authorization credentials of yourname/password. The URL of /projects/test_project/wiki/overview_page/attachments/picture_1.png represents the attachment picture_1.png for the wiki page Overview page in project with identifier test_project.

Result

If you were authorized to perform the operation, and the resource was available, the attachment you specified should have been deleted.

Uploading an attachment to a card

Reference

        Request Method: POST
        URL: /api/v2/projects/project_identifier/cards/card_number/attachments.xml
        The header and body should contain the uploaded file information.

Example

        POST

        http://your.mingle.server:8080/api/v2/projects/test_project/cards/42/attachments.xml

        Header:
        Content-type: multipart/form-data; boundary=----------XnJLe9ZIbbGUYtzPQJ16u1
        authorization: Basic <<encrypted user name and password>>

        Body:
        /var/folders/5J/5JlTqGEhFtKlM1mETxTWzU+++TI/-Tmp-/sample_attachment.txt.1513.0
        application/octet-stream
        ------------XnJLe9ZIbbGUYtzPQJ16u1 
        Content-Disposition: form-data; name="file"; filename="sample_attachment.txt" 
        Content-Type: application/octet-stream 
        Content-Length: 29 

        This is a sample attachment.

        ------------XnJLe9ZIbbGUYtzPQJ16u1--

Explanation

The above is an example of a POST request to a Mingle server running at your.mingle.server, port 8080. The request is made with the authorization credentials encrypted in the header. The URL of api/v2/projects/test_project/cards/42/attachments.xml represents the attachments card numbered 42 in project with identifier test_project. The header and body represent the data to upload for a file named sample_attachment.txt which contains the text:

This is a sample attachment.

Result

If you were authorized to perform the operation, and the resource was available, the attachment you specified should have been uploaded to the card.

Uploading an attachment to a wiki page

Reference

        Request Method: POST
        URL: /api/v2/projects/project_identifier/wiki/wiki_page/attachments.xml
        Parameters: File

Example

       POST

       http://your.mingle.server:8080/api/v2/projects/test_project/wiki/overview_page/attachments.xml

       Header:
       Content-type: multipart/form-data; boundary=----------XnJLe9ZIbbGUYtzPQJ16u1
       authorization: Basic <<encrypted user name and password>>

       Body:
       /var/folders/5J/5JlTqGEhFtKlM1mETxTWzU+++TI/-Tmp-/sample_attachment.txt.1513.0
       application/octet-stream
       ------------XnJLe9ZIbbGUYtzPQJ16u1 
       Content-Disposition: form-data; name="file"; filename="sample_attachment.txt" 
       Content-Type: application/octet-stream 
       Content-Length: 29 

       This is a sample attachment.

       ------------XnJLe9ZIbbGUYtzPQJ16u1--

Explanation

The above is an example of a POST request to a Mingle server running at your.mingle.server, port 8080. The request is made with the authorization credentials encrypted in the header. The URL of api/v2/projects/test_project/wiki/overview_page/attachments.xml represents the attachments for the wiki page Overview page in project with identifier test_project. The header and body represent the data to upload for a file named sample_attachment.txt which contains the text:

This is a sample attachment.

Result

If you were authorized to perform the operation, and the resource was available, the attachment you specified should have been uploaded to the card.