Endpoints

Todos em https://api.kaleidr.com/inference-api/b2b/v1/. Autentique usando a platform key (auth & scopes). Endpoints de streaming retornam text/event-stream (wire contract).

SDK session exchange

O único endpoint que aceita diretamente uma chave publishable. O SDK o chama para você no mount; você só precisa chamá-lo manualmente com infraestrutura de auth personalizada.

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

Gates em ordem (por plano/chave):

1. A chave deve ser publishable (publishable_key_required).
2. O header de browser Origin deve estar presente e na allowlist da chave (origin_required / session_origin_mismatch).
3. O produto deve ser permitido para a chave e admitido pelo tier atual da organização — a admissão efetiva é stored key restrictions ∩ current tier. Uma chave Pro rebaixada para Free só pode criar sessões tile (tier_capability_not_allowed); uma chave que nunca teve o scope retorna insufficient_scope. Passar uma chave a um viewer embed retorna product_not_allowed.
4. Para tile: a franquia mensal de map-loads da organização (map_load_quota_exceeded, 429).

Todas as chamadas runtime abaixo usam o session token retornado, não a chave.

Formato do session token. kld_sess_{env}_{jwt} (por exemplo, kld_sess_live_eyJhbGciOi…). Apresentado como Authorization: Bearer ou X-Api-Key. TTL padrão de 900s (15 min); máximo do servidor 30 min.

basemap_style_id só está presente quando a organização armazenou um canvas de basemap padrão. O SDK o aplica quando o embed não especifica um style próprio; a precedência é styleUrl > styleId > this > kaleidr-morning. Ausente significa "o 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 do control-stream
POST	/chat/button/stream	popup-chat body	SSE — contrato diferente do control-stream
POST	/chat/control/route	{ places[], profile, raw_query }	JSON — falhas retornam { "error": "…" } em HTTP 200, não 4xx. Decidir apenas pelo status trata erros como sucesso.
GET	/retrieval/poi/enrich	?lat & lon & name & category & source? & id? & poi_context? & lang?	JSON

Os três endpoints SSE usam três wire contracts diferentes. Clientes que reutilizam o parser control-stream em streams summary ou button irão falhar. sse-wire-contract documenta o formato 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

Exemplo

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

Falhas de autenticação

• Sem chave / chave inválida → 401.
• Chave válida sem o scope da rota → 403 insufficient_scope.
• Publishable key em runtime (isto é, sem troca prévia) → 401 publishable_requires_session.
• Server key em um navegador → 403 server_key_in_browser.
• Server key de um IP fora da allowlist → 403 ip_not_allowed.
• Session token de uma browser origin fora da allowlist → 403 session_origin_mismatch.
• Acima da quota → 429 — consulte Quota & rate limits.

Consulte Errors para a tabela completa do envelope.