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