Endpoints

Todos bajo https://api.kaleidr.com/inference-api/b2b/v1/. Autentica con la platform key (auth & scopes). Los endpoints de streaming devuelven text/event-stream (wire contract).

SDK session exchange

El único endpoint que acepta directamente una clave publishable. El SDK lo llama por ti al hacer mount; solo necesitas llamarlo manualmente con infraestructura de auth personalizada.

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

Comprobaciones en orden (por plan/clave):

1. La clave debe ser publishable (publishable_key_required).
2. El header Origin del navegador debe estar presente y en la allowlist de la clave (origin_required / session_origin_mismatch).
3. El producto debe estar permitido para la clave y admitido por el nivel actual de la organización — la admisión efectiva es stored key restrictions ∩ current tier. Una clave Pro degradada a Free solo puede crear sesiones tile (tier_capability_not_allowed); una clave que nunca tuvo el scope devuelve insufficient_scope. Pasar una clave a un viewer embed devuelve product_not_allowed.
4. Para tile: la asignación mensual de map-loads de la organización (map_load_quota_exceeded, 429).

Todas las llamadas de runtime siguientes utilizan el session token devuelto, no la clave.

Formato de session token. kld_sess_{env}_{jwt} (p. ej. kld_sess_live_eyJhbGciOi…). Se presenta como Authorization: Bearer o X-Api-Key. TTL predeterminado de 900s (15 min); máximo del servidor 30 min.

basemap_style_id solo está presente cuando la organización ha almacenado un canvas de basemap predeterminado. El SDK lo aplica cuando el embed no especifica un style propio; la precedencia es styleUrl > styleId > this > kaleidr-morning. Su ausencia significa "el embed decide".

Chat (scope ai)

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 — contrato diferente del control-stream
POST	/chat/button/stream	popup-chat body	SSE — contrato diferente del control-stream
POST	/chat/control/route	{ places[], profile, raw_query }	JSON — los fallos devuelven { "error": "…" } con HTTP 200, no 4xx. Decidir solo por status trata los errores como éxito.
GET	/retrieval/poi/enrich	?lat & lon & name & category & source? & id? & poi_context? & lang?	JSON

Los tres endpoints SSE utilizan tres contratos wire diferentes. Los clientes que reutilicen el parser de control-stream en summary o button streams fallarán. sse-wire-contract documenta la estructura de control-stream.

Design (scope design)

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

Ejemplo

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

Fallos de autenticación

• Sin clave / clave incorrecta → 401.
• Clave válida sin el scope de la ruta → 403 insufficient_scope.
• Publishable key en runtime (sin intercambio previo) → 401 publishable_requires_session.
• Server key en un navegador → 403 server_key_in_browser.
• Server key desde una IP fuera de la allowlist → 403 ip_not_allowed.
• Session token desde un origin fuera de la allowlist → 403 session_origin_mismatch.
• Por encima de la cuota → 429 — consulta Quota & rate limits.

Consulta Errors para ver la tabla completa del envelope.