(((meta ((content . "API: Refresh internal data") (name . "title"))) (meta ((content . "manual") (name . "role"))) (meta ((content . "#api #manual #zettelstore") (name . "tags"))) (meta ((content . "zmk") (name . "syntax"))) (meta ((content . "00001012000000 00001012080100 00001018000000") (name . "back"))) (meta ((content . "00001012000000 00001012051400 00001012080100 00001018000000") (name . "backward"))) (meta ((content . "1") (name . "box-number"))) (meta ((content . "(c) 2020-present by Detlef Stern <ds@zettelstore.de>") (name . "copyright"))) (meta ((content . "20211230230441") (name . "created"))) (meta ((content . "00001004011200 00001004051100 00001010040100 00001010070300 00001012050600 00001012051400 00001012920000") (name . "forward"))) (meta ((content . "en") (name . "lang"))) (meta ((content . "EUPL-1.2-or-later") (name . "license"))) (meta ((content . "20260303122105") (name . "modified"))) (meta ((content . "20260303122105") (name . "published"))) (meta ((content . "public") (name . "visibility")))) (p "Zettelstore maintains some internal data to allow faster operations.") (p "One example is the " (a ((href . "00001012051400")) "content search") " for a term: Zettelstore does not need to scan all zettel to find all occurrences for the term." " " "Instead, all words are stored internally, with a list of zettel where they occur.") (p "Another example is the way to determine which zettel are stored in a " (a ((href . "00001004011200")) "ZIP file") "." " " "Scanning a ZIP file is a lengthy operation, therefore Zettelstore maintains a directory of zettel for each ZIP file.") (p "All these internal data may become stale." " " "This should not happen, but when it comes e.g. to file handling, every operating system behaves differently in very subtle ways.") (p "To avoid stopping and re-starting Zettelstore, you can use the API to force Zettelstore to refresh its internal data if you think it is needed." " " "To do this, you must send an HTTP POST request to the " (a ((href . "00001012920000")) "endpoint") " " (kbd "/x") " and you must specify the query parameter " (kbd "cmd=refresh") ".") (pre (code ((class . "language-sh")) "# curl -X POST 'http://127.0.0.1:23123/x?cmd=refresh'")) (p "If successful, you will get an HTTP status code 204 (No Content) with an empty HTTP body.") (p "The request will be successful if either:") (ul (li "Authentication is not enabled, and either Zettelstore was started with the " (a ((href . "00001004051100")) "run-simple") " command or " (a ((href . "00001004010000#refresh-mode")) "refresh-mode") " is set to " (@L (@H "&ldquo;") "true" (@H "&rdquo;")) ",") (li (a ((href . "00001010040100")) "Authentication is enabled") ", you " (a ((href . "00001012050600")) "provide a valid access token") ", and your " (a ((href . "00001010070300")) "user role") " is not " (@L (@H "&ldquo;") "creator" (@H "&rdquo;")) ",") (li "Authentication is enabled, you are either an anonymous user or your user role is " (@L (@H "&ldquo;") "creator" (@H "&rdquo;")) ", and either Zettelstore was started with the run-simple command or refresh-mode is set to " (@L (@H "&ldquo;") "true" (@H "&rdquo;")) ".")) (h2 ((id . "http-status-codes")) "HTTP Status codes") (dl (dt (kbd "204")) (dd (p "Operation was successful, the body is empty.")) (dt (kbd "400")) (dd (p "Request was not valid." " " "There are several reasons for this." " " "Most likely, no query parameter " (kbd "cmd") " was given, or it did not contain the value " (@L (@H "&ldquo;") "refresh" (@H "&rdquo;")) ".")) (dt (kbd "403")) (dd (p "You are not allowed to perform this operation."))))