API: List all zettel

00001012051200 · Info · (manual) · #api #manual #zettelstore

To list all zettel just send a HTTP GET request to the endpoint /z¹. Always use the endpoint /z to work with a list of zettel.

Without further specifications, a plain text document is returned, with one line per zettel. Each line contains in the first 14 characters the zettel identifier. Separated by a space character, the title of the zettel follows:

# curl http://127.0.0.1:23123/z
...
00001012051200 API: List all zettel
00001012050600 API: Provide an access token
00001012050400 API: Renew an access token
00001012050200 API: Authenticate a client
...

The list is not sorted, even in the these examples where it appears to be sorted. If you want to have it ordered, you must specify it with the help of a query expression / search term. See Query the list of all zettel how to do it.

Data output

Alternatively, you may retrieve the zettel list as a parseable object / a symbolic expression by providing the query parameter enc=data:

# curl 'http://127.0.0.1:23123/z?enc=data'
(meta-list (query "") (human "") (list (zettel (id "00001012921200") (meta (title "API: Encoding of Zettel Access Rights") (role "manual") (tags "#api #manual #reference #zettelstore") (syntax "zmk") (back "00001012051200 00001012051400 00001012053300 00001012053400 00001012053900 00001012054000") (backward "00001012051200 00001012051400 00001012053300 00001012053400 00001012053900 00001012054000") (box-number "1") (created "00010101000000") (forward "00001003000000 00001006020400 00001010000000 00001010040100 00001010040200 00001010070200 00001010070300") (modified "20220201171959") (published "20220201171959")) (rights 62)) (zettel (id "00001007030100") ...

Pretty-printed, this results in:

(meta-list (query "")
           (human "")
           (list (zettel (id "00001012921200")
                         (meta (title "API: Encoding of Zettel Access Rights")
                               (role "manual")
                               (tags "#api #manual #reference #zettelstore")
                               (syntax "zmk")
                               (back "00001012051200 00001012051400 00001012053300 00001012053400 00001012053900 00001012054000")
                               (backward "00001012051200 00001012051400 00001012053300 00001012053400 00001012053900 00001012054000")
                               (box-number "1")
                               (created "00010101000000")
                               (forward "00001003000000 00001006020400 00001010000000 00001010040100 00001010040200 00001010070200 00001010070300")
                               (modified "20220201171959")
                               (published "20220201171959"))
                         (rights 62))
                 (zettel (id "00001007030100")

The result is a list, starting with the symbol meta-list.
Then, some key/value pairs are following, also nested.
Keys query and human will be explained later in this manual.
list starts a list of zettel.
zettel itself start, well, a zettel.
id denotes the zettel identifier, encoded as a string.
Nested in meta are the metadata, each as a key/value pair.
rights specifies the access rights the user has for this zettel.

Note

This request (and similar others) will always return a list of metadata, provided the request was syntactically correct. There will never be a HTTP status code 403 (Forbidden), even if authentication was enabled and you did not provide a valid access token. In this case, the resulting list might be quite short (some zettel will have public visibility) or the list might be empty.

With this call, you cannot differentiate between an empty result list (e.g because your search did not found a zettel with the specified term) and an empty list because of missing authorization (e.g. an invalid access token).

HTTP Status codes

200: Retrieval was successful, the body contains an appropriate data value.
400: Request was not valid. There are several reasons for this. Maybe the access bearer token was not valid.

If authentication is enabled, you must include the a valid access token in the Authorization header ↩︎