Skip to main content
POST
/
api
/
lists
/
{id}
/
columns
/
{colId}
/
generate
Generate values for a list column
curl --request POST \
  --url https://app.puffle.ai/api/lists/{id}/columns/{colId}/generate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "rowIds": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ]
}
'
{ "success": true, "taskId": "run_a1b2c3d4e5f6", "rowCount": 42 }

​
Overview

Trigger AI-powered cell generation for a targeted subset of rows on an AI column. Each cell is upserted to status: pending before the sheet-ai-enrich Trigger.dev task is dispatched. Use this to regenerate stale values, fill gaps for rows added after the column was created, or retry failed cells. Only valid on AI columns (those with source: web or source: reasoning). Columns with source: profile return 400 — they are not AI-driven. Credits are previewed (not deducted) before dispatch, then charged only if the task is successfully queued. The credit action is CUSTOM_ENRICHMENT_WEB for web-source columns and CUSTOM_ENRICHMENT_AI otherwise.

​
AI agent notes

Preconditions:
  • The column must be an AI column (source: web or source: reasoning).
  • rowIds must be a non-empty array of existing row UUIDs on this list. Unknown row IDs are silently skipped by the enrichment task (cell upsert without a matching row is a no-op at render time).
Credit contract:
  • 402 is returned before any cell writes, so a failed credit check leaves state untouched.
  • 500 from the Trigger dispatch path does not deduct credits either.
  • Credits are only deducted after a successful dispatch.
Polling for results:
  • Poll the cell row (or use Supabase Realtime on list_cells) until status is terminal (completed or failed).
  • The response includes taskId (the Trigger.dev run ID) — useful for correlating logs in Puffle Seer.

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 and must be a web/reasoning (AI) column — non-AI (source: profile) columns cannot generate values.

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

Request payload for triggering AI-powered cell generation on a subset of rows.

​
rowIds
string<uuid>[]
required

IDs of rows for which to (re)generate the column value. Each row gets its cell upserted to pending status before the enrichment task runs.

Minimum array length: 1
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)$

Response

Task dispatched. Poll the cell row via list_cells (or the preview-cells endpoint for preview columns) for results.

​
success
enum<boolean>
required
Available options:
true
​
taskId
string
required

Trigger.dev run identifier for the dispatched sheet-ai-enrich task.

​
rowCount
integer
required

Number of rows queued for generation.

Required range: 0 < x <= 9007199254740991