API: Retrieve evaluated metadata and content of an existing zettel in various encodings

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

The endpoint to work with evaluated metadata and content of a specific zettel is /v/{ID}, where {ID} is a placeholder for the zettel identifier.

For example, to retrieve some evaluated data about this zettel you are currently viewing, just send a HTTP GET request to the endpoint /v/00001012053500¹. If successful, the output is a JSON object:

# curl http://127.0.0.1:23123/v/00001012053500
{"meta":{"title":[{"t":"Text","s":"API:"},{"t":"Space"},{"t":"Text","s":"Retrieve"},{"t":"Space"},{"t":"Text","s":"evaluated"},{"t":"Space"},{"t":"Text","s":"metadata"},{"t":"Space"},{"t":"Text","s":"and"},{"t":"Space"},{"t":"Text","s":"content"},{"t":"Space"},{"t":"Text","s":"of"},{"t":"Space"},{"t":"Text","s":"an"},{"t":"Space"},{"t":"Text","s":"existing"},{"t":"Space"},{"t":"Text","s":"zettel"},{"t":"Space"},{"t":"Text","s":"in"},{"t":"Space"}, ...

To select another encoding, you can provide a query parameter _enc=[[ENCODING|00001012920500]]. The default encoding is zjson. Others are html, text, and some more.

# curl 'http://127.0.0.1:23123/v/00001012053500?_enc=html'
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>API: Retrieve evaluated metadata and content of an existing zettel in various encodings</title>
<meta name="zs-role" content="manual">
<meta name="keywords" content="api, manual, zettelstore">
<meta name="zs-syntax" content="zmk">
<meta name="zs-back" content="00001012000000">
<meta name="zs-backward" content="00001012000000">
<meta name="zs-box-number" content="1">
<meta name="copyright" content="(c) 2020-2021 by Detlef Stern <ds@zettelstore.de>">
<meta name="zs-forward" content="00001010040100 00001012050200 00001012920000 00001012920800">
<meta name="zs-published" content="00001012053500">
</head>
<body>
<p>The <a href="00001012920000">endpoint</a> to work with evaluated metadata and content of a specific zettel is <kbd>/v/{ID}</kbd>, where <kbd>{ID}</kbd> is a placeholder for the <a href="00001006050000">zettel identifier</a>.</p>
...

You also can use the query parameter _part=[[PART|00001012920800]] to specify which parts of a zettel must be encoded. In this case, its default value is content.

# curl 'http://127.0.0.1:23123/v/00001012053500?_enc=html&_part=meta'
<meta name="zs-title" content="API: Retrieve evaluated metadata and content of an existing zettel in various encodings">
<meta name="zs-role" content="manual">
<meta name="keywords" content="api, manual, zettelstore">
<meta name="zs-syntax" content="zmk">
<meta name="zs-back" content="00001012000000">
<meta name="zs-backward" content="00001012000000">
<meta name="zs-box-number" content="1">
<meta name="copyright" content="(c) 2020-2021 by Detlef Stern <ds@zettelstore.de>">
<meta name="zs-forward" content="00001010040100 00001012050200 00001012920000 00001012920800">
<meta name="zs-lang" content="en">
<meta name="zs-published" content="00001012053500">

The optional query parameter _embed will embed all images into the returned encoding.

HTTP Status codes

200: Retrieval was successful, the body contains an appropriate JSON object.
400: Request was not valid. There are several reasons for this. Maybe the zettel identifier did not consist of exactly 14 digits or _enc / _part contained illegal values.
403: You are not allowed to retrieve data of the given zettel.
404: Zettel not found. You probably used a zettel identifier that is not used in the Zettelstore.

If authentication is enabled, you must include the a valid access token in the Authorization header ↩︎