Advice Content Types

The Taffrail API communicates in JSON. Every request must include an Accept header with the desired MIME type.

If you are not calling the Advice endpoint, send Accept: application/json.

The API always returns JSON, but the advice content inside it can be formatted as:

📘

A note on the response body

All but a few endpoints return a response body. Unless stated otherwise, the response body is in JSON format. Blank fields are omitted rather than being included with a null value. All timestamps are returned in UTC time, following the ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ.

Plain text

Plain text is the default. Use the +text modifier on the Accept header:

  Accept: application/vnd.taffrail.json+text

Example response:

{
  "headline": "Use a Roth IRA when single and your income is below $146,000"
}

HTML

👍

Recommended for most integrations

Most API clients use the HTML content type for its interactive chip and Backlink support.

Use the +html modifier on the Accept header. The plain-text field is always returned alongside a new [fieldName]_html field.

 Accept: application/vnd.taffrail.json+html

Example of Advice using this header:

{
  "headline": "Use a Roth when single and your income is below $146,000",
  "headline_html": "<h1 id=\"taffrail-use-a-roth-when-single-and-your-income-is-below-146000\" data-tf=\"5wYgjI4DyxtIjeRuCXNtP\">Use a Roth when <taffrail-var data-variable-name=\"Tax_Filing_Status\" data-variable-id=\"kxJJOeGun3weVjA74lKtk\" data-variable-type=\"Freetext\" data-variable-raw-value=\"single\">single</taffrail-var> and your income is below <taffrail-var data-variable-name=\"IRS_Limit_Roth_Single_Income_Low\" data-variable-id=\"8laeFmYB4eTtHX-AxmnaZ\" data-variable-type=\"Number\" data-variable-format=\"$0,0\" data-variable-raw-value=\"146000\">$146,000</taffrail-var></h1>\n"
}

Your renderer outputs the HTML as-is and attaches interface events that surface the Backlink (the hyperlink referencing the originating question) through the chip UI. For details on chips, see the Taffrail style guide and the demo below.

📘

Backlinks

A Backlink links a Variable in Advice text to the assumption (or originating question) where the user can modify the input.

Read more about Backlinks.

HTML without hyperlinks

This variant returns the same HTML but strips the Backlink hyperlinks. Use it for tearsheets, printed handouts, or PDF generation where interactive links would not survive.

Use the +htmlnolinks modifier on the Accept header. The plain-text field is always returned alongside a new [fieldName]_html field.

 Accept: application/vnd.taffrail.json+htmlnolinks

Taffrail Variables are still rendered as Web Components in the response, but without the surrounding <a> element. The <taffrail-var> carries data-backlink-required="true" so you can style the Backlink in its static state.

{
  "headline": "Use a Roth when single and your income is below $146,000",
  "headline_html": "<h1 id=\"taffrail-use-a-roth-when-single-and-your-income-is-below-146000\" data-tf=\"5wYgjI4DyxtIjeRuCXNtP\">Use a Roth when <taffrail-var data-variable-name=\"Tax_Filing_Status\" data-variable-id=\"kxJJOeGun3weVjA74lKtk\" data-variable-type=\"Freetext\" data-variable-raw-value=\"single\">single<\/taffrail-var> and your income is below <taffrail-var data-variable-name=\"IRS_Limit_Roth_Single_Income_Low\" data-variable-id=\"8laeFmYB4eTtHX-AxmnaZ\" data-variable-type=\"Number\" data-variable-format=\"$0,0\" data-variable-raw-value=\"146000\">$146,000<\/taffrail-var><\/h1>\n"
}

Markdown

Markdown syntax support may be available in a future release.

Raw

The raw format returns advice content with variable references unresolved (e.g. {{Tax_Filing_Status}} rather than single). Use the +raw modifier on the Accept header.

❗️

For debugging and custom parsing only

Do not use the raw format in production unless you are building a custom interface that resolves variables on the client.

  Accept: application/vnd.taffrail.json+raw

Example response:

{
  "headline": "# Use a Roth when {{Tax_Filing_Status}} and your income is below {{IRS_Limit_Roth_Single_Income_Low}}"
}