Skip to main content

Transforms

Transforms reshape an action's data after it is fetched. Declare a post_transforms: block — an array of transform functions applied in order.

actions:
- name: AddAttribute
http:
url: https://jsonplaceholder.typicode.com/todos/10
post_transforms:
- extract_value: ".body"
- add_attribute:
env: production

The filter transform reuses the assertion vocabulary to keep only matching elements. Every transform and its fields are listed below.

Transform

FieldTypeDescription
rename_attributesMap<string, string> (nullable)Rename attributes (keys) within a JSON object. Maps old attribute names to new attribute names. Example ↓
remove_attributesArray<string> (nullable)Remove specified attributes from the JSON object. Provides an array of attribute names to exclude. Example ↓
keep_attributesArray<string> (nullable)Keep only specified attributes, removing all others. Provides an allowlist of attribute names. Example ↓
move_attributesMap<string, string> (nullable)Move attributes from one location to another. Maps source path to destination path. Example ↓
rename_keysMap<string, string> (nullable)Rename keys at the root level of a JSON object. Maps old key names to new key names. Example ↓
remove_keysArray<string> (nullable)Remove specified keys from the JSON object. Provides an array of key names to exclude. Example ↓
bcryptBcryptTransform (nullable)Hash a value using bcrypt for secure password storage. Supports custom cost factor. Example ↓
add_attributeobject (nullable)Add new attributes to the JSON object with specified key-value pairs. Example ↓
return_rownumber (nullable)Return a specific row from a result set by index (0-based). Example ↓
extract_valuestring (nullable)Extract a single value from the response using a JSON path. Example ↓
extract_arrayTransformExtractArray (nullable)Extract an array from a JSON response with options for flattening and deduplication. Example ↓
extract_with_json_pathstring (nullable)Extract data using a JSON path expression. Shortcut for simple extractions. Example ↓
extract_with_jqstring (nullable)Extract data using jq filter syntax for complex JSON transformations. Example ↓
extract_with_regexExtractWithRegex (nullable)Extract values from a string using regex capture groups. Example ↓
extract_with_cssExtractWithCss (nullable)Extract values from an HTML document with a CSS selector — the counterpart to extract_with_jq for pages instead of JSON. Point value at the HTML string (usually an http… Example ↓
compressTransformCompress (nullable)Compress a value with gzip/zlib/deflate and store it as text. CPU-bound, so on AirPipe-hosted infrastructure it is gated by the compression entitlement per organization; a… Example ↓
decompressTransformDecompress (nullable)The inverse of compress. Same entitlement and the same byte bound, which here bounds the OUTPUT too — a small archive that expands past the limit is refused rather than expanded. Example ↓
totpTransformTotp (nullable)Generate the current RFC 6238 one-time password for a shared secret — for calling an upstream API that demands a second factor. The verifying counterpart is the is_valid_totpExample ↓
parse_xlsxTransformParseXlsx (nullable)Read a spreadsheet (.xlsx/.xls/.ods) that arrived as base64 into rows. CPU- and memory-bound on a file somebody else produced, so on AirPipe-hosted infrastructure it is… Example ↓
parse_pdfTransformParsePdf (nullable)Extract the text of a PDF that arrived as base64. Same entitlement and byte bound as parse_xlsx. Example ↓
add_jwtAddJWT (nullable)Add a JWT token to the response with configurable expiration and payload. Example ↓
read_jwtReadJWT (nullable)Read and decode a JWT token to extract its payload. Example ↓
numericsArray<string> (nullable)Convert string fields to numeric types. Provides an array of field names to convert. Example ↓
group_byArray<string> (nullable)Group array elements by specified fields. Used for aggregation operations. Example ↓
generate_passwordTransformPasswordGen (nullable)Generate a secure random password with customizable options for length and character types. Example ↓
replace_valuesTransformReplaceValues (nullable)Replace values in strings or arrays with support for regex and multiple replacements. Example ↓
flattenTransformFlatten (nullable)Flatten nested objects into a single level with configurable key separators. Example ↓
b64_decodestring (nullable)Decode a Base64-encoded string. Example ↓
b64_decode_as_jsonstring (nullable)Decode a Base64-encoded string and parse as JSON. Example ↓
b64_encodeTransformConfig (nullable)Encode a value to Base64. Can be a direct string or custom transform configuration. Example ↓
yaml_to_jsonTransformConfig (nullable)Convert YAML-formatted string to JSON. Example ↓
parse_csvTransformConfig (nullable)Parse a CSV string into an array of header-keyed row objects. Point it at the CSV string in the action's data (e.g. the raw request body via input: a|raw_body|, or fetched text). Example ↓
to_csvTransformConfig (nullable)Serialize an array of row objects INTO a CSV string — the inverse of parse_csv. Columns come from the first row's keys and every later row is written in that same order. Pair… Example ↓
nested_transformsMap<string, Array<Transform>> (nullable)Apply nested transforms to specific keys. Maps keys to arrays of transform operations. Example ↓
mathTransformMath (nullable)Perform mathematical operations on numeric values with expressions. target is OPTIONAL and defaults to the root object — omit it to read and write fields at the top level (as… Example ↓
aggregateTransformAggregate (nullable)Reduce a JSON array to a summary (sum/avg/min/max/count), optionally grouped. Example ↓
filterTransformFilterSearch (nullable)Filter array elements based on specified conditions. Example ↓
generate_bytesGenerateBytes (nullable)Generate random bytes with specified length. Example ↓
encrypt_valueEncryptValue (nullable)Encrypt a value using AES-256-GCM encryption. Example ↓
hmacHmacSign (nullable)Compute an HMAC of a message — the signing counterpart to the is_valid_hmac assertion. Use it to sign webhook deliveries you SEND, then interpolate the result into a header. Example ↓
decrypt_valueDecryptValue (nullable)Decrypt a value previously sealed with encrypt_value (AES-256-GCM). Example ↓
s3_generate_presigned_urlS3GeneratePresignedURL (nullable)Generate a presigned URL for S3 file access. Example ↓
encode_uriTransformConfig (nullable)URI-encode an entire URL string. Example ↓
encode_uri_componentTransformConfig (nullable)URI-encode a single component of a URL. Example ↓
decode_uriTransformConfig (nullable)URI-decode an encoded URL string. Example ↓
decode_uri_componentTransformConfig (nullable)URI-decode a single component of an encoded URL. Example ↓
generate_slugTransformConfig (nullable)Generate a URL-friendly slug from a string. Example ↓

Field examples

rename_attributes

Rename attributes (keys) within a JSON object. Maps old attribute names to new attribute names.

Example

rename_attributes:
old_name: new_name

remove_attributes

Remove specified attributes from the JSON object. Provides an array of attribute names to exclude.

Example

remove_attributes:
- password
- secret

keep_attributes

Keep only specified attributes, removing all others. Provides an allowlist of attribute names.

Example

keep_attributes:
- id
- name
- email

move_attributes

Move attributes from one location to another. Maps source path to destination path.

Example

move_attributes:
user.name: name
user.email: email

rename_keys

Rename keys at the root level of a JSON object. Maps old key names to new key names.

Example

rename_keys:
user_id: userId
created_at: createdAt

remove_keys

Remove specified keys from the JSON object. Provides an array of key names to exclude.

Example

remove_keys:
- token
- internal_id

bcrypt

Hash a value using bcrypt for secure password storage. Supports custom cost factor.

Example

bcrypt:
key: password # Path to the password value (e.g., .password)
cost: 12 # Cost factor (higher = slower but more secure)

add_attribute

Add new attributes to the JSON object with specified key-value pairs.

Example

add_attribute:
user_uuid: a|uuid| # Auto-generate UUID
verification_token: a|uuid| # Auto-generate token

return_row

Return a specific row from a result set by index (0-based).

Example

return_row: 0    # Return the first row

extract_value

Extract a single value from the response using a JSON path.

Example

extract_value: .user.id

extract_array

Extract an array from a JSON response with options for flattening and deduplication.

Example

extract_array:
from: .items # Path to the array
paths: # Paths to extract from each element
- id
- name
flatten: true # Flatten nested arrays
dedupe: true # Remove duplicates

extract_with_json_path

Extract data using a JSON path expression. Shortcut for simple extractions.

Example

extract_with_json_path: .[0]  # Get first element

extract_with_jq

Extract data using jq filter syntax for complex JSON transformations.

Example

extract_with_jq: '.users | map({id, name})'

extract_with_regex

Extract values from a string using regex capture groups.

Example

extract_with_regex:
value: .phone # Path to source string
expr: "(\\d{3})-(\\d{3})-(\\d{4})" # Regex with capture groups
keys: # Names for captured groups
- area
- prefix
- number

extract_with_css

Extract values from an HTML document with a CSS selector — the counterpart to extract_with_jq for pages instead of JSON. Point value at the HTML string (usually an http action's body) and the result lands under key.

Example

extract_with_css:
value: "" # the whole action data is the HTML string
selector: "article h2.title"
key: titles
all: true # every match, not just the first

compress

Compress a value with gzip/zlib/deflate and store it as text.

CPU-bound, so on AirPipe-hosted infrastructure it is gated by the compression entitlement per organization; a self-hosted agent spends its own CPU and is on by default. Both are additionally bounded by max_compress_bytes (8 MiB default).

Example

compress:
value: rows # what to compress ("" = the whole action data)
key: packed
algorithm: gzip # gzip (default) | zlib | deflate
encoding: base64 # base64 (default) | base64url | hex

decompress

The inverse of compress. Same entitlement and the same byte bound, which here bounds the OUTPUT too — a small archive that expands past the limit is refused rather than expanded.

Example

decompress:
value: packed
key: rows
algorithm: gzip
json: true # parse the result as JSON instead of keeping it as text

totp

Generate the current RFC 6238 one-time password for a shared secret — for calling an upstream API that demands a second factor. The verifying counterpart is the is_valid_totp assertion.

Example

totp:
secret: a|secret::vendor::totp_seed|
key: otp

parse_xlsx

Read a spreadsheet (.xlsx/.xls/.ods) that arrived as base64 into rows.

CPU- and memory-bound on a file somebody else produced, so on AirPipe-hosted infrastructure it is gated by the document_parsing entitlement and bounded by max_document_bytes (16 MiB default). Self-hosted is on by default.

Example

parse_xlsx:
value: file # base64 of the workbook
key: rows
sheet: Orders # optional — the first sheet otherwise
limit: 5000 # optional row cap (default 10000)

parse_pdf

Extract the text of a PDF that arrived as base64. Same entitlement and byte bound as parse_xlsx.

Example

parse_pdf:
value: file
key: text

add_jwt

Add a JWT token to the response with configurable expiration and payload.

Example

add_jwt:
key: jwt # Output key for the token
secret: a|var::JWT_SECRET| # JWT secret (use encrypted variable)
exp: 1d # Expiration STRING (e.g., 1h, 1d, 30m)
data: # Claims — three accepted forms:
sub: a|FetchUser::id| # • object: explicit claim -> value (most flexible)
email: a|FetchUser::email|
# data: [id, email] # • array: copy these fields from this action's input
# data: all # • "all": copy every input field

Security: Store JWT secrets as encrypted AirPipe variables:

secret: a|var::ENCRYPTED_JWT_SECRET|

read_jwt

Read and decode a JWT token to extract its payload.

Example

read_jwt:
key: user_data # Output key for decoded payload
token: .auth_header # Path to JWT token

numerics

Convert string fields to numeric types. Provides an array of field names to convert.

Example

numerics:
- age
- price
- quantity

group_by

Group array elements by specified fields. Used for aggregation operations.

Example

group_by:
- category
- region

generate_password

Generate a secure random password with customizable options for length and character types.

Example

generate_password:
key: temp_password # Output key for generated password
length: 16 # Password length
numbers: true # Include numbers (0-9)
lowercase_letters: true # Include lowercase (a-z)
uppercase_letters: true # Include uppercase (A-Z)
symbols: true # Include symbols (!@#$)

replace_values

Replace values in strings or arrays with support for regex and multiple replacements.

Example - Simple string replacement

replace_values:
target_value: .message # Path to target value
find_str: old # String to find
new_str: new # Replacement string

Example - Multiple value replacement

replace_values:
target_value: .status
values: # Array of values to process
- pending
- approved
find_str: _
new_str: " "

flatten

Flatten nested objects into a single level with configurable key separators.

Example

flatten:
key_separator: . # Separator for nested keys
prefix: user # Optional prefix for all keys
target: .data # Path to nested object

b64_decode

Decode a Base64-encoded string.

Example

b64_decode: .encoded_data    # Path to Base64 string

b64_decode_as_json

Decode a Base64-encoded string and parse as JSON.

Example

b64_decode_as_json: .payload    # Path to Base64-encoded JSON

b64_encode

Encode a value to Base64. Can be a direct string or custom transform configuration.

Example

b64_encode: .data    # Path to value to encode

yaml_to_json

Convert YAML-formatted string to JSON.

Example

yaml_to_json: .yaml_data    # Path to YAML string

parse_csv

Parse a CSV string into an array of header-keyed row objects. Point it at the CSV string in the action's data (e.g. the raw request body via input: a|raw_body|, or fetched text).

Example

parse_csv: "$"                       # replace the root CSV string with the rows
# parse_csv: { json_path: "$", key: rows } # put the rows array under `rows`

to_csv

Serialize an array of row objects INTO a CSV string — the inverse of parse_csv. Columns come from the first row's keys and every later row is written in that same order. Pair it with an email attachment (encoding: utf8) to send a report.

Example

to_csv: "$"                              # replace the root rows array with a CSV string
# to_csv: { json_path: "$", key: csv } # put the CSV string under `csv`

nested_transforms

Apply nested transforms to specific keys. Maps keys to arrays of transform operations.

Example

nested_transforms:
items: # Transform each item in the 'items' array
- remove_keys:
- internal_id
- rename_keys:
user_name: name

math

Perform mathematical operations on numeric values with expressions.

target is OPTIONAL and defaults to the root object — omit it to read and write fields at the top level (as below). Inside an expression, reference a field with the target. prefix; that prefix is the substitution token and is resolved against the target object, so a bare price is left as-is and will not resolve. Set target: only to scope to a nested object (e.g. .data).

Example

math:
expressions: # key = output field name
total: target.price * target.quantity
discounted: target.total * 0.9
decimal_places: 2 # optional: round to 2 places (half away from zero)
to_string: true # optional: render as text, keeping trailing zeros

aggregate

Reduce a JSON array to a summary (sum/avg/min/max/count), optionally grouped.

Example

aggregate: { over: body.data, sum: [amount], count: true, group_by: [status] }

filter

Filter array elements based on specified conditions.

Example

filter:
target: .users # Path to array to filter
conditions:
.age:
is_greater_than: 18
.status:
is_equal_to: "active"

generate_bytes

Generate random bytes with specified length.

Example

generate_bytes:
key: api_key # Output key for generated bytes
length: 32 # Number of bytes to generate

encrypt_value

Encrypt a value using AES-256-GCM encryption.

Example

encrypt_value:
key: encrypted_data # Output key for encrypted result
data: .sensitive_value # Path to value to encrypt
secret_key: a|var::ENCRYPTED_ENCRYPTION_KEY| # Encryption key (must be encrypted variable)
nonce: a|var::NONCE| # Unique nonce (must be encrypted variable)

Security:

  • Store encryption keys as encrypted AirPipe variables
  • Use unique nonce values for each encryption operation

hmac

Compute an HMAC of a message — the signing counterpart to the is_valid_hmac assertion. Use it to sign webhook deliveries you SEND, then interpolate the result into a header.

Example

hmac:
key: signature # Output key for the digest
data: a|BuildPayload::body| # The message to sign
secret: a|Subscriber::secret| # Per-recipient signing secret
algorithm: sha256 # sha1 | sha256 (default) | sha512
encoding: hex # hex (default) | base64

A digest produced here verifies under is_valid_hmac with the same algorithm and encoding.

decrypt_value

Decrypt a value previously sealed with encrypt_value (AES-256-GCM).

Example

decrypt_value:
key: plaintext # Output key for the decrypted string
value: a|Row::enc_value| # Base64 ciphertext (the encrypt_value `.value`)
nonce: a|Row::enc_nonce| # Base64 nonce (the encrypt_value `.nonce`)
tag: a|Row::enc_tag| # Base64 GCM tag (the encrypt_value `.tag`)
secret_key: a|env::AIRPIPE_ENC_SECRET_KEY| # Same key used to encrypt

Security: decryption is authenticated — a wrong key, altered ciphertext, or altered tag fails loudly rather than returning garbage.

s3_generate_presigned_url

Generate a presigned URL for S3 file access.

Example

s3_generate_presigned_url:
bucket: my-bucket # S3 bucket name
file_key: documents/file.pdf # Path to file in bucket
expiration_secs: 3600 # URL expiration (seconds)
endpoint: https://s3.amazonaws.com # S3 endpoint
region: us-east-1 # AWS region
access_key_id: a|var::ENCRYPTED_AWS_ACCESS_KEY| # AWS access key (encrypted variable)
secret_access_key: a|var::ENCRYPTED_AWS_SECRET| # AWS secret key (encrypted variable)
key: presigned_url # Output key for generated URL
json_path: .file_url # Optional: Extract from response

Security: Store AWS credentials securely as encrypted AirPipe variables:

access_key_id: a|var::ENCRYPTED_AWS_ACCESS_KEY|
secret_access_key: a|var::ENCRYPTED_AWS_SECRET|

encode_uri

URI-encode an entire URL string.

Example

encode_uri: .url    # Path to URL to encode

encode_uri_component

URI-encode a single component of a URL.

Example

encode_uri_component: .search_query    # Path to component to encode

decode_uri

URI-decode an encoded URL string.

Example

decode_uri: .encoded_url    # Path to encoded URL

decode_uri_component

URI-decode a single component of an encoded URL.

Example

decode_uri_component: .encoded_param    # Path to encoded component

generate_slug

Generate a URL-friendly slug from a string.

Example

generate_slug: .title    # Path to text to convert to slug

TransformConfig

One of:

CustomTransform

FieldTypeDescription
keystringRequired.
json_pathstringRequired.

TransformExtractArray

FieldTypeDescription
fromstring (nullable)The JSON path to the starting array
pathsArray<string> (nullable)Array of JSON paths to extract values from each element
flattenboolean (nullable)Whether to flatten nested arrays
dedupeboolean (nullable)Whether to remove duplicates

TransformFilterSearch

FieldTypeDescription
targetstring (nullable)
conditionsMap<string, Test>Required. Conditions to filter items in the array.

TransformFlatten

FieldTypeDescription
key_separatorstringRequired.
prefixstring (nullable)
targetstring (nullable)

TransformMath

FieldTypeDescription
targetstring (nullable)Where to apply the expressions (JSONPath). Defaults to the root.
expressionsMap<string, string>Required. Output field name → expression, e.g. total: target.price * target.quantity.
to_stringboolean (nullable)Render the result as a string. With decimal_places this keeps trailing zeros — 10.00 rather than 10 — which is what a money value usually wants to look like.
decimal_placesnumber (nullable)Round the result to this many decimal places, half away from zero (2.125 → 2.13). The value stays a NUMBER unless to_string (or eval_type: string) asks for text.
eval_typeMathEvalType (nullable)Force the result type. decimal_places applies to any float result on its own; this is for coercing (e.g. int to truncate).

TransformPasswordGen

FieldTypeDescription
keystringRequired.
lengthnumberRequired.
numbersboolean (nullable)
lowercase_lettersboolean (nullable)
uppercase_lettersboolean (nullable)
symbolsboolean (nullable)
spacesboolean (nullable)
exclude_similar_charactersboolean (nullable)
strictboolean (nullable)

TransformReplaceValues

FieldTypeDescription
target_valuestringRequired.
target_keystring (nullable)
find_strstring (nullable)
new_strstring (nullable)
regexstring (nullable)
valuesArray<string> (nullable)

BcryptTransform

FieldTypeDescription
keystring (nullable)
valuestring (nullable)
jqstring (nullable)
costnumber (nullable)

AddJWT

FieldTypeDescription
keystringRequired.
secretstringRequired.
expstring (nullable)
dataanyRequired.

ReadJWT

FieldTypeDescription
keystringRequired.
tokenstringRequired.

EncryptValue

FieldTypeDescription
keystringRequired.
datastringRequired.
secret_keystringRequired.
noncestringRequired.

DecryptValue

FieldTypeDescription
keystringRequired.
valuestringRequired.
noncestringRequired.
tagstringRequired.
secret_keystringRequired.

GenerateBytes

FieldTypeDescription
keystringRequired.
lengthnumberRequired.

ExtractWithRegex

FieldTypeDescription
valuestringRequired.
exprstringRequired.
keysArray<string>Required.

ExtractWithCss

FieldTypeDescription
valuestringRequired. JSON path to the HTML string within the action's data. An empty string means the data IS the HTML — which is what an http action fetching a page gives you.
selectorstringRequired. A CSS selector, the same grammar a browser takes: article h2.title, a[href^="/docs"], tr td:nth-child(2).
keystringRequired. Key to write the result under.
attributestring (nullable)Take this attribute from each matched element instead of its text. An element that matches but lacks the attribute contributes null, so an all: true result stays…
htmlboolean (nullable)Take each matched element's inner HTML instead of its text. Mutually exclusive with attribute.
allboolean (nullable)Every match, as an array. Without it, the first match alone — or null when the selector matched nothing.

TransformCompress

FieldTypeDescription
valuestringRequired. JSON path to the value to compress. An empty string means the whole action data. A non-string value is compressed as its compact JSON.
keystringRequired. Key to write the compressed text under.
algorithmstring (nullable)gzip (default), zlib, or deflate (raw, no wrapper).
encodingstring (nullable)How to render the compressed bytes as text: base64 (default), base64url, hex.
levelnumber (nullable)0 (store) to 9 (smallest). Default 6 — zlib's own default, and the point past which more CPU stops buying much.

TransformDecompress

FieldTypeDescription
valuestringRequired. JSON path to the compressed text.
keystringRequired. Key to write the decompressed value under.
algorithmstring (nullable)gzip (default), zlib, or deflate. Must match how it was compressed.
encodingstring (nullable)How the text is encoded: base64 (default), base64url, hex. The two base64 alphabets are accepted interchangeably, so a value that lost its padding crossing a URL still…
jsonboolean (nullable)Parse the result as JSON instead of keeping it as text.

TransformParseXlsx

FieldTypeDescription
valuestringRequired. JSON path to the base64 of the workbook. An empty string means the whole action data.
keystringRequired. Key to write the rows under.
sheetstring (nullable)Sheet name. The first sheet when omitted.
headersboolean (nullable)Treat the first row as column names, so each later row becomes an object. Default true. Set false when the first row is data and every row should be an array.
limitnumber (nullable)Rows to read. Default 10000 — a sheet can hold a million, and returning all of them as JSON is never what a caller wanted.
encodingstring (nullable)How the file is encoded: base64 (default) or base64url.

TransformParsePdf

FieldTypeDescription
valuestringRequired. JSON path to the base64 of the PDF. An empty string means the whole action data.
keystringRequired. Key to write the extracted text under.
encodingstring (nullable)How the file is encoded: base64 (default) or base64url.

TransformTotp

FieldTypeDescription
secretstringRequired. The shared secret, base32 by default.
keystringRequired. Key to write the generated code under.
encodingstring (nullable)How secret is written: base32 (default), hex, or ascii.
digitsnumber (nullable)Code length, 6 (default) to 10.
periodnumber (nullable)Seconds per step. Default 30.
algorithmstring (nullable)sha1 (default), sha256, sha512.

S3GeneratePresignedURL

FieldTypeDescription
operationstring (nullable)get (default) mints a time-limited DOWNLOAD link; put mints a time-limited UPLOAD target the client can PUT straight to, so the file never transits AirPipe.
bucketstringRequired.
file_keystringRequired.
expiration_secsnumberRequired.
endpointstringRequired.
regionstringRequired.
access_key_idstringRequired.
secret_access_keystringRequired.
keystringRequired.
json_pathstring (nullable)

MathEvalType

Type: string — one of: int, float, string, bool

DataType

One of:

  • text | json | csv | xml
  • string — Newline-delimited JSON — one complete JSON document per line. Its own variant rather than a fallback when JSON parsing fails, because guessing would mean a genuinely truncated…