Trilium ETAPI

intent

interact with a trilium notes server (v0.50+) via its etapi rest api to create, read, update, search, or delete notes, branches, attributes, and attachments. use this skill when you need to bulk-import content, push data from external systems (webhooks, rss, email), export trilium subtrees, or trigger backups from outside trilium. do not use this for scripts running inside trilium itself, those should use the internal script api.

inputs

environment variables (required)

• TRILIUM_URL: base url of trilium server, no trailing slash. example: http://localhost:8080
• TRILIUM_TOKEN: etapi authentication token. generate in trilium ui under options > etapi

authentication methods (pick one, use in Authorization header)

1. raw token: Authorization: $TRILIUM_TOKEN (works on all versions)
2. bearer form: Authorization: Bearer $TRILIUM_TOKEN (v0.93+)
3. basic auth: Authorization: Basic $(echo -n "etapi:$TRILIUM_TOKEN" | base64) (v0.56+)

optional: password exchange for token (if no token yet but password auth enabled)

• POST /etapi/auth/login with json body {"password":"YOUR_PASSWORD"} returns authToken

external connection

• trilium notes server instance running and accessible at TRILIUM_URL
• rate limit on /auth/login: repeated failures (429) temporarily blacklist client ip

procedure

step 1: verify server health and auth

inputs: TRILIUM_URL, TRILIUM_TOKEN output: server version, auth confirmed or error with code

curl -s "$TRILIUM_URL/etapi/app-info" \
  -H "Authorization: $TRILIUM_TOKEN" | jq

if auth fails (401), check token validity and regenerate in trilium ui. if server unreachable (connection refused), confirm TRILIUM_URL and trilium process is running.

step 2: search notes (optional, for read workflows)

inputs: TRILIUM_URL, TRILIUM_TOKEN, search query string output: array of matching notes with noteId, title, type

curl -sG "$TRILIUM_URL/etapi/notes" \
  -H "Authorization: $TRILIUM_TOKEN" \
  --data-urlencode 'search=YOUR_QUERY' \
  --data-urlencode 'limit=50' | jq '.results[]'

search syntax matches trilium ui search bar. examples: #tag, #tag=value, note.content *= "phrase", ~relation.title = "value".

step 3: read note metadata

inputs: TRILIUM_URL, TRILIUM_TOKEN, noteId output: note object with noteId, title, type, mime, dateCreated, isProtected

curl -s "$TRILIUM_URL/etapi/notes/$NOTE_ID" \
  -H "Authorization: $TRILIUM_TOKEN" | jq

step 4: read note content

inputs: TRILIUM_URL, TRILIUM_TOKEN, noteId output: raw content as string (html for text notes, source for code notes, binary for files/images)

curl -s "$TRILIUM_URL/etapi/notes/$NOTE_ID/content" \
  -H "Authorization: $TRILIUM_TOKEN"

step 5: create a note

inputs: TRILIUM_URL, TRILIUM_TOKEN, parentNoteId, title, type, content (optional), mime (required for code/file/image) output: NoteWithBranch object containing new note and branch records

curl -sX POST "$TRILIUM_URL/etapi/create-note" \
  -H "Authorization: $TRILIUM_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "parentNoteId": "root",
    "title": "Note Title",
    "type": "text",
    "content": "<p>html content here</p>"
  }' | jq '.note.noteId, .branch.branchId'

valid types: text, code, file, image, search, book, relationMap, render. code/file/image require mime field (e.g. text/x-python, application/octet-stream, image/png).

step 6: write note content

inputs: TRILIUM_URL, TRILIUM_TOKEN, noteId, content body output: 200 ok or error code critical: Content-Type header must be text/plain even for html content. body is sent as binary.

curl -sX PUT "$TRILIUM_URL/etapi/notes/$NOTE_ID/content" \
  -H "Authorization: $TRILIUM_TOKEN" \
  -H 'Content-Type: text/plain' \
  --data-binary @file.html

step 7: patch note metadata

