---
title: "Change a field's name, type, width or options"
description: "Its id never changes: the id IS the column."
canonical: "https://gtable.app/docs/builder-api/fields/update"
updated: "2026-10-05"
---

# Change a field's name, type, width or options

`PATCH https://studio.gtable.app/v1/apps/{appId}/tables/{tableId}/fields/{fieldId}`

Its id never changes: the id IS the column.

`config` is merged into the field's existing settings, and is checked against the type it will have after this call. Its TYPE may change, and the values are converted in the same transaction, anything that reads as the new type is kept, anything that does not is emptied rather than guessed at. A type change can break an interface page, a view's filter or a permission condition written against the old type, so say what it will do before you propose one. Converting to or from a relation is refused: add the new field and delete the old one. Select options are replaced wholesale; keep an option's `id` to keep the rows that hold it, and a removed option leaves its old values in place.

Requires the `schema:write` scope. Operation `fields.update`. MCP tool `fields_update`. CLI, once published: `gtable fields update`.

## Path parameters

| Name      | Type   | Required | Description |
| --------- | ------ | -------- | ----------- |
| `appId`   | string | yes      |             |
| `tableId` | string | yes      |             |
| `fieldId` | string | yes      |             |

## Query parameters

| Name          | Type    | Required | Description |
| ------------- | ------- | -------- | ----------- |
| `acknowledge` | boolean | no       |             |

## Headers

| Name              | Type   | Required | Description                                                                                                                                                                                                                                                        |
| ----------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `Idempotency-Key` | string | no       | Any unique string. Sending the same key with the same request again returns the first response (marked `Idempotency-Replayed: true`) instead of running it twice. Reusing it for a different request is refused with 409. Kept for 24 hours. Up to 255 characters. |

## Request body

| Field    | Type                                                                                                                                                                                                                                                                                                                                                                     | Required | Description               |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | ------------------------- |
| `name`   | string                                                                                                                                                                                                                                                                                                                                                                   | no       | Up to 120 characters.     |
| `type`   | "text" or "longtext" or "email" or "url" or "phone" or "json" or "number" or "currency" or "percent" or "rating" or "duration" or "select" or "multiselect" or "checkbox" or "user" or "attachment" or "date" or "recordId" or "autonumber" or "createdTime" or "createdBy" or "modifiedTime" or "modifiedBy" or "link" or "lookup" or "rollup" or "formula" or "button" | no       |                           |
| `width`  | integer                                                                                                                                                                                                                                                                                                                                                                  | no       | At least 60. At most 900. |
| `config` | object                                                                                                                                                                                                                                                                                                                                                                   | no       |                           |