完整文档索引见 llms.txt。在页面 URL 后附加 .md 即可获取 Markdown 版本；本页的 Markdown 版本可在此获取。

数据表

数据表及其行相关操作

列出所有数据表

获取所有数据表的列表，可选择筛选、排序和分页。每个表都包含 `sizeBytes`，`size` 排序选项按此值排序。

GET/data-tables

请求参数

参数	位置	类型	必填	说明
limit	query	number	否	最多返回的数据项数量。 默认值：100
cursor	query	string	否	将 cursor 参数设为上次请求响应中的 nextCursor 属性，以进行分页。使用默认值时，获取集合的第一页。更多信息，请参阅分页说明。
filter	query	string	否	筛选条件的 JSON 字符串
sortBy	query	string	否	排序格式：field:asc 或 field:desc 可选值：name:asc, name:desc, createdAt:asc, createdAt:desc, updatedAt:asc, updatedAt:desc, size:asc, size:desc

响应

状态码	说明
200	操作成功。
400	请求无效，或提供的数据格式错误。
401	未授权
403	禁止访问

响应结构：200 · application/json

字段	类型	必填	说明
data	array	是	展开字段 字段 类型 必填 说明 data.[]id string 是 数据表的唯一标识符 data.[]name string 是 数据表名称 data.[]columns array 是 列定义 data.[]projectId string 是 此表所属项目的 ID data.[]createdAt string 是 表创建的时间戳 data.[]updatedAt string 是 表上次更新的时间戳 data.[]sizeBytes integer 是 物理存储大小，单位为字节，包括索引和内部开销。删除行后不会立即减少，数值可能延迟几秒更新。
nextCursor	string	是	将 cursor 参数设为先前请求返回的 nextCursor 属性，以对数据表进行分页。使用默认值时，获取集合的第一页。

下载完整 OpenAPI 定义（JSON）

新建数据表

在个人项目或你有权访问的团队项目中新建数据表。

POST/data-tables

请求参数

参数	位置	类型	必填	说明
Idempotency-Key	header	string	否	此 POST 请求的安全重试键。使用 1 到 128 个可见 ASCII 字符。相同的键配合相同的请求，会返回首次成功的响应。使用此键发送不同请求时返回 422。首次请求仍在处理时重试，会返回 409。

请求体

application/json

字段	类型	必填	说明
name	string	是	数据表名称
columns	array	是	表的列定义 展开字段 字段 类型 必填 说明 columns.[]name string 是 列名称 columns.[]type string 是 列的数据类型 可选值：string, number, boolean, date columns.[]csvColumnName string 否 读取值的 CSV 列名称。未设置时，n8n 按位置映射 CSV 列。
projectId	string	否	创建表的项目 ID；省略时，在用户的个人项目中创建表。
fileId	string	否	在 n8n 编辑器中上传的 CSV 文件 ID。设置后，n8n 会使用该文件的行填充新表。只有通过会话认证的调用方才能上传文件，因此 API 密钥调用方不能使用此字段。
hasHeaders	boolean	否	CSV 文件首行是列名时设为 true，仅在设置 fileId 时适用，默认为 true。

响应

状态码	说明
201	操作成功。
400	请求无效，或提供的数据格式错误。
401	未授权
403	禁止访问
409	冲突
415	不支持的媒体类型。
422	无法处理的实体

响应结构：201 · application/json

字段	类型	必填	说明
id	string	是	数据表的唯一标识符
name	string	是	数据表名称
columns	array	是	列定义 展开字段 字段 类型 必填 说明 columns.[]id string 是 列 ID columns.[]name string 是 列名称 columns.[]type string 是 列的数据类型 可选值：string, number, boolean, date columns.[]index integer 是 列位置 columns.[]createdAt string 是 列创建的时间戳 columns.[]updatedAt string 是 列上次更新的时间戳
projectId	string	是	此表所属项目的 ID
createdAt	string	是	表创建的时间戳
updatedAt	string	是	表上次更新的时间戳
sizeBytes	integer	是	物理存储大小，单位为字节，包括索引和内部开销。删除行后不会立即减少，数值可能延迟几秒更新。

