API: Retrieve metadata and content of an existing zettel

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 the 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
...

JSON output

Alternatively, you may retrieve the zettel as a JSON object by providinv the query parameter enc=json:

# curl 'http://127.0.0.1:23123/z/00001012053300?enc=json&part=zettel'
{"id":"00001012053300","meta":{"back":"00001012000000 00001012054400","backward":"00001012000000 00001012054400 00001012920000","box-number":"1","created":"20211004093206","forward":"00001006020000 00001006050000 00001010040100 00001012050200 00001012053400 00001012920000 00001012920800 00001012921200","modified":"20221219160211","published":"20221219160211","role":"manual","syntax":"zmk","tags":"#api #manual #zettelstore","title":"API: Retrieve metadata and content of an existing zettel"},"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, ...

Pretty-printed, this results in:

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

The following keys of the JSON object are used:

"id"

The zettel identifier of the zettel you requested.

"meta"

References an embedded JSON object with only string values. The name/value pairs of this objects are interpreted as the metadata of the new zettel. Please consider the list of supported metadata keys (and their value types).

"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. Other values will result in a HTTP response status code 400.

"content"

Is a string value that contains the content of the zettel to be created. Typically, text content is not encoded, and binary content is encoded via Base64.

"rights"

An integer number that describes the access rights for the zettel.

HTTP Status codes

200

Retrieval was successful, the body contains an appropriate JSON object / plain zettel data.

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.

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