data-tables

n8n DataTables Admin

n8nac has no commands for DataTable lifecycle (n8nac datatable does not exist as of 2.2.x). The only way to create/seed/drop tables outside the n8n UI is the public REST API. This skill encapsulates the exact endpoints + the curl patterns the PreToolUse hook is configured to allow.

Carve-out scope: Only URLs containing /api/v1/data-tables are allowed past the curl-block. Anything else (workflows, credentials, executions) still routes through n8nac — do not try to reach those via curl from here.

Prerequisites

.env must define:

N8N_API_URL=https://your-instance.example.com
N8N_API_KEY=<key from n8n UI → Settings → API>

Source it at the top of every shell invocation:

set -a; source .env; set +a
BASE="${N8N_API_URL%/}/api/v1/data-tables"
AUTH=(-H "X-N8N-API-KEY: $N8N_API_KEY" -H "Accept: application/json")

API Reference (n8n public API v1)

Routes confirmed against packages/cli/src/public-api/v1/handlers/data-tables/ (master).

Tables

Method	Path	Purpose
GET	/data-tables	List tables (query: limit, cursor, projectId, name)
POST	/data-tables	Create table — body: { name, projectId, columns: [{name, type}] }
GET	/data-tables/:id	Get table with columns
PATCH	/data-tables/:id	Rename / update meta — body: { name }
DELETE	/data-tables/:id	Drop table (cascades rows)

Columns

Method	Path	Purpose
GET	/data-tables/:id/columns	List columns
POST	/data-tables/:id/columns	Add column — body: { name, type, index? } (type: string, number, boolean, date)
DELETE	/data-tables/:id/columns/:colId	Drop column
PATCH	/data-tables/:id/columns/:colId	Rename / reindex — body: { name?, index? }

Rows

Method	Path	Purpose
GET	/data-tables/:id/rows	Query rows — query: offset, limit, filter, sortBy, search
POST	/data-tables/:id/rows	Append rows — body: { data: [{col1: val, col2: val}, ...], returnType? }
PUT	/data-tables/:id/rows	Upsert — body: { filter, data, returnData?, dryRun? }
PATCH	/data-tables/:id/rows	Update matching — body: { filter, data, returnData?, dryRun? }
DELETE	/data-tables/:id/rows	Delete matching — query: filter, returnData?, dryRun?

filter is n8n's row-filter DSL — typically { "type":"and", "filters":[{"columnName":"id","condition":"eq","value":42}] }. Conditions: eq, neq, gt, gte, lt, lte, like, notLike, isNull, isNotNull.

Recipes

List all tables

set -a; source .env; set +a
curl -s "${N8N_API_URL%/}/api/v1/data-tables" \
  -H "X-N8N-API-KEY: $N8N_API_KEY" -H "Accept: application/json" | jq .

Create a table with typed columns

curl -s -X POST "${N8N_API_URL%/}/api/v1/data-tables" \
  -H "X-N8N-API-KEY: $N8N_API_KEY" -H "Content-Type: application/json" \
  --data-binary @- <<'JSON' | jq .
{
  "name": "customer_queue",
  "projectId": "<project-id>",
  "columns": [
    { "name": "customer_id", "type": "string" },
    { "name": "status",      "type": "string" },
    { "name": "retries",     "type": "number" },
    { "name": "last_seen",   "type": "date"   }
  ]
}
JSON

Umlaut-safe inline JSON on Windows: Never curl -d '{"name":"Geschäft"}' — use a heredoc as shown (--data-binary @-) or write the JSON to a temp file and pass --data-binary @file.json. See feedback_curl_umlaut_body.md.

Seed rows from a local JSON file

# rows.json: { "data": [ {"customer_id":"abc","status":"new","retries":0,"last_seen":"2026-05-18T00:00:00Z"}, ... ] }
TABLE_ID=<id>
curl -s -X POST "${N8N_API_URL%/}/api/v1/data-tables/$TABLE_ID/rows" \
  -H "X-N8N-API-KEY: $N8N_API_KEY" -H "Content-Type: application/json" \
  --data-binary @rows.json | jq '.data | length'

Read first 50 rows

curl -s "${N8N_API_URL%/}/api/v1/data-tables/$TABLE_ID/rows?limit=50" \
  -H "X-N8N-API-KEY: $N8N_API_KEY" | jq '.data'

Upsert rows by key

curl -s -X PUT "${N8N_API_URL%/}/api/v1/data-tables/$TABLE_ID/rows" \
  -H "X-N8N-API-KEY: $N8N_API_KEY" -H "Content-Type: application/json" \
  --data-binary @- <<'JSON' | jq .
{
  "filter": { "type":"and", "filters":[{"columnName":"customer_id","condition":"eq","value":"abc"}] },
  "data":   { "status":"done", "retries": 1 }
}
JSON

Delete rows by filter

curl -s -X DELETE "${N8N_API_URL%/}/api/v1/data-tables/$TABLE_ID/rows" \
  -H "X-N8N-API-KEY: $N8N_API_KEY" -G \
  --data-urlencode 'filter={"type":"and","filters":[{"columnName":"status","condition":"eq","value":"obsolete"}]}' \
  | jq .

Drop entire table

curl -s -X DELETE "${N8N_API_URL%/}/api/v1/data-tables/$TABLE_ID" \
  -H "X-N8N-API-KEY: $N8N_API_KEY" | jq .

Add a column to existing table

curl -s -X POST "${N8N_API_URL%/}/api/v1/data-tables/$TABLE_ID/columns" \
  -H "X-N8N-API-KEY: $N8N_API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"notes","type":"string"}' | jq .

Workflow Integration

Once a table exists, reference it from a workflow via the dataTable node (operations: getRows, insertRows, updateRows, upsertRow, deleteRows). Inside the workflow node, filters use the same DSL — see feedback_n8n_datatable_upsert.md for the filters.conditions[].keyName quirk.

For node-level discovery:

npx n8nac skills node-info dataTable --json

Safety

• Destructive ops (DELETE table, DELETE rows without dry-run) — confirm with the user first
• Use ?dryRun=true query param on PUT/PATCH/DELETE rows when uncertain about the filter scope
• API key has full instance access — never log the key, never commit .env
• Operations are not transactional across multiple tables — failures partway leave partial state

Why Not n8nac?

n8nac CLI (npx n8nac --help) has no datatable / data-table subcommand as of 2.2.x. DataTable resources live in the n8n instance, not in the workflow source — they are infrastructure, not code. The public REST API is the canonical management channel until n8nac adds first-class support.