(((meta (@ (content . "API: Create a new zettel") (name . "title"))) (meta (@ (content . "manual") (name . "role"))) (meta (@ (content . "#api #manual #zettelstore") (name . "tags"))) (meta (@ (content . "zmk") (name . "syntax"))) (meta (@ (content . "00001005000000 00001012054200") (name . "back"))) (meta (@ (content . "00001005000000 00001012000000 00001012054200 00001012920000") (name . "backward"))) (meta (@ (content . "1") (name . "box-number"))) (meta (@ (content . "(c) 2020-present by Detlef Stern <ds@zettelstore.de>") (name . "copyright"))) (meta (@ (content . "20210713150005") (name . "created"))) (meta (@ (content . "00001006000000 00001006010000 00001006020000 00001006050000 00001012000000 00001012053300 00001012920000 00001012921200 00001012930500") (name . "forward"))) (meta (@ (content . "en") (name . "lang"))) (meta (@ (content . "EUPL-1.2-or-later") (name . "license"))) (meta (@ (content . "20230807170416") (name . "modified"))) (meta (@ (content . "20230807170416") (name . "published"))) (meta (@ (content . "public") (name . "visibility")))) (p "A zettel is created by adding it to the " (a (@ (href . "00001012000000")) "list of zettel") "." " " "Therefore, the " (a (@ (href . "00001012920000")) "endpoint") " to create a new zettel is also " (kbd "/z") ", but you must send the data of the new zettel via a HTTP POST request.") (p "The zettel must be encoded in a " (a (@ (href . "00001006000000")) "plain") " format: first comes the " (a (@ (href . "00001006010000")) "metadata") " and the following content is separated by an empty line." " " "This is the same format as used by storing zettel within a " (a (@ (href . "00001006010000")) "directory box") ".") (pre (code "# curl -X POST --data $'title: Note\\n\\nImportant content.' http://127.0.0.1:23123/z\n20210903211500")) (p "The zettel identifier of the created zettel is returned." " " "In addition, the HTTP response header contains a key " (kbd "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.") (h2 (@ (id . "data-input")) "Data input") (p "Alternatively, you may encode the zettel as a parseable object / a " (a (@ (href . "00001012930500")) "symbolic expression") " by providing the query parameter " (kbd "enc=data") "." " " "The encoding is the same as the data output encoding when you " (a (@ (href . "00001012053300#data-output")) "retrieve a zettel") ".") (p "The encoding for " (a (@ (href . "00001012921200")) "access rights") " must be given, but is ignored." " " "You may encode computed or property " (a (@ (href . "00001006020000")) "metadata keys") ", but these are also ignored.") (h2 (@ (id . "http-status-codes")) "HTTP Status codes") (dl (dt (kbd "201")) (dd (p "Zettel creation was successful, the body contains its " (a (@ (href . "00001006050000")) "zettel identifier") " (data value or plain text).")) (dt (kbd "400")) (dd (p "Request was not valid." (br) "There are several reasons for this." " " "Most likely, the symbolic expression was not formed according to above rules.")) (dt (kbd "403")) (dd (p "You are not allowed to create a new zettel."))))