Skip to main content

Response Transformations

Response transformations let you post-process endpoint responses before variable extraction and dependency mapping. This is useful for reshaping API responses, normalizing nested structures, or filtering irrelevant data.

Overview​

Transformations are a chain of operations applied in sequence to the endpoint's response data. Each step takes the output of the previous step as its input. The transformed result is what gets used for variable extraction and downstream mappings.

Available Transformations​

Flatten​

Flatten nested objects into a single level with dot-separated keys.

FieldDescription
Source pathJSON path to the object to flatten (leave empty for root)
SeparatorCharacter between nested keys (default: .)
Max depthHow many levels deep to flatten

Before:

{ "user": { "profile": { "name": "Alice", "age": 30 } } }

After (separator: .):

{ "user.profile.name": "Alice", "user.profile.age": 30 }

Rename​

Rename fields in the response.

FieldDescription
Field mappingOld name → new name pairs

Before:

{ "usr_id": "123", "usr_name": "Alice" }

After (rename usr_id→userId, usr_name→userName):

{ "userId": "123", "userName": "Alice" }

Filter​

Filter array items by a condition.

FieldDescription
Array pathPath to the array to filter
FieldWhich field on each item to check
Operatorequals, not_equals, contains, starts_with, ends_with, exists
ValueValue to compare against

Before:

[
  { "type": "page", "id": "p1" },
  { "type": "database", "id": "d1" },
  { "type": "page", "id": "p2" }
]

After (filter: type equals "page"):

[
  { "type": "page", "id": "p1" },
  { "type": "page", "id": "p2" }
]

Map​

Extract specific fields from each item in an array.

FieldDescription
Array pathPath to the array
FieldsComma-separated list of field names to keep

Before:

[
  { "id": "1", "name": "Alice", "email": "a@x.com", "metadata": {...} },
  { "id": "2", "name": "Bob", "email": "b@x.com", "metadata": {...} }
]

After (map fields: id, name):

[
  { "id": "1", "name": "Alice" },
  { "id": "2", "name": "Bob" }
]

Pick​

Keep only specified top-level fields, removing everything else.

FieldDescription
FieldsComma-separated list of fields to keep

Before:

{ "data": [...], "meta": {...}, "links": {...}, "debug": {...} }

After (pick: data, meta):

{ "data": [...], "meta": {...} }

Omit​

Remove specified top-level fields, keeping everything else.

FieldDescription
FieldsComma-separated list of fields to remove

Before:

{ "data": [...], "meta": {...}, "links": {...}, "debug": {...} }

After (omit: links, debug):

{ "data": [...], "meta": {...} }

Combine​

Combine multiple fields into a single field.

FieldDescription
Source fieldsFields to combine
Target fieldName of the combined field
Modeconcat (join strings), object (merge into an object), array (collect into an array)
SeparatorFor concat mode, character between values

Before (concat mode, separator: " "):

{ "firstName": "Alice", "lastName": "Smith" }

After (combine firstName+lastName → fullName):

{ "firstName": "Alice", "lastName": "Smith", "fullName": "Alice Smith" }

Using the Transformation Editor​

Adding Transformations​

  1. Open an endpoint's configuration
  2. Find the Response Transformations section
  3. Click Add Transformation
  4. Select the transformation type
  5. Configure the operation parameters

Ordering​

Transformations execute in order from top to bottom. Use the drag handles to reorder steps. The output of each step becomes the input for the next.

Enable/Disable​

Each transformation step has a toggle to enable or disable it without removing it. This is useful for testing — disable a step to see how the chain behaves without it.

Live Preview​

The editor shows a side-by-side preview:

  • Original: The raw endpoint response
  • Transformed: The result after all enabled transformations

This updates in real-time as you modify the chain, making it easy to verify your transformations produce the expected output.

When to Use Transformations​

  • Nested responses: Flatten deeply nested structures for easier variable extraction
  • Inconsistent field names: Rename fields to a consistent schema
  • Mixed-type arrays: Filter array items to only the types you need
  • Large responses: Pick/omit to reduce data before extraction
  • Composite values: Combine fields that need to be used together

Best Practices​

  1. Keep chains short — Fewer steps are easier to understand and debug
  2. Use the preview — Verify each step produces expected output
  3. Filter early — Put filter operations before map/pick to reduce data early
  4. Document purpose — Use clear transformation names so others understand why each step exists

Troubleshooting​

"Transformation produces empty result"​

  • Check that the source path/array path matches the actual response structure
  • Verify filter conditions aren't too restrictive
  • Use the live preview to identify which step removes the data

"Field names don't match after rename"​

  • Rename is case-sensitive — verify exact field names
  • Rename applies to top-level fields only, not nested paths

"Transform chain order matters"​

  • A filter that runs before a flatten will operate on different data than one running after
  • Reorder steps and use the preview to verify