API: Create a new zettel

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

A zettel is created by adding it to the list of zettel. Therefore, the endpoint to create a new zettel is also /j, but you must send the data of the new zettel via a HTTP POST request.

The body of the POST request must contain a JSON object that specifies metadata and content of the zettel to be created. The following keys of the JSON object are used:

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

Other keys will be ignored. Even these three keys are just optional. The body of the HTTP POST request must not be empty and it must contain a JSON object.

Therefore, a body containing just {} is perfectly valid. The new zettel will have no content, its title will be set to the value of default-title (default: “Untitled”), its role is set to the value of default-role (default: “zettel”), and its syntax is set to the value of default-syntax (default: “zmk”).

# curl -X POST --data '{}' http://127.0.0.1:23123/j
{"id":"20210713161000"}

If creating the zettel was successful, the HTTP response will contain a JSON object with one key:

"id"
Contains the zettel identifier of the created zettel for further usage.

In addition, the HTTP response header contains a key Location with a relative URL for the new zettel. A client must prepend the HTTP protocol scheme, the host name, and (optional, but often needed) the post number to make it an absolute URL.

As an example, a zettel with title “Note” and content “Important content.” can be created by issuing:

# curl -X POST --data '{"meta":{"title":"Note"},"content":"Important content."}' http://127.0.0.1:23123/j
{"id":"20210713163100"}

Alternatively, you can use the endpoint /z to create a new zettel. In this case, the zettel must be encoded in a plain format: first comes the metadata and the following content is separated by an empty line. This is the same format as used by storing zettel within a directory box.

# curl -X POST --data $'title: Note\n\nImportant content.' http://127.0.0.1:23123/z
20210903211500

HTTP Status codes

201
Zettel creation was successful, the body contains a JSON object that contains its zettel identifier.
400
Request was not valid. There are several reasons for this. Most likely, the JSON was not formed according to above rules.
403
You are not allowed to create a new zettel.