How to Export Attachments from Jira Cloud Projects via REST API

Summary

This article provides a step-by-step guide on how to export all attachments from a single project in Jira Cloud by leveraging the Jira REST API. You can perform this method directly through API calls.

Diagnosis

You need to download all attachments from work items within a specific project in Jira Cloud. Accomplish this task by using the Jira REST API.

Cause

There is no direct functionality in Jira Cloud's UI to export all attachments from a project. However, the REST API provides a way to retrieve and download these attachments programmatically.

Solution

1. Generate an API Token

   • Visit Atlassian's API token management page to generate an API token. Use this token for authentication purposes. 

2. Prepare the API Request to get all Work Items with Attachments

   • Permissions required - ensure that you have:

     • Browse projects permission for the project containing the work item.

     • Work-item-level security permission if it is configured.

   • Make a POST request to the Jira REST API to search for work items with attachments. Use the following endpoint and payload:

     POST https://<your-domain>.atlassian.net/rest/api/3/search { "jql": "project = <your-project-key> AND NOT attachments is EMPTY", "startAt": 0, "maxResults": 100, "fields": ["attachment"], "fieldsByKeys": false }

   • Replace <your-domain> with your Jira Cloud domain and <your-project-key> with your project's key.

   • Note that the API defaults to a maximum of 100 results per page (controlled by the 'maxResults' parameter), even when fetching attachments. For larger datasets, iterate using the 'startAt' parameter in batches of 100 to retrieve all data. If migrating a large number of issues, such as 20,000 or more, consider implementing batch scripting to automate the downloading and transferring process. Test these scripts in a QA environment to identify and resolve any bottlenecks or errors before production migration. Additionally, ensure attachment URLs are accurately mapped to their respective issues in the CSV file.

3. Make the API Request

   • Use tools like Postman, which provides a user-friendly interface, or curl in the terminal for more advanced users. These tools are widely used and can help you execute API calls effectively.

   • Here is an example using curl:

     curl -sL --request POST \ --user "email@example.com:your-api-token" \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --url "https://<your-domain>.atlassian.net/rest/api/3/search" \ --data '{ "jql": "project = <your-project-key> AND NOT attachments is EMPTY", "startAt": 0, "maxResults": 100, "fields": ["attachment"], "fieldsByKeys": false }'

   • The command returns a JSON response with work items that have attachments.

4. Parse the JSON Response to Extract Attachment URLs

   • If using a command-line tool use a tool like `jq` to easily extract the attachment URLs from the JSON response along with their corresponding work item keys.

   • Here’s a sample command to achieve this:

     curl -sL --request POST \ --user "email@example.com:your-api-token" \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --url "https://<your-domain>.atlassian.net/rest/api/3/search" \ --data '{ "jql": "project = <your-project-key> AND NOT attachments is EMPTY", "startAt": 0, "maxResults": 100, "fields": ["attachment"], "fieldsByKeys": false }' \ | jq -r '.issues[] | {key,attachment:.fields.attachment[]} | [.key, .attachment.content, .attachment.filename] | join(" ")'

     Note:

     • In API version 3, attachments are linked to work items but not directly to comments. If you require attachment data specific to comments, consider using API version 2, where this relationship can be retrieved.

     • Attachments in archived projects can be retrieved.

   • This command will output lines containing the work item key, attachment URL, and filename for each attachment.

5. Download the Attachments

   • Download the attachments with the attachment URLs using another curl command or a similar tool.

   • Here’s an example curl command to download an attachment:

     curl -L --create-dirs --user "email@example.com:your-api-token" --url "<attachment-url>" --output "<issue-key>/<filename>"

Conclusion

By following these steps, you can efficiently export all attachments from a specific project in Jira Cloud using the REST API.

Note that the exported data may require additional processing to make it more organized or easily shareable. Currently, tailoring the output to a more user-friendly format requires custom scripting or external tools.

Note: The Jira REST API does not support including file attachments directly in API requests. Instead, use the generated downloadable attachment URLs provided in the API response. Receiving systems can use these URLs to retrieve and process file contents as needed.

References

1. Basic auth for REST APIs

2. Search for issues using JQL

3. https://stedolan.github.io/jq/