Response Transformation

A Jinja2 template applied to the upstream API response body before it is returned to the widget — letting you filter, reshape, or reformat responses on the server.

The template applies to the incoming response body only — it has no effect on the outgoing request. If the field is blank, the original upstream response is returned as-is.

Fields

Response Body

A Jinja2 template applied to the upstream API response. The template has access to the full response body, status code, and headers.

If blank or not set, the upstream response is passed through unchanged.

Response Content-Type

Overrides the Content-Type header on the response returned to the widget. If blank, the upstream API's original Content-Type is preserved.

Set this when your template changes the output format — for example, if the upstream API returns XML but your template produces JSON, set this to application/json.

Variables

TIP

For the full list of variables, filters, and functions available in templates, see Template Variables.

Three variables are specific to response templates:

• response.body — the upstream response body as a decoded UTF-8 string. If the response is not valid UTF-8 (e.g. binary content), this is None.
• response.status_code — the HTTP status code from the upstream API (integer).
• response.headers — the response headers from the upstream API as a dictionary. Header names are lowercase (e.g., content-type, not Content-Type).

Also available: user.* fields, tenant_id, now(), and all filters (from_json, json_encode, tojson, base64_encode, base64_decode).

get_secret() is not available here

Response templates do not have access to {{ get_secret() }}. Response output is returned to the browser, so secrets are excluded to prevent accidental leakage. Use headers or query parameters if you need to include secret values in the request to the upstream API. See Secrets for details.

jwt_encode() is not available here

Response templates do not have access to jwt_encode(). JWTs are used for authenticating outgoing requests, not for shaping response data.

body_text and body_raw are not available

{{ body_text }} and {{ body_raw }} are not available in response templates. These variables represent the incoming request body — use response.body to access the upstream API's response.

Examples

Extract specific fields from a large response:

{% set data = response.body | from_json %}
{
  "id": {{ data.id }},
  "name": "{{ data.name }}",
  "status": "{{ data.status }}"
}

Handle errors based on status code:

{% if response.status_code == 200 %}
{% set data = response.body | from_json %}
{ "result": {{ data | tojson }} }
{% else %}
{ "error": true, "status": {{ response.status_code }} }
{% endif %}

Include user context in the response:

{% set data = response.body | from_json %}
{
  "tenant": "{{ tenant_id }}",
  "requested_by": "{{ user.email }}",
  "results": {{ data.results | tojson }}
}

Do not output from_json directly

Never use {{ response.body | from_json }} as the entire response template — it produces HTML-escaped Python notation, not valid JSON. Leave the field blank to forward the response as-is, or use {% set %} to extract specific fields. See Template Variables — Behavioral notes for details.

Error handling

If the response template fails to render (e.g. syntax error, type mismatch), the connector returns HTTP 422 with failure_scope set to "Configuration (response template rendering)". This is separate from request template errors, which use "Configuration (template rendering)".

The response template runs on all upstream status codes — including 4xx and 5xx errors. This means you can normalize error responses from different APIs into a consistent format for your widget.

Next Steps

• Calling from Widget Code — Use connectors with response transformation in your widget
• Filtering Sensitive Data — Use response templates to keep hidden records out of the browser
• Template Variables — Full reference for Jinja2 variables, filters, and functions
• Configuration — Overview of all connector fields
• Request Transformation — Reshape outgoing request bodies with Jinja2