ビジネスデータをアップロードする

この機能の位置づけ

アップロードすると、Kaleidr が組織独自のデータに基づいて質問に回答できるようになります。これは Enterprise 向け機能です。公開済みのデータは、サインインしたメンバーが Kaleidr Studio のアシスタントで利用できます。自社サイトやバックエンドで利用するには、データを参照できるキーを発行し、そのキーで質問し、自社の場所が回答に含まれることを確認する 3 つの手順が必要です。自社データを使った回答に全体の流れがあります。このページではアップロードに必要なリクエスト、フィールド、制限、エラー、公開解除と削除を説明します。

これは Studio の地図の Data パネルに追加する表計算ファイル、GeoJSON、GPX トラックなどについてのページではありません。それは全プランで利用できる別機能です。地図上のデータセットを参照してください。

アップロード方法は 2 つありますが、どちらも同じ処理を使用します：

画面： Kaleidr Studio の地図の Data パネル下部にある Data for AI Answers セクション。唯一のアップロード画面で、操作できるのはアップロード権限のある組織のオーナーまたは管理者だけです。Studio でアップロードを参照。
このページの API： Studio の画面も同じ API を使います。ファイル形式、制限、状態、エラーは共通で、どちらで作成したデータバージョンも他方で確認できます。

アップロード前に知っておくべき 3 つの特徴：

質問への回答時にデータを参照します。 Kaleidr はその時点の公開済みリリースを参照するため、公開を解除すると、それ以降の回答は直ちにそのデータを使用しなくなります。
データは自組織のみに提供されます。 組織単位で分離され、一般消費者向け Kaleidr マップや他組織への回答には表示されません。
値を勝手に生成しません。 任意の補助機能がヘッダーと最大 5 行のサンプルから列マッピングを提案します。承認したマッピングに従ってすべての行が変換されます。間違ったマッピングは修正して再実行し、価格、日付、名前を創作しません。

利用条件

要件	詳細
プラン	Enterprise。Free と Pro ではアップロード、公開、再処理、マッピング提案が 403 `vendor_data_not_on_plan` を返します。対象は kaleidr.com/billing で契約する組織のプランで、Studio 固有のプランはありません。
権限	組織のオーナーまたは管理者。それ以外は 403 `org_admin_required`。
上限	組織の契約で決定。詳しくは制限。`GET /shared-api/datahub/limits` で確認できます。参照
画面	Kaleidr Studio の Data パネルにある Data for AI Answers、またはこの API。チェックは共通です。

呼び出しと必要なプラン・権限：

処理	権限	プラン
マッピング提案、アップロード、公開、再実行	オーナーまたは管理者	Enterprise
制限、取り込み状況、バージョン一覧の参照	オーナーまたは管理者	すべて
公開解除、バージョン削除	オーナーまたは管理者	すべて

後半の 2 行は全プランで使えます。Enterprise を解約した組織でも、過去にアップロードした内容を確認して削除できます。

データの利用も Enterprise 限定です。組織が Enterprise にある間だけ Studio アシスタントが公開データから回答します。API キーまたは SDK を使って回答に組織データを含めるには、Enterprise だけが持てる vendor スコープが別途必要です。自社データを使った回答を参照。

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 の場合、3 つの数値は契約によって異なるため、例には固定値を記載していません。limits には以下の 3 つの整数フィールドが常に含まれます。

