Upload an attachment

POST

/attachments

curl --request POST \
  --url https://api.engram.page/attachments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "content_base64": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==", "mime_type": "image/png", "path": "assets/diagram.png" }'

• Production

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.

Authorizations

• bearerAuth

Parameters

Query Parameters

path

string

Vault-relative path. Required for an octet-stream body.

mtime

number

File mtime in seconds (octet-stream body).

mime_type

string

MIME override; detected from the extension when absent (octet-stream body).

Request Body^required

Attachment bytes

UploadAttachmentRequest

object

content_base64

required

Base64-encoded file bytes.

string

mime_type

Detected from path if omitted.

string

nullable

path

required

string

Example

{
  "content_base64": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==",
  "mime_type": "image/png",
  "path": "assets/diagram.png"
}

string format: binary

Responses

200

Uploaded

Media typeapplication/json

AttachmentResponse

object

attachment

required

AttachmentMeta

object

content_hash

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.

string

nullable

created_at

string format: date-time

nullable

id

string format: uuid

nullable

mime_type

string

nullable

mtime

Client mtime (epoch seconds)

number format: float

path

required

string

size_bytes

integer

updated_at

string format: date-time

nullable

Example

{
  "attachment": {
    "path": "assets/diagram.png"
  }
}

400

Invalid base64

Media typeapplication/json

MessageError

object

error

required

string

Example

{
  "error": "not found"
}

402

Attachments require a paid plan / quota

Media typeapplication/json

LimitError

object

current

integer

nullable

error

required

string

limit

One of:

integer

integer

boolean

boolean

limit_key

string

nullable

reason

required

string

tier

string

nullable

upgrade_url

string

nullable

Example

{
  "error": "limit_exceeded",
  "limit_key": "vaults_cap",
  "reason": "vaults_cap_exceeded",
  "tier": "free"
}

408

Raw body stalled before it finished

Media typeapplication/json

MessageError

object

error

required

string

Example

{
  "error": "not found"
}

413

Raw body over the request ceiling

Media typeapplication/json

MessageError

object

error

required

string

Example

{
  "error": "not found"
}

415

MIME or extension not allowed

Media typeapplication/json

MimeRejected

object

error

required

string

extension

string

nullable

mime_type

string

nullable

Example

{
  "error": "mime_not_allowed"
}

422

Missing/invalid content

Media typeapplication/json

MessageError

object

error

required

string

Example

{
  "error": "not found"
}

502

Storage backend failure

Media typeapplication/json

MessageError

object

error

required

string

Example

{
  "error": "not found"
}