API: Retrieve metadata and content of an existing zettel

00001012053300 · Info · (manual) · #api #manual #zettelstore (all)

The endpoint to work with metadata and content of a specific zettel is /z/{ID}, where {ID} is a placeholder for the zettel identifier.

For example, to retrieve some data about this zettel you are currently viewing, just send a HTTP GET request to the endpoint /z/00001012053300¹.

# curl 'http://127.0.0.1:23123/z/00001012053300'
The [[endpoint|00001012920000]] to work with metadata and content of a specific zettel is ''/z/{ID}'', where ''{ID}'' is a placeholder for the [[zettel identifier|00001006050000]].

For example, to retrieve some data about this zettel you are currently viewing, just send a HTTP GET request to the endpoint ''/z/00001012053300''[^If [[authentication is enabled|00001010040100]], you must include a valid [[access token|00001012050200]] in the ''Authorization'' header].

```sh
...

Optionally, you may provide which parts of the zettel you are requesting. In this case, add an additional query parameter part=PART. Valid values for PART are “zettel”, “meta”, and “content” (the default value).

# curl 'http://127.0.0.1:23123/z/00001012053300?part=zettel'
title: API: Retrieve metadata and content of an existing zettel
role: manual
tags: #api #manual #zettelstore
syntax: zmk

The [[endpoint|00001012920000]] to work with metadata and content of a specific zettel is ''/z/{ID}'', where ''{ID}'' is a placeholder for the [[zettel identifier|00001006050000]].

For example, to retrieve some data about this zettel you are currently viewing, just send a HTTP GET request to the endpoint
...

Data output

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

# curl 'http://127.0.0.1:23123/z/00001012053300?enc=data&part=zettel'
(zettel (meta (back "00001006000000 00001012000000 00001012053200 00001012054400") (backward "00001006000000 00001012000000 00001012053200 00001012054400 00001012920000") (box-number "1") (created "20211004093206") (forward "00001006020000 00001006050000 00001010040100 00001012050200 00001012053400 00001012920000 00001012920800 00001012921200 00001012930500") (modified "20230703174152") (published "20230703174152") (role "manual") (syntax "zmk") (tags "#api #manual #zettelstore") (title "API: Retrieve metadata and content of an existing zettel")) (rights 62) (encoding "") (content "The [[endpoint|00001012920000]] to work with metadata and content of a specific zettel is ''/z/{ID}'', where ''{ID}'' is a placeholder for the [[zettel identifier|00001006050000]].\n\nFor example, ...

If you print the result a little bit nicer, you will see its structure:

(zettel (meta (back "00001006000000 00001012000000 00001012053200 00001012054400")
              (backward "00001006000000 00001012000000 00001012053200 00001012054400 00001012920000")
              (box-number "1")
              (created "20211004093206")
              (forward "00001006020000 00001006050000 00001010040100 00001012050200 00001012053400 00001012920000 00001012920800 00001012921200 00001012930500")
              (modified "20230703174152")
              (published "20230703174152")
              (role "manual")
              (syntax "zmk")
              (tags "#api #manual #zettelstore")
              (title "API: Retrieve metadata and content of an existing zettel"))
        (rights 62)
        (encoding "")
        (content "The [[endpoint|00001012920000]] to work with metadata and content of a specific zettel is ''/z/{ID}'', where ''{ID}'' is a placeholder for the [[zettel identifier|00001006050000]].\n\nFor example, ...

The result is a list, starting with the symbol zettel.
Then, some key/value pairs are following, also nested.
Nested in meta are the metadata, each as a key/value pair.
rights specifies the access rights the user has for this zettel.
"encoding" states how the content is encoded. Currently, only two values are allowed: the empty string ("") that specifies an empty encoding, and the string "base64" that specifies the standard Base64 encoding.
The zettel contents is stored as a value of the key content. Typically, text content is not encoded, and binary content is encoded via Base64.

HTTP Status codes

200: Retrieval was successful, the body contains an appropriate data value.
204: Request was valid, but there is no data to be returned. Most likely, you specified the query parameter part=content, but the zettel does not contain any content.
400: Request was not valid.
There are several reasons for this. Maybe the zettel identifier did not consists of exactly 14 digits.
403: You are not allowed to retrieve data of the given zettel.
404: Zettel not found. You probably used a zettel identifier that is not used in the Zettelstore.

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