下载完整 OpenAPI 定义（JSON）

获取数据表

按 ID 获取特定数据表。

GET/data-tables/{dataTableId}

请求参数

参数	位置	类型	必填	说明
dataTableId	path	string	是	数据表的 ID

响应

状态码	说明
200	操作成功。
401	未授权
403	禁止访问
404	未找到指定资源。

响应结构：200 · application/json

字段	类型	必填	说明
id	string	是	数据表的唯一标识符
name	string	是	数据表名称
columns	array	是	列定义 展开字段 字段 类型 必填 说明 columns.[]id string 是 列 ID columns.[]name string 是 列名称 columns.[]type string 是 列的数据类型 可选值：string, number, boolean, date columns.[]index integer 是 列位置 columns.[]createdAt string 是 列创建的时间戳 columns.[]updatedAt string 是 列上次更新的时间戳
projectId	string	是	此表所属项目的 ID
createdAt	string	是	表创建的时间戳
updatedAt	string	是	表上次更新的时间戳
sizeBytes	integer	是	物理存储大小，单位为字节，包括索引和内部开销。删除行后不会立即减少，数值可能延迟几秒更新。

下载完整 OpenAPI 定义（JSON）

删除数据表

删除数据表，同时删除表中的所有行。

DELETE/data-tables/{dataTableId}

请求参数

参数	位置	类型	必填	说明
dataTableId	path	string	是	数据表的 ID

响应

状态码	说明
204	操作成功。
401	未授权
403	禁止访问
404	未找到指定资源。

下载完整 OpenAPI 定义（JSON）

更新数据表

更新数据表名称。

PATCH/data-tables/{dataTableId}

请求参数

参数	位置	类型	必填	说明
dataTableId	path	string	是	数据表的 ID

请求体

application/json

字段	类型	必填	说明
name	string	是	数据表的新名称

响应

状态码	说明
200	操作成功。
400	请求无效，或提供的数据格式错误。
401	未授权
403	禁止访问
404	未找到指定资源。
409	冲突
415	不支持的媒体类型。

响应结构：200 · application/json

字段	类型	必填	说明
id	string	是	数据表的唯一标识符
name	string	是	数据表名称
columns	array	是	列定义 展开字段 字段 类型 必填 说明 columns.[]id string 是 列 ID columns.[]name string 是 列名称 columns.[]type string 是 列的数据类型 可选值：string, number, boolean, date columns.[]index integer 是 列位置 columns.[]createdAt string 是 列创建的时间戳 columns.[]updatedAt string 是 列上次更新的时间戳
projectId	string	是	此表所属项目的 ID
createdAt	string	是	表创建的时间戳
updatedAt	string	是	表上次更新的时间戳
sizeBytes	integer	是	物理存储大小，单位为字节，包括索引和内部开销。删除行后不会立即减少，数值可能延迟几秒更新。

下载完整 OpenAPI 定义（JSON）

列出数据表依赖项

列出使用此数据表的工作流。

GET/data-tables/{dataTableId}/dependencies

请求参数

参数	位置	类型	必填	说明
limit	query	number	否	最多返回的数据项数量。 默认值：100
cursor	query	string	否	将 cursor 参数设为上次请求响应中的 nextCursor 属性，以进行分页。使用默认值时，获取集合的第一页。更多信息，请参阅分页说明。
dataTableId	path	string	是	数据表的 ID

响应

状态码	说明
200	操作成功。
400	请求无效，或提供的数据格式错误。
401	未授权
403	禁止访问
404	未找到指定资源。

响应结构：200 · application/json

字段	类型	必填	说明
data	array	是	展开字段 字段 类型 必填 说明 data.[]type string 是 与所请求资源的关系。credential、dataTable、subWorkflow、errorWorkflow：所请求的工作流使用此依赖项。parentWorkflow：此工作流使用所请求的资源。errorWorkflowParent：此工作流将所请求的工作流用作错误工作流。agent：此智能体使用所请求的资源。 可选值：agent, credential, dataTable, errorWorkflow, errorWorkflowParent, parentWorkflow, subWorkflow data.[]id string 是 data.[]name string 是 data.[]projectId string 否 依赖项所属项目（已知时返回）。
nextCursor	string	是
inaccessibleCount	integer	是	你无权访问的依赖项数量；这些依赖项不会列出。

