API: Retrieve context of an existing zettel

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

The context of an origin zettel consists of those zettel that are somehow connected to the origin zettel. Direct connections of an origin zettel to other zettel are visible via metadata values, such as backward, forward or other values with type identifier or set of identifier.

The context is defined by a direction, a cost, and a limit:

The search for the context of a zettel stops at the home zettel. This zettel is connected to all other zettel. If it is included, the context would become too big and therefore unusable.

To retrieve the context of an existing zettel, use the endpoint /x/{ID}1.

# curl 'http://127.0.0.1:23123/x/00001012053800?limit=3&dir=forward&cost=5'
{"id": "00001012053800","meta": {...},"rights":62,"list":[{"id": "00001012921000","meta": {...},"rights":62},{"id": "00001012920800","meta": {...},"rights":62},{"id": "00010000000000","meta": {...},"rights":62}]}

Formatted, this translates into:2

{
  "id": "00001012053800",
  "meta": {...},
  "rights": 62,
  "list": [
    {
      "id": "00001012921000",
      "meta": {...},
      "rights":62
    },
    {
      "id": "00001012920800",
      "meta": {...},
      "rights":62
    },
    {
      "id": "00010000000000",
      "meta": {...},
      "rights":62
    }
  ]
}

Keys

The following top-level JSON keys are returned:

id

The zettel identifier for which the context was requested.

meta:

The metadata of the zettel, encoded as a JSON object.

rights

An integer number that describes the access rights for the given zettel.

list

A list of JSON objects with keys id, meta, and rights that contains the zettel of the context.

HTTP Status codes

200

Retrieval was successful, the body contains an appropriate JSON object.

400

Request was not valid.

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.

  1. Mnemonic: conteXt ↩︎
  2. Metadata (key meta) are hidden to make the overall structure easier to read. ↩︎