Skip to content

Build your personal knowledge base with Trilium Notes

71.7 KB
Raw Blame
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"