((META (EMPTY-STRING title "API: Refresh internal data") (WORD role "manual") (TAG-SET tags ("#api" "#manual" "#zettelstore")) (WORD syntax "zmk") (ZID-SET back ("00001012000000" "00001012080100" "00001018000000")) (ZID-SET backward ("00001012000000" "00001012051400" "00001012080100" "00001018000000")) (NUMBER box-number "1") (STRING copyright "(c) 2020-present by Detlef Stern <ds@zettelstore.de>") (TIMESTAMP created "20211230230441") (ZID-SET forward ("00001004011200" "00001004020000" "00001004051100" "00001010040100" "00001010070300" "00001012050600" "00001012051400" "00001012920000")) (WORD lang "en") (EMPTY-STRING license "EUPL-1.2-or-later") (TIMESTAMP modified "20260702143501") (TIMESTAMP published "20260702143501") (WORD visibility "public")) (BLOCK (PARA (TEXT "Zettelstore maintains internal data to make operations faster.") (SOFT) (TEXT "This allows it, for example, to quickly ") (LINK () (ZETTEL "00001012051400") (TEXT "find occurrences of a word")) (TEXT " without checking every zettel individually.") (SOFT) (TEXT "It also avoids repeatedly scanning ") (LINK () (ZETTEL "00001004011200") (TEXT "ZIP files")) (TEXT " containing zettel by remembering their metadata.")) (PARA (TEXT "In rare cases, this internal data may become outdated.") (SOFT) (TEXT "This should not happen, but differences in file systems and operating systems can occasionally lead to inconsistencies.") (SOFT) (TEXT "It may also happen if certain ") (LINK () (ZETTEL "00001004020000") (TEXT "system configuration settings")) (TEXT " have been changed.")) (PARA (TEXT "To resolve such issues without restarting Zettelstore, you can trigger a refresh of the internal data.") (SOFT) (TEXT "During a refresh, all zettel are read and processed again, and the internal data is updated accordingly.")) (PARA (TEXT "To trigger a refresh, send an HTTP POST request to the ") (LITERAL-INPUT () "/x") (TEXT " ") (LINK () (ZETTEL "00001012920000") (TEXT "endpoint")) (TEXT " with the query parameter ") (LITERAL-INPUT () "cmd=refresh") (TEXT ":")) (VERBATIM-CODE (("" . "sh")) "# curl -X POST 'http://127.0.0.1:23123/x?cmd=refresh'") (PARA (TEXT "If successful, the request returns HTTP status code 204 (No Content) with an empty body.")) (PARA (TEXT "The request succeeds if one of the following conditions is met:")) (UNORDERED () (BLOCK (PARA (TEXT "Authentication is not enabled, and Zettelstore was started with the ") (LINK () (ZETTEL "00001004051100") (LITERAL-INPUT () "run-simple")) (TEXT " command or ") (LINK () (ZETTEL "00001004010000#refresh-mode") (LITERAL-INPUT () "refresh-mode")) (TEXT " is set to ") (FORMAT-QUOTE () (TEXT "true")))) (BLOCK (PARA (LINK () (ZETTEL "00001010040100") (TEXT "Authentication is enabled")) (TEXT ", and you ") (LINK () (ZETTEL "00001012050600") (TEXT "provide a valid access token")) (TEXT ", while your ") (LINK () (ZETTEL "00001010070300") (TEXT "user role")) (TEXT " is not ") (FORMAT-QUOTE () (TEXT "creator")))) (BLOCK (PARA (TEXT "Authentication is enabled, you are either an anonymous user or your user role is ") (FORMAT-QUOTE () (TEXT "creator")) (TEXT ", and Zettelstore was started with the ") (LITERAL-INPUT () "run-simple") (TEXT " command or ") (LITERAL-INPUT () "refresh-mode") (TEXT " is set to ") (FORMAT-QUOTE () (TEXT "true")) (TEXT ".")))) (HEADING 1 () "http-status-codes" "http-status-codes" (TEXT "HTTP Status codes")) (DESCRIPTION () ((LITERAL-INPUT () "204")) (BLOCK (BLOCK (PARA (TEXT "Operation was successful, the body is empty.")))) ((LITERAL-INPUT () "400")) (BLOCK (BLOCK (PARA (TEXT "Request was not valid.") (SOFT) (TEXT "There are several reasons for this.") (SOFT) (TEXT "Most likely, no query parameter ") (LITERAL-INPUT () "cmd") (TEXT " was given, or it did not contain the value ") (FORMAT-QUOTE () (TEXT "refresh")) (TEXT ".")))) ((LITERAL-INPUT () "403")) (BLOCK (BLOCK (PARA (TEXT "You are not allowed to perform this operation.")))))))