---
title: "Issue attachments"
canonical: https://workspace.socra.com/docs/cortex/guides/issue-attachments
---

# Issue attachments

Attach private evidence and working files to a Cortex Issue. Each file belongs to the Issue and can appear in comments on that Issue.

## Access and limits

The examples use the [Socra CLI with Cortex installed](/docs/cortex/reference/cli). You need an existing Issue; use its ID wherever an example shows `ISSUE_ID`.

Attachment access follows the Issue and its owning Module. A principal that can read the Issue can list and download its available files. An Issue operator can upload files as part of their work.

Each file must contain at least one byte and can be no larger than 25 MiB. The CLI keeps the original filename and infers a media type from common file extensions. Other extensions use `application/octet-stream`.

Uploads and downloads use short-lived private URLs. The CLI handles those URLs without printing them. During upload, Cortex verifies the declared size, media type, and SHA-256 checksum before the file becomes available.

## Upload a file

Upload one local file to an Issue:

```bash
socra cortex attachment upload ISSUE_ID ./evidence.png
```

When the upload completes, the command prints an attachment ID such as `issue_attachment_...`. Use that value for `ATTACHMENT_ID` in later commands.

List the ready files owned by the Issue:

```bash
socra cortex attachment list ISSUE_ID
```

Confirm that the uploaded filename and attachment ID appear in the list. The list excludes incomplete and removed attachments and supports `--limit` and `--after` pagination.

## Add attachments to a comment

Create a comment with the uploaded attachment:

```bash
socra cortex comment create --issue ISSUE_ID --body "Test evidence" --attachments ATTACHMENT_ID
```

Pass a comma-separated list to place up to 20 completed attachments when you create the comment. Every attachment must belong to the same Issue as the comment.

To add a completed attachment to a comment you already wrote, replace `COMMENT_ID` with that comment's ID:

```bash
socra cortex attachment place ATTACHMENT_ID --comment COMMENT_ID --position 0
```

The optional `--position` value is zero-based. Only the comment author can add or remove a placement. The same Issue attachment can appear in more than one comment.

List every placement for an Issue:

```bash
socra cortex attachment placements ISSUE_ID
```

Remove one placement by its `comment_attachment_...` ID:

```bash
socra cortex attachment unplace PLACEMENT_ID
```

Removing a placement leaves the Issue attachment available for download and for other comments.

## Download a file

Choose the destination path explicitly:

```bash
socra cortex attachment download ATTACHMENT_ID ./downloaded-evidence.png
```

The command refuses to replace an existing destination. Add `--force` only when you intend to overwrite that local file.

## Remove an attachment

> **Warning:** Removing an attachment deletes its private file bytes. Cortex cannot restore them.

The uploader or a principal with edit access to the Module can remove an attachment:

```bash
socra cortex attachment delete ATTACHMENT_ID
```

The attachment disappears from lists and downloads. The Issue history retains a record of where the removed file appeared in comments. Re-upload the original file to create a new attachment if you need it again.

## Use attachments through MCP or the API

The MCP server exposes `issue_attachment_*` tools for file preparation, completion, listing, download, and removal. It exposes `comment_attachment_*` tools for comment placements. A direct upload must send the exact declared bytes and required headers to the prepared URL before calling the completion tool.

The [Cortex API reference](/docs/cortex/reference/api) describes the same resources. Review the [Cortex MCP reference](/docs/cortex/reference/mcp) before allowing an agent host to write or remove files.