Endpoints

All under https://api.kaleidr.com/inference-api/b2b/v1/. Authenticate with the platform key (auth & scopes). Streaming endpoints return text/event-stream (wire contract).

SDK session exchange

The one endpoint that accepts a publishable key directly. The SDK calls it for you on mount; you only call it yourself with custom auth plumbing.

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

Gates in order: key must be publishable (publishable_key_required), browser Origin present and allowlisted (origin_required / origin_not_allowed), product allowed for the key (product_not_allowed), required scope present (insufficient_scope), and — for tile — the org's monthly map-loads allowance (map_load_quota_exceeded, 429). All runtime calls below use the returned session token, not the key.

basemap_style_id is present only when the organization has stored a default basemap canvas. The SDK applies it when the embed does not name a style of its own; the precedence is styleUrl > styleId > this > kaleidr-morning. Absent means "the embed decides", which is also what an older API returns.

Chat (ai scope)

Method	Path	Body	Returns
POST	/chat/control/stream	{ messages[], location?, map_zoom?, lang?, session_id? }	SSE
POST	/chat/summary/stream	{ type: "poi" | "building", … }	SSE
POST	/chat/button/stream	popup-chat body	SSE
POST	/chat/control/route	{ places[], profile, raw_query }	JSON route
GET	/retrieval/poi/enrich	?lat&lon&name&category&…	JSON

Design (design scope)

Method	Path	Body	Returns
POST	/design/analyze	dataset sample	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

Example

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"}]}'

No / bad key → 401. Valid key without the route's scope → 403 (insufficient_scope). Over quota → 429. See Errors.