上傳您的企業資料
本功能的用途
通過上傳功能，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。 它會對樣本行執行建議對應，並報告每個區塊產生多少記錄。透過sample_result，您可在上傳前發現看似正確但沒有輸出記錄的對應。 - HTTP 200 不保證
errors為空。 系統仍可能傳回不可執行的對應並列出全部問題，方便您直接修正。常見問題包括：缺少必需欄位、引用不存在的列、無效 IANA 時區或非三個字母的貨幣代碼。 - 最多取五行完整樣本。 如果
csv_head不以換行結束，最後一行會被丟棄，避免把截斷的行誤認為完整行。 - 不會儲存任何內容。 您可以自行修改建議，並在下一步上傳。
| 狀態 | 含義 |
|---|---|
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 不算新上傳：系統會傳回該金鑰先前建立的處理工作（ingest），因此不會因上述 409 或 429 而遭拒。系統不會將這次的請求本文與第一次的本文比較，因此如果使用舊金鑰傳送不同的檔案，新檔案會被捨棄。不過，系統仍會先驗證請求，再查詢該金鑰；因此重送仍可能因請求太大而傳回 413、因 403 org_admin_required 或 vendor_data_not_on_plan 而遭拒，或因違反任何限制而傳回 422。只要所屬版本（release）仍存在，系統便會記住該金鑰；當版本被刪除或自動移除後，同一金鑰會開始一次新的上傳。
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，然後再次呼叫發佈 API。
一步完成發佈
提交 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 巢狀層級 | 巢狀太深的 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 或對應電子錶格：**在處理任務運行期間驗證，處理狀態變為
failed時，error_report.errors會包含相應原因。
自定義 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 平台的錯誤代碼目錄。