{
  "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	1 回の場所数。CSV ではデータ行数。
`limits.documents`	integer	1 回の文書数。
`limits.artifact_mb`	integer	ファイルサイズ（MiB）。
`reason`	string または null	`can_upload` が `false` なら `vendor_data_not_on_plan`、それ以外は `null`。利用不可の上限値はすべて 0。

数値は組織の契約で個別に定められたものです。ただし、いずれもアップロード処理自体が受け付けられる上限を超えることはできません。プラットフォームは 3 つの項目それぞれに技術的な上限を設けており、契約でもその上限は引き上げられません。

ステータス	意味
200	すべてのプランのオーナーまたは管理者。Enterprise 未満では拒否ではなく `can_upload: false` を返します。
401	アクセストークンがない、期限切れ、またはアクセストークンではありません。
403 `org_admin_required`	組織のオーナーまたは管理者ではありません。

認証

すべての呼び出しで、サインイン中の Kaleidr アカウントのアクセストークンを Bearer として送信します：

Authorization: Bearer <account access token>

API キーではありません。kld_pk_… や kld_sk_… は拒否されます。キーは連携を識別しますが、データのアップロードは組織管理の操作なので、権限を持つ人物による認証が必要です。
ID トークンではなくアクセストークンを使用します。
トークンはサインインしたオーナーか管理者のもので、セッションとともに期限切れになります。長期認証情報は現時点でありません。自動アップロードを実装する前に Kaleidr にお問い合わせください。
Studio 画面では別途取得不要です。サインイン中のメンバーのセッションを使います。

このページのエンドポイントはすべて https://api.kaleidr.com 配下です。例では環境変数からトークンを読み取ります：

export KALEIDR_ACCESS_TOKEN='<account access token>'

複数組織を管理する場合、アップロード本文またはその他の呼び出しのクエリ ?org_id= に org_id を指定します。省略すると主組織が選ばれます。

アップロードできるもの

1 回のアップロードは JSON リクエストに文字列として含めるテキストファイル 1 つです。ファイル名の拡張子によって読み取り方式が決まります。

元データ	送信形式	含まれる情報
場所一覧	固定カラム名の `.csv`、マッピングなし	場所
宿泊日・部屋・料金ごとに 1 行の表	`.csv` と `mapping_spec`	場所、部屋タイプ、料金プラン、日別料金、在庫
すべてを構造化済み	`.json` バンドル	上記に加えて営業時間と文書

アップロードには少なくとも 1 件の場所が必要です。

場所一覧の CSV

ヘッダーには次の列名を使います：

列	必須	備考
`name`	はい	名前のない行があると行番号付きでエラーになります。
`timezone`	はい	`Europe/London` などの IANA タイムゾーン。
`lat`, `lng`	位置指定のいずれか	指定した座標をそのまま使用。
`address`	位置指定のいずれか	`lat` と `lng` がない場合に座標を特定。
`category`	いいえ	`hotel` や `restaurant` などの短い分類名。
`ref`	いいえ	独自 ID。なければ行番号で識別。

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

列マッピングを使う表

宿泊施設、部屋、プラン、日付、価格などの観測値ごとに 1 行ある表は固定列名だけでは解釈できません。各フィールドに対応する列を示す 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`	1 つの項目を識別する列。同じ値を持つ行は同じ場所、部屋タイプ、プランとして扱われます。
`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`, `price_amount`, `price_currency`	`price_currency`
`daily_inventory`	`stay_date`, `units_available`	なし

次の 2 つに違反すると検証エラーになります：

表にないフィールドは拒否されます。 エラーには問題のフィールドと許可値が示されます：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 ファイルは次のリストを含む 1 つのオブジェクトです。項目間の参照には 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` は一意。場所が少なくとも 1 件。
`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 として記録されます。

数値は有限でなければなりません。座標、価格、個数、自由形式 JSON 内で NaN や Infinity は許可されず、行エラーになります。

アップロードの流れ

1 回のアップロードから、処理ジョブの 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 文字。アカウントごとに 1 時間 30 回。
費用	提案ごとに 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 を確認します。 提案をサンプル行に適用し、セクションごとの生成件数を表示します。マッピングが正しそうでも生成件数がゼロならここで分かります。
200 でも errors は空とは限りません。 列不足、存在しない列名、不正な IANA タイムゾーン、通貨コードの形式などをまとめて返すため、修正できます。
サンプルは最大 5 件の完全な行だけです。 csv_head の最後が改行で終わらない場合、その行は途中で切れている可能性があるので破棄されます。
データは保存されません。 提案を編集して次のステップで送信します。 (sample_result)

ステータス	意味
403 `org_admin_required`	どの組織のオーナー・管理者でもありません。
403 `vendor_data_not_on_plan`	組織の管理権限はありますが Enterprise 組織がありません。
422	`csv_head` が 16,384 文字超、ヘッダーなし、列名重複、完全なデータ行なし。`detail` に理由が入ります。
429（レート）	アカウントから直近 1 時間に 30 件超。
429（AI クレジット）	組織の期間内クレジットが尽きました。
502 `mapping proposal unavailable`	提案を作成できません。再試行するか手動で定義してください。

2 種類の 429 を見分ける

どちらも HTTP 429 を返します。本文を確認してください：

	レート制限	AI クレジット不足
本文	`{ "detail": "at most 30 mapping proposals per hour" }`	標準クォータ本文
識別方法	`error` フィールドなし。`detail` は左記メッセージ。	`"error": "quota_exceeded"` と `limit`, `used`, `remaining`, `reset_at`。
対処	1 アカウントの直近 1 時間の制限なので待つ。	`reset_at` を待つ、クレジットを追加する、手動マッピングを作る。

{
  "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
}

例には実際には存在する 4 フィールドが省略されています。limit と used は契約に基づく組織の枠と使用量です。product と meter は提案が Studio 機能であるため Studio の計測名を示し、API 側のものではありません。ただしクレジットプールは同じです。他のクォータ拒否と同様に error で判定します。

提案の課金方法：

403、422、レート制限の 429 で拒否された呼び出しは消費しません。サンプルの不備によって 422 で拒否されたリクエストも、1 時間あたり 30 件の上限には計上されます。
応答が届かず提案を作れなかった 502 は消費しません。
応答が生成されたものの利用できなかった 502 では、その生成トークンが課金されます。
errors が空でない提案も生成されたため通常どおり課金されます。

Studio では時間当たりの提案回数制限と AI クレジット不足を別々のメッセージで表示します。マッピングは手動でも作成・編集でき、その場合 AI クレジットは不要です。

2. プレビューをステージする


リクエスト	`POST /shared-api/datahub/ingests`
権限	オーナーまたは管理者、Enterprise
ヘッダー	`Idempotency-Key`（8～128 文字、必須）

本文フィールド	型	既定値	意味
`filename`	最大 200 文字の string	必須	`.csv` か `.json` で終わる名前。拡張子でパーサーを選びます。
`artifact`	string	必須	ファイルの生テキスト。
`source`	`"csv"`、`"api"`、`"manual"`	`"csv"`	データ元のラベル。パーサー選択には使われません。`"json"` は無効で 422。
`mapping_spec`	最大 64 KB の object	なし	表の列マッピング。単純な場所 CSV と JSON バンドルでは省略。
`preview`	boolean	`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 は組織単位で管理されます。同じキーの再送信は新規処理を作らず、既存の ingest を dispatched: false とともに返します。マッピングを修正して意図的に再ステージする場合は新しいキーを使ってください。同じキーでは古い結果が返ります。

dispatched は今回の呼び出しで処理が開始されたかを表します。新規 ingest で false なら pending のままなので、再ディスパッチで開始します。

初回アップロードやマッピングを変更したときは preview: true を使います。

同時に 1 回、1 時間当たりの上限もあります。 同じ組織の取り込みが実行中か、直近 1 時間に 30 回開始している場合、新しいアップロードは拒否されます：

ステータス	`detail`	意味	対処
409	`org_ingest_in_progress`	組織の別ジョブが `running`。	`succeeded` か `failed` まで確認し、同じ `Idempotency-Key` で再送信。
429	`ingest_rate_limited`	直近 1 時間に 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
  }
}

