Trilium

Trilium ETAPI

Overview

ETAPI is the external REST API for Trilium Notes (Trilium ≥ 0.50). All requests require token auth. Resources are addressed by 12-char IDs: noteId, branchId, attributeId, attachmentId.

Core concepts:

When to Use

Do not use for scripts running *inside* Trilium — use the frontend/backend Script API directly, no HTTP needed.

Setup

All examples below assume:

export TRILIUM_URL="http://localhost:8080"   # no trailing /etapi
export TRILIUM_TOKEN=""

If you only have a password (and the server allows password login), exchange it for a token:

curl -sX POST "$TRILIUM_URL/etapi/auth/login" \
  -H 'Content-Type: application/json' \
  -d '{"password":"YOUR_PASSWORD"}' | jq -r .authToken

Three auth styles (pick one, in the Authorization header): 1. Authorization: $TRILIUM_TOKEN — raw token (works on every version) 2. Authorization: Bearer $TRILIUM_TOKEN — Bearer form (v0.93+) 3. Authorization: Basic $(echo -n "etapi:$TRILIUM_TOKEN" | base64) — Basic auth (v0.56+)

Quick Reference

| Operation | Method | Path | |-----------|--------|------| | Health / version | GET | /etapi/app-info | | Search notes | GET | /etapi/notes?search=... | | Read note metadata | GET | /etapi/notes/{noteId} | | Read note content | GET | /etapi/notes/{noteId}/content | | Write note content | PUT | /etapi/notes/{noteId}/content (text/plain) | | Create note | POST | /etapi/create-note | | Patch note metadata | PATCH | /etapi/notes/{noteId} | | Delete note | DELETE | /etapi/notes/{noteId} | | Export subtree as ZIP | GET | /etapi/notes/{noteId}/export?format=html\|markdown | | Import ZIP | POST | /etapi/notes/{noteId}/import | | Create / move branch | POST | /etapi/branches | | Create attribute | POST | /etapi/attributes | | Create attachment | POST | /etapi/attachments | | Day note (auto-create) | GET | /etapi/calendar/days/{YYYY-MM-DD} | | Inbox | GET | /etapi/inbox/{YYYY-MM-DD} | | Trigger DB backup | PUT | /etapi/backup/{name} |

Full endpoint, parameter, and schema reference: api-reference.md.

Core Patterns (curl + jq)

All snippets below assume TRILIUM_URL and TRILIUM_TOKEN are exported.

1. Health check

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

2. Create a text note

curl -sX POST "$TRILIUM_URL/etapi/create-note" \
  -H "Authorization: $TRILIUM_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "parentNoteId": "root",
    "title": "Hello from ETAPI",
    "type": "text",
    "content": "
Created via curl
"
  }' | jq '{noteId: .note.noteId, branchId: .branch.branchId}'

Returns NoteWithBranch: the new note plus the branch mounting it.

3. Replace note content

Content lives on a separate endpoint and the body is text/plain even when the content is HTML:

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

4. Search

# fulltext + label
curl -sG "$TRILIUM_URL/etapi/notes" \
  -H "Authorization: $TRILIUM_TOKEN" \
  --data-urlencode 'search=tolkien #book' \
  --data-urlencode 'limit=10' | jq '.results[] | {noteId, title}'

Search syntax matches the Trilium UI search bar. Common forms: #tag, #tag=value, note.content *= "...", ~relation.title = "...".

5. Tag a note

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

6. Day note (auto-created on demand)

TODAY=$(date +%F)
curl -s "$TRILIUM_URL/etapi/calendar/days/$TODAY" \
  -H "Authorization: $TRILIUM_TOKEN" | jq -r .noteId

7. Clone a note to another location (branch)

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
  }"

8. Export a subtree as ZIP

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

9. Trigger a server-side backup

curl -sX PUT "$TRILIUM_URL/etapi/backup/now" \
  -H "Authorization: $TRILIUM_TOKEN"
Writes to dataDirectory/backup/backup-now.db

Common Pitfalls

Note Types

| type | Use | mime required? | |------|-----|----------------| | text | Rich text (HTML) | no | | code | Source code | yes (e.g. text/x-python) | | file | Binary file | yes | | image | Image | yes (e.g. image/png) | | search | Saved search | no | | book | Folder-style container | no | | relationMap | Relation map | no | | render | Custom renderer | no |

You may also see these on read: noteMap, mermaid, webView, shortcut, doc, contentWidget, launcher.

Workflow: Append to today's day note

A typical inbox / capture flow — append arbitrary text to today's day note:

TODAY=$(date +%F)
NOTE_ID=$(curl -s "$TRILIUM_URL/etapi/calendar/days/$TODAY" \
  -H "Authorization: $TRILIUM_TOKEN" | jq -r .noteId)
OLD=$(curl -s "$TRILIUM_URL/etapi/notes/$NOTE_ID/content" \
  -H "Authorization: $TRILIUM_TOKEN")
NEW="${OLD}
$(date +%H:%M) — $1
"
curl -sX PUT "$TRILIUM_URL/etapi/notes/$NOTE_ID/content" \
  -H "Authorization: $TRILIUM_TOKEN" \
  -H 'Content-Type: text/plain' \
  --data-binary "$NEW"

When You Need More

All examples below assume:

export TRILIUM_URL="http://localhost:8080"   # no trailing /etapi
export TRILIUM_TOKEN=""

If you only have a password (and the server allows password login), exchange it for a token:

curl -sX POST "$TRILIUM_URL/etapi/auth/login" \
  -H 'Content-Type: application/json' \
  -d '{"password":"YOUR_PASSWORD"}' | jq -r .authToken

Three auth styles (pick one, in the Authorization header): 1. Authorization: $TRILIUM_TOKEN — raw token (works on every version) 2. Authorization: Bearer $TRILIUM_TOKEN — Bearer form (v0.93+) 3. Authorization: Basic $(echo -n "etapi:$TRILIUM_TOKEN" | base64) — Basic auth (v0.56+)