API: List metadata of all zettel

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

To list the metadata of all zettel just send a HTTP GET request to the endpoint /j1. If successful, the output is a JSON object:

# curl http://127.0.0.1:23123/j
{"query":"","list":[{"id":"00001012051200","meta":{"title":"API: Renew an access token","tags":"#api #manual #zettelstore","syntax":"zmk","role":"manual"},"rights":62},{"id":"00001012050600","meta":{"title":"API: Provide an access token","tags":"#api #manual #zettelstore","syntax":"zmk","role":"manual"},"rights":62},{"id":"00001012050400","meta":{"title":"API: Renew an access token","tags":"#api #manual #zettelstore","syntax":"zmk","role":"manual"},"rights":62},{"id":"00001012050200","meta":{"title":"API: Authenticate a client","tags":"#api #manual #zettelstore","syntax":"zmk","role":"manual"},"rights":62},{"id":"00001012000000","meta":{"title":"API","tags":"#api #manual #zettelstore","syntax":"zmk","role":"manual"},"rights":62}]}

The JSON object contains a key "list" where its value is a list of zettel JSON objects. These zettel JSON objects themselves contains the keys "id" (value is a string containing the zettel identifier), "meta" (value as a JSON object), and "rights" (encodes the access rights for the given zettel). The value of key "meta" effectively contains all metadata of the identified zettel, where metadata keys are encoded as JSON object keys and metadata values encoded as JSON strings.

Additionally, the JSON object contains a key "query" with a string value. It will contain a textual description of the underlying query if you select only some zettel. Without a selection, the value is the empty string.

If you reformat the JSON output from the GET /j call, you'll see its structure better:

{
  "query": "",
  "list": [
    {
      "id": "00001012051200",
      "meta": {
        "title": "API: List for all zettel some data",
        "tags": "#api #manual #zettelstore",
        "syntax": "zmk",
        "role": "manual"
      },
      "rights":62
    },
    {
      "id": "00001012050600",
      "meta": {
        "title": "API: Provide an access token",
        "tags": "#api #manual #zettelstore",
        "syntax": "zmk",
        "role": "manual"
      },
      "rights":62
    },
    {
      "id": "00001012050400",
      "meta": {
        "title": "API: Renew an access token",
        "tags": "#api #manual #zettelstore",
        "syntax": "zmk",
        "role": "manual"
      },
      "rights":62
    },
    {
      "id": "00001012050200",
      "meta": {
        "title": "API: Authenticate a client",
        "tags": "#api #manual #zettelstore",
        "syntax": "zmk",
        "role": "manual"
      },
      "rights":62
    },
    {
      "id": "00001012000000",
      "meta": {
        "title": "API",
        "tags": "#api #manual #zettelstore",
        "syntax": "zmk",
        "role": "manual"
      },
      "rights":62
    }
  ]
}

In this special case, the metadata of each zettel just contains the four default keys title, tags, syntax, and role.

Alternatively, you can retrieve the list of zettel in a simple, plain format using the endpoint /z. In this case, a plain text document is returned, with one line per zettel. Each line contains in the first 14 characters the zettel identifier. Separated by a space character, the title of the zettel follows:

# curl http://127.0.0.1:23123/z
00001012051200 API: Renew an access token
00001012050600 API: Provide an access token
00001012050400 API: Renew an access token
00001012050200 API: Authenticate a client
00001012000000 API

Note

This request will always return a list of metadata, provided the request was syntactically correct. There will never be a HTTP status code 403 (Forbidden), even if authentication was enabled and you did not provide a valid access token. In this case, the resulting list might be quite short (some zettel will have public visibility) or the list might be empty.

With this call, you cannot differentiate between an empty result list (e.g because your content search did not found a zettel with the specified term) and an empty list because of missing authorization (e.g. an invalid access token).

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 access bearer token was not valid.
  1. If authentication is enabled, you must include the a valid access token in the Authorization header ↩︎