アップロードはすべて成功するか、すべて失敗するかのどちらかです。1行でも検証に失敗すれば、そのアップロードからは何もステージングされません。ファイルを修正し、新しい 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 は不要です。クライアント側でタイムアウトしても Kaleidr 側で成功していた場合、再試行は 409 ingest_is_not_a_preview を返します。公開リクエストが重なった場合は 409 publish_already_in_progress です。どちらも公開が進行中または完了済みであることを示します。繰り返し公開するのではなく、取り込み処理のステータスを確認してください。

409 には別のケースがあります。org_ingest_in_progress は組織の別のアップロードが処理中であり、今回の公開処理は開始されなかったことを意味します。その取り込み処理が succeeded または failed になるまで待ち、再度公開を呼び出してください。

1回の操作で公開する

preview: false を指定するか preview を省略すると、ファイルの読み込み後に自動公開されます。別途公開リクエストを送る必要はありません。マッピングの検証が済んだ定期アップロードに使用してください。

停止した取り込み処理を再開する


リクエスト	`POST /shared-api/datahub/ingests/{ingest_id}/dispatch`
実行できるユーザー	Enterprise のオーナーまたは管理者

取り込み処理が pending のまま進まない場合（dispatched が false など）、またはデータ自体が原因ではない理由で failed になった場合に使用します。1つの取り込み処理は最大3回まで実行されます。

