title: API: Create a new zettel
role: manual
tags: #api #manual #zettelstore
syntax: zmk
back: 00001005000000 00001012054200
backward: 00001005000000 00001012000000 00001012054200 00001012920000
box-number: 1
copyright: (c) 2020-present by Detlef Stern <ds@zettelstore.de>
created: 20210713150005
forward: 00001006000000 00001006010000 00001006020000 00001006050000 00001012000000 00001012920000 00001012921200 00001012930500
lang: en
license: EUPL-1.2-or-later
modified: 20251215173046
published: 20251215173046
visibility: public

A zettel is created by adding it to the [list of zettel](00001012000000).
Therefore, the [endpoint](00001012920000) to create a new zettel is also `/z`, but you must send the data of the new zettel via an HTTP POST request.

The zettel must be encoded in a [plain](00001006000000) format: first comes the [metadata](00001006010000) and the following content is separated by an empty line.
This is the same format as used by storing zettel within a [directory box](00001006010000).

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

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 port number to make it an absolute URL.

# Data input

Alternatively, you may encode the zettel as a parseable object / a [symbolic expression](00001012930500) by providing the query parameter `enc=data`.
The encoding is the same as the data output encoding when you [retrieve a zettel](00001012053300#data-output).

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

# HTTP Status codes