API: Zettelstore readiness
Zettelstore starts its web service before the initial indexing of all zettel is complete. Until then, search results and some calculated metadata may be incomplete. Zettel metadata evaluated in this phase contains the key index-state with the value incomplete.
To find out whether the box service is completely ready, send an HTTP GET request to the endpoint /x with the query parameter data=ready.
This request does not require authentication, even if authentication is enabled. It does not provide any information about the content of the Zettelstore.
# curl -i 'http://127.0.0.1:23123/x?data=ready'
HTTP/1.1 503 Service Unavailable
Cache-Control: no-store
Retry-After: 1
Content-Type: text/plain; charset=utf-8
incomplete# curl -i 'http://127.0.0.1:23123/x?data=ready'
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: text/plain; charset=utf-8
readyThe body contains a plain text value for human readers, followed by a newline:
- ready
The box service is started, and the initial indexing is complete.
- incomplete
The box service is started, but the initial indexing is not complete yet.
The HTTP status code is authoritative. Clients must treat the status codes 200 and 204 as “ready”. Currently, only 200 is used, with the body ready. Future versions may respond with 204 and an empty body. Status 503 means “incomplete”. The body is informational only and should not be evaluated by clients. Intermediate components, such as reverse proxies, may replace the body of a 503 response.
Once ready is reported, the state does not change back during the lifetime of the Zettelstore process, even if the index is rebuilt later. During a rebuild, the previous index continues to serve requests.
Clients should poll this endpoint until it reports ready. The value of the Retry-After header is a hint for the polling interval in seconds.
HTTP Status codes
- 200, 204
The box service is ready. Currently, only 200 is used.
- 400
The value of the query parameter data is unknown.
- 503
The box service is running, but the initial indexing is not complete. Try again after the number of seconds given in the Retry-After header.