ステータス	意味
409 `ingest_already_succeeded`	処理済みのため、何もする必要はありません。
409 `ingest_already_running`	現在処理中です。
409 `ingest_attempts_exhausted`	3回の試行を使い切りました。新しい `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 を基にしながら下書きを2つの状態に分けるため、追加のAPI呼び出しなしで表示可能な操作を判断できます。

`state`	`status`	意味	可能な操作
`processing`	`draft`	アップロードが待機中または読み込み中です。1段階での公開やプレビューからの公開処理中も含みます。	待機、または削除
`preview`	`draft`	プレビューのステージングが完了し、判断を待っています。	公開または削除
`published`	`published`	回答に利用される公開リリースです。	公開停止
`superseded`	`superseded`	新版への置換、公開停止、プレビュー期限切れのいずれかです。	削除
`failed`	`failed`	アップロードを読み込めませんでした。	削除
`deleting`	`deleting`	削除中です。	なし

一覧には最新50件のリリースが新しい順に表示されます。組織ごとに同時に published となるリリースは1件までで、公開停止後は0件です。削除中のリリースは ?status=deleting を指定しない限り一覧から除外され、削除完了後はすべての一覧から消えます。

リリースを取り下げる

データを取り下げる操作は2つに分けられています。公開停止は公開リリースの提供を止め、削除は未公開のリリースを消去します。どちらもすべてのプランのオーナーまたは管理者が実行でき、Enterprise 以外へ変更した組織でも過去のデータを取り下げられます。いずれも本文や Idempotency-Key は不要で、繰り返し実行しても安全です。

Kaleidr Studio での操作

Data for AI Answers にある Releases 一覧の各行には、その状態に応じた操作が表示され、送信前に確認が求められます。Enterprise を解約した組織でも、リリースが残っている間はオーナーと管理者が一覧と2つの操作を使用できます。その場合はアップロード手順の代わりに「アップロードは Enterprise プランの機能です。」と表示されます。

行の表示	操作	確認メッセージ	続いて表示される内容
Published	Unpublish	「このリリースの公開を停止しますか？別のリリースを公開するまで Kaleidr AI はこのデータで回答しません。このリリースを再公開することはできません。」	「公開停止中…」の後に「公開を停止しました。Kaleidr AI はこのデータで回答しなくなりました。」と表示され、行は Superseded になります。
Draft、Superseded、Failed	Delete	「このリリースと派生データをすべて削除しますか？元には戻せません。」	「削除中…」の後に「リリースを削除しました。」と表示され、行が消えます。
Processing	なし

各確認画面には操作用ボタンと Cancel ボタンがあります。公開中のリリースには Delete が表示されません。APIで削除を試みた場合は「このリリースは公開中です。削除する前に公開を停止してください。」と表示されます。詳しくは Releases 一覧を参照してください。

リリースの公開を停止する


リクエスト	`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" }

