Skip to content

Build your personal knowledge base with Trilium Notes

docs(etapi): document binary uploads to note and attachment content

Elian Doran9727399afd50
diff --git a/apps/server/spec/etapi/attachment-content.spec.ts b/apps/server/spec/etapi/attachment-content.spec.ts
index 5fc9e41657..6cf3ca1076 100644
--- a/apps/server/spec/etapi/attachment-content.spec.ts
+++ b/apps/server/spec/etapi/attachment-content.spec.ts
@@ -53,14 +53,36 @@ describe("etapi/attachment-content", () => {
expect(response.text).toStrictEqual(text);
});
- it("supports binary content", async() => {
+ it("stores binary content uploaded to an attachment created without content", async() => {
+ const created = await supertest(app)
+ .post(`/etapi/attachments`)
+ .auth(USER, token, { "type": "basic"})
+ .send({
+ "ownerId": createdNoteId,
+ "role": "image",
+ "mime": "image/png",
+ "title": "image.png",
+ "position": 10
+ })
+ .expect(201);
+ const attachmentId = created.body.attachmentId;
+
+ // Bytes that are not valid UTF-8, so a text round trip would corrupt them.
+ const bytes = Buffer.from([ 0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0x00, 0xff, 0xfe, 0x80 ]);
await supertest(app)
- .put(`/etapi/attachments/${createdAttachmentId}/content`)
+ .put(`/etapi/attachments/${attachmentId}/content`)
.auth(USER, token, { "type": "basic"})
.set("Content-Type", "application/octet-stream")
- .set("Content-Transfer-Encoding", "binary")
- .send(Buffer.from("Hello world"))
+ .send(bytes)
.expect(204);
+
+ const response = await supertest(app)
+ .get(`/etapi/attachments/${attachmentId}/content`)
+ .auth(USER, token, { "type": "basic"})
+ .responseType("blob")
+ .expect(200)
+ .expect("Content-Type", "image/png");
+ expect(Buffer.compare(response.body, bytes)).toBe(0);
});
it("refuses to read and write a protected attachment's content", async () => {
diff --git a/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Advanced Usage/ETAPI (REST API).html b/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Advanced Usage/ETAPI (REST API).html
index 3a3c2fdf84..8454c5f4e7 100644
--- a/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Advanced Usage/ETAPI (REST API).html
+++ b/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Advanced Usage/ETAPI (REST API).html
@@ -53,4 +53,24 @@ curl "$SERVER/etapi/notes/$NOTE_ID/content" -H "Authorization: $TOKEN" </code></
a directory called <code>out</code>, simply replace the last statement in
the script with:</p><pre><code class="language-text-x-trilium-auto">curl -H "Authorization: $TOKEN" \
-X GET "$SERVER/etapi/notes/$NOTE_ID/export" \
- --output "out/$NOTE_ID.zip"</code></pre>
\ No newline at end of file
+ --output "out/$NOTE_ID.zip"</code></pre>
+<h2>Uploading binary content</h2>
+<p>A JSON request body can only carry text, so the <code>content</code> field
+ of <code>POST /etapi/attachments</code> stores exactly the string it receives.
+ To upload an image, a PDF or any other binary file, send the raw bytes
+ to the content endpoint with the <code>application/octet-stream</code> content
+ type. The same applies to the content of a note (<code>PUT /etapi/notes/{noteId}/content</code>).</p>
+<p>To attach a file to a note, create the attachment without content, then
+ upload the file to it:</p><pre><code class="language-text-x-trilium-auto">ATTACHMENT_ID=$(curl -s -X POST "$SERVER/etapi/attachments" \
+ -H "Authorization: $TOKEN" \
+ -H "Content-Type: application/json" \
+ -d "{\"ownerId\": \"$NOTE_ID\", \"role\": \"file\", \"mime\": \"application/pdf\", \"title\": \"report.pdf\", \"position\": 10}" \
+ | jq -r .attachmentId)
+
+curl -X PUT "$SERVER/etapi/attachments/$ATTACHMENT_ID/content" \
+ -H "Authorization: $TOKEN" \
+ -H "Content-Type: application/octet-stream" \
+ --data-binary @report.pdf</code></pre>
+<p>Use <code>--data-binary</code> rather than <code>-d</code>, which strips
+ line breaks from the file. For an image, set <code>role</code> to <code>image</code> and <code>mime</code> to
+ the image's type, such as <code>image/png</code>.</p>
\ No newline at end of file
diff --git a/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Basic Concepts and Features/Notes/Printing & Exporting as PDF.html b/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Basic Concepts and Features/Notes/Printing & Exporting as PDF.html
index 50931fe8f9..8b724fa0e2 100644
--- a/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Basic Concepts and Features/Notes/Printing & Exporting as PDF.html
+++ b/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Basic Concepts and Features/Notes/Printing & Exporting as PDF.html
@@ -116,9 +116,9 @@
href="#root/_help_4TIF1oA4VQRO">Options</a>&nbsp;and assigning a key combination
for:</p>
<ul>
- <li class="ck-list-marker-italic"><em>Print Active Note</em>
+ <li><em>Print Active Note</em>
</li>
- <li class="ck-list-marker-italic"><em>Export Active Note as PDF</em>
+ <li><em>Export Active Note as PDF</em>
</li>
</ul>
<h2>Constraints &amp; limitations</h2>
diff --git a/apps/server/src/assets/etapi.openapi.yaml b/apps/server/src/assets/etapi.openapi.yaml
index a0234c0f0a..35d77d9163 100644
--- a/apps/server/src/assets/etapi.openapi.yaml
+++ b/apps/server/src/assets/etapi.openapi.yaml
@@ -236,21 +236,29 @@ paths:
operationId: getNoteContent
responses:
"200":
- description: note content response
+ description: note content, served with the note's MIME type as `Content-Type`
content:
- text/html:
+ "*/*":
schema:
type: string
+ format: binary
put:
description: Updates note content identified by its ID
operationId: putNoteContentById
requestBody:
- description: html content of note
+ description: >
+ New content of the note. Send text (such as the HTML of a text note) as
+ `text/plain` and binary data (such as the file of an image or file note) as
+ `application/octet-stream`; other content types are not accepted.
required: true
content:
text/plain:
schema:
type: string
+ application/octet-stream:
+ schema:
+ type: string
+ format: binary
responses:
"204":
description: note content updated
@@ -671,21 +679,29 @@ paths:
operationId: getAttachmentContent
responses:
"200":
- description: attachment content response
+ description: attachment content, served with the attachment's MIME type as `Content-Type`
content:
- text/html:
+ "*/*":
schema:
type: string
+ format: binary
put:
description: Updates attachment content identified by its ID
operationId: putAttachmentContentById
requestBody:
- description: html content of attachment
+ description: >
+ New content of the attachment. Send text as `text/plain` and binary data
+ (such as an image or a PDF) as `application/octet-stream`; other content
+ types are not accepted.
required: true
content:
text/plain:
schema:
type: string
+ application/octet-stream:
+ schema:
+ type: string
+ format: binary
responses:
"204":
description: attachment content updated
@@ -1296,6 +1312,10 @@ components:
type: string
content:
type: string
+ description: >
+ Text content of the attachment, stored as-is. To store binary content,
+ create the attachment without it, then upload the data with
+ `PUT /attachments/{attachmentId}/content`.
position:
type: integer
format: int32
diff --git a/docs/User Guide/User Guide/Advanced Usage/ETAPI (REST API).md b/docs/User Guide/User Guide/Advanced Usage/ETAPI (REST API).md
index c50694b731..869d7984dd 100644
--- a/docs/User Guide/User Guide/Advanced Usage/ETAPI (REST API).md
+++ b/docs/User Guide/User Guide/Advanced Usage/ETAPI (REST API).md
@@ -70,4 +70,25 @@ As another example, to obtain a .zip export of a note and place it in a director
curl -H "Authorization: $TOKEN" \
-X GET "$SERVER/etapi/notes/$NOTE_ID/export" \
--output "out/$NOTE_ID.zip"
-```
\ No newline at end of file
+```
+
+## Uploading binary content
+
+A JSON request body can only carry text, so the `content` field of `POST /etapi/attachments` stores exactly the string it receives. To upload an image, a PDF or any other binary file, send the raw bytes to the content endpoint with the `application/octet-stream` content type. The same applies to the content of a note (`PUT /etapi/notes/{noteId}/content`).
+
+To attach a file to a note, create the attachment without content, then upload the file to it:
+
+```
+ATTACHMENT_ID=$(curl -s -X POST "$SERVER/etapi/attachments" \
+ -H "Authorization: $TOKEN" \
+ -H "Content-Type: application/json" \
+ -d "{\"ownerId\": \"$NOTE_ID\", \"role\": \"file\", \"mime\": \"application/pdf\", \"title\": \"report.pdf\", \"position\": 10}" \
+ | jq -r .attachmentId)
+
+curl -X PUT "$SERVER/etapi/attachments/$ATTACHMENT_ID/content" \
+ -H "Authorization: $TOKEN" \
+ -H "Content-Type: application/octet-stream" \
+ --data-binary @report.pdf
+```
+
+Use `--data-binary` rather than `-d`, which strips line breaks from the file. For an image, set `role` to `image` and `mime` to the image's type, such as `image/png`.
\ No newline at end of file