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。