> ## Documentation Index > Fetch the complete documentation index at: https://docs.gc.ai/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml PATCH /vaults/{id}/columns/{columnId} openapi: 3.0.3 info: title: GC AI External API version: 1.0.0 description: >- The GC AI External API allows programmatic access to GC AI's chat capabilities. It's designed for integration with workflow automation tools like Zapier, Make, n8n, or custom applications. ## Authentication All API requests must include an API key in the `Authorization` header: ``` Authorization: gcai_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx ``` API keys can be created in the GC AI app under **Settings → API**. ## Multi-turn Conversations Conversations can span multiple turns: pass the `chat_id` returned by a completion back on your next request to continue the same chat. See [Multi-turn Conversations](/api-reference/concepts/multi-turn). ## Current Limitations The following is not yet available via API: - **Interactive clarification**: the model cannot pause to ask the caller a follow-up question; the `askUserQuestions` tool is disabled on the API surface ## Usage Usage is tracked and viewable in the GC AI app under **Settings → API → View Usage**. ## Support For API support, contact [support@gc.ai](mailto:support@gc.ai) or reach out to your account representative. contact: email: support@gc.ai servers: - url: https://app.gc.ai/api/external/v1 description: Production server security: [] tags: - name: Async Jobs description: Poll the status and result of asynchronous API jobs - name: Chat description: AI chat completion endpoints - name: Chats description: Chat management, message history, and sharing endpoints - name: Contract Intelligence description: Vault discovery and document ingestion endpoints for Contract Intelligence - name: Files description: File upload and management endpoints - name: Folders description: Folder management endpoints - name: Playbooks description: Playbook review endpoints - name: Profiles description: Personal and company profile endpoints - name: Projects description: Project management endpoints - name: Skills description: Skill library management endpoints - name: Utility description: Health check and connectivity endpoints - name: Usage description: Usage and credit/billing reporting endpoints paths: /vaults/{id}/columns/{columnId}: patch: tags: - Contract Intelligence summary: Update a vault column description: >- 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. operationId: updateVaultColumn parameters: - schema: type: string format: uuid description: The vault ID required: true description: The vault ID name: id in: path - schema: type: string format: uuid description: >- The column ID from `GET /vaults/{id}/columns`. Built-in columns report `id: null` and cannot be addressed here. required: true description: >- The column ID from `GET /vaults/{id}/columns`. Built-in columns report `id: null` and cannot be addressed here. name: columnId in: path requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateVaultColumnRequest' responses: '200': description: The updated column content: application/json: schema: $ref: '#/components/schemas/VaultColumnUpdateResponse' '400': description: >- Invalid request body, an option list that is not 2 to 12 unique values, an `ai` column left with no instructions, a column GC AI manages, or a spreadsheet-owned column whose fill mode cannot change content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Missing or malformed API key content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: >- Contract Intelligence is not enabled for this account. Contact support to request access., or the caller cannot manage this vault's columns content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Vault or column not found, or access denied content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: >- The vault is archived. Restore it with `POST /vaults/{id}/restore` before changing it. content: application/json: schema: $ref: '#/components/schemas/Error' '422': description: >- Vault access is per-user and requires a user-scoped API key (u:gcai_...). content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: >- Rate limit exceeded. See [Rate Limits](/api-reference/concepts/rate-limits) for the tiers, limits, and how to back off. headers: Retry-After: schema: type: string description: Seconds to wait before retrying after a rate-limit block. example: '60' required: true description: Seconds to wait before retrying after a rate-limit block. RateLimit-Limit: schema: type: string description: Request quota for the applicable window. example: '3' required: true description: Request quota for the applicable window. RateLimit-Remaining: schema: type: string description: Requests remaining in the current window. example: '0' required: true description: Requests remaining in the current window. RateLimit-Reset: schema: type: string description: Seconds until the quota resets. example: '60' required: true description: Seconds until the quota resets. content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: Service temporarily unavailable headers: Retry-After: schema: type: string description: >- Seconds to wait before retrying after a transient service outage. example: '5' required: true description: >- Seconds to wait before retrying after a transient service outage. content: application/json: schema: $ref: '#/components/schemas/Error' security: - ApiKeyAuth: [] components: schemas: UpdateVaultColumnRequest: type: object properties: label: type: string minLength: 1 maxLength: 200 description: >- New column heading. The `field_key` does not follow a rename, so every value already extracted stays attached. instructions: type: string maxLength: 4000 description: New instructions. field_type: type: string enum: - text - date - date_range - enum - multi_enum - boolean - number - currency - percentage - duration - email - url - list - rich_text description: >- New value shape. Send `field_meta` in the same request when the new type needs a different option list. field_meta: oneOf: - type: object properties: type: type: string enum: - enum options: type: array items: type: string minLength: 1 maxLength: 200 description: >- The values this column can hold. Between 2 and 12, all different. example: - Renewal - New business - Amendment required: - type - options - type: object properties: type: type: string enum: - multi_enum options: type: array items: type: string minLength: 1 maxLength: 200 description: >- The values this column can hold. Between 2 and 12, all different. A document can carry more than one. required: - type - options - nullable: true description: >- New option list. Send `null` to clear it. Omit it to leave the current one in place. extraction_mode: type: string enum: - ai - manual description: >- New fill mode. A column a spreadsheet owns cannot move in or out of `import`, so those columns reject this field. sort_order: type: integer description: New placement weight. VaultColumnUpdateResponse: allOf: - $ref: '#/components/schemas/VaultColumnResponse' - type: object properties: auto_rescan: oneOf: - type: object properties: status: type: string enum: - queued queued: type: number description: >- Documents committed to the re-scan. Zero means no document held a value for this column, or every one that did was already queued. total_files: type: number description: >- Documents that hold a value for this column, including any already queued. required: - status - queued - total_files - type: object properties: status: type: string enum: - failed description: >- The column was saved and the re-scan could not be queued. Trigger a re-scan from the app when you want fresh values. required: - status - type: object properties: status: type: string enum: - deferred_to_sample run_id: type: string nullable: true description: >- The scan review this vault is waiting on. The re-scan runs when that review is approved. required: - status - run_id - type: object properties: status: type: string enum: - limit_reached used_today: type: number description: Re-analysis actions this vault has spent today. limit: type: number description: Re-analysis actions this vault gets per day. org_blocked: type: boolean description: >- True when re-analysis is turned off for the whole account, so waiting for tomorrow will not help. required: - status - used_today - limit - org_blocked - nullable: true description: >- 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. required: - auto_rescan Error: type: object properties: error: type: string description: Error message code: type: string description: >- Machine-readable error code present on some errors (e.g. `RATE_LIMITED`, `INSUFFICIENT_CREDITS`, `TRIAL_NOT_STARTED`, `BILLING_NOT_CONFIGURED`). Branch on this rather than the human-readable `error` string. message: type: string description: Additional error details details: type: object additionalProperties: nullable: true description: Validation error details (for 400 errors) required: - error VaultColumnResponse: type: object properties: id: type: string nullable: true format: uuid description: >- 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. field_key: type: string description: >- 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. example: renewalNotice label: type: string description: The column heading shown in the vault table example: Renewal notice instructions: type: string description: >- For an `ai` column, the prompt extraction reads each document with. For a `manual` or `import` column, a note to whoever reads the column. field_type: type: string enum: - text - date - date_range - enum - multi_enum - boolean - number - currency - percentage - duration - email - url - list - rich_text - party_list - related_agreement_list description: >- The shape of the values in this column. Built-in columns can report `party_list` and `related_agreement_list`, which you cannot set yourself. field_meta: oneOf: - type: object properties: type: type: string enum: - enum options: type: array items: type: string minLength: 1 maxLength: 200 description: The values extraction can assign to this column. legacy_options: type: array items: type: string minLength: 1 maxLength: 200 description: >- Values that documents extracted under an older version of this option list still hold. They stay readable and filterable, and extraction never assigns them again. required: - type - options - type: object properties: type: type: string enum: - multi_enum options: type: array items: type: string minLength: 1 maxLength: 200 description: The values extraction can assign to this column. required: - type - options - nullable: true description: >- The option list for an `enum` or `multi_enum` column. Null for every other type. extraction_mode: type: string enum: - ai - manual - import description: >- 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. kind: type: string enum: - built_in - system - custom description: >- 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. editable: type: boolean description: >- 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. sort_order: type: number nullable: true description: >- Placement weight for this column, or null for a built-in one. The table orders columns by `sort_order` first and creation time second. created_at: type: string nullable: true description: ISO 8601 creation timestamp, or null for a built-in column updated_at: type: string nullable: true description: ISO 8601 last-update timestamp, or null for a built-in column required: - id - field_key - label - instructions - field_type - field_meta - extraction_mode - kind - editable - sort_order - created_at - updated_at securitySchemes: ApiKeyAuth: type: apiKey in: header name: Authorization description: |- API key for authentication. Format: `gcai_xxxxxxxxx` Create API keys in the GC AI app under Settings → API. ````