Working with Attachments

Amanda Jennewein
Amanda Jennewein
  • Updated



Attachments can be uploaded through the API and associated with an item in three calls.

  1. Create an attachment item
  2. Upload the file
  3. Associate the attachment to an item

This should be straightforward after you have done it once. An example is done via Postman, a Google Chrome extension, as our documentation tool, Swagger, does not support the uploading of files.

Step 1: Create an Attachment Item
Attachment items contain the metadata for an attachment file. Creating an attachment item is very similar to any other item, in that you need to include the name and description.


 Attachment Item JSON
Only the name field is required to create an attachment item unless the Item Type has been configured differently.



      "name":"Poppy Flower",

      "description":"A pretty picture"




Post your attachment Item to this path:

POST /rest/v1/projects/{projectID}/attachments

 The response will say the attachment was created. Use the location to determine the id:









Step 2: Upload the File
Upload a file using a PUT with form data. The endpoint is /rest/v1/attachments/{attachmentID}/file. The key for the form data should be 'file'.

Here is a screenshot of what it looks like in Postman:


Step 3: Associate Attachment Item with Item
To be clear, the attachment item is an item that has the metadata about an attachment. This is different from an item like a requirement found in the explorer tree of Jama. You must enable the Attachment widget on the item type before associating attachments to items.

POST the attachment item ID to the attachment endpoint of the item you would like to associate with. Any of these paths are acceptable:

  • /rest/v1/items/{id}/attachments
  • /rest/v1/testplans/{id}/attachments
  • /rest/v1/testruns/{id}/attachments

The JSON is very simple:





That's it! You can make some other attachment related operations listed below:

GET /rest/v1/attachments{attachmentId}

     Gets attachment meta data

PUT /rest/v1/attachment/{attachmentId}/file

     Uploads file to attachment

GET /rest/v1/attachment/{attachmentId}/file

     Download the attached file

GET /rest/v1/attachments/{attachmentId}/comments

     Gets all comments for attachment Item

GET /rest/v1/items/{id}/attachments

     Gets attachments on an Item. This also works for test plans and test runs.

POST /rest/v1/items/{id}/attachments

     Associates attachment item to the item

DELETE /rest/v1/item/{id}/attachments/{attachmentId}

     Removes the association from the item. The attachment item still exists.

Related to

Was this article helpful?

0 out of 0 found this helpful

Have more questions? Submit a request



Please sign in to leave a comment.