inputs: TRILIUM_URL, TRILIUM_TOKEN, noteId, patch object output: updated note object note: only patches title, type, mime, dateCreated, utcDateCreated. to change content, use step 6.

curl -sX PATCH "$TRILIUM_URL/etapi/notes/$NOTE_ID" \
  -H "Authorization: $TRILIUM_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"title": "New Title"}'

step 8: create attribute (label or relation)

inputs: TRILIUM_URL, TRILIUM_TOKEN, noteId, type (label|relation), name, value, isInheritable output: attribute object with attributeId

curl -sX POST "$TRILIUM_URL/etapi/attributes" \
  -H "Authorization: $TRILIUM_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "noteId": "'$NOTE_ID'",
    "type": "label",
    "name": "priority",
    "value": "high",
    "isInheritable": false
  }'

step 9: create branch (clone note to new parent or move)

inputs: TRILIUM_URL, TRILIUM_TOKEN, noteId, parentNoteId, notePosition, prefix output: branch object with branchId note: to re-parent, delete old branch first then create new one. PATCH /branches only handles prefix and notePosition.

curl -sX POST "$TRILIUM_URL/etapi/branches" \
  -H "Authorization: $TRILIUM_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "noteId": "'$CHILD_ID'",
    "parentNoteId": "'$NEW_PARENT_ID'",
    "prefix": "",
    "notePosition": 100,
    "isExpanded": false
  }'

use notePosition=5 to insert at front, large value like 1000000 to push to end. default is 10. after bulk reorders, call POST /refresh-note-ordering/{parentNoteId}.

step 10: create attachment

inputs: TRILIUM_URL, TRILIUM_TOKEN, noteId, title, binary file content output: attachment object with attachmentId

curl -sX POST "$TRILIUM_URL/etapi/attachments" \
  -H "Authorization: $TRILIUM_TOKEN" \
  -F "file=@/path/to/file" \
  -F "noteId=$NOTE_ID" \
  -F "title=Attachment Title"

step 11: get or create day note

inputs: TRILIUM_URL, TRILIUM_TOKEN, date string YYYY-MM-DD output: day note object with auto-created branches if not exist

curl -s "$TRILIUM_URL/etapi/calendar/days/2024-01-15" \
  -H "Authorization: $TRILIUM_TOKEN" | jq '.noteId'

step 12: delete note

inputs: TRILIUM_URL, TRILIUM_TOKEN, noteId output: 200 ok or error code critical: deleting the last branch of a note also deletes the note itself. if note has multiple branches, only the branch is deleted.

curl -sX DELETE "$TRILIUM_URL/etapi/notes/$NOTE_ID" \
  -H "Authorization: $TRILIUM_TOKEN"

step 13: export subtree as zip

inputs: TRILIUM_URL, TRILIUM_TOKEN, noteId, format (html|markdown) output: zip file written to stdout or specified file

curl -s "$TRILIUM_URL/etapi/notes/$NOTE_ID/export?format=markdown" \
  -H "Authorization: $TRILIUM_TOKEN" -o subtree.zip

to export whole document, use noteId=root.

step 14: import zip to note

inputs: TRILIUM_URL, TRILIUM_TOKEN, noteId, zip file output: import result object

curl -sX POST "$TRILIUM_URL/etapi/notes/$NOTE_ID/import" \
  -H "Authorization: $TRILIUM_TOKEN" \
  -F "file=@subtree.zip"

step 15: trigger database backup

inputs: TRILIUM_URL, TRILIUM_TOKEN, backup name output: 200 ok or error code

curl -sX PUT "$TRILIUM_URL/etapi/backup/now" \
  -H "Authorization: $TRILIUM_TOKEN"

writes to server's dataDirectory/backup/backup-now.db.

decision points

if you are on trilium < 0.93, use raw token form (Authorization: $TRILIUM_TOKEN), not bearer. raw form works on all versions 0.50+.

