上传您的企业数据
本功能的用途
通过上传功能，Kaleidr 可以依据您组织自己的数据回答问题。这是 Enterprise 企业版功能。发布的上传数据可供已登录组织成员在 Kaleidr Studio 助手中使用。若要在您的网站或后端使用，还需完成三个步骤：创建可读取数据的密钥、使用该密钥提问，并检查回答是否包含您的地点。使用自有数据生成回答介绍完整流程与数据应用方式。本页专门说明上传环节：请求、字段、限制、错误以及取消发布或删除数据版本的方法。
本页不是介绍在 Kaleidr Studio 地图 Data 面板中添加的文件，例如电子表格、GeoJSON 或 GPX 轨迹。那是所有套餐都可使用的独立功能：参阅地图数据集。
数据可通过两种方式上传，两者使用同一处理流程：
- **界面：**任何 Kaleidr Studio 地图的 Data 面板底部都有 Data for AI Answers 区域。这是唯一的上传界面； 只有具备上传权限的组织所有者或管理员能看到上传控件。操作步骤见在 Studio 中上传。
- **本页介绍的 API：**界面发出的请求与此 API 相同，因此下文的文件格式、限制、状态和错误同时适用于两种方式；一方创建的版本也会在另一方显示。
上传前需要了解以下三个特性：
- 回答问题时才检索您的数据。 Kaleidr 会在回答时查询已发布版本，因此取消发布后，新的回答会立即停止使用这些数据。
- 数据只提供给您的组织。 数据按组织隔离，不会出现在 Kaleidr 面向消费者的地图或其他组织的回答中。
- 不会凭空生成您的数据值。 可选的映射辅助工具仅使用表头和最多五行样本建议列映射。文件中的每一行随后按您批准的映射转换；映射错误需要自行更正并重新执行，不会虚构价格、日期或名称。
可用性
| 要求 | 说明 |
|---|---|
| 套餐 | Enterprise。 Free 和 Pro 的上传、发布、重新派发及映射建议请求会返回 403 vendor_data_not_on_plan。以组织在 kaleidr.com/billing 购买的 Kaleidr 套餐为准；Studio 没有独立套餐。 |
| 角色 | 组织所有者或管理员。否则返回 403 org_admin_required。 |
| 限制 | 由组织协议确定。参阅限制。GET /shared-api/datahub/limits 可返回组织自己的数值。 参考 |
| 界面 | Kaleidr Studio 的 Data 面板中 Data for AI Answers 区域，或者本页 API。两者使用相同的处理流程和检查。 |
不同请求所需的角色与套餐：
| 操作 | 角色 | 套餐 |
|---|---|---|
| 建议映射、上传、发布、重新派发 | 所有者或管理员 | Enterprise |
| 读取限制、处理状态与版本列表 | 所有者或管理员 | 任意套餐 |
| 取消发布、删除版本 | 所有者或管理员 | 任意套餐 |
第二、三行操作在所有套餐中都可用，因此组织即使降级到无法上传的套餐，仍能查看和下架以前上传的数据。
使用自有数据也仅限 Enterprise，且在两个使用场景都如此：Studio 助手仅在组织为 Enterprise 时才引用已发布版本；通过 API 密钥或 SDK 获取带有自有数据的回答，还需要独立的 vendor 权限范围，只有 Enterprise 组织可获得。详见使用自有数据生成回答。
Studio 的 Data for AI Answers 区域会根据组织套餐与您的角色显示不同内容： 请参阅无法上传时该区域显示的内容。
您的组织可以上传多少数据
上传前先查询限制。Studio 打开该区域时也会调用此接口。
| 项目 | 说明 |
|---|---|
| 请求 | GET /shared-api/datahub/limits |
| 调用者 | 任意套餐的所有者或管理员 |
| 查询参数 | 可选 org_id：管理多个组织时指定目标组织。 |
curl https://api.kaleidr.com/shared-api/datahub/limits \
-H "Authorization: Bearer $KALEIDR_ACCESS_TOKEN"
对于 Enterprise 组织，此示例刻意省略三项限制值，因为它们由您的组织协议决定，示例数字并不适用于您。limits 始终包含下表的三个整数字段。
{
"can_upload": true,
"plan": "enterprise",
"limits": { "…": "places, documents and artifact_mb: three integers, described below" },
"reason": null
}
在 Free 和 Pro 中，该请求仍会返回 200，并说明不可上传的原因：
{
"can_upload": false,
"plan": "pro",
"limits": { "places": 0, "documents": 0, "artifact_mb": 0 },
"reason": "vendor_data_not_on_plan"
}
| 字段 | 类型 | 含义 |
|---|---|---|
can_upload | boolean | 该组织是否允许上传。 |
plan | string 或 null | 限制所属套餐：free、pro 或 enterprise。 |
limits.places | integer | 单次上传允许的地点数；CSV 按数据行计数。 |
limits.documents | integer | 单次上传允许的文档数。 |
limits.artifact_mb | integer | 上传文件大小上限，单位 MiB。 |
reason | string 或 null | can_upload 为 false 时是 vendor_data_not_on_plan，否则为 null。不可上传时限制值全部为 0。 |
这些数值是根据贵组织的合同单独确定的。任何限额都不能高于平台本身允许的上传上限：平台为这三项指标分别设置技术上限，合同也不能突破这些上限。
| 状态 | 含义 |
|---|---|
| 200 | 所有套餐中的组织所有者或管理员都能获得。Enterprise 以下返回 can_upload: false，而不是拒绝请求。 |
| 401 | 访问令牌缺失、过期或类型不正确。 |
403 org_admin_required | 当前用户不是组织所有者或管理员。 |
身份验证
所有请求都使用已登录 Kaleidr 账户的访问令牌作为 Bearer：
Authorization: Bearer <account access token>
- 它不是 API 密钥。
kld_pk_…和kld_sk_…密钥都会被拒绝。密钥用于标识集成应用，而上传数据属于组织管理操作，因此必须以具有相应角色的登录用户身份验证。 - 必须使用访问令牌，而不是 ID 令牌。
- 访问令牌属于已登录的组织所有者或管理员，并随登录会话过期。目前没有该 API 的长期凭证。如果需要自动定时上传，请在 开发前联系 Kaleidr。
- 在 Studio 界面上传时不需要自己管理令牌：它会使用登录成员的会话。
本页所有路径均以 https://api.kaleidr.com 为基础地址。示例从环境变量读取访问令牌：
export KALEIDR_ACCESS_TOKEN='<account access token>'
如果您管理多个组织，可通过 org_id 指定组织：上传时放在请求正文中，其他操作使用 ?org_id= 查询参数。省略时默认选择您的主要组织。
可以上传的内容
每次上传包含一个文本文件，作为 JSON 请求中的字符串发送。文件扩展名决定解析方式。
| 您拥有的数据 | 应提交 | 包含内容 |
|---|---|---|
| 地点列表 | 使用固定列名且无需映射的 .csv 文件 | 地点 |
| 每晚、每个房间或每种价格一行的电子表格导出 | .csv 及 mapping_spec | 地点、房型、价格方案、每日房价与可用量 |
| 已经结构化的完整数据 | .json 数据包 | 上述全部内容，另加营业时间与文档 |
每次上传至少包含一个地点。
地点 CSV
标题行使用以下列名：
| 列 | 必填 | 说明 |
|---|---|---|
name | 是 | 缺少名称的行会导致上传失败，并报告行号。 |
timezone | 是 | IANA 时区，例如 Europe/London。 |
lat、lng | 两种位置表示之一 | 已给定的坐标会直接使用。 |
address | 两种位置表示之一 | 缺少 lat 和 lng 时，根据地址查找坐标。 |
category | 否 | 简短类别，例如 hotel 或 restaurant。 |
ref | 否 | 您自己的记录标识符；省略时用行号识别记录。 |
name,timezone,lat,lng,address,category
Harbor Hotel,Europe/London,51.5079,-0.0877,"1 Example Street, London",hotel
Canal House,Europe/Amsterdam,,,"Example Gracht 12, Amsterdam",hotel
使用列映射的电子表格
当一张表的每行代表一次记录（酒店、房间、套餐、日期或价格）时，不能直接按固定列名读取。提交 mapping_spec 指明源表列与目标字段的对应关系。
Property,Address,Room,Plan,Date,Nightly Rate,Available
Harbor Hotel,"1 Example Street, London",Double,Flexible,2026-11-06,189.00,4
Harbor Hotel,"1 Example Street, London",Suite,Flexible,2026-11-06,320.00,1
{
"places": {
"ref_from": ["Property"],
"fields": {
"name": "Property",
"address": "Address",
"timezone": { "const": "Europe/London" },
"category": { "const": "hotel" }
}
},
"room_types": { "ref_from": ["Room"], "fields": { "name": "Room" } },
"rate_plans": { "ref_from": ["Plan"], "fields": { "name": "Plan" } },
"daily_rates": {
"fields": {
"stay_date": "Date",
"price_amount": "Nightly Rate",
"price_currency": { "const": "GBP" }
}
},
"daily_inventory": {
"fields": { "stay_date": "Date", "units_available": "Available" }
}
}
映射规则：
| 部分 | 含义 |
|---|---|
| 区块 | places（必需）、room_types、rate_plans、daily_rates 和 daily_inventory；只包含实际拥有数据的区块。 |
ref_from | 指定识别记录的列。这些列的值相同的行代表同一个地点、房型或价格方案。 |
fields | 将每个目标字段映射到源列名。少数字段也可指定常量，例如 { "const": "value" }。 |
映射只能设置下表所列的字段。最后一列说明哪些字段允许使用常量。
| 区块 | 可映射字段 | 允许使用常量 |
|---|---|---|
places | name、address、timezone、category、lat、lng、overture_id | timezone、category |
room_types | name | name |
rate_plans | name、currency、cancellation_policy、board_basis | name、currency |
daily_rates | stay_date（ISO 日期）、price_amount（非负数）、price_currency（三个字母） | price_currency |
daily_inventory | stay_date、units_available（非负整数） | 无 |
违反下面两条规则都会导致验证错误：
- 不允许表格以外的字段。 错误会指出字段以及对应区块允许的字段，例如
room_types.fields.beds: not a field a mapping can set -- room_types takes name。无法通过电子表格单元格映射的属性（如床位数或自由属性）应通过 JSON 数据包提交。 - 不允许在其他字段使用常量。 价格、日期、数量、地点名称和位置必须来自源表的列，例如
daily_rates.fields.price_amount: must name a column -- a constant cannot supply this field。常量只用于整个表都相同的值，如时区或货币。
这些错误会出现在映射建议的 errors 列表中 ；当按错误映射上传时，会出现在 error_report 中。处理过程失败，且不会暂存任何数据。
如果包含 daily_rates，就必须同时包含 room_types 和 rate_plans，因为每项价格都对应一种房型和一个价格方案。如果源表没有方案列，可为方案名称使用常量。
列映射只适用于 .csv。对 .json 文件同时提交映射会导致处理失败。
JSON 数据包
.json 文件是一个包含下列列表中任意若干列表的对象。不同列表中的记录通过 ref 相互引用。
{
"places": [
{
"ref": "harbor",
"name": "Harbor Hotel",
"timezone": "Europe/London",
"lat": 51.5079,
"lng": -0.0877,
"address": "1 Example Street, London",
"category": "hotel"
}
],
"room_types": [{ "ref": "double", "place_ref": "harbor", "name": "Double" }],
"rate_plans": [{ "ref": "flex", "place_ref": "harbor", "name": "Flexible" }],
"daily_rates": [
{
"place_ref": "harbor",
"room_type_ref": "double",
"rate_plan_ref": "flex",
"stay_date": "2026-11-06",
"price_amount": 189.0,
"price_currency": "GBP"
}
],
"daily_inventory": [
{ "place_ref": "harbor", "room_type_ref": "double", "stay_date": "2026-11-06", "units_available": 4 }
],
"hours": [
{ "place_ref": "harbor", "weekday": 0, "opens": "07:00", "closes": "23:00" },
{ "place_ref": "harbor", "valid_from": "2026-12-25", "valid_through": "2026-12-25", "is_closed": true }
],
"documents": [
{ "title": "Cancellation policy", "text": "Free cancellation until 18:00 on the day before arrival." }
]
}
| 列表 | 必需字段 | 说明 |
|---|---|---|
places | name、timezone，以及 lat 与 lng 或 address | ref 必须唯一。至少有一个地点。 |
room_types、rate_plans | place_ref、name | ref 在各自列表内必须唯一。 |
daily_rates | place_ref、room_type_ref、rate_plan_ref、stay_date、price_amount、price_currency | |
daily_inventory | place_ref、room_type_ref、stay_date、units_available | |
hours | place_ref，加 weekday 或 valid_from 日期 | weekday 为 0 至 6，0 表示星期一；opens 和 closes 为一天中的时间。 |
documents | title、text | 只能包含直接写入的文本。 |
这些列表也接受可选字段，每个字段都有大小限制：参阅字段限制。
关于文档：
- 文档由
title和内联text组成。填写的存储路径或密钥会被忽略；文档不能指向外部文件。 - 可选的
mime指明文本格式。支持text/plain、text/markdown和text/html；其他值统一记录为text/plain。
数值必须为有限值。NaN 和 Infinity 不能用于坐标、价格、数量或自定义 JSON 字段；出现这些值时会报告该行错误。
上传流程
一次上传产生一个 ingest（处理任务）和一个 release（带版本号的结果）。发布前版本为 draft。发布操作会一次性替换旧的已发布版本，使读取方永远不会看到只更新了一部分的数据。替换期间也不会出现短暂的无数据状态；只有主动取消发布当前版本才会使组织没有已发布版本。
propose a mapping ─► stage a preview ─► check the result ─► publish
(optional, POST /ingests GET /ingests/{id} POST /ingests/{id}/publish
for a sheet) preview: true
later, to take a release back out: unpublish ─► delete
POST /releases/{id}/unpublish DELETE /releases/{id}
1. 建议映射（可选）
当电子表格没有映射配置时使用此功能。只发送文件开头部分：表头和少量数据行，不必发送完整导出文件。
| 项目 | 说明 |
|---|---|
| 请求 | POST /inference-api/vendor/mapping/propose |
| 调用者 | Enterprise 组织的所有者或管理员；与上传权限相同。 |
| 请求正文 | { "csv_head": "<the first characters of your file>" } |
| 限制 | csv_head 长度为 1 至 16,384 个字符；每个账户每小时最多 30 次建议。 |
| 费用 | 每次建议消耗组织 AI 积分，按使用的令牌计费。本页其他请求不消耗 AI 积分。 |
curl -X POST https://api.kaleidr.com/inference-api/vendor/mapping/propose \
-H "Authorization: Bearer $KALEIDR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"csv_head":"Property,Address,Room,Plan,Date,Nightly Rate,Available\nHarbor Hotel,\"1 Example Street, London\",Double,Flexible,2026-11-06,189.00,4\nHarbor Hotel,\"1 Example Street, London\",Suite,Flexible,2026-11-06,320.00,1\n"}'
{
"mapping_spec": { "places": { "ref_from": ["Property"], "fields": { "name": "Property", "address": "Address", "timezone": { "const": "Europe/London" } } }, "room_types": { "ref_from": ["Room"], "fields": { "name": "Room" } } },
"notes": "Time zone inferred from the addresses.",
"columns": ["Property", "Address", "Room", "Plan", "Date", "Nightly Rate", "Available"],
"sample_result": { "places": 1, "room_types": 2, "rate_plans": 1, "daily_rates": 2, "daily_inventory": 2 },
"errors": []
}
如何理解返回结果：
- 首先检查
sample_result。 它会对样本行执行建议映射，并报告每个区块产生多少记录。在上传前就能发现看似正确但没有输出记录的映射。 - HTTP 200 不保证
errors为空。 系统仍可能返回不可执行的映射并列出全部问题，方便您直接修正。常见问题包括：缺少必需字段、引用不存在的列、无效 IANA 时区或非三个字母的货币代码。 - 最多取五行完整样本。 如果
csv_head不以换行结束，最后一行会被丢弃，避免把截断的行误认为完整行。 - 不会保存任何内容。 您可以自行修改建议，并在下一步上传。
(
sample_result)
| 状态 | 含义 |
|---|---|
403 org_admin_required | 您不是任何组织的所有者或管理员。 |
403 vendor_data_not_on_plan | 您有管理权限，但没有任何组织订阅 Enterprise，因此无法上传。 |
| 422 | csv_head 超过 16,384 字符、无表头、列名重复或没有完整数据行。detail 会说明原因。 |
| 429（速率限制） | 当前账户最近一小时已超过 30 次建议。 |
| 429（AI 积分） | 当前周期的组织 AI 积分已经用完。 |
502 mapping proposal unavailable | 无法生成建议。可重试或手动编写映射。 |
区分两种 429 错误
两种拒绝都返回 429 状态，请查看响应正文：
| 项目 | 速率限制 | AI 积分耗尽 |
|---|---|---|
| 响应正文 | { "detail": "at most 30 mapping proposals per hour" } | 标准配额响应 |
| 判断方法 | 没有 error 字段，detail 为上述提示。 | "error": "quota_exceeded"，并带有 limit、used、remaining 和 reset_at。 |
| 处理办法 | 等待。限制按账户过去一小时计算。 | 等待 reset_at、增加 AI 积分，或手动编写映射。 |
{
"error": "quota_exceeded",
"detail": "Usage limit reached. Please try again later.",
"tier": "enterprise",
"remaining": 0,
"reset_at": "2026-11-01T04:00:00+00:00",
"period": "month",
"reset_in_seconds": 1296000
}
示例有意省略四个真实存在的字段。limit 和 used 分别记录组织协议中的额度与已使用量。product 和 meter 标识 Kaleidr Studio 的计数器，而不是 API 计数器；两者共享组织 AI 积分池。应按 error 进行分支处理，与其他配额拒绝相同。
映射建议的计费方式：
- 被拒绝的请求（403、422 或速率限制 429）不消耗积分。 即使请求因样本问题收到 422 响应，也会计入每小时 30 次的限制。
- 未收到模型响应而无法生成建议的 502 不消耗积分。
- 收到模型响应但无法使用的 502，仍会按该响应令牌计费。
- 即使建议的
errors不为空，只要生成了建议，就照常计费。
Studio 中，两种情况分别提示：“You have reached the hourly limit for mapping proposals. Try again later, or edit the mapping by hand.”以及“Your organization's AI credits for this period are used up. You can still write the mapping by hand.”手动编写映射不需要建议，也不会消耗 AI 积分。
2. 暂存预览
| 项目 | 说明 |
|---|---|
| 请求 | POST /shared-api/datahub/ingests |
| 调用者 | Enterprise 组织所有者或管理员 |
| 请求头 | 必需 Idempotency-Key，长度 8 至 128 个字符 |
| 正文字段 | 类型 | 默认值 | 含义 |
|---|---|---|---|
filename | 最长 200 字符的字符串 | 必需 | 必须以 .csv 或 .json 结尾；扩展名决定解析器。 |
artifact | 字符串 | 必需 | 文件的原始文本。 |
source | "csv"、"api" 或 "manual" | "csv" | 只标识数据来源，不决定解析器。"json" 不是合法值，会返回 422。 |
mapping_spec | 最多 64 KB 的对象 | 无 | CSV 列映射。地点 CSV 或 JSON 数据包应省略。 |
preview | 布尔值 | false | true 表示只暂存供检查，false 表示解析后立即发布。 |
org_id | UUID | 主要组织 | 指定上传的组织。 |
curl -X POST https://api.kaleidr.com/shared-api/datahub/ingests \
-H "Authorization: Bearer $KALEIDR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: places-2026-10-10-a" \
-d '{
"filename": "places.csv",
"source": "csv",
"preview": true,
"artifact": "name,timezone,lat,lng,address,category\nHarbor Hotel,Europe/London,51.5079,-0.0877,\"1 Example Street, London\",hotel\n"
}'
{
"ingest_id": "5f0c2a1e-…",
"release_id": "a81d77b0-…",
"status": "pending",
"status_url": "/shared-api/datahub/ingests/5f0c2a1e-…",
"dispatched": true
}
Idempotency-Key 在组织范围内唯一。重复提交同一个键，会返回该键已经创建的处理任务，并设置 dispatched: false，不会创建第二个任务。需要重新暂存（例如修改映射后）时应使用新键，否则会返回旧映射创建的任务。
dispatched 表示这次调用是否已经启动处理。新任务返回 false 说明没有启动，仍停留在 pending；需使用重新派发接口启动。
首次上传以及每次修改映射后都应设置 preview: true。
每次只能处理一个上传任务，并且有每小时次数限制。 如果同一组织已有任务正在运行，或过去一小时已启动 30 次上传，新请求会被拒绝：
| 状态 | detail | 含义 | 处理办法 |
|---|---|---|---|
| 409 | org_ingest_in_progress | 组织另一个任务状态为 running。 | 查询该任务，直到 succeeded 或 failed，然后使用相同的 Idempotency-Key 重试。 |
| 429 | ingest_rate_limited | 组织最近一小时创建了 30 个处理任务，预览也算。 | 等待后重试。可先使用映射建议验证配置，避免反复暂存。 |
| 413 | request_body_too_large | 整个请求超过 32 MiB。 | 缩小文件。参阅限制。 |
重复发送已经使用过的 Idempotency-Key 不算新上传：系统会返回已有的导入任务，不会因上述 409 或 429 限制而拒绝。请求正文不会与首次提交的正文比较，因此使用旧密钥发送的不同文件会被忽略。不过，请求会在查找密钥之前接受校验，所以重试仍可能因 413、403 org_admin_required 或 vendor_data_not_on_plan，或者违反某项限制而收到 422。只要对应的发布版本仍存在，该密钥就会保留；版本被删除或自动清理后，同一密钥将启动一次新上传。
3. 检查结果
| 项目 | 说明 |
|---|---|
| 请求 | GET /shared-api/datahub/ingests/{ingest_id} |
| 调用者 | 任意套餐的所有者或管理员 |
curl https://api.kaleidr.com/shared-api/datahub/ingests/5f0c2a1e-… \
-H "Authorization: Bearer $KALEIDR_ACCESS_TOKEN"
{
"ingest_id": "5f0c2a1e-…",
"release_id": "a81d77b0-…",
"status": "succeeded",
"attempts": 1,
"row_counts": {
"places": 1,
"room_types": 0,
"rate_plans": 0,
"daily_rates": 0,
"daily_inventory": 0,
"hours": 0,
"documents": 0
},
"error_report": null,
"created_at": "2026-10-10T09:12:04Z",
"started_at": "2026-10-10T09:12:20Z",
"finished_at": "2026-10-10T09:12:41Z"
}
status 会从 pending 进入 running，最终成为 succeeded 或 failed。
succeeded：row_counts按数据类型显示成功解析的记录数。发布前应与预期数量核对。failed：error_report.errors会列出无法解析的记录及原因（最多显示 200 条），error_report.error_count是总数。失败的处理任务不会影响当前已发布版本。
{
"status": "failed",
"error_report": {
"errors": [
"places[1]: missing lat/lng -- supply coordinates, or an address to geocode from",
"places[2]: unknown timezone 'London'"
],
"error_count": 2
}
}
上传是全有或全无的操作：只要任意一行验证失败，整个上传都不会暂存。修正文件，并使用新的 Idempotency-Key 重新上传。
4. 发布
| 项目 | 说明 |
|---|---|
| 请求 | POST /shared-api/datahub/ingests/{ingest_id}/publish |
| 调用者 | Enterprise 组织所有者或管理员 |
| 请求 正文 | 无 |
curl -X POST https://api.kaleidr.com/shared-api/datahub/ingests/5f0c2a1e-…/publish \
-H "Authorization: Bearer $KALEIDR_ACCESS_TOKEN"
响应结构与暂存响应相同，但 status: "pending"。只有以 preview: true 暂存并最终 succeeded 的任务才能发布。
发布时会重新处理文件。 系统使用相同文件及映射重新解析，因此计数与标识符和预览一致。唯一可能变化的是仅用地址定位的地点：发布时重新地理编码，如果匹配结果更好，坐标可能略有不同。
再次轮询状态。 处理任务重新回到 pending，然后运行并以 succeeded 结束。此时新版本已经发布，旧版本被取代。
在这里把 409 视为“已经在处理”，而不是需要重复提交的错误。 发布接口不接受也不需要 Idempotency-Key。如果首次请求在客户端超时但服务端已接受，再次调用可能返回 409 ingest_is_not_a_preview；若两次调用重叠则返回 publish_already_in_progress。这些都说明发布已完成或正在进行，应查询任务状态，而非继续调用发布接口。
有一种 409 情况不同：org_ingest_in_progress 表示贵组织还有另一项上传正在处理，所以本次发布并未开始。请等待该导入任务变为 succeeded 或 failed，然后再次调用发布接口。
一步完成发布
提交 preview: false，或省略 preview，系统会在读取文件后直接发布，无需单独调用发布接口。适用于映射已验证的周期性上传。
重新启动停滞的处理任务
| 项目 | 说明 |
|---|---|
| 请求 | POST /shared-api/datahub/ingests/{ingest_id}/dispatch |
| 调用者 | Enterprise 组织所有者或管理员 |
如果处理任务一直停留在 pending（例如 dispatched 为 false），或因非数据问题进入 failed，可使用此接口重新启动。每个任务最多处理三次。
| 状态 | 含义 |
|---|---|
409 ingest_already_succeeded | 任务已成功，无需操作。 |
409 ingest_already_running | 任务正在处理。 |
409 ingest_attempts_exhausted | 已达到三次尝试上限，应使用新的 Idempotency-Key 上传。 |
409 org_ingest_in_progress | 组织另一个处理任务正在运行；等它结束后重试。 |
404 ingest_not_found | 贵组织不存在此 ID 的导入任务，或者其发布版本正在删除或已删除，因此无需重新启动。 |
列出数据版本
| 项目 | 说明 |
|---|---|
| 请求 | GET /shared-api/datahub/releases |
| 调用者 | 任意套餐的所有者或管理员 |
| 查询参数 | 可选 status：draft、published、superseded、failed 或 deleting；其他值返回 422 unknown_release_status。还可传入 org_id。 |
curl "https://api.kaleidr.com/shared-api/datahub/releases?status=published" \
-H "Authorization: Bearer $KALEIDR_ACCESS_TOKEN"
[
{
"id": "a81d77b0-…",
"status": "published",
"published_at": "2026-10-10T09:15:02Z",
"superseded_at": null,
"created_at": "2026-10-10T09:12:04Z",
"state": "published",
"ingest_id": "5f0c2a1e-…"
}
]
| 字段 | 类型 | 含义 |
|---|---|---|
id | UUID | 数据版本 ID，用于取消发布和删除接口。 |
status | 字符串 | draft、published、superseded、failed 或 deleting。 |
published_at | 时间戳或 null | 发布时间。 |
superseded_at | 时间戳或 null | 被替换、取消发布或预览过期的时间 。 |
created_at | 时间戳 | 上传请求被接受的时间。 |
state | 字符串 | 版本当前允许的操作，见下表。 |
ingest_id | UUID 或 null | 生成该版本的处理任务 ID，可用于查询状态或发布。 |
state 在 status 基础上把草稿分成两类，方便客户端无需再次请求就知道应提供哪种操作：
state | status | 含义 | 可执行的操作 |
|---|---|---|---|
processing | draft | 上传排队或正在处理；包括一步发布及正在发布的预览。 | 等待，或删除。 |
preview | draft | 预览暂存成功，等待您的决定。 | 发布或删除。 |
published | published | 当前用于生成回答的版本。 | 取消发布。 |
superseded | superseded | 被新版本替换、取消发布或预览过期。 | 删除。 |
failed | failed | 文件无法正确处理。 | 删除。 |
deleting | deleting | 删除进行中。 | 暂不能执行操作。 |
列表只包含最新的 50 个版本，按时间倒序排列。每个组织最多同时拥有一个 published 版本，取消发布后则一个也没有。正在删除的版本默认不在列表中，除非使用 ?status=deleting 过滤；完成删除后将从所有列表消失。 (参考)
下架数据版本
移除数据需要两个不同的接口：unpublish 让当前已发布版本停止提供服务；delete 删除非已发布版本。两者均允许任何套餐的组织所有者或管理员调用，因此降级后的组织仍可删除数据。两者都不需要请求正文或 Idempotency-Key，重复调用也安全。
在 Kaleidr Studio 中操作
Data for AI Answers 区域的 Releases 列表会根据每个版本状态显示相应操作，并在执行前要求确认。组织离开 Enterprise 后，只要仍保有版本，所有者与管理员仍可以看到包含 Unpublish 和 Delete 的列表，上传控件会替换为“Uploading is part of the Enterprise plan.”提示。
| 行状态 | 操作 | 确认提示 | 后续显示 |
|---|---|---|---|
| Published | Unpublish | “Unpublish this release? Kaleidr AI stops answering from this data until you publish another release. This release cannot be published again.” | 先显示“Unpublishing…”，随后提示“Unpublished. Kaleidr AI no longer answers from this data.”，状态变为 Superseded。 |
| Draft、Superseded、Failed | Delete | “Delete this release? This removes the release and everything made from it, and cannot be undone.” | “Deleting…”，随后显示“Release deleted.”，该行 从列表消失。 |
| Processing | 无 |
每个确认窗口都有对应操作按钮和 Cancel 按钮。界面不会给已发布版本提供 Delete。如果通过 API 尝试直接删除，界面会显示：“This release is published. Unpublish it before you delete it.”详细说明见版本列表。
取消发布版本
| 项目 | 说明 |
|---|---|
| 请求 | POST /shared-api/datahub/releases/{release_id}/unpublish |
| 调用者 | 任意套餐的所有者或管理员 |
| 请求正文 | 无 |
| 查询参数 | 可选 org_id |
curl -X POST https://api.kaleidr.com/shared-api/datahub/releases/a81d77b0-…/unpublish \
-H "Authorization: Bearer $KALEIDR_ACCESS_TOKEN"
{ "release_id": "a81d77b0-…", "status": "superseded" }
接口返回时，该版本立即停止提供服务。随后将发生以下变化：
- 组织不再拥有已发布版本，直到发布另一个版本。之前曾生效的旧版本不会自动恢复。Kaleidr 会继续基于通用知识回答，且回答中不会特别说明您的数据已撤下。
- 无法再次发布同一个版本。 如需恢复相同的数据，必须重新上传文件并发布。
- 该版本会以
superseded状态留在列表中，可以删除，否则会按保留策略自动清理。
| 状态 | detail | 含义 |
|---|---|---|
| 200 | 版本变为 superseded。重复调用仍返回 200；对已经处于 superseded 的版本也一样，包括刚被新发布版本取代的记录。 | |
| 403 | org_admin_required | 当前账户不是该组织所有者或管理员。 |
| 404 | release_not_found | 组织内不存在该版本，或正在删除。 |
| 409 | release_not_published | 版本为草稿或失败，从未提供服务，无需取消发布。 |
删除版本
| 项目 | 说明 |
|---|---|
| 请求 | DELETE /shared-api/datahub/releases/{release_id} |
| 调用者 | 任意套餐的所有者或管理员 |
| 请求正文 | 无 |
| 查询参数 | 可选 org_id |
curl -X DELETE https://api.kaleidr.com/shared-api/datahub/releases/a81d77b0-… \
-H "Authorization: Bearer $KALEIDR_ACCESS_TOKEN"
HTTP/1.1 202 Accepted
{ "release_id": "a81d77b0-…", "status": "deleting", "dispatched": true }
删除会移除版本、为该版本上传的文件及 Kaleidr 根据它生成的全部内容。删除后无法恢复。
- 已发布版本必须先取消发布。 直接删除会返回 409
release_is_published。其他状态的版本都可删除，包括预览、被替换版本、失败版本和正在处理的上传。 - 请求返回 202，实际删除稍后完成。 返回时版本即进入
deleting状态：默认版本列表不再显示，不能发布；其 处理任务返回 404ingest_not_found。 这也适用于读取任务状态和重新派发请求。 dispatched表示这次请求是否启动了删除。false说明系统稍后会自动启动，您也可以重新调用。- 重复调用安全。 删除期间再次调用仍返回 202；完成后版本不存在，返回 404
release_not_found。此时可以把 404 视为“已经删除”。
| 状态 | detail | 含义 |
|---|---|---|
| 202 | 版本正在 deleting，完成前重复调用也返回 202。 | |
| 403 | org_admin_required | 当前账户不是组织所有者或管理员。 |
| 404 | release_not_found | 组织内不存在该版本，包括已完成删除的版本。 |
| 409 | release_is_published | 版本仍处于发布状态；请先取消发布。 |
要确认删除完成，可通过 ?status=deleting 列出版本；空列表表示没有版本仍在删除。
旧版本会自动删除
您不必手动删除已经不是当前版本的数据。Kaleidr 会按照与删除接口相同的方式自动清理：
| 版本状态 | 删除时间 |
|---|---|
superseded：被新版本替换或取消发布 | 被替换或取消发布后 30 天 |
| 从未发布的预览 | 14 天后过期，再过 30 天删除 |
failed | 最后一次处 理结束后 30 天 |
published | 只要仍在发布状态，就不会自动删除 |
删除无法触及的数据
删除完成后，已删除版本不会用于新生成的回答。但删除不能清除有时效的缓存回答、已保存的聊天记录、备份，或处理数据时已发送给模型提供商的文本。完整限制见删除操作无法触及的数据。
限制
组织协议规定的限制
上传文件的大小与记录数量限制由您的组织协议确定。 平台对每项限制都有技术上限，组织合同不得超出这些上限。
| 限制 | Enterprise | 超过限制时 |
|---|---|---|
artifact 大小 | 按组织协议设置 | 上传时返回 422 |
| CSV 行数（不含表头） | 按组织协议设置 | 上传时返回 422 |
| JSON 数据包中的地点数量 | 按组织协议设置 | 上传时返回 422 |
| JSON 数据包中的文档数量 | 按组织协议设置 | 上传时返回 422 |
GET /shared-api/datahub/limits返回适用于当前组织的实际限制。- Free 与 Pro 无法上传，因此没有上传额度；上传请求返回 403
vendor_data_not_on_plan。 - 限制按组织计算。每次发布都会完整替换上一个版本，因此这些限制同时约束单次上传与当前已发布的数据。
上传超过任何限制时返回 422，各条原因都会指出限制值与套餐。下列示例以 <count> 表示实际提交数量，以 <limit> 表示组织限制：
{ "detail": { "errors": ["<count> places exceed the limit of <limit> (enterprise plan)"] } }
其他三个原因具有相同格式：<count> documents exceed the limit of <limit> (enterprise plan)、csv has more than <limit> rows; the places limit is <limit> (enterprise plan) 和 artifact is <size> MB; the limit is <limit> MB (enterprise plan)。文件大小超限时系统不会进一步解析文件，因此只返回这一条原因。
适用于所有组织的固定限制
| 限制 | 数值 | 超限结果 |
|---|---|---|
| 整个上传请求大小 | 32 MiB | 413 request_body_too_large |
| 单次上传房型数 | 10,000 | JSON 上传时 422；映射表处理失败 |
| 单次上传价格方案数 | 10,000 | JSON 上传时 422；映射表处理失败 |
| JSON 数据包营业时间行数 | 25,000 | 上传时 422 |
| 每次上传的每晚价格和可用量记录总数 | 200,000 | 导入失败：daily facts: <count> rows exceed the cap of 200000 |
| 每次上传所有文档的文本总量 | 最多约 600,000 字符；分散在多个文档中时上限会更低 | 导入失败：documents: chunk count exceeds the cap of 500 |
| 上传 JSON 的嵌套深度 | 嵌套过深会被拒绝 | 上传时 422 |
mapping_spec | 64 KB | 上传时 422 |
filename | 最长 200 字符，须以 .csv 或 .json 结尾 | 上传时 422 |
| 每个组织同时运行的上传 | 1 | 409 org_ingest_in_progress (上传、发布和重新派发时) |
| 每组织新上传次数 | 每小时 30 次 | 429 ingest_rate_limited |
映射建议的 csv_head | 16,384 字符 | 422 |
| 映射建议 | 每账户每小时 30 次，每次消耗 AI 积分 | 429，参阅区分两种 429 |
| 每个处理任务的尝试次数 | 3 | 重新派发时 409 |
| 未发布预览 | 14 天 | 发布时 409 |
| 不再是当前版本的版本 | 30 天 | 按保留策略自动删除 |
整个请求限制大于上传文件限制，因为文件作为 JSON 字符串传输，转义字符会增加请求大小。超过 32 MiB 的请求在解析前返回 413；请求总大小未超限但文件超出组织协议限制时返回 422。
大小或记录数超限时会返回 422，最多列出 200 个原因。所有组织共同适用的行数限制会出现如下示例：
{ "detail": { "errors": ["10001 room_types exceed the cap of 10000"] } }
JSON 嵌套过深时会返回相同结构的响应：
{ "detail": { "errors": ["upload is nested too deeply"] } }
CSV 行数限制会统计文件的所有数据行，不论这些行描述何种对象。按每天房价逐行导出的表格很容易触及行数上限。大型价格与库存数据更适合使用 JSON 数据包，后者会在上传时统计地点、文档、房型、价格方案与营业时间记录。
字段限制
每个值都有长度或大小上限。文本按字符计数；自由格式 JSON 值（您提交的对象或数组）按序列化为 JSON 后的字节数计量。
| 列表 | 字段 | 限制 |
|---|---|---|
| 所有列表 | ref、place_ref、room_type_ref、rate_plan_ref | 128 字符 |
places | name | 200 字符 |
places | category | 100 字符 |
places | timezone | 64 字符 |
places | overture_id（可选） | 128 字符 |
places | address | 序列化 JSON 后 2,048 字节 |
places | schema_org（可选对象） | 序列化 JSON 后 16,384 字节 |
room_types | name | 200 字符 |
room_types | amenities（可选数组）、attributes（可选对象） | 各自序列化 JSON 后 8,192 字节 |
rate_plans | name | 200 字符 |
rate_plans | currency（可选） | 3 字符 |
rate_plans | cancellation_policy（可选） | 2,000 字符 |
rate_plans | board_basis（可选） | 100 字符 |
rate_plans | attributes（可选对象） | 序列化 JSON 后 8,192 字节 |
hours | note（可选） | 500 字符 |
documents | title | 300 字符 |
具体在哪个阶段报告超限，取决于提交的格式：
- **JSON 数据包：**上传时检查。接口返回 422，每条原因指明具体行与字段，例如
places[3]: name is longer than 200 characters或room_types[0]: amenities is larger than 8192 bytes as JSON。 - **地点 CSV 或映射电子表格：**在处理任务运行期间验证，失败时
error_report.errors包含相应原因。 (failed)
自定义 JSON 值包含 NaN 或 Infinity 时，会报告 <list>[<row>]: <field> holds a non-finite number。
预览会过期
预览暂存完成后，如果一直没有发布，将在 14 天 后过期并标记为 superseded，暂时仍保留在版本列表中，但不允许发布。发布请求会返回 409 no_previewed_release_to_publish；如需继续应重新上传。与其他被替换版本相同，过期预览会在此后 30 天按保留规则删除；您也可以提前删除。
字段使用说明
**每个地点都必须提供 timezone，而且它会影响回答。**价格与库存以地点的当地日历日期计算，因此悉尼酒店的“今晚”与伦敦酒店的“今晚”对应的 日期可能不同。如果源表没有时区列，应映射一个常量：
{ "timezone": { "const": "Australia/Sydney" } }
应认真选择时区。错误时区会让回答在一天中的大部分时间看似正确，却在午夜前后出错。缺少时区或提供无效 IANA 时区名称都会报错。
如果已有坐标，尽量直接提交。 包含 lat 与 lng 的地点会精确使用所给坐标。仅提供地址时系统会尝试地理编码；如果匹配结果不够可信，会报告该行错误并要求您提供坐标，而不会猜测。把地点错误地标在地图上，比报告无法解析更糟。
重复上传相同的导出文件是安全的。 映射电子表格中的记录 ID 来自 ref_from 指定的列，因此相同导出会产生相同 ID。新发布 版本会替换旧版本，而不是追加。
每个版本都是完整的数据快照。 不会从先前版本继承任何记录。如果新文件不包含上个月的地点，发布后这些地点就不会再出现在回答中。
请发送 UTF-8 文本。 把 ZIP、gzip 压缩文件或 PDF 简单改名为 .csv 或 .json 仍会被拒绝。
错误
除返回原因列表的情况外，上传接口错误响应一般采用 { "detail": "<code>" } 结构。
| 状态 | detail | 含义 |
|---|---|---|
| 401 | 访问令牌缺失、过期或并非访问令牌。 | |
| 403 | org_admin_required | 当前账户不是组织所有者或管理员。 |
| 403 | vendor_data_not_on_plan | 组织未订阅 Enterprise。上传、发布、重新派发都会返回此错误；读取、取消发布和删除不会因套餐被拒绝。 |
| 404 | ingest_not_found | 组织内没有该处理任务，或其版本正被删除/已删除。 |
| 404 | release_not_found | 组织内没有该版本。取消发布、删除时可返回此错误，包括已删除完成的版本。 |
| 409 | release_not_published | 对草稿或失败版本调用取消发布。 |
| 409 | release_is_published | 对已发布版本直接调用删除，需先取消发布。 |
| 409 | ingest_conflict | 两个上传使用同一 Idempotency-Key 发生冲突；重试。 |
| 409 | ingest_is_not_a_preview | 处理任务不是预览，或已请求发布。 |
| 409 | ingest_already_running | 任务正在处理。 |
| 409 | no_previewed_release_to_publish | 预览失败、未完成或已过期。 |
| 409 | publish_already_in_progress | 两次发布调用重叠，已有一个正在执行。 |
| 409 | ingest_already_succeeded | 对已完成任务请求重新派发。 |
| 409 | ingest_attempts_exhausted | 已达到三次处理尝试上限。 |
| 409 | org_ingest_in_progress | 同一组织已有任务正在处理。应等待结束后重试。 |
| 413 | request_body_too_large | 上传请求超过 32 MiB；发布、重新派发和读取接口限制为 1 MiB。 |
| 422 | { "errors": [ … ] } | 文件或映射超出限制、字段超出大小限制、JSON 嵌套过深或文件无法按 CSV/JSON 读取；最多返回 200 条原因，套餐限制错误会指明限制与套餐。 参考 |
| 429 | ingest_rate_limited | 组织最近一小时已启动 30 次上传。 |
| 422 | 验证错误列表 | 缺少字段或字段不合法，例如没有 Idempotency-Key、扩展名错误、source 不在允许的三个值内。 |
| 422 | unknown_release_status | status 过滤器不是五个合法值之一。 |
文件超过组织大小限制时返回 422，并将原因写入 errors。413 表示整个请求超限，其正文为 { "detail": "request_body_too_large" }。
映射建议接口有独立错误说明，参阅建议映射。如果账户不具备上传权限，会返回 403 org_admin_required 或 vendor_data_not_on_plan。当账户达到每小时请求上限或组织 AI 积分耗尽时返回 429。
当前尚不支持的功能
- 增量更新。 不支持 upsert、删除单条记录或查询“自上次以来发生的变化”。新版本会完整替换旧版本，整个版本可以取消发布或删除。
- 重新发布早期版本。 处于 superseded 或已经取消发布的版本不能恢复为当前版本；需重新上传文件。
- 保存映射配置。 每次上传都需传入映射，不能存储映射并通过 ID 引用。
- 连接器。 Kaleidr 不会自动从数据库、预订系统或电子表格服务拉取数据。
- Multipart 或二进制上传。 文件以 JSON 正文中的字符串形式传输。
相关页面
- 使用自有数据生成回答：完整流程、套餐、限制与验证方法，以及所有套餐均可使用的地图数据集功能。
- 认证与权限范围：创建可读取数据的密钥。
- 错误参考：整个 Kaleidr 平台的错误代码目录。