API: Query the list of all zettel

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

The endpoint /q allows to query the list of all zettel1.

A query is an optional search expression, together with an optional list of actions (described below). An empty search expression will select all zettel. An empty list of action, or no valid action, returns the list of all selected zettel metadata.

Search expression and action list are separated by a vertical bar character (|, U+007C), and must be given with the query parameter q.

For example, to list all roles used in the Zettelstore, send a HTTP GET request to the endpoint /q?q=|role. If successful, the output is a JSON object:

# curl http://127.0.0.1:23123/q?q=|role
{"map":{"configuration":["00000000090002","00000000090000", ... ,"00000000000001"],"manual":["00001014000000", ... ,"00001000000000"],"zettel":["00010000000000", ... ,"00001012070500","00000000090001"]}}

The JSON object only contains the key "map" with the value of another object. This second object contains all role names as keys and the list of identifier of those zettel with this specific role as a value.

Similar, to list all tags used in the Zettelstore, send a HTTP GET request to the endpoint /q?q=|tags. If successful, the output is a JSON object:

# curl http://127.0.0.1:23123/q?q=|tags
{"map":{"#api":[:["00001012921000","00001012920800","00001012920522",...],"#authorization":["00001010040700","00001010040400",...],...,"#zettelstore":["00010000000000","00001014000000",...,"00001001000000"]}}

The JSON object only contains the key "map" with the value of another object. This second object contains all tags as keys and the list of identifier of those zettel with this tag as a value.

If you want only those tags that occur at least 100 times, use the endpoint /q?q=|MIN100+tags. You see from this that actions are separated by space characters.

There are two types of actions: parameters and aggregates. The following actions are supported:

MINn (parameter)
Emit only those values with at least n aggregated values. n must be a positive integer, MIN must be given in upper-case letters.
MAXn (parameter)
Emit only those values with at most n aggregated values. n must be a positive integer, MAX must be given in upper-case letters.
Any metadata key of type Word, WordSet, or TagSet (aggregates)
Emit an aggregate of the given metadata key. The key can be given in any letter case.

Only the first aggregate action will be executed.

If no valid aggregate action is given, the metadata of all selected zettel are returned.2

# curl http://127.0.0.1:23123/q
{"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 the keys "query" and "human" with a string value. Both will contain a textual description of the underlying query if you select only some zettel with a query expression. Without a selection, the values are the empty string. "query" returns the normalized query expression itself, while "human" is the normalized query expression to be read by humans.

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

{
  "query": "",
  "human": "",
  "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.

Note

This request (and similar others) 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 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
Query was successful.
204
Query was successful, but results in no content. Most likely, you specified no appropriate aggregator.
400
Request was not valid. There are several reasons for this. Maybe the access bearer token was not valid, or you forgot to specify a valid query.
  1. If authentication is enabled, you must include the a valid access token in the Authorization header ↩︎
  2. For this reason, a HTTP GET to the endpoint /j is an alias for the endpoint /q. ↩︎