リクエストが返された時点でリリースの提供は停止します。その結果は以下のとおりです。

次のリリースを公開するまで、組織に公開リリースはなくなります。 以前のリリースが自動的に復活することはありません。回答は一般知識に基づいて継続し、データが消えたことは通知されません。
このリリースは再公開できません。 同じデータを復元するにはファイルを改めてアップロードして公開してください。
リリースは 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 となり一覧から除外され、公開不可になります。取り込み処理の取得も 404 ingest_not_found を返します。これは状態の照会と再ディスパッチにも適用されます。
dispatched はこの呼び出しで削除を開始したかを示します。false でも少し後で自動開始され、再送も可能です。
再送しても安全です。 削除中は同じ 202 を返し、完了後はリリースが存在せず 404 release_not_found を返します。この 404 は「削除済み」と扱ってください。

ステータス	`detail`	意味
202		リリースは `deleting` で、削除完了まで再送しても同じ応答になります。
403	`org_admin_required`	組織のオーナーまたは管理者ではありません。
404	`release_not_found`	完全削除済みも含め、組織に該当リリースがありません。
409	`release_is_published`	公開中です。公開停止してから削除してください。

削除を確認するには ?status=deleting でリリース一覧を取得します。空であれば削除進行中のリリースはありません。

古いリリースの自動削除

現行ではなくなったリリースを手動削除する必要はありません。Kaleidr が削除 API と同じ方法で自動的に除去します。

