Endpoints

全部位於 https://api.kaleidr.com/inference-api/b2b/v1/ 下。使用 platform key 進行身分驗證（auth & scopes）。Streaming endpoint 傳回 text/event-stream（wire contract）。

SDK session exchange

唯一直接接受 publishable key 的 endpoint。SDK 會在 mount 時 自動呼叫；只有使用 custom auth plumbing 時才需要自行呼叫。

Method	Path	Body	Returns
POST	/sdk/sessions	{ product: "chat" | "editor" | "viewer" | "tile" }	{ session_token, expires_in, product, basemap_style_id? }

Gate 依以下順序執行（按 plan/key）：

1. key 必須是 publishable（publishable_key_required）。
2. browser Origin header 必須存在並位於 key 的 allowlist 中 （origin_required / session_origin_mismatch）。
3. Product 必須同時被 key 以及 org 目前 tier 允許 — effective admission 為 stored key restrictions ∩ current tier。Pro key 降級至 Free 後只能 mint tile session （tier_capability_not_allowed）；從未擁有該 scope 的 key 會傳回 insufficient_scope。向 viewer embed 傳入 key 會傳回 product_not_allowed。
4. 對 tile：org 的 monthly map-loads allowance （map_load_quota_exceeded, 429）。

下方所有 runtime call 都使用傳回的 session token，而不是 key。

Session token 格式。 kld_sess_{env}_{jwt}（例如 kld_sess_live_eyJhbGciOi…）。透過 Authorization: Bearer 或 X-Api-Key 提交。預設 TTL 為 900s（15 min）； server 最大值為 30 min。

basemap_style_id 只有在 organization 已儲存 default basemap canvas 時 存在。當 embed 未指定自己的 style 時，SDK 會套用它； 優先順序為 styleUrl > styleId > this > kaleidr-morning。 不存在時代表「由 embed 決定」。

Chat（ai scope）

Method	Path	Body	Returns
POST	/chat/control/stream	{ messages[], location?, map_zoom?, lang?, session_id?, app_snapshot?, auto_actions? }	SSE — control-stream contract
POST	/chat/summary/stream	{ type: "poi" | "building", … }	SSE — 與 control-stream 不同的 contract
POST	/chat/button/stream	popup-chat body	SSE — 與 control-stream 不同的 contract
POST	/chat/control/route	{ places[], profile, raw_query }	JSON — failure 會在 HTTP 200 下傳回 { "error": "…" }，而不是 4xx。只依 status 判斷會把錯誤當成成功。
GET	/retrieval/poi/enrich	?lat & lon & name & category & source? & id? & poi_context? & lang?	JSON

這三個 SSE endpoint 使用三個不同的 wire contract。如果 client 在 summary 或 button stream 中重複使用 control-stream parser，就會出錯。 sse-wire-contract 記錄了 control-stream 結構。

Design（design scope）

Method	Path	Body	Returns
POST	/design/analyze	{ dataset: {…columns, sample_rows[]}, prompt?, options? }	JSON recommendation (metered)
POST	/design/apply-direct	parsed dataset + roles	JSON partial MapSpec
GET	/design/styles	—	style catalog
GET	/design/samples	—	worked-sample catalog
GET	/design/themes	—	theme-pack catalog

範例

curl -N https://api.kaleidr.com/inference-api/b2b/v1/chat/control/stream \
  -H "X-Api-Key: kld_sk_live_…" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{"messages":[{"role":"user","content":"cafes near the Louvre"}]}'

身分驗證失敗

• 沒有 key / key 錯誤 → 401。
• 有效 key 但缺少 route scope → 403 insufficient_scope。
• runtime 中直接使用 publishable key（即未先 exchange）→ 401 publishable_requires_session。
• 瀏覽器中的 server key → 403 server_key_in_browser。
• 來自 key allowlist 外 IP 的 server key → 403 ip_not_allowed。
• 來自 key allowlist 外 browser origin 的 session token → 403 session_origin_mismatch。
• 超過 quota → 429 — 請參閱 Quota & rate limits。

完整 envelope table 請參閱 Errors。