New API response format

Versions 0.16.0 (beta) and 0.17.0 represent the introduction of a new API response format for the Taffrail API.

This is entirely opt-in right now. Some details are below.


In V1 (anything prior to 0.16.0), the API responds with a single advice[] array containing the stack of "display nodes" in the order our Engine sees them.

In V2, the API relies on this same "display node" collection, but the API returns new subsets of the data instead of a singular advice[] array that needs to be filtered client-side.

Replaced advice[] with:

  • advice[] - collection of "regular" advice (basically any Advice node without a type tag specified)
  • assumptions[] - collection of Advice nodes tagged as assumption type
  • currentFocus{input request} - current location where API is stuck, i.e., the last unanswered question. If all questions are answered, this field disappears.
  • examples[] - collection of Advice nodes tagged as example type
  • inputRequests[] - collection of Input Request nodes
    • Each item now has two additional properties:
      • index (int) - literally the index of the item in the array
      • backlink{} - the id, name, and value of the variable linked to the input request. This is currently looked up every time client-side.
  • opengraph{} - object containing open graph data for link previews, search engines, etc. The data is sourced from the first Advice node (the primary recommendation/main heading)
  • sources[] - combined list of all AdviceSet and Input Request and Advice reference documents, de-duplicated

Overhauled Sources (referenceDocuments[])

  • Added fileId property to all types
  • For any non-link or non-file types, no changes
  • For files:
    • Removed body if NULL
    • Add sizeFormatted using the Numeral library
    • Add displayUrl, e.g., View file (pdf), 1.2mb which helps with consistency when building lists of links when some are files
  • For links:
    • Removed size
    • Removed versionId
    • Changed contentType from text/plain to text/x-uri
    • Added url_isCanonical if the OG scraper found one
    • Added displayUrl which is the URL without the protocol and host prefix


  • Remove audienceType (root level), it is no longer in use

HTML rendering

  • Any Markdown table elements will automatically have class="taffrail-table" added to the markup
  • Any Markdown blockquote elements will have class="taffrail-blockquote" added to the markup