Build your personal knowledge base with Trilium Notes
TypeScript electronelectron-appknowledge-baseknowledge-graphknowledge-managementknowledge-management-graphlocal-firstnote-managmentnote-takernote-takingnotebooknotesnotes-apppersonal-knowledge-basepersonal-wikiscriptableself-hostedself-hostingwiki
openapi: "3.0.3"
info:
version: 1.0.0
title: ETAPI
description: External Trilium API
contact:
name: Trilium Notes Team
email: [email protected]
url: https://triliumnotes.org
license:
name: GNU Affero General Public License v3.0 or later
url: https://www.gnu.org/licenses/agpl-3.0.en.html
servers:
- url: http://localhost:37740/etapi
- url: http://localhost:8080/etapi
security:
- EtapiTokenAuth: []
- EtapiBasicAuth: []
tags:
- name: Notes
description: Notes and their content, and the import and export of whole subtrees.
x-icon: bx bx-note
- name: Branches
description: Branches place a note in the tree, under a parent note.
x-icon: bx bx-git-branch
- name: Attributes
description: Labels and relations of a note.
x-icon: bx bx-purchase-tag
- name: Attachments
description: Files attached to a note.
x-icon: bx bx-paperclip
- name: Revisions
description: Snapshots of a note's content.
x-icon: bx bx-history
- name: Calendar
description: Day, week, month and year notes of the journal, and the inbox note.
x-icon: bx bx-calendar
- name: Tokens
description: Obtaining and revoking ETAPI tokens with the password.
x-icon: bx bx-key
- name: Application
description: Information about the instance, backups and metrics.
x-icon: bx bx-server
paths:
/create-note:
post:
summary: Create a note
description: Create a note and place it into the note tree
tags: [Notes]
operationId: createNote
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/CreateNoteDef"
responses:
"201":
description: note created
content:
application/json; charset=utf-8:
schema:
$ref: "#/components/schemas/NoteWithBranch"
"409":
description: a note with the given noteId already exists (NOTE_ALREADY_EXISTS)
content:
application/json; charset=utf-8:
schema:
$ref: "#/components/schemas/Error"
default:
description: unexpected error
content:
application/json; charset=utf-8:
schema:
$ref: "#/components/schemas/Error"
/notes:
get:
summary: Search notes
description: Search notes
tags: [Notes]
operationId: searchNotes
parameters:
- name: search
in: query
required: true
description: search query string as described in https://triliumnext.github.io/Docs/Wiki/search.html
schema:
type: string
examples:
fulltext:
summary: Fulltext search for keywords (not exact match)
value: "towers tolkien"
fulltextExactMatch:
summary: Fulltext search for exact match (notice the double quotes)
value: '"Two Towers"'
fulltextWithLabel:
summary: Fulltext search for keyword AND matching label
value: "towers #book"
- name: fastSearch
in: query
required: false
description: enable fast search (fulltext doesn't look into content)
schema:
type: boolean
default: false
- name: includeArchivedNotes
in: query
required: false
description: search by default ignores archived notes. Set to 'true' to includes archived notes into search results.
schema:
type: boolean
default: false
- name: ancestorNoteId
in: query
required: false
description: search only in a subtree identified by the subtree noteId. By default whole tree is searched.
schema:
$ref: "#/components/schemas/EntityId"
- name: ancestorDepth
in: query
required: false
description: define how deep in the tree should the notes be searched
schema:
type: string
examples:
directChildren:
summary: depth of exactly 1 (direct children) to the ancestor (root if not set)
value: eq1
grandGrandChildren:
summary: depth of exactly 3 to the ancestor (root if not set)
value: eq3
lessThan4:
summary: depth less than 4 (so 1, 2, 3) to the ancestor (root if not set)
value: lt4
greaterThan2:
summary: depth greater than 2 (so 3, 4, 5, 6...) to the ancestor (root if not set)
value: gt4
- name: orderBy
in: query
required: false
description: name of the property/label to order search results by
schema:
type: string
example:
- title
- "#publicationDate"
- isProtected
- isArchived
- dateCreated
- dateModified
- utcDateCreated
- utcDateModified
- parentCount
- childrenCount
- attributeCount
- labelCount
- ownedLabelCount
- relationCount
- ownedRelationCount
- relationCountIncludingLinks
- ownedRelationCountIncludingLinks
- targetRelationCount
- targetRelationCountIncludingLinks
- contentSize
- contentAndAttachmentsSize
- contentAndAttachmentsAndRevisionsSize
- revisionCount
- name: orderDirection
in: query
required: false
description: order direction, ascending or descending
schema:
type: string
default: asc
enum:
- asc
- desc
- name: limit
in: query
required: false
description: limit the number of results you want to receive
schema:
type: integer
example: 10
- name: debug
in: query
required: false
description: set to true to get debug information in the response (search query parsing)
schema:
type: boolean
default: false
responses:
"200":
description: search response
content:
application/json; charset=utf-8:
schema:
$ref: "#/components/schemas/SearchResponse"
default:
description: unexpected error
content:
application/json; charset=utf-8:
schema:
$ref: "#/components/schemas/Error"
/notes/{noteId}:
parameters:
- name: noteId
in: path
required: true
schema:
$ref: "#/components/schemas/EntityId"
get:
summary: Get a note
description: Returns a note identified by its ID
tags: [Notes]
operationId: getNoteById
responses:
"200":
description: note response
content:
application/json; charset=utf-8:
schema:
$ref: "#/components/schemas/Note"
default:
description: unexpected error
content:
application/json; charset=utf-8:
schema:
$ref: "#/components/schemas/Error"
patch:
summary: Update a note
description: patch a note identified by the noteId with changes in the body
tags: [Notes]
operationId: patchNoteById
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/Note"
responses:
"200":
description: note updated
content:
application/json; charset=utf-8:
schema:
$ref: "#/components/schemas/Note"
default:
description: unexpected error
content:
application/json; charset=utf-8:
schema:
$ref: "#/components/schemas/Error"
delete:
summary: Delete a note
description: deletes a single note based on the noteId supplied
tags: [Notes]
operationId: deleteNoteById
responses:
"204":
description: note deleted
default:
description: unexpected error
content:
application/json; charset=utf-8:
schema:
$ref: "#/components/schemas/Error"
/notes/{noteId}/content:
parameters:
- name: noteId
in: path
required: true
schema:
$ref: "#/components/schemas/EntityId"
get:
summary: Get the content of a note
description: Returns note content identified by its ID. The response carries the note's MIME type as its `Content-Type`.
tags: [Notes]
operationId: getNoteContent
responses:
"200":
description: note content
content:
"*/*":
schema:
type: string
format: binary
put:
summary: Replace the content of a note
description: Updates note content identified by its ID
tags: [Notes]
operationId: putNoteContentById
requestBody:
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
/notes/{noteId}/export:
parameters:
- name: noteId
in: path
required: true
schema:
$ref: "#/components/schemas/EntityId"
- name: format
in: query
required: false
schema:
enum:
- html
- markdown
- share
default: html
get:
summary: Export a subtree
description: >-
Exports ZIP file export of a given note subtree. To export whole document, use "root" for noteId.
Protected notes are exported as "[protected]", without their content or attachments, even while
the protected session is open. The "share" format refuses a subtree that contains a protected note
with NOTE_IS_PROTECTED.
tags: [Notes]
operationId: exportNoteSubtree
responses:
"200":
description: export ZIP file
content:
application/zip:
schema:
type: string
format: binary
default:
description: unexpected error
content:
application/json; charset=utf-8:
schema:
$ref: "#/components/schemas/Error"
/notes/{noteId}/import:
parameters:
- name: noteId
in: path
required: true
schema:
$ref: "#/components/schemas/EntityId"
post:
summary: Import a ZIP archive
description: Imports ZIP file into a given note.
tags: [Notes]
operationId: importZip
requestBody:
description: >
The ZIP file, sent as `application/zip` or `application/octet-stream`;
other content types are not accepted.
required: true
content:
application/zip:
schema:
type: string
format: binary
application/octet-stream:
schema:
type: string
format: binary
responses:
"201":
description: note created
content:
application/json; charset=utf-8:
schema:
$ref: "#/components/schemas/NoteWithBranch"
default:
description: unexpected error
content:
application/json; charset=utf-8:
schema:
$ref: "#/components/schemas/Error"
/notes/{noteId}/revision:
parameters:
- name: noteId
in: path
required: true
schema:
$ref: "#/components/schemas/EntityId"
- name: format
in: query
required: false
schema:
enum:
- html
- markdown
default: html
post:
summary: Create a revision
description: Create a note revision for the given note
tags: [Revisions]
operationId: createRevision
responses:
"204":
description: revision has been created
default:
description: unexpected error
content:
application/json; charset=utf-8:
schema:
$ref: "#/components/schemas/Error"
/notes/{noteId}/revisions:
parameters:
- name: noteId
in: path
required: true
schema:
$ref: "#/components/schemas/EntityId"
get:
summary: List the revisions of a note
description: |
Returns the revisions of a note identified by its ID. Protected revisions are
omitted, since they cannot be read through ETAPI individually either.
tags: [Revisions]
operationId: getNoteRevisions
responses:
"200":
description: list of revisions
content:
application/json; charset=utf-8:
schema:
type: array
items:
$ref: "#/components/schemas/Revision"
default:
description: unexpected error
content:
application/json; charset=utf-8:
schema:
$ref: "#/components/schemas/Error"
/notes/{noteId}/attachments:
parameters:
- name: noteId
in: path
required: true
schema:
$ref: "#/components/schemas/EntityId"
get:
summary: List the attachments of a note
description: Returns all attachments for a note identified by its ID
tags: [Attachments]
operationId: getNoteAttachments
responses:
"200":
description: list of attachments
content:
application/json; charset=utf-8:
schema:
type: array
items:
$ref: "#/components/schemas/Attachment"
default:
description: unexpected error
content:
application/json; charset=utf-8:
schema:
$ref: "#/components/schemas/Error"
/notes/{noteId}/undelete:
parameters:
- name: noteId
in: path
required: true
schema:
$ref: "#/components/schemas/EntityId"
post:
summary: Restore a deleted note
description: Restore a deleted note. The note must be deleted and must have at least one undeleted parent.
tags: [Notes]
operationId: undeleteNote
responses:
"200":
description: note restored successfully
content:
application/json; charset=utf-8:
schema:
type: object
properties:
success:
type: boolean
example: true
default:
description: unexpected error
content:
application/json; charset=utf-8:
schema:
$ref: "#/components/schemas/Error"
/notes/history:
get:
summary: List recent changes
description: Returns recent changes including note creations, modifications, and deletions
tags: [Notes]
operationId: getNoteHistory
parameters:
- name: ancestorNoteId
in: query
required: false
description: Limit changes to a subtree identified by this note ID. Defaults to "root" (all notes).
schema:
$ref: "#/components/schemas/EntityId"
responses:
"200":
description: list of recent changes
content:
application/json; charset=utf-8:
schema:
type: array
items:
$ref: "#/components/schemas/RecentChange"
default:
description: unexpected error
content:
application/json; charset=utf-8:
schema:
$ref: "#/components/schemas/Error"
/revisions/{revisionId}:
parameters:
- name: revisionId
in: path
required: true
schema:
$ref: "#/components/schemas/EntityId"
get:
summary: Get a revision
description: Returns a revision identified by its ID
tags: [Revisions]
operationId: getRevisionById
responses:
"200":
description: revision response
content:
application/json; charset=utf-8:
schema:
$ref: "#/components/schemas/Revision"
default:
description: unexpected error
content:
application/json; charset=utf-8:
schema:
$ref: "#/components/schemas/Error"
/revisions/{revisionId}/content:
parameters:
- name: revisionId
in: path
required: true
schema:
$ref: "#/components/schemas/EntityId"
get:
summary: Get the content of a revision
description: Returns revision content identified by its ID
tags: [Revisions]
operationId: getRevisionContent
responses:
"200":
description: revision content response
content:
text/html:
schema:
type: string
default:
description: unexpected error
content:
application/json; charset=utf-8:
schema:
$ref: "#/components/schemas/Error"
/branches:
post:
summary: Create a branch
description: >
Create a branch (clone a note to a different location in the tree).
In case there is a branch between parent note and child note already,
then this will update the existing branch with prefix, notePosition and isExpanded.
tags: [Branches]
operationId: postBranch
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/Branch"
responses:
"200":
description: existing branch updated
content:
application/json; charset=utf-8:
schema:
$ref: "#/components/schemas/Branch"
"201":
description: branch created
content:
application/json; charset=utf-8:
schema:
$ref: "#/components/schemas/Branch"
default:
description: unexpected error
content:
application/json; charset=utf-8:
schema:
$ref: "#/components/schemas/Error"
/branches/{branchId}:
parameters:
- name: branchId
in: path
required: true
schema:
$ref: "#/components/schemas/EntityId"
get:
summary: Get a branch
description: Returns a branch identified by its ID
tags: [Branches]
operationId: getBranchById
responses:
"200":
description: branch response
content:
application/json; charset=utf-8:
schema:
$ref: "#/components/schemas/Branch"
default:
description: unexpected error
content:
application/json; charset=utf-8:
schema:
$ref: "#/components/schemas/Error"
patch:
summary: Update a branch
description: patch a branch identified by the branchId with changes in the body. Only prefix and notePosition can be updated. If you want to update other properties, you need to delete the old branch and create a new one.
tags: [Branches]
operationId: patchBranchById
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/Branch"
responses:
"200":
description: branch updated
content:
application/json; charset=utf-8:
schema:
$ref: "#/components/schemas/Branch"
default:
description: unexpected error
content:
application/json; charset=utf-8:
schema:
$ref: "#/components/schemas/Error"
delete:
summary: Delete a branch
description: >
deletes a branch based on the branchId supplied. If this is the last branch of the (child) note,
then the note is deleted as well.
tags: [Branches]
operationId: deleteBranchById
responses:
"204":
description: branch deleted
default:
description: unexpected error
content:
application/json; charset=utf-8:
schema:
$ref: "#/components/schemas/Error"
/attachments:
post:
summary: Create an attachment
description: create an attachment
tags: [Attachments]
operationId: postAttachment
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/CreateAttachment"
responses:
"201":
description: attachment created
content:
application/json; charset=utf-8:
schema:
$ref: "#/components/schemas/Attachment"
default:
description: unexpected error
content:
application/json; charset=utf-8:
schema:
$ref: "#/components/schemas/Error"
/attachments/{attachmentId}:
parameters:
- name: attachmentId
in: path
required: true
schema:
$ref: "#/components/schemas/EntityId"
get:
summary: Get an attachment
description: Returns an attachment identified by its ID
tags: [Attachments]
operationId: getAttachmentById
responses:
"200":
description: attachment response
content:
application/json; charset=utf-8:
schema:
$ref: "#/components/schemas/Attachment"
default:
description: unexpected error
content:
application/json; charset=utf-8:
schema:
$ref: "#/components/schemas/Error"
patch:
summary: Update an attachment
description: patch an attachment identified by the attachmentId with changes in the body. Only role, mime, title, and position are patchable.
tags: [Attachments]
operationId: patchAttachmentById
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/Attachment"
responses:
"200":
description: attribute updated
content:
application/json; charset=utf-8:
schema:
$ref: "#/components/schemas/Attachment"
default:
description: unexpected error
content:
application/json; charset=utf-8:
schema:
$ref: "#/components/schemas/Error"
delete:
summary: Delete an attachment
description: deletes an attachment based on the attachmentId supplied.
tags: [Attachments]
operationId: deleteAttachmentById
responses:
"204":
description: attachment deleted
default:
description: unexpected error
content:
application/json; charset=utf-8:
schema:
$ref: "#/components/schemas/Error"
/attachments/{attachmentId}/content:
parameters:
- name: attachmentId
in: path
required: true
schema:
$ref: "#/components/schemas/EntityId"
get:
summary: Get the content of an attachment
description: Returns attachment content identified by its ID. The response carries the attachment's MIME type as its `Content-Type`.
tags: [Attachments]
operationId: getAttachmentContent
responses:
"200":
description: attachment content
content:
"*/*":
schema:
type: string
format: binary
put:
summary: Replace the content of an attachment
description: Updates attachment content identified by its ID
tags: [Attachments]
operationId: putAttachmentContentById
requestBody:
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
/attributes:
post:
summary: Create an attribute
description: create an attribute for a given note
tags: [Attributes]
operationId: postAttribute
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/Attribute"
responses:
"201":
description: attribute created
content:
application/json; charset=utf-8:
schema:
$ref: "#/components/schemas/Attribute"
"409":
description: an attribute with the given attributeId already exists (ATTRIBUTE_ALREADY_EXISTS)
content:
application/json; charset=utf-8:
schema:
$ref: "#/components/schemas/Error"
default:
description: unexpected error
content:
application/json; charset=utf-8:
schema:
$ref: "#/components/schemas/Error"
/attributes/{attributeId}:
parameters:
- name: attributeId
in: path
required: true
schema:
$ref: "#/components/schemas/EntityId"
get:
summary: Get an attribute
description: Returns an attribute identified by its ID
tags: [Attributes]
operationId: getAttributeById
responses:
"200":
description: attribute response
content:
application/json; charset=utf-8:
schema:
$ref: "#/components/schemas/Attribute"
default:
description: unexpected error
content:
application/json; charset=utf-8:
schema:
$ref: "#/components/schemas/Error"
patch:
summary: Update an attribute
description: patch an attribute identified by the attributeId with changes in the body. For labels, only value and position can be updated. For relations, only position can be updated. If you want to modify other properties, you need to delete the old attribute and create a new one.
tags: [Attributes]
operationId: patchAttributeById
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/Attribute"
responses:
"200":
description: attribute updated
content:
application/json; charset=utf-8:
schema:
$ref: "#/components/schemas/Attribute"
default:
description: unexpected error
content:
application/json; charset=utf-8:
schema:
$ref: "#/components/schemas/Error"
delete:
summary: Delete an attribute
description: deletes an attribute based on the attributeId supplied.
tags: [Attributes]
operationId: deleteAttributeById
responses:
"204":
description: attribute deleted
default:
description: unexpected error
content:
application/json; charset=utf-8:
schema:
$ref: "#/components/schemas/Error"
/refresh-note-ordering/{parentNoteId}:
parameters:
- name: parentNoteId
in: path
required: true
schema:
$ref: "#/components/schemas/EntityId"
post:
summary: Refresh the order of child notes
description: >
notePositions in branches are not automatically pushed to connected clients and need a specific instruction.
If you want your changes to be in effect immediately, call this service after setting branches' notePosition.
Note that you need to supply "parentNoteId" of branch(es) with changed positions.
tags: [Branches]
operationId: postRefreshNoteOrdering
responses:
"204":
description: note ordering refreshed
default:
description: unexpected error
content:
application/json; charset=utf-8:
schema:
$ref: "#/components/schemas/Error"
/inbox/{date}:
get:
summary: Get the inbox note
description: >
returns an "inbox" note, into which note can be created. Date will be used depending on whether the inbox
is a fixed note (identified with #inbox label) or a day note in a journal. A database with neither
returns the root note, and ignores the date, rather than creating a journal to hold a day note.
tags: [Calendar]
operationId: getInboxNote
parameters:
- name: date
in: path
required: true
schema:
type: string
format: date
example: 2022-02-22
responses:
"200":
description: inbox note
content:
application/json; charset=utf-8:
schema:
$ref: "#/components/schemas/Note"
default:
description: unexpected error
content:
application/json; charset=utf-8:
schema:
$ref: "#/components/schemas/Error"
/calendar/days/{date}:
get:
summary: Get a day note
description: returns a day note for a given date. Gets created if doesn't exist.
tags: [Calendar]
operationId: getDayNote
parameters:
- name: date
in: path
required: true
schema:
type: string
format: date
example: 2022-02-22
responses:
"200":
description: day note
content:
application/json; charset=utf-8:
schema:
$ref: "#/components/schemas/Note"
default:
description: unexpected error
content:
application/json; charset=utf-8:
schema:
$ref: "#/components/schemas/Error"
/calendar/week-first-day/{date}:
get:
summary: Get the day note starting the week
description: |
Returns the day note for the first day of the week containing the given date, honouring
the configured first day of week. The note is created if it doesn't exist. This returns a
day note, not a week note, so unlike /calendar/weeks/{week} it does not require the
enableWeekNote label on the calendar root.
tags: [Calendar]
operationId: getWeekFirstDayNote
parameters:
- name: date
in: path
required: true
description: Any date within the week, in the format YYYY-MM-DD.
schema:
type: string
format: date
example: 2022-02-22
responses:
"200":
description: day note starting the week
content:
application/json; charset=utf-8:
schema:
$ref: "#/components/schemas/Note"
default:
description: unexpected error
content:
application/json; charset=utf-8:
schema:
$ref: "#/components/schemas/Error"
/calendar/weeks/{week}:
get:
summary: Get a week note
description: Returns a week note for a given ISO week (format YYYY-Www, e.g., 2025-W01). The note is created if it doesn't exist.
tags: [Calendar]
operationId: getWeekNote
parameters:
- name: week
in: path
required: true
description: The ISO 8601 week identifier (YYYY-Www).
schema:
type: string
pattern: "[0-9]{4}-W[0-9]{2}"
example: "2025-W01"
responses:
"200":
description: week note
content:
application/json; charset=utf-8:
schema:
$ref: "#/components/schemas/Note"
default:
description: unexpected error
content:
application/json; charset=utf-8:
schema:
$ref: "#/components/schemas/Error"
/calendar/months/{month}:
get:
summary: Get a month note
description: Returns a month note for a given month (format YYYY-MM, e.g., 2022-02). The note is created if it doesn't exist.
tags: [Calendar]
operationId: getMonthNote
parameters:
- name: month
in: path
required: true
schema:
type: string
pattern: "[0-9]{4}-[0-9]{2}"
example: 2022-02
responses:
"200":
description: month note
content:
application/json; charset=utf-8:
schema:
$ref: "#/components/schemas/Note"
default:
description: unexpected error
content:
application/json; charset=utf-8:
schema:
$ref: "#/components/schemas/Error"
/calendar/years/{year}:
get:
summary: Get a year note
description: Returns a year note for a given year (format YYYY, e.g., 2022). The note is created if it doesn't exist.
tags: [Calendar]
operationId: getYearNote
parameters:
- name: year
in: path
required: true
schema:
type: string
pattern: "^[0-9]{4}$"
example: "2022"
responses:
"200":
description: year note
content:
application/json; charset=utf-8:
schema:
$ref: "#/components/schemas/Note"
default:
description: unexpected error
content:
application/json; charset=utf-8:
schema:
$ref: "#/components/schemas/Error"
/auth/login:
post:
summary: Log in
description: get an ETAPI token based on password for further use with ETAPI. Too many requests from one IP address within a short time, such as failed logins, block that address for a while.
tags: [Tokens]
operationId: login
security: [] # no token based auth for login endpoint
requestBody:
required: true
content:
application/json:
schema:
properties:
password:
type: string
description: user's password used to e.g. login to Trilium server and/or protect notes
totpToken:
type: string
description: the current TOTP code, or one of the recovery codes; required when multi-factor authentication with TOTP is enabled. Each code is accepted once.
tokenName:
type: string
description: name of the created token, shown in the list of ETAPI tokens
responses:
"201":
description: auth token
content:
application/json; charset=utf-8:
schema:
properties:
authToken:
type: string
example: Bc4bFn0Ffiok_4NpbVCDnFz7B2WU+pdhW8B5Ne3DiR5wXrEyqdjgRIsk=
"401":
description: "wrong credentials: `WRONG_PASSWORD`, `TOTP_REQUIRED` (TOTP is enabled and no `totpToken` was sent) or `WRONG_TOTP`"
content:
application/json; charset=utf-8:
schema:
$ref: "#/components/schemas/Error"
"429":
description: too many requests
default:
description: unexpected error
content:
application/json; charset=utf-8:
schema:
$ref: "#/components/schemas/Error"
/auth/logout:
post:
summary: Log out
description: logout (delete/deactivate) an ETAPI token
tags: [Tokens]
operationId: logout
responses:
"204":
description: logout successful
default:
description: unexpected error
content:
application/json; charset=utf-8:
schema:
$ref: "#/components/schemas/Error"
/app-info:
get:
summary: Get application info
description: returns information about the running Trilium instance
tags: [Application]
operationId: getAppInfo
responses:
"200":
description: app info
content:
application/json; charset=utf-8:
schema:
$ref: "#/components/schemas/AppInfo"
default:
description: unexpected error
content:
application/json; charset=utf-8:
schema:
$ref: "#/components/schemas/Error"
/backup/{backupName}:
parameters:
- name: backupName
in: path
required: true
description: If the backupName is e.g. "now", then the backup will be written to "backup-now.db" file
schema:
$ref: "#/components/schemas/StringId"
put:
summary: Create a backup
description: Create a database backup under a given name
tags: [Application]
operationId: createBackup
responses:
"204":
description: backup has been created
default:
description: unexpected error
content:
application/json; charset=utf-8:
schema:
$ref: "#/components/schemas/Error"
/metrics:
get:
summary: Get instance metrics
description: |
Returns instance and database metrics for monitoring: note, attachment, revision,
branch, attribute and blob counts, note and attachment type breakdowns, version
information and database size. Counts only — no note titles, content or attributes.
The same data is served by GET /api/metrics to the web session.
tags: [Application]
operationId: getMetrics
parameters:
- name: format
in: query
required: false
description: Response format. Defaults to Prometheus text.
schema:
type: string
enum: [prometheus, json]
default: prometheus
responses:
"200":
description: instance metrics
content:
text/plain:
schema:
type: string
example: |
# HELP trilium_info Trilium instance information
# TYPE trilium_info gauge
trilium_info{version="0.99.3",db_version="231"} 1 1701432000
# HELP trilium_notes_total Total number of notes including deleted
# TYPE trilium_notes_total gauge
trilium_notes_total 1234 1701432000
application/json:
schema:
$ref: "#/components/schemas/Metrics"
default:
description: unexpected error
content:
application/json; charset=utf-8:
schema:
$ref: "#/components/schemas/Error"
components:
securitySchemes:
EtapiTokenAuth:
type: apiKey
in: header
name: Authorization
EtapiBasicAuth:
type: http
scheme: basic
description: >
Basic Auth where username is arbitrary string (e.g. "trilium", not checked),
username is the ETAPI token.
To emphasize, do not use Trilium password here (won't work), only the generated
ETAPI token (from Options -> ETAPI)
schemas:
CreateNoteDef:
type: object
required:
- parentNoteId
- title
- type
- content
properties:
parentNoteId:
$ref: "#/components/schemas/EntityId"
description: Note ID of the parent note in the tree
title:
type: string
type:
type: string
enum:
- text
- code
- file
- image
- search
- book
- relationMap
- render
mime:
type: string
description: this needs to be specified only for note types 'code', 'file', 'image'.
example: application/json
content:
type: string
notePosition:
type: integer
description: >
Position of the note in the parent. Normal ordering is 10, 20, 30 ...
So if you want to create a note on the first position, use e.g. 5, for second position 15, for last e.g. 1000000
prefix:
type: string
description: >
Prefix is branch (placement) specific title prefix for the note.
Let's say you have your note placed into two different places in the tree,
but you want to change the title a bit in one of the placements. For this you can use prefix.
isExpanded:
type: boolean
description: true if this note (as a folder) should appear expanded
noteId:
$ref: "#/components/schemas/EntityId"
description: DON'T specify unless you want to force a specific noteId. It must not belong to an existing note.
branchId:
$ref: "#/components/schemas/EntityId"
description: DON'T specify unless you want to force a specific branchId
dateCreated:
$ref: "#/components/schemas/LocalDateTime"
description: Local timestap of the note creation. Specify only if you want to override the default (current datetime in the current timezone/offset).
utcDateCreated:
$ref: "#/components/schemas/UtcDateTime"
description: UTC timestap of the note creation. Specify only if you want to override the default (current datetime).
utcDateModified:
$ref: "#/components/schemas/UtcDateTime"
description: >
UTC timestamp of the note's last modification, e.g. to keep the date of a note being migrated
from another application. The local dateModified is derived from it. Specify only if you want
to override the default (current datetime).
Note:
type: object
properties:
noteId:
$ref: "#/components/schemas/EntityId"
readOnly: true
title:
type: string
description: |
Title of the note. Returned as "[protected]" for protected notes, since ETAPI
cannot open a protected session.
type:
type: string
enum:
[
text,
code,
render,
file,
image,
search,
relationMap,
book,
noteMap,
mermaid,
webView,
shortcut,
doc,
contentWidget,
launcher,
]
mime:
type: string
isProtected:
type: boolean
readOnly: true
blobId:
type: string
description: ID of the blob object which effectively serves as a content hash
attributes:
$ref: "#/components/schemas/AttributeList"
readOnly: true
parentNoteIds:
$ref: "#/components/schemas/EntityIdList"
readOnly: true
childNoteIds:
$ref: "#/components/schemas/EntityIdList"
readOnly: true
parentBranchIds:
$ref: "#/components/schemas/EntityIdList"
readOnly: true
childBranchIds:
$ref: "#/components/schemas/EntityIdList"
readOnly: true
dateCreated:
$ref: "#/components/schemas/LocalDateTime"
dateModified:
$ref: "#/components/schemas/LocalDateTime"
readOnly: true
utcDateCreated:
$ref: "#/components/schemas/UtcDateTime"
utcDateModified:
$ref: "#/components/schemas/UtcDateTime"
description: >
Writable through PATCH, e.g. to restore a migrated note's date after its content was rewritten.
The local dateModified is derived from it.
Branch:
type: object
description: Branch places the note into the tree, it represents the relationship between a parent note and child note
properties:
branchId:
$ref: "#/components/schemas/EntityId"
noteId:
$ref: "#/components/schemas/EntityId"
readOnly: true
description: identifies the child note
parentNoteId:
$ref: "#/components/schemas/EntityId"
readOnly: true
description: identifies the parent note
prefix:
type: string
notePosition:
type: integer
format: int32
isExpanded:
type: boolean
utcDateModified:
$ref: "#/components/schemas/UtcDateTime"
readOnly: true
NoteWithBranch:
type: object
properties:
note:
$ref: "#/components/schemas/Note"
branch:
$ref: "#/components/schemas/Branch"
Attachment:
type: object
description: Attachment is owned by a note, has title and content
properties:
attachmentId:
$ref: "#/components/schemas/EntityId"
readOnly: true
ownerId:
$ref: "#/components/schemas/EntityId"
description: identifies the owner of the attachment, is either noteId or revisionId
role:
type: string
mime:
type: string
title:
type: string
description: |
Title of the attachment. Returned as "[protected]" for protected attachments,
since ETAPI cannot open a protected session.
position:
type: integer
format: int32
blobId:
type: string
description: ID of the blob object which effectively serves as a content hash
dateModified:
$ref: "#/components/schemas/LocalDateTime"
readOnly: true
utcDateModified:
$ref: "#/components/schemas/UtcDateTime"
readOnly: true
utcDateScheduledForErasureSince:
$ref: "#/components/schemas/UtcDateTime"
readOnly: true
contentLength:
type: integer
format: int32
CreateAttachment:
type: object
properties:
ownerId:
$ref: "#/components/schemas/EntityId"
description: identifies the owner of the attachment, is either noteId or revisionId
role:
type: string
mime:
type: string
title:
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
Attribute:
type: object
description: Attribute (Label, Relation) is a key-value record attached to a note.
properties:
attributeId:
$ref: "#/components/schemas/EntityId"
noteId:
$ref: "#/components/schemas/EntityId"
readOnly: true
description: identifies the child note
type:
type: string
enum: [label, relation]
name:
type: string
pattern: '^[^\s]+'
example: shareCss
value:
type: string
position:
type: integer
format: int32
isInheritable:
type: boolean
utcDateModified:
$ref: "#/components/schemas/UtcDateTime"
readOnly: true
AttributeList:
type: array
items:
$ref: "#/components/schemas/Attribute"
SearchResponse:
type: object
required:
- results
properties:
results:
type: array
items:
$ref: "#/components/schemas/Note"
debugInfo:
type: object
description: debugging info on parsing the search query enabled with &debug=true parameter
EntityId:
type: string
pattern: "[a-zA-Z0-9_]{4,32}"
example: evnnmvHTCgIn
StringId:
type: string
pattern: "[a-zA-Z0-9_]{1,32}"
example: my_ID
EntityIdList:
type: array
items:
$ref: "#/components/schemas/EntityId"
LocalDateTime:
type: string
pattern: '[0-9]{4}-[0-9]{2}-[0-9]{2} [0-9]{2}:[0-9]{2}:[0-9]{2}\.[0-9]{3}[\+\-][0-9]{4}'
example: 2021-12-31 20:18:11.930+0100
UtcDateTime:
type: string
pattern: '[0-9]{4}-[0-9]{2}-[0-9]{2} [0-9]{2}:[0-9]{2}:[0-9]{2}\.[0-9]{3}Z'
example: 2021-12-31 19:18:11.930Z
AppInfo:
type: object
properties:
appVersion:
type: string
description: Trilium version
example: 0.50.2
dbVersion:
type: integer
format: int32
description: DB version
example: 194
syncVersion:
type: integer
format: int32
description: Sync protocol version
example: 25
buildDate:
type: string
format: date-time
description: build date
example: 2022-02-09T22:52:36+01:00
buildRevision:
type: string
description: git build revision
example: 23daaa2387a0655685377f0a541d154aeec2aae8
dataDirectory:
type: string
description: data directory where Trilium stores files
example: /home/user/data
clipperProtocolVersion:
type: string
description: version of the supported Trilium Web Clipper protocol
example: 1.1
utcDateTime:
type: string
description: current UTC date time
example: 2022-03-07T21:54:25.277Z
Error:
type: object
required:
- status
- code
- message
properties:
status:
type: integer
format: int32
description: HTTP status, identical to the one given in HTTP response
example: 400
code:
type: string
description: stable string constant
example: NOTE_IS_PROTECTED
message:
type: string
description: Human readable error, potentially with more details,
example: Note 'evnnmvHTCgIn' is protected and cannot be modified through ETAPI
Revision:
type: object
description: Revision represents a snapshot of note's title and content at some point in the past.
properties:
revisionId:
$ref: "#/components/schemas/EntityId"
readOnly: true
noteId:
$ref: "#/components/schemas/EntityId"
readOnly: true
type:
type: string
enum:
[
text,
code,
render,
file,
image,
search,
relationMap,
book,
noteMap,
mermaid,
webView,
shortcut,
doc,
contentWidget,
launcher,
]
mime:
type: string
isProtected:
type: boolean
readOnly: true
title:
type: string
blobId:
type: string
description: ID of the blob object which effectively serves as a content hash
dateLastEdited:
$ref: "#/components/schemas/LocalDateTime"
readOnly: true
dateCreated:
$ref: "#/components/schemas/LocalDateTime"
readOnly: true
utcDateLastEdited:
$ref: "#/components/schemas/UtcDateTime"
readOnly: true
utcDateCreated:
$ref: "#/components/schemas/UtcDateTime"
readOnly: true
utcDateModified:
$ref: "#/components/schemas/UtcDateTime"
readOnly: true
contentLength:
type: integer
format: int32
readOnly: true
RecentChange:
type: object
description: Represents a recent change event (creation, modification, or deletion).
properties:
noteId:
$ref: "#/components/schemas/EntityId"
readOnly: true
title:
type: string
description: Title at the time of the change (may be "[protected]" for protected notes)
current_title:
type: string
description: Current title of the note (may be "[protected]" for protected notes)
current_isDeleted:
type: boolean
description: Whether the note is currently deleted
current_deleteId:
type: string
description: Delete ID if the note is deleted
current_isProtected:
type: boolean
description: Whether the note is protected
utcDate:
$ref: "#/components/schemas/UtcDateTime"
description: UTC timestamp of the change
date:
$ref: "#/components/schemas/LocalDateTime"
description: Local timestamp of the change
canBeUndeleted:
type: boolean
description: Whether the note can be undeleted (only present for deleted notes)
Metrics:
type: object
description: Instance and database metrics, as served by GET /etapi/metrics?format=json
properties:
version:
type: object
properties:
app:
type: string
example: "0.99.3"
db:
type: integer
example: 231
node:
type: string
example: v22.14.0
sync:
type: integer
example: 35
buildDate:
type: string
example: "2024-09-07T18:36:34Z"
buildRevision:
type: string
example: 7c0d6930fa8f20d269dcfbcbc8f636a25f6bb9a7
database:
type: object
properties:
totalNotes:
type: integer
deletedNotes:
type: integer
activeNotes:
type: integer
protectedNotes:
type: integer
totalAttachments:
type: integer
deletedAttachments:
type: integer
activeAttachments:
type: integer
totalRevisions:
type: integer
totalBranches:
type: integer
totalAttributes:
type: integer
totalBlobs:
type: integer
totalEtapiTokens:
type: integer
totalRecentNotes:
type: integer
noteTypes:
type: object
description: Number of active notes per note type
additionalProperties:
type: integer
example:
text: 800
code: 200
attachmentTypes:
type: object
description: Number of active attachments per MIME type
additionalProperties:
type: integer
example:
image/png: 45
application/pdf: 14
statistics:
type: object
properties:
oldestNote:
type: string
nullable: true
newestNote:
type: string
nullable: true
lastModified:
type: string
nullable: true
databaseSizeBytes:
type: integer
nullable: true
timestamp:
type: string
example: "2024-12-01T12:00:00.000Z"