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. 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 describes the same resources. Review the Cortex MCP reference before allowing an agent host to write or remove files.