Work item attachments

  • Article

TFS 2017 | TFS 2015 | TFS 2013

Note

Looking for REST APIS that support TFS 2018 or later versions? See the Azure DevOps REST API Reference.

api-version = 1.0

If you haven't already, look at the information on getting started with these APIs.

Upload an attachment

To attach a file to a work item, upload the attachment to the attachment store, then attach it to the work item.

Note

For Team Services, you can add up to 100 attachments to a work item. Attempts to add more result in an error message upon saving the work item.

POST https://{instance}/DefaultCollection/_apis/wit/attachments?api-version={version}&filename={string}

Content-Type: application/octet-stream

{ file-contents }
Parameter Type Notes
URL
instance string TFS server name ({server:port}).
Query
api-version string Version of the API to use.
filename string The name of the file in the attachment store (typically the same as the name of the source of the attachment).
uploadType enum{simple, chunked} Default is simple. Use chunked upload type for uploading large files (>130 MB).
Body
file-contents string The contents of the file.

A text file

Sample request

POST https://mytfsserver/DefaultCollection/_apis/wit/attachments?fileName=textAsFileAttachment.txt&api-version=1.0

"User text content to upload"

Sample response

{
  "id": "6b2266bf-a155-4582-a475-ca4da68193ef",
  "url": "https://mytfsserver/DefaultCollection/_apis/wit/attachments/6b2266bf-a155-4582-a475-ca4da68193ef?fileName=textAsFileAttachment.txt"
}

Sample code

View sample for a full example on uploading an attachment to a work item.

function UploadAttachment() {
   var files = document.getElementById('fileselect').files;
   
   if (!files.length) {
       alert('Please select a file!');
       return;
   }
   
   var file = files[0];
   var filename = file.name;
   var reader = new FileReader();
   
   reader.onloadend = function (evt) {
       if (evt.target.readyState == FileReader.DONE) {
           // Post file content to server
           $.ajax({
               url: "http://fabrikam.visualstudio.com/DefaultCollection/_apis/wit/attachments?filename=" + filename + "&api-version=1.0",
               data: evt.target.result,
               processData: false,
               contentType: "application/octet-stream",
               type: "POST"
           });
       }
   };
   
   reader.readAsArrayBuffer(file);
}

Chunked upload

On accounts with higher attachment upload limits (>130MB), you will need to used "chunked" upload to upload your file. First, register your chunked upload by doing the following:

POST https://{account}.VisualStudio.com/DefaultCollection/_apis/wit/attachments?uploadType=chunked&fileName={filename}&api-version={version}

Sample request

POST https://mytfsserver/DefaultCollection/_apis/wit/attachments?uploadType=chunked&fileName=largefile.zip&api-version=2.0

Sample response

{
  "id": "de471719-27b2-40ab-ac40-4890f3eb1443",
  "url": "https://mytfsserver/DefaultCollection/_apis/wit/attachments/de471719-27b2-40ab-ac40-4890f3eb1443?fileName=test.txt"
}

Next, upload your content to the attachment endpoint returned in the previous request via PUT.

PUT https://{account}.VisualStudio.com/DefaultCollection/_apis/wit/attachments/{attachmentid}?uploadType=chunked&api-version={version}

Specify the byte range of the chunk using Content-Length. For example: "Content-Length": "bytes 0-39999/50000" for the first 40000 bytes of a 50000 byte file.

Sample request

POST https://mytfsserver/DefaultCollection/_apis/wit/attachments/de471719-27b2-40ab-ac40-4890f3eb1443?uploadType=chunked&api-version=2.0

"{zip content chunk 1}"

Sample response

{
  "id": "de471719-27b2-40ab-ac40-4890f3eb1443",
  "url": "https://mytfsserver/DefaultCollection/_apis/wit/attachments/de471719-27b2-40ab-ac40-4890f3eb1443"
}

Sample request

PUT https://mytfsserver/DefaultCollection/_apis/wit/attachments/de471719-27b2-40ab-ac40-4890f3eb1443?uploadType=chunked&api-version=2.0

"{zip content chunk 2}"

Sample response

{
  "id": "de471719-27b2-40ab-ac40-4890f3eb1443",
  "url": "https://mytfsserver/DefaultCollection/_apis/wit/attachments/de471719-27b2-40ab-ac40-4890f3eb1443"
}

Download an attachment

GET https://{instance}/DefaultCollection/_apis/wit/attachments/{attachment}?api-version={version}
Parameter Type Notes
URL
instance string TFS server name ({server:port}).
attachment GUID ID of the attachment to download.
Query
api-version string Version of the API to use.

Sample request

GET https://fabrikam-fiber-inc:8080/DefaultCollection/_apis/wit/attachments/fbb31ee5-740d-4254-9453-07c1bd189ead?api-version=1.0

Response

Status code: 200

{ file-contents }

Sample code