if you have a password but no token, exchange it first via POST /etapi/auth/login with json body {"password":"..."}. extract authToken from response. if auth fails with 429, the server is rate-limiting, wait before retry.

if you need to change note parent, do not use PATCH /branches. you must delete the old branch (DELETE /etapi/branches/{branchId}) then create a new one (POST /etapi/branches) with the new parentNoteId.

if you need to patch an attribute, only value and position are patchable for labels, and only position for relations. anything else (name, type) requires delete and recreate.

if you receive a 401 (unauthorized), confirm:

• TRILIUM_TOKEN is set and non-empty
• token was not revoked in trilium ui
• token has not expired (tokens don't typically expire unless server is restarted with new config)

if search returns empty but you expect results, check:

• search syntax is valid (examples: #label, #label=value, note.content *= "text")
• note content is indexed (new notes are indexed on next server startup or after manual re-index)
• if note is in protected branch, search may not include it

if note content PUT fails with 400, ensure:

• Content-Type header is text/plain not text/html
• body is valid for the note type (html for text, code for code, binary for file/image)

if bulk note creation times out, add pagination:

• create in smaller batches (50-100 per request) with delays between batches
• use --max-time 30 on curl to avoid hanging

if export or import fails with file size errors, check:

• server disk space is available
• zip file is not corrupted
• noteId exists and user has read/write permission

if you see NOTE_IS_PROTECTED error code, the note is write-protected. you need to unprotect it in the ui first or use a different note.

output contract

health check output (step 1)

• json object with appVersion, hostname, other metadata, or error object with status, code, message

search output (step 2)

• json object: {results: [{noteId, title, type, mime, ...}, ...], hasMore: boolean}

read metadata output (steps 3, 5)

• json object: {noteId, title, type, mime, dateCreated, utcDateCreated, isProtected, parentCount, ...}

read content output (step 4)

• raw string (no json wrapper). for text/html notes, html string. for code, source code. for file/image, binary blob.

create note output (step 5)

• json object: {note: {noteId, title, ...}, branch: {branchId, parentNoteId, ...}}

patch metadata output (step 7)

• json object with updated note fields

attribute output (step 8)

• json object: {attributeId, noteId, type, name, value, isInheritable, ...}

branch output (step 9)

• json object: {branchId, noteId, parentNoteId, notePosition, prefix, isExpanded, ...}

attachment output (step 10)

• json object: {attachmentId, noteId, title, fileSize, role, ...}

day note output (step 11)

• json object: {noteId, title, ...}

delete output (step 12)

• 200 ok (no body) on success, or error object

export output (step 13)

• binary zip file (write to disk with -o filename.zip)

import output (step 14)

• json object with import statistics or error

backup output (step 15)

• 200 ok (no body) on success, or error object

all error responses follow format: {status: "error"|"not-found"|..., code: "ERROR_CODE", message: "human string"}. code is stable and should be used in conditionals, not message.

outcome signal

health check passes if step 1 returns 200 with appVersion field and no 401/403 error.

search finds notes if step 2 returns results array with length > 0 and matching titles/noteIds.

note created if step 5 returns noteId in response (non-empty string, 12 chars, alphanumeric).

content updated if step 6 returns 200 and subsequent read (step 4) returns the new content.

metadata patched if step 7 returns updated note object with your new field values.

attribute added if step 8 returns attributeId and subsequent read of note shows the attribute in ui.

branch created if step 9 returns branchId and note now appears under new parent in ui.

attachment uploaded if step 10 returns attachmentId and subsequent read of note lists attachment.

day note exists if step 11 returns noteId (created on demand if not exist).

note deleted if step 12 returns 200 and subsequent read (step 3) returns 404.

export completes if step 13 writes valid zip file to disk (can be unzipped without error).

import succeeds if step 14 returns json with import count > 0 and new notes appear in ui.

backup triggered if step 15 returns 200 and backup file appears in server dataDirectory/backup/.

credits: original skill by yanickxia at clawhub, enriched for implexa standards with explicit decision branches, auth options, edge cases, and output contracts.