Endpoints

جميعها تحت https://api.kaleidr.com/inference-api/b2b/v1/. تتم المصادقة باستخدام platform key (auth & scopes). وتعيد streaming endpoints text/event-stream (wire contract).

SDK session exchange

الـ endpoint الوحيد الذي يقبل مفتاح publishable مباشرةً. يستدعيه 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? }

يتم تطبيق gates بالترتيب (حسب الخطة/المفتاح):

1. يجب أن يكون المفتاح publishable (publishable_key_required).
2. يجب أن يكون header باسم browser Origin موجودًا وضمن allowlist الخاصة بالمفتاح (origin_required / session_origin_mismatch).
3. يجب أن يكون Product مسموحًا للمفتاح و مسموحًا به ضمن current tier للمؤسسة — effective admission هي stored key restrictions ∩ current tier. مفتاح Pro تم تخفيضه إلى Free لا يمكنه سوى mint لـ tile sessions (tier_capability_not_allowed)؛ أما المفتاح الذي لم يمتلك scope مطلقًا فيعيد insufficient_scope. وتمرير مفتاح إلى viewer embed يعيد product_not_allowed.
4. بالنسبة إلى tile: monthly map-loads allowance الخاصة بالمؤسسة (map_load_quota_exceeded, 429).

جميع runtime calls أدناه تستخدم session token الذي تم إرجاعه، وليس المفتاح.

صيغة Session token. kld_sess_{env}_{jwt} (مثل kld_sess_live_eyJhbGciOi…). ويتم تقديمه كـ Authorization: Bearer أو X-Api-Key. Default TTL هو 900s (15 min)؛ والحد الأقصى من server هو 30 min.

توجد basemap_style_id فقط عندما تكون المؤسسة قد خزنت default basemap canvas. ويطبقها SDK عندما لا يحدد embed style خاصًا به؛ وترتيب الأولوية هو styleUrl > styleId > this > kaleidr-morning. وعدم وجودها يعني "embed هو الذي يقرر".

Chat (نطاق 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 — عقد مختلف عن control-stream
POST	/chat/button/stream	popup-chat body	SSE — عقد مختلف عن control-stream
POST	/chat/control/route	{ places[], profile, raw_query }	JSON — تُعاد حالات الفشل كـ { "error": "…" } عند HTTP 200 وليس 4xx. الاعتماد على status يجعل الأخطاء تبدو نجاحًا.
GET	/retrieval/poi/enrich	?lat & lon & name & category & source? & id? & poi_context? & lang?	JSON

تستخدم SSE endpoints الثلاثة ثلاثة wire contracts مختلفة. العملاء الذين يعيدون استخدام control-stream parser مع summary أو button streams سيتعطلون. توثق sse-wire-contract بنية control-stream.

Design (نطاق 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

مثال

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

حالات فشل المصادقة

• لا يوجد مفتاح / مفتاح غير صالح → 401.
• مفتاح صالح دون scope الخاص بالـ route → 403 insufficient_scope.
• Publishable key أثناء runtime (أي لم يتم exchange له أولًا) → 401 publishable_requires_session.
• Server key في browser → 403 server_key_in_browser.
• Server key من IP خارج allowlist الخاصة بالمفتاح → 403 ip_not_allowed.
• Session token من browser origin خارج allowlist الخاصة بالمفتاح → 403 session_origin_mismatch.
• تجاوز quota → 429 — راجع Quota & rate limits.

راجع Errors للاطلاع على جدول envelope الكامل.