Attachments - Memos

Overview

Attachments are files uploaded to Memos and associated with memos. Supported file types include images, videos, audio, documents, and more. Attachments can be stored locally or in S3-compatible storage.

Create Attachment

Uploads a new file attachment. The file content is provided as base64-encoded bytes in the request.

POST /api/v1/attachments

curl -X POST https://your-memos-instance.com/api/v1/attachments \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "attachment": {
      "filename": "screenshot.png",
      "type": "image/png",
      "content": "iVBORw0KGgoAAAANSUhEUgAAAAUA..."
    }
  }'

Request Body

attachment

object

required

The attachment to create

Show properties

filename

string

required

The filename with extension (e.g., "document.pdf"). Must not contain invalid characters.

content

bytes

required

The file content encoded as base64 bytes

type

string

MIME type of the file (e.g., "image/png", "application/pdf"). If not provided, will be detected from filename or content.

external_link

string

Optional external URL for the attachment (alternative to uploading content)

memo

string

Optional memo to associate with this attachment. Format: memos/{memo_id}

attachment_id

string

Optional custom ID for the attachment. If not provided, a unique ID will be generated.

File Upload Limits

Maximum file size determined by instance settings (default: 32 MB)
Configurable via upload_size_limit_mb in storage settings
Files exceeding the limit will return a 400 Invalid Argument error

EXIF Metadata Stripping

For privacy protection, EXIF metadata is automatically stripped from uploaded images:

Affected formats: JPEG, JPG, TIFF, WebP, HEIC, HEIF
Removed data: GPS location, camera settings, device information, timestamps
Quality: Images are re-encoded at 95% JPEG quality to maintain visual fidelity

Response

name

string

The resource name of the attachment. Format: attachments/{attachment_id}

create_time

timestamp

The creation timestamp

filename

string

The filename of the attachment

type

string

The MIME type of the attachment

size

integer

The size of the attachment in bytes

memo

string

The associated memo resource name, if any. Format: memos/{memo_id}

external_link

string

The external link, if provided

Error Responses

400

error

Invalid Argument

Missing required fields (filename, content)
Filename contains invalid characters
Invalid MIME type format
File size exceeds limit

401

error

Unauthenticated - User not authenticated

Example Response

{
  "name": "attachments/xyz789abc",
  "create_time": "2024-01-15T14:30:00Z",
  "filename": "screenshot.png",
  "type": "image/png",
  "size": 245680,
  "memo": "memos/abc123"
}

List Attachments

Retrieves a paginated list of attachments with optional filtering and sorting.

GET /api/v1/attachments

curl "https://your-memos-instance.com/api/v1/attachments?page_size=20&filter=mime_type=='image/png'" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Query Parameters

page_size

integer

Maximum number of attachments to return. Default: 50, Maximum: 1000

page_token

string

Token for retrieving the next page of results (from previous response)

filter

string

CEL expression to filter attachments. Examples:

mime_type == "image/png"
filename.contains("report")
create_time > timestamp("2024-01-01T00:00:00Z")
memo == "memos/abc123"

Supported operators: ==, !=, <, <=, >, >=, : (contains), inSupported fields: filename, mime_type, create_time, memo

order_by

string

Sort order. Examples:

"create_time desc" (default)
"filename asc"
"size desc"

Response

attachments

array

Array of attachment objects (same structure as Create Attachment response)

next_page_token

string

Token for retrieving the next page. Omitted if no more pages.

total_size

integer

Total count of attachments (may be approximate)

Example Response

{
  "attachments": [
    {
      "name": "attachments/xyz789",
      "create_time": "2024-01-15T14:30:00Z",
      "filename": "report.pdf",
      "type": "application/pdf",
      "size": 1048576,
      "memo": "memos/abc123"
    },
    {
      "name": "attachments/def456",
      "create_time": "2024-01-14T09:15:00Z",
      "filename": "photo.jpg",
      "type": "image/jpeg",
      "size": 524288
    }
  ],
  "next_page_token": "CgVhYmNkZQ==",
  "total_size": 42
}

Get Attachment

Retrieves metadata for a single attachment by ID. To download the actual file, use the file server endpoint.

GET /api/v1/attachments/{attachment_id}

curl https://your-memos-instance.com/api/v1/attachments/xyz789 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Path Parameters

attachment_id

string

required

The ID of the attachment to retrieve

Response

Returns an attachment object (same structure as Create Attachment response).

Error Responses

400

error

Invalid Argument - Invalid attachment ID format

404

error

Not Found - Attachment does not exist

Update Attachment

Updates specific fields of an attachment using field masks. Typically used to update the associated memo or external link.

PATCH /api/v1/attachments/{attachment_id}

curl -X PATCH https://your-memos-instance.com/api/v1/attachments/xyz789 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "attachment": {
      "name": "attachments/xyz789",
      "memo": "memos/newmemo123"
    },
    "update_mask": {
      "paths": ["memo"]
    }
  }'

Path Parameters

attachment_id

string

required

The ID of the attachment to update

Request Body

attachment

object

required

The attachment object with updated fields. Must include name field.

update_mask