下载完整 OpenAPI 定义（JSON）

列出数据表的列

获取特定数据表的所有列。

GET/data-tables/{dataTableId}/columns

请求参数

参数	位置	类型	必填	说明
dataTableId	path	string	是	数据表的 ID

响应

状态码	说明
200	操作成功。
401	未授权
403	禁止访问
404	未找到指定资源。

响应结构：200 · application/json

字段	类型	必填	说明
[]id	string	是	列 ID
[]name	string	是	列名称
[]type	string	是	列的数据类型 可选值：string, number, boolean, date
[]index	integer	是	列位置
[]createdAt	string	是	列创建的时间戳
[]updatedAt	string	是	列上次更新的时间戳
[]dataTableId	string	是	此列所属数据表的 ID

下载完整 OpenAPI 定义（JSON）

向数据表添加列

向现有数据表添加新列。

POST/data-tables/{dataTableId}/columns

请求参数

参数	位置	类型	必填	说明
Idempotency-Key	header	string	否	此 POST 请求的安全重试键。使用 1 到 128 个可见 ASCII 字符。相同的键配合相同的请求，会返回首次成功的响应。使用此键发送不同请求时返回 422。首次请求仍在处理时重试，会返回 409。
dataTableId	path	string	是	数据表的 ID

请求体

application/json

字段	类型	必填	说明
name	string	是	列名。必须以字母开头，后续只能包含字母、数字和下划线，最多 63 个字符。
type	string	是	列的数据类型 可选值：string, number, boolean, date
index	integer	否	列位置，可选；省略时追加到末尾

响应

状态码	说明
201	操作成功。
400	请求无效，或提供的数据格式错误。
401	未授权
403	禁止访问
404	未找到指定资源。
409	冲突
415	不支持的媒体类型。
422	无法处理的实体

响应结构：201 · application/json

字段	类型	必填	说明
id	string	是	列 ID
name	string	是	列名称
type	string	是	列的数据类型 可选值：string, number, boolean, date
index	integer	是	列位置
createdAt	string	是	列创建的时间戳
updatedAt	string	是	列上次更新的时间戳
dataTableId	string	是	此列所属数据表的 ID

下载完整 OpenAPI 定义（JSON）

删除列

从数据表移除列，同时删除该列中的所有数据。

DELETE/data-tables/{dataTableId}/columns/{columnId}

请求参数

参数	位置	类型	必填	说明
dataTableId	path	string	是	数据表的 ID
columnId	path	string	是	列的 ID

响应

状态码	说明
204	操作成功。
401	未授权
403	禁止访问
404	未找到指定资源。

下载完整 OpenAPI 定义（JSON）

更新列

重命名数据表中的列和／或调整其顺序。

PATCH/data-tables/{dataTableId}/columns/{columnId}

请求参数

参数	位置	类型	必填	说明
dataTableId	path	string	是	数据表的 ID
columnId	path	string	是	列的 ID

请求体

application/json

字段	类型	必填	说明
name	string	否	列名。必须以字母开头，后续只能包含字母、数字和下划线，最多 63 个字符。
index	integer	否	新的列位置，从零开始计数

响应

状态码	说明
200	操作成功。
400	请求无效，或提供的数据格式错误。
401	未授权
403	禁止访问
404	未找到指定资源。
409	冲突
415	不支持的媒体类型。

响应结构：200 · application/json

字段	类型	必填	说明
id	string	是	列 ID
name	string	是	列名称
type	string	是	列的数据类型 可选值：string, number, boolean, date
index	integer	是	列位置
createdAt	string	是	列创建的时间戳
updatedAt	string	是	列上次更新的时间戳
dataTableId	string	是	此列所属数据表的 ID

下载完整 OpenAPI 定义（JSON）

列出数据表的行

获取数据表中的行，可选择筛选、排序和分页。

GET/data-tables/{dataTableId}/rows

请求参数

