# renameLabel

Mutation

Rename one label across the whole workspace; asynchronous — every creator carrying it follows the new spelling.

Available to agents as MCP tool `renameLabel` — see [Write tools](/api/v2/docs/mcp/write-tools#rename-label).

## Arguments

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `labelName` | `String!` | Yes | — | The label to rename, exactly as the `labels` query returns it. Matching ignores case and surrounding whitespace. Not length-limited: a label longer than the creation limit stays renameable. A blank name is rejected. |
| `newLabelName` | `String!` | Yes | — | The new spelling, stored as typed (surrounding whitespace is stripped). At most 100 characters. A different label that already has this name refuses the rename — there is no implicit merge; use `mergeLabels` to fold one label into another. A respelling of the same label (`VIP` → `vip`) is allowed. A blank name is rejected. |

## Returns

| Name | Type | Description |
| --- | --- | --- |
| `operationId` | `ID` | The `rename_label` operation that runs this rename; poll it with `operation(id:)`. Null when userErrors is non-empty. A label operation tracks progress with `status`, `total` and `processed` only — its record-derived counts are always 0 and its item-id lists always empty. |
| `scheduled` | `Boolean!` | True when the rename is scheduled; `operationId` is then set. False when userErrors is non-empty. The rename is asynchronous. |
| `userErrors` | [`[UserError!]!`](/api/v2/docs/types/user-error) | Errors that refused the request, on the input at fault: a blank or over-long name, a label that does not exist, is being deleted or is already being renamed, a new name that another label already has, or no user to attribute the rename to. Empty on success. |

## Examples

### Rename a label

Schedule the workspace-wide rename of a label; every creator carrying it follows the new name.

```graphql
mutation RenameLabelDefault($labelName: String!, $newLabelName: String!) {
  renameLabel(labelName: $labelName, newLabelName: $newLabelName) {
    scheduled
    operationId
    userErrors {
      field
      message
    }
  }
}
```

Variables:

```json
{
  "labelName": "Plant Parents",
  "newLabelName": "Plant Lovers"
}
```

Response — HTTP 200:

```json
{
  "data": {
    "renameLabel": {
      "scheduled": true,
      "operationId": "fb352d7d-aafd-544a-93f8-eed5bf50ad39",
      "userErrors": []
    }
  }
}
```