Endpoints

Alle unter https://api.kaleidr.com/inference-api/b2b/v1/. Authentifiziere dich mit dem Platform Key (auth & scopes). Streaming-Endpoints geben text/event-stream zurück (wire contract).

SDK-Session-Exchange

Der einzige Endpoint, der einen Publishable Key direkt akzeptiert. Das SDK ruft ihn beim Mounten für dich auf; du rufst ihn nur bei eigener Auth-Integration selbst auf.

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

Prüfungen in Reihenfolge (je Plan/Schlüssel):

1. Der Schlüssel muss publishable sein (publishable_key_required).
2. Der Browser-Origin-Header muss vorhanden sein und in der Allowlist des Schlüssels stehen (origin_required / session_origin_mismatch).
3. Das Produkt muss für den Schlüssel und den aktuellen Tier der Organisation zugelassen sein — die effektive Zulassung ist stored key restrictions ∩ current tier. Ein Pro-Key, der auf Free heruntergestuft wurde, kann nur Tile-Sessions erstellen (tier_capability_not_allowed); ein Schlüssel, der den Scope nie hatte, gibt insufficient_scope zurück. Wird ein Schlüssel an ein Viewer-Embed übergeben, folgt product_not_allowed.
4. Für tile: das monatliche Map-Loads-Kontingent der Organisation (map_load_quota_exceeded, 429).

Alle Runtime-Aufrufe darunter verwenden das zurückgegebene Session-Token, nicht den Schlüssel.

Session-Token-Format. kld_sess_{env}_{jwt} (z. B. kld_sess_live_eyJhbGciOi…). Gesendet als Authorization: Bearer oder X-Api-Key. Standard-TTL 900s (15 min); Server-Maximum 30 min.

basemap_style_id ist nur vorhanden, wenn die Organisation eine Standard-Basemap-Canvas gespeichert hat. Das SDK verwendet sie, wenn das Embed keinen eigenen Style nennt; Priorität: styleUrl > styleId > this > kaleidr-morning. Fehlt der Wert, bedeutet dies "das Embed entscheidet".

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 — anderer Contract als control-stream
POST	/chat/button/stream	popup-chat body	SSE — anderer Contract als control-stream
POST	/chat/control/route	{ places[], profile, raw_query }	JSON — Fehler geben { "error": "…" } bei HTTP 200 zurück, nicht 4xx. Wer nur nach Status verzweigt, behandelt Fehler als Erfolg.
GET	/retrieval/poi/enrich	?lat & lon & name & category & source? & id? & poi_context? & lang?	JSON

Die drei SSE-Endpoints verwenden drei unterschiedliche Wire Contracts. Clients, die den Control-Stream-Parser für Summary- oder Button-Streams wiederverwenden, brechen. sse-wire-contract dokumentiert die Control-Stream-Struktur.

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

Beispiel

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

Authentifizierungsfehler

• Kein / ungültiger Schlüssel → 401.
• Gültiger Schlüssel ohne Scope der Route → 403 insufficient_scope.
• Publishable Key zur Runtime (also vorher nicht ausgetauscht) → 401 publishable_requires_session.
• Server Key im Browser → 403 server_key_in_browser.
• Server Key von einer IP außerhalb seiner Allowlist → 403 ip_not_allowed.
• Session-Token aus einem Browser-Origin außerhalb der Allowlist → 403 session_origin_mismatch.
• Kontingent überschritten → 429 — siehe Quota & rate limits.

Siehe Errors für die vollständige Envelope-Tabelle.