<!-- BusyBot node reference — https://busybot.net/tools/rename-keys/ -->

> Node: Rename Keys (`rename_keys`) · Action · v1
> Category: Core Nodes · Credentials: none
> Updated: 2026-08-16

# Rename Keys

> Rename item field names

## Overview

The Rename Keys tool renames properties/fields in item JSON data. It supports two modes: (1) Direct key mapping with dot-notation for nested paths (e.g., level1.level2.oldKey → level1.level2.newKey), and (2) Regex-based bulk renaming with depth control, case-insensitive matching, and capture group replacement.

**Category:** Core Nodes  
**Tool Name:** `rename_keys`  
**Version:** 1

**Appearance:** Icon: `lucide-Replace` | Color: `#772244`

## Node Type

**Action** — processes input items and produces output

## Input / Output

| Direction | Port(s) |
|-----------|--------|
| Input | `Input` |
| Output | `Output`, `Error` |

## Credentials

This tool does not require any credentials.

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Keys | `fixedCollection` | No | `{}` | Adds a key which should be renamed. Accepts multiple entries, applied in the order you list them. |
| — Current Key Name | `string` | No | — | The current name of the key. Supports dot-notation for nested paths (e.g., "level1.level2.currentKey"). |
| — New Key Name | `string` | No | — | The new name for the key. Supports dot-notation for nested paths (e.g., "level1.level2.newKey"). |
| Additional Options | `collection` | No | `{}` | Bulk renaming by pattern, applied after the direct renames above. |
| — Regex | `fixedCollection` | No | `{}` | Adds a regular expression for bulk key renaming. Accepts multiple entries. |
| — — Regular Expression | `string` | No | — | Regex to match the key name. |
| — — Replace With | `string` | No | — | The replacement string. Supports regex captures ($1, $2, etc.). |
| — — Options | `collection` | No | `{}` | Matching settings for this one expression. |
| — — — Case Insensitive | `boolean` | No | `false` | Whether to use case insensitive match. |
| — — — Max Depth | `number` | No | `-1` | Maximum depth to replace keys (-1 for unlimited, 0 for top level only). |
| Max Concurrency | `number` | No | `10` | Maximum number of items to process concurrently. |

## Output Data

One output item per input item, with the same values under new names. The item is copied and rewritten, so nothing else changes: values, types and nesting are untouched, and binary data is forwarded.

Renaming runs in two passes:

1. **Keys** — each Current Key Name is looked up (dot-notation walks into nested objects), removed, and written back at New Key Name. An entry is skipped when either name is empty, when both names are identical, or when the field is not present on the item — a missing field is never an error.
2. **Regex** — every entry in Additional Options → Regex is applied to the key names themselves. A key that matches is replaced using the expression, so `^temp_(.+)$` with `final_$1` turns `temp_total` into `final_total`. Matching is case-sensitive unless Case Insensitive is on, and Max Depth limits how far into nested objects the rename descends (`0` = top level only, `-1` = the whole item). Array indices are never renamed, but the objects inside arrays are still visited.

Because both passes rewrite key names, downstream expressions must use the new names, e.g. `{{ $json.first_name }}`.

## Usage Examples

- Rename "firstName" to "first_name" using direct mapping
- Use regex to strip prefixes from all field names
- Rename nested fields using dot-notation paths

## Example Configuration

Rename two fields:

```json
{
  "type": "rename_keys",
  "parameters": {
    "maxConcurrency": 5,
    "keys": {
      "key": [
        {
          "currentKey": "email_address",
          "newKey": "email"
        },
        {
          "currentKey": "phone_number",
          "newKey": "phone"
        }
      ]
    }
  }
}
```

Rename a nested field with dot-notation:

```json
{
  "type": "rename_keys",
  "parameters": {
    "keys": {
      "key": [
        {
          "currentKey": "user.profile.displayName",
          "newKey": "user.profile.name"
        }
      ]
    }
  }
}
```

Strip a prefix from every matching key, two levels deep:

```json
{
  "type": "rename_keys",
  "parameters": {
    "additionalOptions": {
      "regexReplacement": {
        "replacements": [
          {
            "searchRegex": "^temp_(.+)$",
            "replaceRegex": "final_$1",
            "options": {
              "caseInsensitive": true,
              "depth": 2
            }
          }
        ]
      }
    }
  }
}
```

Combine a direct rename with a bulk pattern:

```json
{
  "type": "rename_keys",
  "parameters": {
    "maxConcurrency": 10,
    "keys": {
      "key": [
        {
          "currentKey": "id",
          "newKey": "recordId"
        }
      ]
    },
    "additionalOptions": {
      "regexReplacement": {
        "replacements": [
          {
            "searchRegex": "^temp_(.+)$",
            "replaceRegex": "$1",
            "options": {
              "caseInsensitive": true,
              "depth": 3
            }
          }
        ]
      }
    }
  }
}
```

### Error Handling

| Mode | Behavior |
|------|----------|
| **stop** | Halts workflow on first error |
| **continue** | Skips failed items, passes successful ones through |
| **errorPort** | Routes failed items to Error output port |

## Tips

Renames item field names using direct key mapping or regex patterns with dot-notation support.

### Behavior notes

- **Direct renames run before regex renames.** A regex written against the original key name will not match if a Keys entry already renamed that field.
- **A rename that lands on an existing key overwrites it.** Check for collisions before renaming several fields onto similar names.
- **Dot-notation is the default.** A key that genuinely contains a dot in its name has to be reached with a regex instead, since the direct mapping treats the dot as a path separator.