API: Retrieve context of an existing zettel

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:

• Direction: connections are directed. For example, the metadata value of backward lists all zettel that link to the current zettel, while forward list all zettel to which the current zettel links to. When you are only interested in one direction, set the parameter dir either to the value backward or forward. All other values, including a missing value, is interpreted as both.
• Cost: a normal direct connection has cost 5, an indirect connection is the length of the shortest path between two zettel. The cost of a folgezettel or a precursor zettel is just 1, the cost of successor zettel and predecessor zettel are 2. You should limit the cost by using the parameter cost. Its default value is 17. A value of 0 does disable any cost check.
• Limit: to set an upper bound for the returned context, you should use the parameter limit. Its default value is 200. A value of 0 disables does not limit the number of elements returned.

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}¹.

# 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:²

{
  "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. ↩︎