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 の current tier に認められている必要があります — effective admission は stored key restrictions ∩ current tier です。 Pro key が Free に downgrade されると tile session のみ mint できます （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 は、key ではなく返された session token を使用します。

Session token format. kld_sess_{env}_{jwt}（例： kld_sess_live_eyJhbGciOi…）。Authorization: Bearer または X-Api-Key として提示します。Default TTL 900s（15 min）、server max は30 minです。

basemap_style_id は org に 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 は 4xx ではなく HTTP 200 で { "error": "…" } を返す。status だけで分岐すると error を success と扱います。
GET	/retrieval/poi/enrich	?lat & lon & name & category & source? & id? & poi_context? & lang?	JSON

3つの SSE endpoint は それぞれ異なる3つの wire contract を使用します。 summary や button stream に control-stream parser を再利用すると client は壊れます。 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"}]}'

Auth failure

• key なし / 不正 → 401。
• 有効な key だが route の scope がない → 403 insufficient_scope。
• runtime で publishable key を直接使用（事前 exchange なし）→ 401 publishable_requires_session。
• Browser 内の server key → 403 server_key_in_browser。
• 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 を参照してください。