API: List plain text titles of all or some zettel

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

To list the plain text titles of all zettel just send a HTTP GET request to the endpoint /z1.

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

The query parameter q allows you to specify query expressions for a full-text search of all zettel content and/or restricting the search according to specific metadata, similar to endpoint /q to query zettel.

You are allowed to specify this query parameter more than once.

This parameter loosely resembles the search form of the web user interface.

For example, if you want to retrieve all zettel that contain the string API in its title, your request will be:

# curl 'http://127.0.0.1:23123/z?q=title%3AAPI'
00001012921000 API: JSON structure of an access token
00001012920500 Formats available by the API
00001012920000 Endpoints used by the API
...

An implicit precondition is that the zettel must contain the given metadata key. For a metadata key like title, which has a default value, this precondition should always be true. But the situation is different for a key like url. Both curl 'http://localhost:23123/z?q=url%3A' and curl 'http://localhost:23123/z?q=url%3A!' may result in an empty list.

Alternatively, you also can use the endpoint /z for a simpler result format. The first example translates to:

# curl 'http://127.0.0.1:23123/z?q=title%3AAPI'
00001012921000 API: JSON structure of an access token
00001012920500 Formats available by the API
00001012920000 Endpoints used by the API
...

Other output formats

If you want to get the list of metadata of all or some zettel in JSON format, use endpoint /q to query the list of zettel.

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 ↩︎