curl --request PATCH \
--url https://app.gc.ai/api/external/v1/vaults/{id}/columns/{columnId} \
--header 'Authorization: <api-key>' \
--header 'Content-Type: application/json' \
--data '
{
"label": "<string>",
"instructions": "<string>",
"field_meta": {
"type": "enum",
"options": [
"Renewal",
"New business",
"Amendment"
]
},
"sort_order": 123
}
'import requests
url = "https://app.gc.ai/api/external/v1/vaults/{id}/columns/{columnId}"
payload = {
"label": "<string>",
"instructions": "<string>",
"field_meta": {
"type": "enum",
"options": ["Renewal", "New business", "Amendment"]
},
"sort_order": 123
}
headers = {
"Authorization": "<api-key>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
label: '<string>',
instructions: '<string>',
field_meta: {type: 'enum', options: ['Renewal', 'New business', 'Amendment']},
sort_order: 123
})
};
fetch('https://app.gc.ai/api/external/v1/vaults/{id}/columns/{columnId}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://app.gc.ai/api/external/v1/vaults/{id}/columns/{columnId}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PATCH",
CURLOPT_POSTFIELDS => json_encode([
'label' => '<string>',
'instructions' => '<string>',
'field_meta' => [
'type' => 'enum',
'options' => [
'Renewal',
'New business',
'Amendment'
]
],
'sort_order' => 123
]),
CURLOPT_HTTPHEADER => [
"Authorization: <api-key>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://app.gc.ai/api/external/v1/vaults/{id}/columns/{columnId}"
payload := strings.NewReader("{\n \"label\": \"<string>\",\n \"instructions\": \"<string>\",\n \"field_meta\": {\n \"type\": \"enum\",\n \"options\": [\n \"Renewal\",\n \"New business\",\n \"Amendment\"\n ]\n },\n \"sort_order\": 123\n}")
req, _ := http.NewRequest("PATCH", url, payload)
req.Header.Add("Authorization", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.patch("https://app.gc.ai/api/external/v1/vaults/{id}/columns/{columnId}")
.header("Authorization", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"label\": \"<string>\",\n \"instructions\": \"<string>\",\n \"field_meta\": {\n \"type\": \"enum\",\n \"options\": [\n \"Renewal\",\n \"New business\",\n \"Amendment\"\n ]\n },\n \"sort_order\": 123\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://app.gc.ai/api/external/v1/vaults/{id}/columns/{columnId}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Patch.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"label\": \"<string>\",\n \"instructions\": \"<string>\",\n \"field_meta\": {\n \"type\": \"enum\",\n \"options\": [\n \"Renewal\",\n \"New business\",\n \"Amendment\"\n ]\n },\n \"sort_order\": 123\n}"
response = http.request(request)
puts response.read_body{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"field_key": "renewalNotice",
"label": "Renewal notice",
"instructions": "<string>",
"field_type": "text",
"field_meta": {
"type": "enum",
"options": [
"<string>"
],
"legacy_options": [
"<string>"
]
},
"extraction_mode": "ai",
"kind": "built_in",
"editable": true,
"sort_order": 123,
"created_at": "<string>",
"updated_at": "<string>",
"auto_rescan": {
"status": "queued",
"queued": 123,
"total_files": 123
}
}{
"error": "<string>",
"code": "<string>",
"message": "<string>",
"details": {}
}{
"error": "<string>",
"code": "<string>",
"message": "<string>",
"details": {}
}{
"error": "<string>",
"code": "<string>",
"message": "<string>",
"details": {}
}{
"error": "<string>",
"code": "<string>",
"message": "<string>",
"details": {}
}{
"error": "<string>",
"code": "<string>",
"message": "<string>",
"details": {}
}{
"error": "<string>",
"code": "<string>",
"message": "<string>",
"details": {}
}{
"error": "<string>",
"code": "<string>",
"message": "<string>",
"details": {}
}{
"error": "<string>",
"code": "<string>",
"message": "<string>",
"details": {}
}{
"error": "<string>",
"code": "<string>",
"message": "<string>",
"details": {}
}Update a Vault Column
Change a column’s label, instructions, value type, option list, fill mode, or placement. Send only the fields you want to change; everything you leave out keeps its current value. field_key is not one of them: it is frozen at creation so the values already extracted stay attached.
Changing the value type of an ai column makes the values already extracted for it stale, because they were stored as text read under the old type. GC AI queues a re-scan of the documents that hold one and reports it in auto_rescan. The column is saved whatever auto_rescan says, so treat that field as news about the re-scan and not as an error. When the vault is waiting on a scan review, the re-scan waits for that approval instead of starting now.
Only a custom column accepts changes. A system column (Document Name, Document Status, Document Title) returns 400, and so does a column a connected spreadsheet owns if you try to move it in or out of import.
Requires the editor or owner role in the vault and the organization-level permission to manage vaults.
Requires a user-scoped API key (u:gcai_...). A vault is shared with named people, so an organization-scoped key has no identity to resolve vault access with.
curl --request PATCH \
--url https://app.gc.ai/api/external/v1/vaults/{id}/columns/{columnId} \
--header 'Authorization: <api-key>' \
--header 'Content-Type: application/json' \
--data '
{
"label": "<string>",
"instructions": "<string>",
"field_meta": {
"type": "enum",
"options": [
"Renewal",
"New business",
"Amendment"
]
},
"sort_order": 123
}
'import requests
url = "https://app.gc.ai/api/external/v1/vaults/{id}/columns/{columnId}"
payload = {
"label": "<string>",
"instructions": "<string>",
"field_meta": {
"type": "enum",
"options": ["Renewal", "New business", "Amendment"]
},
"sort_order": 123
}
headers = {
"Authorization": "<api-key>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
label: '<string>',
instructions: '<string>',
field_meta: {type: 'enum', options: ['Renewal', 'New business', 'Amendment']},
sort_order: 123
})
};
fetch('https://app.gc.ai/api/external/v1/vaults/{id}/columns/{columnId}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://app.gc.ai/api/external/v1/vaults/{id}/columns/{columnId}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PATCH",
CURLOPT_POSTFIELDS => json_encode([
'label' => '<string>',
'instructions' => '<string>',
'field_meta' => [
'type' => 'enum',
'options' => [
'Renewal',
'New business',
'Amendment'
]
],
'sort_order' => 123
]),
CURLOPT_HTTPHEADER => [
"Authorization: <api-key>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://app.gc.ai/api/external/v1/vaults/{id}/columns/{columnId}"
payload := strings.NewReader("{\n \"label\": \"<string>\",\n \"instructions\": \"<string>\",\n \"field_meta\": {\n \"type\": \"enum\",\n \"options\": [\n \"Renewal\",\n \"New business\",\n \"Amendment\"\n ]\n },\n \"sort_order\": 123\n}")
req, _ := http.NewRequest("PATCH", url, payload)
req.Header.Add("Authorization", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.patch("https://app.gc.ai/api/external/v1/vaults/{id}/columns/{columnId}")
.header("Authorization", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"label\": \"<string>\",\n \"instructions\": \"<string>\",\n \"field_meta\": {\n \"type\": \"enum\",\n \"options\": [\n \"Renewal\",\n \"New business\",\n \"Amendment\"\n ]\n },\n \"sort_order\": 123\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://app.gc.ai/api/external/v1/vaults/{id}/columns/{columnId}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Patch.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"label\": \"<string>\",\n \"instructions\": \"<string>\",\n \"field_meta\": {\n \"type\": \"enum\",\n \"options\": [\n \"Renewal\",\n \"New business\",\n \"Amendment\"\n ]\n },\n \"sort_order\": 123\n}"
response = http.request(request)
puts response.read_body{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"field_key": "renewalNotice",
"label": "Renewal notice",
"instructions": "<string>",
"field_type": "text",
"field_meta": {
"type": "enum",
"options": [
"<string>"
],
"legacy_options": [
"<string>"
]
},
"extraction_mode": "ai",
"kind": "built_in",
"editable": true,
"sort_order": 123,
"created_at": "<string>",
"updated_at": "<string>",
"auto_rescan": {
"status": "queued",
"queued": 123,
"total_files": 123
}
}{
"error": "<string>",
"code": "<string>",
"message": "<string>",
"details": {}
}{
"error": "<string>",
"code": "<string>",
"message": "<string>",
"details": {}
}{
"error": "<string>",
"code": "<string>",
"message": "<string>",
"details": {}
}{
"error": "<string>",
"code": "<string>",
"message": "<string>",
"details": {}
}{
"error": "<string>",
"code": "<string>",
"message": "<string>",
"details": {}
}{
"error": "<string>",
"code": "<string>",
"message": "<string>",
"details": {}
}{
"error": "<string>",
"code": "<string>",
"message": "<string>",
"details": {}
}{
"error": "<string>",
"code": "<string>",
"message": "<string>",
"details": {}
}{
"error": "<string>",
"code": "<string>",
"message": "<string>",
"details": {}
}Authorizations
API key for authentication. Format: gcai_xxxxxxxxx
Create API keys in the GC AI app under Settings → API.
Path Parameters
The vault ID
The column ID from GET /vaults/{id}/columns. Built-in columns report id: null and cannot be addressed here.
Body
New column heading. The field_key does not follow a rename, so every value already extracted stays attached.
1 - 200New instructions.
4000New value shape. Send field_meta in the same request when the new type needs a different option list.
text, date, date_range, enum, multi_enum, boolean, number, currency, percentage, duration, email, url, list, rich_text New option list. Send null to clear it. Omit it to leave the current one in place.
Show child attributes
Show child attributes
New fill mode. A column a spreadsheet owns cannot move in or out of import, so those columns reject this field.
ai, manual New placement weight.
Response
The updated column
Unique column identifier, or null for a built-in column. A built-in column has no row of its own in this vault, so it has no ID and cannot be changed or deleted.
The stable key extracted values are stored under. It is set once, when the column is created, and never changes, so renaming the column keeps every value already extracted for it.
"renewalNotice"
The column heading shown in the vault table
"Renewal notice"
For an ai column, the prompt extraction reads each document with. For a manual or import column, a note to whoever reads the column.
The shape of the values in this column. Built-in columns can report party_list and related_agreement_list, which you cannot set yourself.
text, date, date_range, enum, multi_enum, boolean, number, currency, percentage, duration, email, url, list, rich_text, party_list, related_agreement_list The option list for an enum or multi_enum column. Null for every other type.
Show child attributes
Show child attributes
How the column gets filled. ai: extraction reads it out of each document. manual: a person types it and no scan ever touches it. import: values come from a connected spreadsheet, which owns the column. You can create ai and manual columns; an import column is created by connecting a spreadsheet in the app.
ai, manual, import What this column is. built_in: merged into every vault by GC AI, with no ID and no way to change it. system: owned by this vault but managed by GC AI (Document Name, Document Status, Document Title), so it has an ID but rejects every change and every delete. custom: yours, and the only kind PATCH and DELETE accept.
built_in, system, custom True when this column can be changed with PATCH /vaults/{id}/columns/{columnId}. Built-in and system columns report false: GC AI owns their name, type, options, and prompt. One exception, on both surfaces: sort_order is list position rather than identity, so it can be set on any column that has an ID.
Placement weight for this column, or null for a built-in one. The table orders columns by sort_order first and creation time second.
ISO 8601 creation timestamp, or null for a built-in column
ISO 8601 last-update timestamp, or null for a built-in column
What happened to the re-scan a type change triggered, or null when the change needed none. A non-null value never means the update failed.
Show child attributes
Show child attributes
Was this page helpful?