参数	位置	类型	必填	说明
limit	query	number	否	最多返回的数据项数量。 默认值：100
cursor	query	string	否	将 cursor 参数设为上次请求响应中的 nextCursor 属性，以进行分页。使用默认值时，获取集合的第一页。更多信息，请参阅分页说明。
dataTableId	path	string	是	数据表的 ID
filter	query	string	否	筛选条件的 JSON 字符串
sortBy	query	string	否	排序格式：columnName:asc 或 columnName:desc
search	query	string	否	在所有字符串列中搜索的文本

响应

状态码	说明
200	操作成功。
400	请求无效，或提供的数据格式错误。
401	未授权
403	禁止访问
404	未找到指定资源。

响应结构：200 · application/json

字段	类型	必填	说明
data	array	是	展开字段 字段 类型 必填 说明 data.[]id integer 是 行 ID，自动生成 data.[]createdAt string 是 行创建的日期和时间 data.[]updatedAt string 是 行上次更新的日期和时间
nextCursor	string	是	将 cursor 参数设为先前请求返回的 nextCursor 属性，以对行进行分页。使用默认值时，获取集合的第一页。

下载完整 OpenAPI 定义（JSON）

向数据表插入行

向数据表插入一行或多行。

POST/data-tables/{dataTableId}/rows

请求参数

参数	位置	类型	必填	说明
Idempotency-Key	header	string	否	此 POST 请求的安全重试键。使用 1 到 128 个可见 ASCII 字符。相同的键配合相同的请求，会返回首次成功的响应。使用此键发送不同请求时返回 422。首次请求仍在处理时重试，会返回 409。
dataTableId	path	string	是	数据表的 ID

请求体

application/json

字段	类型	必填	说明
data	array	是	待插入的行数组。每行都是以列名为键的对象。
returnType	联合类型	否	count：仅返回插入行数。id：返回对象数组，每个对象包含一条已插入行的 id。all：返回所有已插入行的完整数据。 默认值："count" 展开字段 结构 1 结构 2 结构 3

响应

状态码	说明
200	操作成功。
400	请求无效，或提供的数据格式错误。
401	未授权
403	禁止访问
404	未找到指定资源。
409	冲突
415	不支持的媒体类型。
422	无法处理的实体

响应结构：200 · application/json

结构 1

字段	类型	必填	说明
success	boolean	是	可选值：True
insertedRows	integer	是

结构 2

字段	类型	必填	说明
[]id	integer	是

结构 3

字段	类型	必填	说明
[]id	integer	是	行 ID，自动生成
[]createdAt	string	是	行创建的日期和时间
[]updatedAt	string	是	行上次更新的日期和时间

下载完整 OpenAPI 定义（JSON）

在数据表中更新或插入行

更新现有行；没有行符合筛选条件时，插入新行。

POST/data-tables/{dataTableId}/rows/upsert

请求参数

参数	位置	类型	必填	说明
Idempotency-Key	header	string	否	此 POST 请求的安全重试键。使用 1 到 128 个可见 ASCII 字符。相同的键配合相同的请求，会返回首次成功的响应。使用此键发送不同请求时返回 422。首次请求仍在处理时重试，会返回 409。
dataTableId	path	string	是	数据表的 ID

请求体

application/json

字段	类型	必填	说明
filter	object	是	用于匹配现有行的筛选条件。没有匹配行时，n8n 插入新行。 展开字段 字段 类型 必填 说明 filter.type 联合类型 否 默认值："and" 展开字段 结构 1 结构 2 filter.filters array 是 展开字段 字段 类型 必填 说明 filter.filters.[]columnName string 是 filter.filters.[]condition 联合类型 是 filter.filters.[]value 联合类型 是
data	object	是	行的列值
returnData	boolean	否	设为 true 时，返回更新或插入的行：更新时返回匹配行，插入时返回新行。设为 false 时，成功后返回 true。 默认值：false
dryRun	boolean	否	设为 true 时，仅预览变更，不保存。 默认值：false

响应

状态码	说明
200	操作成功。
400	请求无效，或提供的数据格式错误。
401	未授权
403	禁止访问
404	未找到指定资源。
409	冲突
415	不支持的媒体类型。
422	无法处理的实体

响应结构：200 · application/json

结构 1

结构 2