object

required

Specifies which fields to update.

Show paths

paths

array

required

Array of field paths to update: ["memo", "external_link", "filename"]

Updatable Fields

memo - Associated memo resource name
external_link - External URL
filename - Filename (metadata only, doesn’t rename actual file)

You cannot update the content or type fields. To change the file content, delete the attachment and create a new one.

Response

Returns the updated attachment object.

Error Responses

400

error

Invalid Argument - Invalid update_mask or field values

401

error

Unauthenticated - User not authenticated

403

error

Permission Denied - User doesn’t own the attachment

404

error

Not Found - Attachment does not exist

Delete Attachment

Deletes an attachment and its associated file. This operation is permanent and cannot be undone.

DELETE /api/v1/attachments/{attachment_id}

curl -X DELETE https://your-memos-instance.com/api/v1/attachments/xyz789 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Path Parameters

attachment_id

string

required

The ID of the attachment to delete

Response

Returns empty response on success.

Error Responses

401

error

Unauthenticated - User not authenticated

403

error

Permission Denied - User doesn’t own the attachment

404

error

Not Found - Attachment does not exist

Downloading Files

To download the actual file content, use the file server endpoint (separate from the API).

GET /file/{attachment_id}/{filename}

curl -O https://your-memos-instance.com/file/xyz789/document.pdf

This endpoint:

Returns the raw file content with appropriate Content-Type header
Supports range requests for streaming large files
Sets Content-Disposition header for proper filename handling
Works without authentication for attachments linked to public memos

Thumbnail Generation

Thumbnails are automatically generated for supported image formats.

Supported Formats

image/png
image/jpeg

Thumbnails are:

Generated on-demand when first requested
Cached in .thumbnail_cache/ directory
Limited to 3 concurrent generation operations
Automatically sized (typically 512px width, maintaining aspect ratio)

Accessing Thumbnails

curl https://your-memos-instance.com/file/xyz789/image.png?thumbnail=1

Add ?thumbnail=1 query parameter to request the thumbnail version.

Storage Backends

Local Storage (Default)

Attachments are stored in the data directory:

{MEMOS_DATA}/assets/{attachment_id}

S3-Compatible Storage

Configure via instance storage settings to use:

Amazon S3
MinIO
Cloudflare R2
Any S3-compatible service

S3 configuration includes:

Automatic pre-signed URL generation
Configurable expiration times
Support for custom endpoints
Bucket and region configuration

Common MIME Types

Images

image/png - PNG images
image/jpeg - JPEG images
image/gif - GIF animations
image/webp - WebP images
image/svg+xml - SVG vector graphics

Documents

application/pdf - PDF documents
application/msword - Microsoft Word (.doc)
application/vnd.openxmlformats-officedocument.wordprocessingml.document - Word (.docx)
text/plain - Plain text files
text/markdown - Markdown files

Audio/Video

audio/mpeg - MP3 audio
audio/wav - WAV audio
video/mp4 - MP4 video
video/webm - WebM video

Best Practices

File Naming

Use descriptive filenames with proper extensions
Avoid special characters that may cause issues on different filesystems
Keep filenames reasonably short (under 255 characters)

Performance

Use thumbnails for image previews instead of loading full-size images
Consider using external_link for very large files hosted elsewhere
Implement pagination when listing many attachments

Security

Attachments inherit visibility from their associated memo
EXIF data is automatically stripped from images to protect privacy
Validate file types on upload to prevent malicious content

Storage Management

Regularly review and delete unused attachments
Configure S3 lifecycle policies for automatic archival/deletion
Monitor storage usage through instance settings

Overview

Resources

Integration

​Overview

​Create Attachment

​Request Body

​File Upload Limits

​EXIF Metadata Stripping

​Response

​Error Responses

​Example Response

​List Attachments

​Query Parameters

​Response

​Example Response

​Get Attachment

​Path Parameters

​Response

​Error Responses

​Update Attachment

​Path Parameters

​Request Body

​Updatable Fields

​Response

​Error Responses

​Delete Attachment

​Path Parameters

​Response

​Error Responses

​Downloading Files

​Thumbnail Generation

​Supported Formats

​Accessing Thumbnails

​Storage Backends

​Local Storage (Default)

​S3-Compatible Storage

​Common MIME Types

​Images

​Documents

​Audio/Video

​Archives

​Best Practices

​File Naming

​Performance

​Security

​Storage Management

Build docs developers (and LLMs) love

Overview

Create Attachment

Request Body

File Upload Limits

EXIF Metadata Stripping

Response

Error Responses

Example Response

List Attachments

Query Parameters

Response

Example Response

Get Attachment

Path Parameters

Response

Error Responses

Update Attachment

Path Parameters

Request Body

Updatable Fields

Response

Error Responses

Delete Attachment

Path Parameters

Response

Error Responses

Downloading Files

Thumbnail Generation

Supported Formats

Accessing Thumbnails

Storage Backends

Local Storage (Default)

S3-Compatible Storage

Common MIME Types

Images

Documents

Audio/Video

Archives

Best Practices

File Naming

Performance

Security

Storage Management