API: Create a new zettel

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

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

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

The zettel identifier of the created zettel is returned. 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.

Data input

Alternatively, you may encode the zettel as a parseable object / a symbolic expression by providing the query parameter enc=data. The encoding is the same as the data output encoding when you retrieve a zettel.

The encoding for access rights must be given, but is ignored. You may encode computed or property metadata keys, but these are also ignored.

HTTP Status codes


Zettel creation was successful, the body contains its zettel identifier (data value or plain text).


Request was not valid. There are several reasons for this. Most likely, the symbolic expression was not formed according to above rules.


You are not allowed to create a new zettel.