---
title: "Upload an attachment"
method: POST
path: "/api/attachments"
tags: ["Attachments"]
---

# Upload an attachment

`POST /api/attachments`

## Request

- Base URL: `https://api.engram.page`
- URL: `https://api.engram.page/api/attachments`
- Auth: HTTP bearer

Uploads an attachment to the vault's storage backend. Send the raw bytes as `application/octet-stream` with `path`, `mtime` and optional `mime_type` in the query string, or (legacy) base64 JSON. Attachments are a paid-tier feature (402 on Free, which is also limited to text MIME types), the MIME type and extension must pass the whitelist (415), the file must be within the per-plan size and total-quota limits (402), a raw body over the request ceiling returns 413, a raw body that stalls returns 408, a non-numeric `mtime` or `mime_type` returns 422, and a storage backend failure returns 502.

## Query parameters

- `path` string
- `mtime` number
- `mime_type` string

## Request body

- UploadAttachmentRequest
  - `content_base64` string, required: Base64-encoded file bytes.
  - `mime_type` string, nullable: Detected from path if omitted.
  - `path` string, required

## Response `200`

Uploaded

- AttachmentResponse
  - `attachment` AttachmentMeta, required
    - `content_hash` string, nullable: Opaque content fingerprint. Stable for identical bytes and scoped to the owning account. Compare against a local copy to decide whether an upload is needed; re-uploading matching bytes is accepted but does no work.
    - `created_at` string, date-time, nullable
    - `id` string, uuid, nullable
    - `mime_type` string, nullable
    - `mtime` number, float: Client mtime (epoch seconds)
    - `path` string, required
    - `size_bytes` integer
    - `updated_at` string, date-time, nullable

## Other responses

- `400`: Invalid base64
- `402`: Attachments require a paid plan / quota
- `408`: Raw body stalled before it finished
- `413`: Raw body over the request ceiling
- `415`: MIME or extension not allowed
- `422`: Missing/invalid content
- `502`: Storage backend failure

---

[API](https://skmtc.dev/engram/apis/engram-api.md) · [All operations](https://skmtc.dev/engram/apis/engram-api/llms.txt) · [OpenAPI document](https://skmtc.dev/engram/apis/engram-api/revisions/8c4c2eec29dc?raw)