Fields

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

Its id never changes: the id IS the column.

PATCH/v1/apps/{appId}/tables/{tableId}/fields/{fieldId}

Request

curl --request PATCH \
  --url 'https://studio.gtable.app/v1/apps/<appId>/tables/<tableId>/fields/<fieldId>' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "<string>",
  "type": "text",
  "width": 123,
  "config": {}
}'

import json
import requests

url = "https://studio.gtable.app/v1/apps/<appId>/tables/<tableId>/fields/<fieldId>"
headers = {
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
}
payload = json.loads("{\"name\":\"<string>\",\"type\":\"text\",\"width\":123,\"config\":{}}")

response = requests.request("PATCH", url, headers=headers, json=payload)
print(response.json())

const response = await fetch("https://studio.gtable.app/v1/apps/<appId>/tables/<tableId>/fields/<fieldId>", {
  method: "PATCH",
  headers: {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "name": "<string>",
    "type": "text",
    "width": 123,
    "config": {}
  }),
});

const data = await response.json();
console.log(data);

<?php
$client = curl_init();

curl_setopt($client, CURLOPT_URL, "https://studio.gtable.app/v1/apps/<appId>/tables/<tableId>/fields/<fieldId>");
curl_setopt($client, CURLOPT_CUSTOMREQUEST, "PATCH");
curl_setopt($client, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
]);
curl_setopt($client, CURLOPT_POSTFIELDS, "{\"name\":\"<string>\",\"type\":\"text\",\"width\":123,\"config\":{}}");
curl_setopt($client, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($client);
curl_close($client);
echo $response;

package main

import (
  "bytes"
  "fmt"
  "io"
  "net/http"
)

func main() {
  req, _ := http.NewRequest("PATCH", "https://studio.gtable.app/v1/apps/<appId>/tables/<tableId>/fields/<fieldId>", bytes.NewBuffer([]byte("{\"name\":\"<string>\",\"type\":\"text\",\"width\":123,\"config\":{}}")))
  req.Header.Set("Authorization", "Bearer <token>")
  req.Header.Set("Content-Type", "application/json")
  res, _ := http.DefaultClient.Do(req)
  defer res.Body.Close()
  data, _ := io.ReadAll(res.Body)
  fmt.Println(string(data))
}

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

var request = HttpRequest.newBuilder(URI.create("https://studio.gtable.app/v1/apps/<appId>/tables/<tableId>/fields/<fieldId>"))
    .header("Authorization", "Bearer <token>")
    .header("Content-Type", "application/json")
    .method("PATCH", HttpRequest.BodyPublishers.ofString("{\"name\":\"<string>\",\"type\":\"text\",\"width\":123,\"config\":{}}"))
    .build();

var response = HttpClient.newHttpClient().send(
    request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

require 'net/http'
require 'json'

uri = URI("https://studio.gtable.app/v1/apps/<appId>/tables/<tableId>/fields/<fieldId>")
request = Net::HTTP::Patch.new(uri)
request["Authorization"] = "Bearer <token>"
request["Content-Type"] = "application/json"
request.body = "{\"name\":\"<string>\",\"type\":\"text\",\"width\":123,\"config\":{}}"

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http|
  http.request(request)
end

puts response.body

application/json

{
  "data": {
    "id": "<string>",
    "name": "<string>",
    "width": 123,
    "type": "<string>",
    "config": {}
  }
}

{
  "error": {
    "code": "not_found",
    "message": "<string>",
    "details": {}
  }
}

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
`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

Response

application/json

Success

dataobjectrequired

Show child attributes

idstringrequired

namestringrequired

widthinteger

typestringrequired

configobjectrequired

curl --request PATCH \ --url 'https://studio.gtable.app/v1/apps/<appId>/tables/<tableId>/fields/<fieldId>' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "name": "<string>", "type": "text", "width": 123, "config": {} }'

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

Path parameters

Query parameters

Headers

Request body

Response

Use these docs with your AI tools

Query these docs via MCP

Query these docs over HTTP

Read these docs as Markdown