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 형식. 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는 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는 4xx가 아니라 HTTP 200에서 { "error": "…" } 반환. status만 보면 error를 success로 처리하게 됩니다.
GET	/retrieval/poi/enrich	?lat & lon & name & category & source? & id? & poi_context? & lang?	JSON

세 SSE endpoint는 서로 다른 세 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"}]}'

인증 실패

• key 없음 / 잘못된 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를 참조하세요.