リリース	削除時期
`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 が返されます。
制限は組織単位です。公開時に以前のリリースを丸ごと置き換えるため、各制限は1回のアップロードと公開データの両方に適用されます。

制限を超えるアップロードには 422 が返され、理由に制限値とプランが示されます。送信した件数を <count>、組織の上限を <limit> と表します。

{ "detail": { "errors": ["<count> places exceed the limit of <limit> (enterprise plan)"] } }

残り3種類のメッセージも次の形式です。<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`
1回のアップロードの客室タイプ数	10,000	JSON ではアップロード時 422、マッピング済みシートでは取り込み失敗
1回のアップロードの料金プラン数	10,000	JSON ではアップロード時 422、マッピング済みシートでは取り込み失敗
JSON バンドルの営業時間行数	25,000	アップロード時 422
1 回のアップロードに含まれる宿泊日ごとの料金と空室数の行数の合計	200,000	取り込み失敗：`daily facts: <count> rows exceed the cap of 200000`
1 回のアップロードに含まれる全ドキュメントのテキストの合計	最大約 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` (アップロード、公開、再ディスパッチ時)
組織ごとの新規アップロード数	1時間に30件	429 `ingest_rate_limited`
提案用の `csv_head`	16,384文字	422
マッピング提案	アカウントごとに1時間30件、各提案はAIクレジットを使用	429：2種類の429の見分け方
1つの取り込み処理の実行回数	3	再実行時409
未公開のプレビュー	14日	公開時409
現行ではなくなったリリース	30日	自動削除

ファイルは JSON 内で文字列として送られ、エスケープによりサイズが大きくなるため、リクエスト全体の上限はファイルの上限より大きくなっています。32 MiB を超えたリクエストは読み込み前に 413 で拒否されます。リクエスト全体は上限内でも組織のファイルサイズ制限を超えた場合は 422 です。

サイズまたは件数の制限を超えると、最大200件の理由一覧を伴う 422 が返されます。すべての組織に共通する行数制限を超えた場合の例は次のとおりです。

{ "detail": { "errors": ["10001 room_types exceed the cap of 10000"] } }

JSON のネストが深すぎて読み取れない場合も同じ形式になります。

{ "detail": { "errors": ["upload is nested too deeply"] } }

CSV の上限では、各行が何を表していてもファイル内の行数として数えられます。1泊ごとに1行があるシートはすぐに上限に達します。大規模な料金と在庫のセットは 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" } }

時間帯は慎重に選択してください。誤った時間帯では1日の大半で正しくても、深夜前後に誤った回答になります。時間帯が欠けている場合や実在しない IANA 名称の場合はエラーになります。

座標がある場合は指定してください。 lat と lng はそのまま使用されます。住所しかない場所は住所から位置を特定しますが、信頼性の低い一致は推測せずに拒否され、該当行がエラーとして報告されます。その場合は座標を指定してください。誤った場所にピンを置くより未解決として報告する方が適切です。

同じエクスポートを再アップロードしても安全です。 マッピング済みシートでは ref_from で指定した列から識別子が生成されるため、同じファイルなら同じ識別子になります。新しいリリースは古いリリースを置き換えるだけで、追加されません。

各リリースは単独で完全なデータを含む必要があります。 以前のリリースからデータを引き継ぎません。先月の場所が新しいファイルになければ、公開後は回答にも表示されません。

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` の2つのアップロードが競合しました。再試行してください。
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`	3回試行済みの処理に再実行を要求しました。
409	`org_ingest_in_progress`	組織内で別の取り込み処理を実行中です。完了まで待ってください。
413	`request_body_too_large`	アップロードリクエストは 32 MiB 超です。公開・再実行・参照リクエストは 1 MiB が上限です。
422	`{ "errors": [ … ] }`	ファイルやマッピング、フィールドのサイズ制限超過、過度な JSON ネスト、CSV/JSON としての読み込み失敗です。理由が文で列挙され、プラン制限の超過時は値とプラン名が示されます。
429	`ingest_rate_limited`	組織が過去1時間に30件のアップロードを開始しました。
422	検証エラー一覧	`Idempotency-Key` の欠落、拡張子の不一致、`source` の無効な値など
422	`unknown_release_status`	`status` フィルターが許可される5つの値に含まれません。

組織のファイルサイズ制限を超えると、errors に理由を含む 422 を返します。リクエスト全体のサイズが上限を超えると 413 と { "detail": "request_body_too_large" } を返します。

マッピング提案にはマッピングを提案するで説明する固有のエラーがあります。アップロードできないアカウントには 403 org_admin_required または vendor_data_not_on_plan、時間あたりの上限超過や組織のAIクレジット不足には 429 が返されます。

現在提供されていない機能

差分更新。 upsert、個別レコード削除、「前回からの変更」を取得するAPIはありません。リリースは前のリリースを丸ごと置き換え、リリース単位で公開停止や削除ができます。
以前のリリースの再公開。 superseded または公開停止されたリリースを現行に戻せません。ファイルを再アップロードしてください。
保存されたマッピング。 マッピングは各アップロードで送信し、IDで保存・再参照する仕組みはありません。
コネクター。 Kaleidr はデータベース、予約システム、スプレッドシートサービスからデータを自動取得しません。
マルチパート形式やバイナリファイル。 ファイルは JSON 本文内の文字列として送信します。

この機能の位置づけ​

利用条件​

組織がアップロードできる量​

認証​

アップロードできるもの​

場所一覧の CSV​

列マッピングを使う表​

JSON バンドル​

アップロードの流れ​

1. マッピングを提案する（任意）​

2 種類の 429 を見分ける​

2. プレビューをステージする​

3. 結果を確認する​

4. 公開する​

1回の操作で公開する​

停止した取り込み処理を再開する​

リリース一覧​

リリースを取り下げる​

Kaleidr Studio での操作​

リリースの公開を停止する​

リリースを削除する​

古いリリースの自動削除​

削除対象に含まれないもの​

制限​

契約で定める制限​

すべての組織に共通する制限​

フィールドごとの制限​

プレビューの期限切れ​

フィールドの注意事項​

エラー​

現在提供されていない機能​

関連ページ​