Skip to main content
PATCH
/
api
/
lists
/
{id}
/
columns
/
{colId}
Update a list column
curl --request PATCH \
  --url https://app.puffle.ai/api/lists/{id}/columns/{colId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "isFilter": true,
  "position": 4503599627370495,
  "isPreview": false
}
'
{
  "column": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "listId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "<string>",
    "prompt": "<string>",
    "responseType": "auto",
    "source": "profile",
    "subject": "person",
    "isFilter": true,
    "position": 4503599627370495,
    "schema": {
      "type": "text",
      "format": "plain",
      "currency": "USD",
      "scale": "none",
      "textFormat": "short",
      "options": [
        "<string>"
      ],
      "itemType": "text",
      "maxItems": 4503599627370495,
      "linkType": "generic"
    },
    "enrichmentType": "work_email",
    "config": {},
    "createdAt": "2023-11-07T05:31:56Z",
    "isPreview": true,
    "category": "built-in",
    "builtInKey": "<string>"
  }
}

​
Overview

Custom enrichment columns (AI, web, profile, FullEnrich contact, hiring status, news, LinkedIn posts, site crawl, website overview) are updated through the generic list-column PATCH endpoint. There is no dedicated custom-enrichment-columns route — the column type is determined by enrichmentType when the column is created, and subsequent updates flow through the same handler as every other list column. Supported updates:
  • name — rename the column.
  • isFilter — toggle the filter flag.
  • position — reorder the column.
  • isPreview: false — promote a preview column (created on the first 3 rows) to a full column. The server backfills pending cells for every remaining row and dispatches the appropriate enrichment task.
Preview promotion is credit-gated: if the caller can’t afford the backfill, the request fails with 402 before any writes.
Custom enrichment columns do not have a separate API. All updates — including promoting a preview, renaming, or repositioning — flow through PATCH /api/lists/{id}/columns/{colId}. If you are coming from an older doc or SDK that references PATCH /api/custom-enrichment-columns/{id}, replace it with this endpoint.

​
AI agent notes

Preview -> full promotion. Passing isPreview: false triggers two side effects:
  1. Pending cells are inserted for every row not already covered by the 3-row preview (skipping duplicates).
  2. The appropriate Trigger.dev enrichment task is dispatched for those new rows. For AI / web columns, this is sheet-ai-enrich batched in groups of 100.
Non-fatal trigger failures. If the enrichment dispatch fails, the column is still promoted and the user can retry via POST /api/lists/{id}/columns/{colId}/generate (for AI columns). Credits are only deducted after successful dispatch.Empty body is a 400. At least one updatable field must be present.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

​
id
string<uuid>
required

List UUID. Must be owned by the caller.

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
​
colId
string<uuid>
required

Column UUID. Must belong to the list at path param id.

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

Body

application/json

At least one field must be present, or the server returns 400. Passing isPreview: false promotes a preview column and triggers backfill enrichment for all remaining rows.

​
name
string

Rename the column.

​
isFilter
boolean

Toggle whether this column is treated as a filter.

​
position
integer

Reorder the column — 0 is the leftmost non-built-in slot.

Required range: 0 <= x <= 9007199254740991
​
isPreview
enum<boolean>

Set to false to promote a preview column into a permanent column. Promotion backfills cells for the remaining rows (those not covered by the initial 3-row preview) and dispatches the enrichment task for them. Pre-flight credit check applies; returns 402 if the caller can't afford the backfill.

Available options:
false

Response

Column updated. When promoting a preview, enrichment for the remaining rows is dispatched asynchronously.

​
column
object
required

A column on a list.