Upload

File upload and download for note attachments.

Service: notes.upload

File upload and download for note attachments. Attachments are created via the parent note (via note_attachment in create or updateOneById). Binary content is then uploaded directly to cloud storage through presigned URLs.

Upload flow

1. Create an attachment record by including a new entry (without id) in the note_attachment array when creating or updating a note. The server returns the assigned id with status: "pending"
2. Call requestUploadUrl to get a presigned upload URL for each part
3. PUT the encrypted chunk body to the presigned URL (standard HTTP PUT, not WebSocket)
4. Call confirmChunk for each uploaded part
5. Call finalizeUpload to assemble parts and mark the attachment as ready

For thumbnails repeat steps 2–4 with chunk_type: "thumbnail_128" (single chunk). Thumbnails do not require a separate finalize call.

requestUploadUrl

Request a presigned upload URL for a single chunk/part.

WebSocket

Request

{
  "jsonrpc": "2.0",
  "method": "notes.upload.requestUploadUrl",
  "params": {
    "file_id": "1920438291760",
    "object_key": "a1/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "chunk_type": "file"
  },
  "id": 30
}

Param	Type	Required	Description
file_id	string	✅	Attachment record id
object_key	string	✅	Client-generated object key for storage (format: <uuid[:2]>/<uuid>)
chunk_type	string		"file" (default) or "thumbnail_128"

Response

{
  "jsonrpc": "2.0",
  "result": {
    "object_key": "a1/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "upload_url": "https://storage.example.com/enbox-notes-attachments/a1/a1b2c3d4-...?X-Amz-..."
  },
  "id": 30
}

confirmChunk

Confirm that a chunk/part was successfully uploaded.

WebSocket

Request

{
  "jsonrpc": "2.0",
  "method": "notes.upload.confirmChunk",
  "params": {
    "file_id": "1920438291760",
    "object_key": "a1/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "chunk_index": 0,
    "chunk_type": "file"
  },
  "id": 31
}

Param	Type	Required	Description
file_id	string	✅	Attachment record id
object_key	string	✅	Object key used during upload
chunk_index	integer		0-based part order. Default 0
chunk_type	string		"file" (default) or "thumbnail_128"

Response

{
  "jsonrpc": "2.0",
  "result": {
    "chunk_id": "1920438291770",
    "chunk_index": 0,
    "size_bytes": 102400
  },
  "id": 31
}

finalizeUpload

Complete the multipart upload and mark the attachment as ready. The server assembles all confirmed parts into a single S3 object, then creates the final chunk record.

WebSocket

Request

{
  "jsonrpc": "2.0",
  "method": "notes.upload.finalizeUpload",
  "params": {
    "file_id": "1920438291760"
  },
  "id": 32
}

Param	Type	Required	Description
file_id	string	✅	Attachment record id

Response

{
  "jsonrpc": "2.0",
  "result": {
    "file_id": "1920438291760",
    "status": "ready"
  },
  "id": 32
}

requestDownloadUrls

Request presigned download URLs for specific chunks of an attachment.

WebSocket

Request

{
  "jsonrpc": "2.0",
  "method": "notes.upload.requestDownloadUrls",
  "params": {
    "file_id": "1920438291760",
    "chunk_indexes": [0],
    "chunk_type": "file"
  },
  "id": 33
}

Param	Type	Required	Description
file_id	string	✅	Attachment record id
chunk_indexes	integer[]	✅	0-based indexes of chunks to download
chunk_type	string		"file" (default) or "thumbnail_128"

Response

{
  "jsonrpc": "2.0",
  "result": [
    {
      "chunk_index": 0,
      "download_url": "https://storage.example.com/enbox-notes-attachments/a1/a1b2c3d4-...?X-Amz-...",
      "size_bytes": 102400
    }
  ],
  "id": 33
}

For thumbnails (chunk_type: "thumbnail_128") use chunk_indexes: [0]. The result contains a single entry or an empty array if no thumbnail exists.