API: Refresh internal data

Zettelstore maintains internal data to make operations faster. This allows it, for example, to quickly find occurrences of a word without checking every zettel individually. It also avoids repeatedly scanning ZIP files containing zettel by remembering their metadata.

In rare cases, this internal data may become outdated. This should not happen, but differences in file systems and operating systems can occasionally lead to inconsistencies. It may also happen if certain system configuration settings have been changed.

To resolve such issues without restarting Zettelstore, you can trigger a refresh of the internal data. During a refresh, all zettel are read and processed again, and the internal data is updated accordingly.

To trigger a refresh, send an HTTP POST request to the /x endpoint with the query parameter cmd=refresh:

# curl -X POST 'http://127.0.0.1:23123/x?cmd=refresh'

If successful, the request returns HTTP status code 204 (No Content) with an empty body.

The request succeeds if one of the following conditions is met:

• Authentication is not enabled, and Zettelstore was started with the run-simple command or refresh-mode is set to “true”
• Authentication is enabled, and you provide a valid access token, while your user role is not “creator”
• Authentication is enabled, you are either an anonymous user or your user role is “creator”, and Zettelstore was started with the run-simple command or refresh-mode is set to “true”.

HTTP Status codes

204

Operation was successful, the body is empty.

400

Request was not valid. There are several reasons for this. Most likely, no query parameter cmd was given, or it did not contain the value “refresh”.

403

You are not allowed to perform this operation.