字段	类型	必填	说明
[]id	integer	是	行 ID，自动生成
[]createdAt	string	是	行创建的日期和时间
[]updatedAt	string	是	行上次更新的日期和时间
[]dryRunState	string	是	此条目显示的是变更前还是变更后的行状态 可选值：before, after

结构 3

字段	类型	必填	说明
[]id	integer	是	行 ID，自动生成
[]createdAt	string	是	行创建的日期和时间
[]updatedAt	string	是	行上次更新的日期和时间

下载完整 OpenAPI 定义（JSON）

更新数据表中的行

更新数据表中符合筛选条件的行。

PATCH/data-tables/{dataTableId}/rows/update

请求参数

参数	位置	类型	必填	说明
dataTableId	path	string	是	数据表的 ID

请求体

application/json

字段	类型	必填	说明
filter	object	是	匹配待更新行的筛选条件。 展开字段 字段 类型 必填 说明 filter.type 联合类型 否 默认值："and" 展开字段 结构 1 结构 2 filter.filters array 是 展开字段 字段 类型 必填 说明 filter.filters.[]columnName string 是 filter.filters.[]condition 联合类型 是 filter.filters.[]value 联合类型 是
data	object	是	待更新的列值
returnData	boolean	否	设为 true 时，返回更新后的行；设为 false 时，成功后返回 true。 默认值：false
dryRun	boolean	否	设为 true 时，仅预览变更，不保存。 默认值：false

响应

状态码	说明
200	操作成功。
400	请求无效，或提供的数据格式错误。
401	未授权
403	禁止访问
404	未找到指定资源。
415	不支持的媒体类型。

响应结构：200 · application/json

结构 1

结构 2

字段	类型	必填	说明
[]id	integer	是	行 ID，自动生成
[]createdAt	string	是	行创建的日期和时间
[]updatedAt	string	是	行上次更新的日期和时间
[]dryRunState	string	是	此条目显示的是变更前还是变更后的行状态 可选值：before, after

结构 3

字段	类型	必填	说明
[]id	integer	是	行 ID，自动生成
[]createdAt	string	是	行创建的日期和时间
[]updatedAt	string	是	行上次更新的日期和时间

下载完整 OpenAPI 定义（JSON）

清空数据表中的所有行

永久删除数据表中的所有行，保留表结构。此操作无法撤销。

DELETE/data-tables/{dataTableId}/rows/clear

请求参数

参数	位置	类型	必填	说明
dataTableId	path	string	是	数据表的 ID

响应

状态码	说明
200	操作成功。
401	未授权
403	禁止访问
404	未找到指定资源。

响应结构：200 · application/json

字段	类型	必填	说明
deletedCount	integer	是	已删除的行数

下载完整 OpenAPI 定义（JSON）

删除数据表中的行

删除数据表中符合筛选条件的行。必须提供筛选条件，防止意外删除所有数据。

DELETE/data-tables/{dataTableId}/rows/delete

请求参数

参数	位置	类型	必填	说明
dataTableId	path	string	是	数据表的 ID
filter	query	string	是	筛选条件的 JSON 字符串。必填，以防意外删除所有数据。
returnData	query	string	否	为 true 时，返回已删除的行；为 false 时，成功后返回 true。 默认值："false" 可选值：true, false
dryRun	query	string	否	为 true 时，预览将删除哪些行，不实际删除。 默认值："false" 可选值：true, false

响应

状态码	说明
200	操作成功。
400	请求无效，或提供的数据格式错误。
401	未授权
403	禁止访问
404	未找到指定资源。

响应结构：200 · application/json

结构 1

结构 2

字段	类型	必填	说明
[]id	integer	是	行 ID，自动生成
[]createdAt	string	是	行创建的日期和时间
[]updatedAt	string	是	行上次更新的日期和时间
[]dryRunState	string	是	此条目显示的是变更前还是变更后的行状态 可选值：before, after

结构 3

字段	类型	必填	说明
[]id	integer	是	行 ID，自动生成
[]createdAt	string	是	行创建的日期和时间
[]updatedAt	string	是	行上次更新的日期和时间

下载完整 OpenAPI 定义（JSON）