---
schema: rendered-html/v1
title: "Attach Files to an Issue | Developer Portal for YouTrack and Hub Documentation"
source_url: https://www.jetbrains.com/help/youtrack/devportal/api-usecase-attach-files.html
generated_at: 2026-06-11T15:01:13.577025+00:00
---

Feedback

Thanks for your feedback!

Was this page helpful?

YesNo

Developer Portal for YouTrack and Hub

- Developer Portal
- Apps
- MCP Tools
- YouTrack Workflows
- YouTrack Import Scripts
- YouTrack Form API
- YouTrack REST API
- Get Started with REST API
- REST API Reference
- REST API Use Cases
- Create an Issue
- Create an Issue and Set Custom Fields
- Get Issues List with All Values
- Get Value for an Issue Custom Field
- [Add Value to a Set](jetbrains__com__help__youtrack__devportal__api-usecase-add-value-to-bundle.md)
- Update Issue Custom Fields
- [Update a Text Field Value](jetbrains__com__help__youtrack__devportal__api-usecase-update-text-field-value.md)
- Clear Values of Custom Fields
- [Apply Commands to Issues](jetbrains__com__help__youtrack__devportal__api-usecase-commands.md)
- Tag or Untag Issues
- [Work with Issue Tags](jetbrains__com__help__youtrack__devportal__api-usecase-work-with-tags.md)
- [Attach Files to an Issue](api-usecase-attach-files.html)
- [Delete an Issue Attachment](jetbrains__com__help__youtrack__devportal__api-usecase-delete-issue-attachment.md)
- [Download an Issue Attachment](jetbrains__com__help__youtrack__devportal__api-usecase-download-issue-attachment.md)
- Link Issues
- [Get Issue History](jetbrains__com__help__youtrack__devportal__api-usecase-issue-history.md)
- [Get a Database Backup](jetbrains__com__help__youtrack__devportal__api-usecase-backup.md)
- Add User to Project Team
- REST API Troubleshooting
- Color Indices List
- Hub REST API

1. YouTrack REST API
2. REST API Use Cases
3. [Attach Files to an Issue](#0)

# Attach Files to an Issue﻿

Last modified: 07 May 2026

## Use Case﻿

Use the REST API to upload one or more files to an existing issue.

## Summary﻿

To attach a file to an issue:

1. Get a list of issues to get the entity ID of the target issue.
2. Attach files to the issue by sending a POST request to the following endpoint:

   ```
   /api/issues/{issueID}/attachments
   ```

## Step-by-Step﻿

1. Get the list of issues in a target project.

   ```
   curl -X GET 'https://example.youtrack.cloud/api/issues?query=in:NP&$top=3&fields=id,idReadable,summary' \
   -H 'Accept: application/json' \
   -H 'Authorization: Bearer perm:cm9vdA==.MjZGZWI=.WB02vjX0cM2ltLTJXUE3VOWHpJYYNx'
   ```

   The `query` request parameter lets us filter the list of issues by a search query. In this sample, we use the query to get only the issues that belong to the target project (`NP`).

   For this particular example, to shorten the list of returned issues, we use `$top=3` parameter to get only first three found issues.

   In the `fields` request parameter, we instruct the server to return the following attributes for each issue found:

   - `id` and `idReadable` - both database entity ID and an ID of the issue in the project, respectively.
   - `summary` - issue's summary may help to identify the target issue.

   In the response to this request, the server returns the following data:

   ```
   [
     {
       "summary": "Investigation task",
       "idReadable": "NP-56",
       "id": "99-356",
       "$type": "Issue"
     },
     {
       "summary": "Marketing activities",
       "idReadable": "NP-39",
       "id": "99-303",
       "$type": "Issue"
     },
     {
       "summary": "TODO for release",
       "idReadable": "NP-77",
       "id": "99-500",
       "$type": "Issue"
     }
   ]
   ```
2. Locate the ID of the target issue. In this case, let's take the issue `NP-77` with the database ID `99-500`.
3. To attach files to an issue, send a `POST` request with the file content to the following endpoint:

   ```
   /api/issues/{issueID}/attachments
   ```

   This endpoint expects file upload data in `multipart/form-data` format. Use this request pattern when you upload a file using `multipart/form-data`, for example with the `cURL -F upload=@...` option.

   For this use case, we use the following `cURL` command:

   ```
   curl -v -i -F upload=@/Users/jetbrains/Downloads/youtrack.txt \
   -F upload=@/Users/jetbrains/Downloads/youtrack_new.jpeg \
   -H 'Authorization: Bearer perm:cm9vdA==.MjZGZWI=.WB02vjX0cM2ltLTJXUE3VOWHpJYYNx' \
   -H 'Content-Type: multipart/form-data' \
   -X POST 'https://example.youtrack.cloud/api/issues/99-500/attachments?fields=id,name'
   ```

   Here are the key parts of this request:

   - `-F upload=@/Users/jetbrains/Downloads/youtrack.txt` uploads a file as a multipart form field named `upload`.
   - To attach multiple files in one request, repeat the `-F upload=@...` option for each file:

     ```
     -F upload=@/Users/jetbrains/Downloads/youtrack.txt \
     -F upload=@/Users/jetbrains/Downloads/youtrack_new.jpeg
     ```
   - The `@` prefix tells `cURL` to read the file content from the local filesystem.
   - `Content-Type: multipart/form-data` is the correct content type for this upload pattern.
   > ### note
   >
   > This example describes multipart file upload. It is not a JSON-based request for base64-encoded attachment content.

   In the response, the server returns the `name` and database entity ID of the attached files:

   ```
   [
     {"name":"youtrack.txt","id":"134-31","$type":"IssueAttachment"},
     {"name":"youtrack_new.jpeg","id":"134-32","$type":"IssueAttachment"}
   ]
   ```

That’s it: we’ve attached all our files to the issue.

> ### note
>
> Please note that you cannot simultaneously create a new issue and add attachments to it. You can attach files only to an already existing issue.

- [Attach Files to an Issue](/help/youtrack/devportal/api-usecase-attach-files.html)
- [Use Case](/help/youtrack/devportal/api-usecase-attach-files.html#use-case)
- [Summary](/help/youtrack/devportal/api-usecase-attach-files.html#summary)
- [Step-by-Step](/help/youtrack/devportal/api-usecase-attach-files.html#step-by-step)

[Work with Issue Tags](jetbrains__com__help__youtrack__devportal__api-usecase-work-with-tags.md)[Delete an Issue Attachment](jetbrains__com__help__youtrack__devportal__api-usecase-delete-issue-attachment.md)

- Privacy & Security
- Terms Of Use
- Trademarks
- Legal

Copyright © 2000–2026 JetBrains s.r.o.
