Endpoints

Tous sous https://api.kaleidr.com/inference-api/b2b/v1/. Authentifiez-vous avec la platform key (auth & scopes). Les endpoints de streaming renvoient text/event-stream (wire contract).

SDK session exchange

Le seul endpoint qui accepte directement une clé publishable. Le SDK l’appelle pour vous au mount ; vous ne l’appelez vous-même qu’avec une infrastructure d’auth personnalisée.

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

Contrôles dans l’ordre (selon plan/clé) :

1. La clé doit être publishable (publishable_key_required).
2. Le header browser Origin doit être présent et dans l’allowlist de la clé (origin_required / session_origin_mismatch).
3. Le produit doit être autorisé pour la clé et admis par le niveau actuel de l’organisation — l’admission effective est stored key restrictions ∩ current tier. Une clé Pro rétrogradée vers Free ne peut créer que des sessions tile (tier_capability_not_allowed) ; une clé n’ayant jamais eu le scope renvoie insufficient_scope. Passer une clé à un viewer embed renvoie product_not_allowed.
4. Pour tile : l’allocation mensuelle de map-loads de l’organisation (map_load_quota_exceeded, 429).

Tous les appels runtime ci-dessous utilisent le session token renvoyé, pas la clé.

Format du session token. kld_sess_{env}_{jwt} (par ex. kld_sess_live_eyJhbGciOi…). Présenté comme Authorization: Bearer ou X-Api-Key. TTL par défaut 900s (15 min) ; maximum serveur 30 min.

basemap_style_id n’est présent que lorsque l’organisation a stocké un canvas de basemap par défaut. Le SDK l’applique lorsque l’embed ne spécifie aucun style propre ; priorité : styleUrl > styleId > this > kaleidr-morning. Son absence signifie "l’embed décide".

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 — contrat différent du control-stream
POST	/chat/button/stream	popup-chat body	SSE — contrat différent du control-stream
POST	/chat/control/route	{ places[], profile, raw_query }	JSON — les échecs renvoient { "error": "…" } avec HTTP 200, pas 4xx. Se baser uniquement sur le status traite les erreurs comme des succès.
GET	/retrieval/poi/enrich	?lat & lon & name & category & source? & id? & poi_context? & lang?	JSON

Les trois endpoints SSE utilisent trois wire contracts différents. Les clients qui réutilisent le parser control-stream pour les streams summary ou button casseront. sse-wire-contract documente la structure 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

Exemple

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

Échecs d’authentification

• Pas de clé / mauvaise clé → 401.
• Clé valide sans le scope de la route → 403 insufficient_scope.
• Publishable key au runtime (donc non échangée au préalable) → 401 publishable_requires_session.
• Server key dans un navigateur → 403 server_key_in_browser.
• Server key depuis une IP hors de l’allowlist → 403 ip_not_allowed.
• Session token depuis un browser origin hors de l’allowlist → 403 session_origin_mismatch.
• Quota dépassé → 429 — consultez Quota & rate limits.

Consultez Errors pour le tableau complet de l’envelope.