版本 API
查看表单的发布历史和版本快照。
版本 API 允许您查看表单的发布历史。每次发布表单时，NueForm 会创建一个包含完整表单配置和所有问题的版本快照。版本还包含变更日志，概述自上次发布以来的变更内容。
所有响应体均使用 snake_case 字段命名。
Endpoints
列出表单版本
GET
/api/v1/forms/:id/versions返回表单的所有已发布版本，按版本号排序（最新优先）。每个版本包含完整的表单快照和修改内容的变更日志。
路径参数
idstring必填表单 ID
响应字段
idstring唯一版本 ID
form_idstring此版本所属的表单
versioninteger递增的版本号（1, 2, 3, ...）
published_bystring发布此版本的用户 ID
published_by_namestring发布者的显示名称
created_atstringISO 8601 此版本发布时间戳
changelogarray自上一版本以来的变更列表
changelog[].typestring变更类型（参见下方变更日志条目类型）
changelog[].descriptionstring人类可读的变更描述
snapshotobject发布时的完整表单状态（包括所有表单字段和问题）
变更日志条目类型
form_createdstring表单初次创建
publishedstring发布事件（包含版本号）
question_addedstring添加了新问题
question_updatedstring修改了已有问题
question_deletedstring删除了问题
question_reorderedstring重新排序了问题
theme_changedstring修改了主题属性
settings_changedstring修改了表单设置
title_changedstring更改了表单标题
description_changedstring更改了表单描述
响应
json
{
"versions": [
{
"id": "66c3d4e5f6a7b8c9d0e1f2a3",
"form_id": "665a1b2c3d4e5f6a7b8c9d0e",
"version": 3,
"published_by": "665a0a1b2c3d4e5f6a7b8c9d",
"published_by_name": "Alice Johnson",
"created_at": "2026-02-28T14:00:00.000Z",
"changelog": [
{
"type": "question_updated",
"description": "Updated question: \"How did you hear about us?\""
},
{
"type": "question_added",
"description": "Added question: \"Would you recommend us to a friend?\""
},
{
"type": "theme_changed",
"description": "Changed theme color from #6366f1 to #2563eb"
}
],
"snapshot": {
"title": "Customer Feedback Survey",
"description": "Help us improve our product",
"theme_color": "#2563eb",
"background_color": "#ffffff",
"show_progress_bar": true,
"questions": [
{
"id": "66a1b2c3d4e5f6a7b8c9d001",
"type": "short_text",
"title": "What is your name?",
"required": true,
"order": 0,
"properties": {}
},
{
"id": "66a1b2c3d4e5f6a7b8c9d002",
"type": "multiple_choice",
"title": "How did you hear about us?",
"required": true,
"order": 1,
"properties": {
"choices": [
{ "label": "Search engine" },
{ "label": "Social media" },
{ "label": "Friend or colleague" },
{ "label": "Other" }
]
}
},
{
"id": "66a1b2c3d4e5f6a7b8c9d004",
"type": "yes_no",
"title": "Would you recommend us to a friend?",
"required": false,
"order": 2,
"properties": {}
}
]
}
},
{
"id": "66c2d3e4f5a6b7c8d9e0f1a2",
"form_id": "665a1b2c3d4e5f6a7b8c9d0e",
"version": 2,
"published_by": "665a0a1b2c3d4e5f6a7b8c9d",
"published_by_name": "Alice Johnson",
"created_at": "2026-02-15T10:30:00.000Z",
"changelog": [
{
"type": "question_added",
"description": "Added question: \"How did you hear about us?\""
}
],
"snapshot": { ... }
},
{
"id": "66c1d2e3f4a5b6c7d8e9f0a1",
"form_id": "665a1b2c3d4e5f6a7b8c9d0e",
"version": 1,
"published_by": "665a0a1b2c3d4e5f6a7b8c9d",
"published_by_name": "Alice Johnson",
"created_at": "2026-01-15T10:30:00.000Z",
"changelog": [
{
"type": "form_created",
"description": "Created form"
}
],
"snapshot": { ... }
}
]
}
代码示例
bash
curl -X GET "https://api.nueform.io/api/v1/forms/665a1b2c3d4e5f6a7b8c9d0e/versions" \
-H "Authorization: Bearer YOUR_API_KEY"
版本管理工作原理
- 编辑 -- 对表单进行更改（添加问题、更新主题、修改设置）。表单的
has_unpublished_changes标志设置为true。 - 发布 -- 调用
POST /api/v1/forms/:id/publish创建新版本。NueForm 会拍摄当前表单状态的快照，记录变更日志，并递增版本号。 - 在线表单 -- 受访者始终看到最新的已发布版本。表单上的
published_version_id指向当前激活的版本。 - 取消发布 -- 调用
DELETE /api/v1/forms/:id/publish使表单下线。版本历史会被保留。
当前表单状态（可通过表单 API编辑）可能与最新发布版本不同（如果自上次发布以来进行了编辑）。
错误响应
此端点返回的标准错误响应。
错误码
401Unauthorized缺少或无效的 API 密钥
403Forbidden团队表单权限不足
404Not Found表单未找到
500Server Error服务器内部错误
错误示例
json
{
"error": "Form not found"
}
最后更新：2026年4月6日