Pontos de acesso da API

Cada endpoint público da API da plataforma Kaleidr é descrito em uma seção própria.

• URL base: https://api.kaleidr.com/inference-api/b2b/v1
• Credencial: Authorization: Bearer … ou X-Api-Key: …. No backend, use uma chave de servidor (kld_sk_live_…). No navegador, use um token de sessão (kld_sess_live_…). Uma chave publicável só é aceita na troca por uma sessão. Consulte Autenticação e escopos.
• Corpos: JSON, UTF-8. Envie Content-Type: application/json em cada POST. O corpo pode ter até 2 MiB, ou 5 MiB nos endpoints /design/*. Corpos maiores recebem 413 request_too_large.
• Erros: respostas 4xx ou 5xx com corpo JSON, descritas em Erros. Um endpoint informa falhas com status 200: consulte Rotas.

Os exemplos usam uma chave de servidor armazenada em uma variável de ambiente:

export KALEIDR_KEY="kld_sk_live_…"

Resumo

Endpoint	Finalidade	Escopo	Cobrança
POST /sdk/sessions	Trocar uma chave publicável por uma sessão	Escopo do produto	Um carregamento de mapa para tile; gratuito nos demais casos
POST /sdk/share-sessions	Trocar o ID de um mapa publicado por uma sessão de chat	nenhum	Gratuito
POST /chat/control/stream	Enviar uma pergunta e transmitir resposta, locais, ações e rotas	ai	Créditos de IA pelos tokens utilizados
POST /chat/control/route	Traçar uma rota entre coordenadas conhecidas	ai	Gratuito
GET /retrieval/geocode/forward	Converter texto digitado em locais e endereços	ai	Créditos de IA, taxa fixa
POST /spot	Identificar local, endereço, regiões e conteúdo opcional em um ponto	ai	Créditos de IA, taxa fixa
POST /spot/overview/stream	Transmitir uma breve visão geral de um item retornado por /spot	ai	Créditos de IA pelos tokens utilizados
GET /retrieval/poi/enrich	Obsoleto, use /spot. Detalhes e fotos de um local	ai	Créditos de IA, taxa fixa
POST /chat/summary/stream	Obsoleto, use /spot/overview/stream. Transmitir resumo de local ou edifício	ai	Créditos de IA pelos tokens utilizados
POST /chat/button/stream	Transmitir a resposta a uma pergunta sobre um local	ai	Créditos de IA pelos tokens utilizados
POST /design/analyze	Recomendar um design de mapa para uma tabela de dados	design	Créditos de IA, taxa fixa
POST /design/apply-direct	Criar uma camada de mapa com uma tabela e um estilo	design	Gratuito
GET /design/styles, /design/samples, /design/themes	Catálogos de design	design	Gratuito

O funcionamento das cobranças, reservas e limites está em Cotas e limites de taxa.

Todos os endpoints de execução podem retornar os erros descritos em Erros comuns a todos os endpoints de execução. As seções abaixo listam apenas os erros específicos de cada endpoint.

---

POST /sdk/sessions

Troca uma chave publicável por um token de sessão de curta duração, vinculado à origem da solicitação e a um produto. O SDK faz essa troca a cada montagem com chave. Chame o endpoint diretamente apenas no seu próprio cliente de navegador.

Autenticação: chave publicável. Exige: cabeçalho Origin (adicionado pelo navegador). Cobrança: um carregamento de mapa quando product é tile; caso contrário, nenhuma.

Campo	Tipo	Obrigatório	Observações
product	string	Sim	chat, editor, viewer ou tile.

curl -s https://api.kaleidr.com/inference-api/b2b/v1/sdk/sessions \
  -H "X-Api-Key: kld_pk_live_…" \
  -H "Origin: https://www.example.com" \
  -H "Content-Type: application/json" \
  -d '{"product":"chat"}'

{
  "session_token": "kld_sess_live_eyJhbGciOi…",
  "expires_in": 900,
  "product": "chat",
  "basemap_style_id": null
}

basemap_style_id indica o mapa base padrão da sua organização ou null quando não há um configurado.

Status	Código	Quando ocorre
401	Invalid or missing API key	Chave desconhecida, revogada ou expirada.
403	publishable_key_required	A chave é de servidor ou legada.
403	origin_required	Cabeçalho Origin ausente.
403	origin_not_allowed	A origem não está entre as permitidas para a chave.
403	product_not_allowed	Os produtos permitidos para a chave excluem product.
403	tier_capability_not_allowed	O plano não inclui o produto ou seu escopo.
403	insufficient_scope	A chave foi criada sem o escopo do produto.
422	validação	product está ausente ou não é um dos quatro valores permitidos.
429	rate_limited	Trocas de sessão demais para esta chave. Retry-After: 5.
429	map_load_quota_exceeded	Apenas tile: cota de carregamentos de mapa esgotada.
404	sessions_disabled	Sessões desativadas na plataforma. Entre em contato com o suporte.
503	sessions_not_configured	Falha da plataforma. Tente novamente e, se persistir, contate o suporte.

A duração, as regras de renovação e a ordem dessas verificações estão em Autenticação e escopos: troca de sessão.

POST /sdk/share-sessions

Troca o ID de um mapa publicado por uma sessão de chat, permitindo que visitantes conversem sem precisar colocar uma chave na página. O bloco Kaleidr AI do mapa no Studio precisa ativar o recurso solicitado.

Autenticação: nenhuma. Exige: cabeçalho Origin. Cobrança: nenhuma; as chamadas de chat feitas com a sessão são cobradas da organização proprietária do mapa.

Campo	Tipo	Obrigatório	Observações
share_id	string	Sim	De 1 a 128 caracteres: letras, dígitos, _ e -.
feature	string	Não	control_tower (o padrão), o painel Ask Kaleidr do mapa, ou popups, o chat com IA nos pop-ups. Cada um só é concedido enquanto seu interruptor está ativo.

curl -s https://api.kaleidr.com/inference-api/b2b/v1/sdk/share-sessions \
  -H "Origin: https://www.example.com" \
  -H "Content-Type: application/json" \
  -d '{"share_id":"your-map-id","feature":"control_tower"}'

{ "session_token": "kld_sess_live_eyJhbGciOi…", "expires_in": 300, "product": "chat" }

Status	Código	Quando ocorre
403	origin_required	Cabeçalho Origin ausente.
404	not_found	Nenhum mapa publicado ou link de compartilhamento tem este ID, ou o mapa do link de compartilhamento não está publicado.
403	chat_disabled	O Kaleidr AI do mapa não ativa o recurso solicitado.
403	origin_not_allowed	A página não pertence aos domínios permitidos.
403	owner_has_no_organization	O proprietário não tem uma organização para cobrança.
403	tier_capability_not_allowed	O plano do proprietário não inclui chat.
422	validação	share_id está ausente ou contém caracteres inválidos, ou feature não é nenhum dos dois valores.
429	rate_limited	Trocas demais para este mapa ou a partir deste endereço. Retry-After: 5.
404	sessions_disabled	Sessões desativadas na plataforma.
503	share_grant_unavailable, sessions_not_configured	Falha da plataforma. Tente novamente.

Consulte Kaleidr AI em um mapa publicado.

---

POST /chat/control/stream

Recebe uma pergunta e transmite a resposta: texto enquanto é gerado, locais mencionados com coordenadas, ações no mapa e rotas. É o endpoint que alimenta o Kaleidr Chat.

Autenticação: chave de servidor, token de sessão ou chave legada. Escopo: ai. Cobrança: créditos de IA conforme os tokens usados pela resposta. Resposta: text/event-stream, descrita no contrato de transmissão SSE.

Campo	Tipo	Obrigatório	Padrão	Observações
messages	array de { role, content }	Não	[]	Conversa até aqui, do turno mais antigo ao mais recente, terminando na nova mensagem do usuário. role pode ser user ou assistant. Outros papéis, incluindo system, e mensagens com content vazio são ignorados. A pergunta respondida é a última mensagem user. Limites de tamanho abaixo.
session_id	string	Não	gerado	ID de conversa de 1 a 128 caracteres: letras, dígitos, _, ., : e -. Forneça um ID estável e reutilize-o em todos os turnos. Caso seja omitido, o servidor gera um ID para a solicitação e o devolve nos eventos phase e start.
location	objeto { lat, lng }	Não	nenhum	Local que o usuário está vendo: centro do mapa. Usado para interpretar “perto daqui”.
map_zoom	número	Não	nenhum	Nível de zoom do mapa.
lang	string	Não	"en"	Idioma da resposta no padrão BCP 47, como fr ou pt-BR. Até 35 caracteres.
layout	string	Não	nenhum	O layout do viewer em que a conversa ocorre: "guide" enquanto o viewer incorporado mostra seu layout de guia; caso contrário, omita. Até 16 caracteres.
app_snapshot	objeto	Não	nenhum	Aceito, mas desnecessário; omita.
auto_actions	booleano	Não	nenhum	Aceito, mas desnecessário; omita.

Campos desconhecidos são aceitos e ignorados. Não há um campo para instruções de sistema, persona, ferramentas nem contexto próprio. A solicitação contém apenas a conversa, uma localização e um idioma.

O servidor não armazena a transcrição por você. Envie sempre os turnos anteriores em messages, com o mesmo session_id.

Um session_id pertence somente à sua organização. O contexto de curto prazo da conversa é mantido por organização, de modo que outra organização que envie o mesmo ID não consegue visualizar nem alterar sua conversa. Dentro da sua organização, atribua um ID único à conversa de cada usuário final.

Limites de solicitação

Pedidos que ultrapassem qualquer um desses limites são recusados com 422 antes de gerar uma resposta, sem cobrança. O corpo é {"detail": "<code>"}.

Limite	Valor	Código
Mensagens em messages	400	too_many_messages
Comprimento do content de uma mensagem	64.000 caracteres	message_too_long
Comprimento total de todos os valores content	200.000 caracteres	conversation_too_long
session_id	De 1 a 128 caracteres: letras, dígitos, _, ., :, -	invalid_session_id
lang	35 caracteres	lang_too_long
layout	16 caracteres	invalid_layout

Todas as mensagens contam para esses limites, inclusive as ignoradas. Uma conversa longa costuma atingir o limite de comprimento total antes do limite de quantidade de mensagens. Envie apenas os turnos recentes necessários e remova os mais antigos. Consulte Como ler o fluxo.

curl -N https://api.kaleidr.com/inference-api/b2b/v1/chat/control/stream \
  -H "Authorization: Bearer $KALEIDR_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "session_id": "trip-42",
    "messages": [{"role": "user", "content": "Where is the Louvre, and what is next to it?"}],
    "location": {"lat": 48.8566, "lng": 2.3522},
    "map_zoom": 12,
    "lang": "en"
  }'

-N desativa o buffer de saída do curl para imprimir os quadros assim que chegam. Exemplo de resposta abreviada:

event: phase
data: {"type": "phase", "phase": "thinking", "session_id": "trip-42"}

: keep-alive

event: start
data: {"type": "start", "session_id": "trip-42", "purpose": "control"}

data: {"text": "The [[Louvre Museum]] is on the right bank of the Seine"}

event: place
data: {"name": "Louvre Museum", "coordinates": {"lat": 48.8606, "lng": 2.3376}, "category": "museum"}

data: {"text": ", with the [[Tuileries Garden]] directly to its west."}

event: place
data: {"name": "Tuileries Garden", "coordinates": {"lat": 48.8635, "lng": 2.3275}, "category": "park"}

event: early_actions
data: {"type": "early_actions", "actions": [{"type": "map.fitBounds", "payload": {"coordinates": [[2.3376, 48.8606], [2.3275, 48.8635]], "padding": 50, "maxZoom": 15, "duration": 1000}}], "places_count": 2, "is_partial": true}

event: end
data: {"type": "end", "full_text": "The [[Louvre Museum]] is on the right bank of the Seine, with the [[Tuileries Garden]] directly to its west.", "places": [{"name": "Louvre Museum", "coordinates": {"lat": 48.8606, "lng": 2.3376}, "category": "museum"}, {"name": "Tuileries Garden", "coordinates": {"lat": 48.8635, "lng": 2.3275}, "category": "park"}], "actions": [], "question_type": "…", "response_time": 6.4, "total_tokens": 3120}

event: quota
data: {"type": "quota", "product": "b2b", "meter": "b2b.tokens", "tier": "pro", "used": 184223, "limit": 5000000, "reset_at": "2026-11-01T04:00:00+00:00", "period": "month"}

Status	Código	Quando ocorre
413	request_too_large	O corpo da solicitação supera 2 MiB.
422	validação	O corpo não contém JSON válido ou algum campo tem tipo incorreto.
422	too_many_messages, message_too_long, conversation_too_long, invalid_session_id, lang_too_long, invalid_layout	A solicitação ultrapassa um limite.
429	quota_exceeded	A reserva de créditos de IA ou o teto mensal desta chave é insuficiente.

O evento quota do exemplo é a versão recebida por uma chave de servidor. Um fluxo lido com token de sessão contém uma versão menor: veja o evento quota.

Depois que o streaming começa, uma falha chega como evento error, e não como status HTTP. Para criar um cliente, consulte Leitura do fluxo.

POST /chat/control/route

Calcula uma rota entre coordenadas que você já conhece. Nenhuma pergunta é feita e nenhum texto é gerado.

Autenticação: chave de servidor, token de sessão ou chave legada. Escopo: ai. Cobrança: nenhuma. Mesmo assim, é preciso haver saldo disponível de créditos de IA para a chamada ser aceita.

Campo	Tipo	Obrigatório	Padrão	Observações
places	array de objetos	Sim, pelo menos dois	[]	Cada objeto é { lat, lng, name? }, com lat e lng numéricos diretamente no nível superior do objeto. label pode substituir name. Entradas sem lat e lng numéricos são ignoradas sem erro.
profile	string	Não	"driving"	driving, walking, cycling ou transit. Qualquer outro valor usa driving.
raw_query	string	Não	"Show directions"	Texto digitado pelo usuário, se houver.

O primeiro local é a origem e o último é o destino.

O formato de um lugar é diferente no fluxo

Um evento place no fluxo de chat contém a posição aninhada: { "coordinates": { "lat": …, "lng": … } }. Este endpoint exige lat e lng diretamente no objeto. Enviar um lugar do fluxo sem alterações resulta em error, pois nenhuma entrada contém coordenadas utilizáveis.

curl -s https://api.kaleidr.com/inference-api/b2b/v1/chat/control/route \
  -H "Authorization: Bearer $KALEIDR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "places": [
      {"name": "Louvre Museum", "lat": 48.8606, "lng": 2.3376},
      {"name": "Tuileries Garden", "lat": 48.8635, "lng": 2.3275}
    ],
    "profile": "walking"
  }'

Sucesso é uma resposta 200 com action (valores ilustrativos):

{
  "action": {
    "type": "map.showRoute",
    "payload": {
      "id": "control-directions",
      "label": "Directions",
      "profile": "walking",
      "coordinates": [[2.3376, 48.8606], [2.3352, 48.8619], [2.3275, 48.8635]],
      "distance_m": 870,
      "duration_s": 640,
      "turn_by_turn": [{ "text": "Walk west on Rue de Rivoli." }],
      "attribution": {
        "text": "© OpenStreetMap contributors",
        "url": "https://www.openstreetmap.org/copyright",
        "license": "https://opendatacommons.org/licenses/odbl/"
      }
    }
  },
  "route": { "…": "the full planning result the action was built from" }
}

Desenhe action.payload.coordinates, uma lista de pares [lng, lat]. distance_m está em metros e duration_s em segundos. Exiba attribution.text com link para attribution.url sempre que mostrar a rota.

Para profile: "transit", payload.transit contém uma viagem sem baldeação: caminhada, um trajeto de transporte e outra caminhada. O nível superior não contém attribution; o crédito da operadora fica em payload.transit.attribution. Mostre-o junto à viagem.

Este endpoint informa falhas com HTTP 200

Não conseguir planejar uma rota não é um erro 4xx. A resposta é 200, com uma string error e sem action:

{ "error": "Route planning failed." }

Isso ocorre quando o planejador não consegue conectar os lugares ou falha por qualquer outro motivo. Se menos de dois lugares tiverem coordenadas válidas, o texto será At least two resolved places are required to build a route.. Esse texto foi feito para exibição direta, portanto verifique a presença de error, e não sua redação. Uma viagem de transporte público sem serviço direto responde da mesma forma, com o motivo em palavras e três campos extras: reason, covered e available.

Verifique o corpo da resposta, não o status:

const res = await fetch(`${API}/chat/control/route`, { method: 'POST', headers, body });
if (!res.ok) throw new Error(`route request refused: ${res.status}`); // 401, 403, 422, 429
const data = await res.json();
if (data.error) {
  showMessage(data.error); // a 200 that is a failure
} else {
  drawLine(data.action.payload.coordinates);
}

Falhas de autenticação, escopo, validação, cota e limite de taxa continuam sendo respostas normais 401, 403, 422 e 429.

GET /retrieval/geocode/forward

Converte o texto digitado em locais e endereços correspondentes. Foi criado para campos de pesquisa ou de Origem/Destino.

Autenticação: chave de servidor, token de sessão ou chave legada. Escopo: ai. Cobrança: créditos de IA, taxa fixa por chamada, cobrada mesmo quando results está vazio.

Parâmetro	Tipo	Obrigatório	Padrão	Observações
q	string	Sim		De 1 a 200 caracteres: nome de local, endereço com número de imóvel ou lat,lng digitados.
near_lat	número	Não		De −90 a 90. Prioriza resultados próximos. Usado somente com near_lng.
near_lng	número	Não		De −180 a 180. Usado somente com near_lat.
limit	inteiro	Não	5	De 1 a 20.
mode	string	Não		Modalidade de deslocamento (driving, walking, cycling, transit). Uma viagem curta prioriza resultados próximos.

curl -s -G https://api.kaleidr.com/inference-api/b2b/v1/retrieval/geocode/forward \
  -H "Authorization: Bearer $KALEIDR_KEY" \
  --data-urlencode "q=20 W 34th St, New York" \
  --data-urlencode "limit=3"

{
  "query": "20 W 34th St, New York",
  "results": [
    {
      "lat": 40.7484,
      "lng": -73.9857,
      "display_name": "20 W 34th St, New York, NY 10001",
      "type": "address",
      "source": "…",
      "id": "…",
      "confidence": "exact",
      "attribution": {
        "dataset": "us/ny/city_of_new_york",
        "license": "…",
        "attribution": "Address data from the NYC Department of City Planning."
      }
    }
  ],
  "attribution": {
    "text": "Overture Maps Foundation, overturemaps.org",
    "licenses": [
      "https://cdla.dev/permissive-2-0/",
      "https://www.apache.org/licenses/LICENSE-2.0",
      "https://opensource.foursquare.com/places-notice-txt/",
      "https://docs.overturemaps.org/attribution/"
    ],
    "sources": [
      {
        "dataset": "us/ny/city_of_new_york",
        "license": "…",
        "attribution": "Address data from the NYC Department of City Planning."
      }
    ]
  }
}

Todos os resultados contêm lat, lng, display_name, type e source. Os demais campos aparecem quando aplicáveis:

Campo do resultado	Significado
id	Para um endereço: identificador Kaleidr daquele número de porta, que permanece estável entre atualizações de dados e pode ser armazenado e comparado.
confidence	Como o resultado corresponde ao texto (tabela abaixo). Ausente se lat,lng foi digitado.
approximate, method, matched_numbers, within_m, score	Apenas em endereços estimados (abaixo).
attribution	Condições do conjunto de dados de origem: dataset, license e, quando aplicável, license_url, attribution (crédito a exibir) e use_restriction.

confidence	O resultado é
exact	O número digitado, na rua e localidade indicadas.
fuzzy	O mesmo, apesar de erro de grafia no nome da rua.
name_exact	Um local cujo nome corresponde exatamente às palavras digitadas.
locality	Cidade, região ou bairro indicado no texto.
interpolated, nearest	Estimativa de um número de imóvel ausente nos dados.
partial	Rua cujo nome completo começa com o texto digitado.
name_partial	Local cujo nome compartilha algumas palavras digitadas.
ambiguous	Endereço sem localidade indicada nem referência próxima: uma entre várias opções.

Endereços estimados. Quando o número digitado não consta nos dados, a resposta o coloca na rua correspondente: entre os números conhecidos mais próximos no mesmo lado, no número conhecido mais próximo ou ao longo do quarteirão cuja faixa numérica o contém. O resultado inclui approximate: true e:

Campo	Significado
method	"interpolated" (entre dois números conhecidos), "nearest" (no número conhecido mais próximo) ou "range" (ao longo do quarteirão).
matched_numbers	Números utilizados como base da estimativa.
within_m	Distância em metros entre esses números ou comprimento do quarteirão: limite máximo do desvio se a numeração segue a ordem. Ausente com "nearest".
score	Confiança de 0 a 1. Pontuação baixa indica uma localização aproximada na rua, não a porta exata.

Uma correspondência exata nunca inclui esses campos.

Atribuição. Encaminhe o campo de nível superior attribution junto dos resultados. O campo text é o crédito que deve ser exibido, e licenses contém os termos que acompanham os dados. Se houver endereços, attribution.sources lista cada conjunto de dados de endereços utilizado. Respeite a use_restriction de cada conjunto para esses resultados:

Conjunto de dados	Crédito a exibir	Restrição de uso
au/countrywide (G-NAF)	G-NAF © Geoscape Australia, licenciado pela Commonwealth da Austrália conforme o Open Geo-coded National Address File (G-NAF) End User Licence Agreement.	Não utilizar para gerar endereços ou compilações de endereços para envio postal, a menos que cada endereço seja verificado quanto ao recebimento de correspondência por fonte diferente de G-NAF; o uso deve cumprir os Australian Privacy Principles.
ca/countrywide (Statistics Canada)	Adaptado de Statistics Canada, National Address Register, 2025-07-29. Isso não representa endosso do produto pela Statistics Canada.	Não identificar pessoas, empresas ou organizações, nem sugerir endosso pela Statistics Canada.
us/ny/city_of_new_york	Dados de endereços do NYC Department of City Planning.	Nenhuma.
us/ma/statewide (MassGIS)	MassGIS (Bureau of Geographic Information), Commonwealth of Massachusetts EOTSS	Nenhuma (domínio público).

Nenhuma correspondência e falha interna têm a mesma aparência. Uma consulta sem resultados retorna 200 com "results": []. Uma pesquisa que falha internamente também pode retornar o mesmo; nesse caso, não há cobrança. Trate um array vazio como “nada a mostrar”, e não como erro.

Status	Código	Quando ocorre
422	validação	q ausente, vazio ou com mais de 200 caracteres; limit ou coordenada fora do intervalo permitido.
429	quota_exceeded	Os créditos de IA disponíveis não cobrem a chamada.

POST /spot

Responde o que existe em um ponto: o local clicado pelo usuário, o endereço mais próximo e as regiões que contêm o ponto. Cada valor informa o crédito que precisa ser exibido. Sob solicitação, também inclui conteúdo descritivo e fotos do local.

Autenticação: chave de servidor, token de sessão ou chave legada. Escopo: ai. Cobrança: créditos de IA, taxa fixa por chamada conforme o item mais caro solicitado em want, cobrada mesmo que nada seja encontrado. content ou photos custam a taxa de /retrieval/poi/enrich quando o conteúdo é obtido para esta chamada; caso contrário, address custa a taxa de /retrieval/geocode/forward. Conteúdo já obtido para uma solicitação anterior não é cobrado; assim, essa chamada, se também solicitar address, cobra a taxa de geocodificação. Chamadas que solicitam apenas entities, regions, boundaries ou tenants são gratuitas. O padrão de want inclui address, portanto omitir want cobra a taxa de geocodificação.

Campo	Tipo	Obrigatório	Padrão	Observações
lat	número	Sim		De −90 a 90. O ponto.
lng	número	Sim		De −180 a 180.
zoom	número	Não		De 0 a 24. Nível de zoom do mapa.
hint	objeto	Não		O que o usuário clicou (abaixo).
want	array de strings	Não	["entities", "address", "regions"]	Partes que serão retornadas (abaixo).
lang	string	Não	"en"	Idioma de content. Até 16 caracteres.

O ponto determina o resultado; a dica apenas seleciona. Uma dica escolhe entre o que está no ponto e nunca desloca a resposta. Um lugar a mais de 75 metros de lat, lng não será retornado, qualquer que seja a dica.

Campo hint	Observações
id	Identificador do lugar no Kaleidr: a parte de uma referência poi: após os dois-pontos.
name	Nome do lugar, conforme aparece no rótulo do mapa. Até 200 caracteres. É comparado por correspondência exata com os lugares no ponto e identifica o lugar para content. Quando region_level é county, state ou country, também seleciona a região desse nível cujo nome corresponda, desconsiderando maiúsculas, minúsculas e acentos, entre as regiões no ponto (para estado ou país, também as que ficam a até 5 km do ponto). Se o nome não corresponder a nenhuma delas, nada muda.
category	Categoria do lugar. Até 100 caracteres. Usada para content.
region_level	Com boundaries, retorna somente o contorno da região neste nível (city, county, state ou country); sem essa opção, retorna o contorno de todas as regiões. Com name, a região desse nível tanto em regions quanto em boundaries é aquela selecionada pelo nome.
layer, wiki_title, ta_location_id, yelp_business_id, data_source	Campos aceitos. São usados pelos próprios aplicativos do Kaleidr; omita-os.

Valor de want	Adiciona
entities	O lugar clicado, quando hint identifica um lugar localizado no ponto.
address	O endereço de rua mais próximo.
regions	A cidade e o condado (somente nos Estados Unidos), o estado e o país que contêm o ponto. Se o ponto estiver no mar, a até 5 km da costa, retorna o estado e o país mais próximos.
boundaries	regions, cada uma com seu contorno (apenas um nível quando hint.region_level é informado).
content	Conteúdo descritivo do lugar: resumo, fotos e link. Requer o nome do lugar, obtido do lugar clicado ou de hint.name.
photos	Somente as fotos do lugar. Tem o mesmo custo que content.
tenants	Os lugares identificados pelo nome perto do ponto, do mais próximo ao mais distante: os estabelecimentos em um edifício. Seu aplicativo mantém os que estão dentro da área ocupada pelo edifício que ele exibe.

curl -s https://api.kaleidr.com/inference-api/b2b/v1/spot \
  -H "Authorization: Bearer $KALEIDR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "lat": 40.7484,
    "lng": -73.9857,
    "zoom": 17,
    "hint": {"name": "Empire State Building", "category": "landmark"},
    "want": ["entities", "address", "regions"]
  }'

Uma resposta abreviada com valores ilustrativos:

{
  "spot": { "lat": 40.7484, "lng": -73.9857, "zoom": 17 },
  "entities": [
    {
      "ref": "poi:3f1c2a9e-…",
      "kind": "poi",
      "role": "clicked",
      "name": { "value": "Empire State Building", "license": "CDLA-Permissive-2.0", "attr": "a1" },
      "at": { "lat": 40.74844, "lng": -73.98566 },
      "facts": {
        "category": { "value": "landmark_and_historical_building", "license": "CDLA-Permissive-2.0", "attr": "a1" },
        "website": { "value": "https://www.esbnyc.com", "license": "CDLA-Permissive-2.0", "attr": "a1" }
      }
    }
  ],
  "address": {
    "ref": "address:ka1…",
    "line": { "value": "20 W 34th St, New York, NY 10001", "license": "CDLA-Permissive-2.0", "attr": "a2" },
    "at": { "lat": 40.7484, "lng": -73.9857 }
  },
  "regions": [
    {
      "ref": "region:tiger:3651000",
      "kind": "region",
      "level": "city",
      "name": { "value": "New York", "license": "LicenseRef-Public-Domain", "attr": "a3" },
      "label": { "lat": 40.6976, "lng": -73.9795 }
    },
    {
      "ref": "region:tiger:36",
      "kind": "region",
      "level": "state",
      "name": { "value": "New York", "license": "LicenseRef-Public-Domain", "attr": "a3" },
      "label": { "lat": 42.7559, "lng": -75.8099 }
    }
  ],
  "attributions": {
    "a1": { "text": "© Overture Maps Foundation", "license": "CDLA-Permissive-2.0" },
    "a2": { "text": "Address data from the NYC Department of City Planning.", "license": "CDLA-Permissive-2.0" },
    "a3": { "text": "U.S. Census Bureau, TIGER/Line", "license": "LicenseRef-Public-Domain" }
  },
  "withheld": ["building_facts"]
}

Campo	Significado
spot	O ponto enviado: { lat, lng, zoom }.
entities	O local clicado e, quando solicitados, os estabelecimentos no edifício; caso contrário, um array vazio. Cada entrada contém ref, kind ("poi" para o local clicado, "tenant" para um estabelecimento), role ("clicked" ou "inside"), name, at (posição própria do local, { lat, lng }) e facts (category e, se conhecido, website do local clicado). O ref de um estabelecimento é uma referência poi:, que também pode ter sua descrição transmitida. Ignore entradas de kind desconhecido.
address	Endereço mais próximo ou null: { ref, line, at }.
regions	Regiões que contêm o ponto, da menor para a maior. Cada uma tem ref, kind ("region"), level (city, county, state ou country), name e label: ponto para posicionar o nome da região, { lat, lng }, ou null. Com want: ["boundaries"], também contém geometry, seu contorno em geometria GeoJSON.
content	Aparece quando want inclui content ou photos, o nome do local é conhecido e o conteúdo pode ser retornado. É o objeto de /retrieval/poi/enrich (campos) ou, ao solicitar apenas photos, { photos, source, cached }, ambos acrescidos de license e attr. Pode ser null quando não há conteúdo recuperável.
attributions	Créditos desta resposta: { text, license }, indexados pelo attr de cada valor.
withheld	Conteúdo omitido pela API devido a restrições, agrupado por tipo; array vazio quando nada foi omitido.

Uma ref identifica um elemento para /spot/overview/stream: poi:<id> para um local, address:<id> para um endereço, region:<source>:<id> para uma região (<source> é tiger, nuts ou ne). Os aplicativos próprios do Kaleidr também usam building:<id>, que a API não retorna. Trate as referências como strings opacas.

Exibir a atribuição de cada valor

Cada valor de um conjunto de dados é um objeto { value, license, attr }: dado, licença e chave de attributions. Sempre que exibir um valor, exiba também attributions[attr].text, ao lado ou em uma área de créditos acessível. Uma resposta pode misturar várias fontes; um único crédito para a resposta inteira não é suficiente. Mantenha license e a atribuição com o valor ao armazená-lo ou repassá-lo.

content recebe atribuição da mesma forma, usando seu próprio attr. Um valor com live_only: true pode ser exibido somente ao usuário atual, nunca armazenado nem repassado.

Consulte Licenças de dados para saber o que cada licença exige.

O que a API não retorna

Os próprios aplicativos do Kaleidr exibem mais informações sobre um ponto do que a API, porque parte dos dados não é licenciada para outros sites:

• Valores sob ODbL, derivados do OpenStreetMap: fatos sobre edifícios (andares, altura e classe). Resumos de edifícios também não estão disponíveis.
• Respostas de provedores terceirizados: consultas de endereços em serviços de geocodificação e notas, avaliações e fotos do Yelp e do Tripadvisor.

withheld permite distinguir “não se sabe nada aqui” de “não disponível pela API”. Ele identifica tipos, nunca valores: building_facts quando o ponto está em um edifício; content quando o único conteúdo sobre o local pode não ser disponibilizado. Outras entradas identificam outras partes omitidas da mesma forma.

Erros de POST /spot:

Status	Código	Quando ocorre
413	request_too_large	O corpo ultrapassa 2 MiB.
422	validação	lat ou lng ausente ou fora dos limites, zoom fora de 0 a 24, want com valor desconhecido ou campo longo demais ou malformado.
429	quota_exceeded	Os créditos de IA disponíveis não cobrem a chamada.

Uma parte que não pôde ser consultada é retornada vazia (null ou []). A chamada ainda é cobrada.

POST /spot/overview/stream

Transmite uma descrição escrita curta de um item retornado por /spot, identificado por seu ref.

Autenticação: chave de servidor, token de sessão ou chave legada. Escopo: ai. Cobrança: créditos de IA conforme os tokens usados. Cada descrição é gerada para a solicitação. Resposta: text/event-stream: normalmente um quadro place com o nome completo do local, como "Springfield, Ohio, United States of America", seguido dos quadros de resumo de local. Consulte Streams de resumo e botões.

Campo	Tipo	Obrigatório	Padrão	Observações
ref	string	Sim		Uma ref de uma resposta de /spot, com até 128 caracteres, ou place: (abaixo).
lat, lng	número	Sim		Ponto enviado a /spot.
lang	string	Não	"en"	Idioma da descrição. Até 16 caracteres.
hint	objeto	Somente para place:		{ name, category? }: nome a descrever.

ref	Descrição
poi:<id>	O local.
region:<source>:<id>	A região.
place:	Um nome para o qual Kaleidr não tem registro, como um local que /spot retornou sem entidade. Envie o nome em hint.name.
address:<id>, building:<id>	Não disponível pela API: o fluxo envia um quadro error. Veja O que a API não retorna.

O elemento é localizado novamente em lat, lng, portanto nenhum dado da solicitação é assumido como fato sobre ele. Uma referência poi: a mais de 75 metros do ponto, uma referência region: que não contém o ponto e place: sem hint.name também recebem um quadro error.

curl -N https://api.kaleidr.com/inference-api/b2b/v1/spot/overview/stream \
  -H "Authorization: Bearer $KALEIDR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ref": "poi:3f1c2a9e-…", "lat": 40.7484, "lng": -73.9857, "lang": "en"}'

Uma referência que não pode ser descrita retorna este quadro no lugar de um resumo. Ele contém ref e não inclui partial_text:

event: error
data: {"type": "error", "message": "Nothing to describe here.", "ref": "address:ka1…"}

Status	Código	Quando ocorre
413	request_too_large	O corpo ultrapassa 2 MiB.
422	validação	ref não segue nenhum dos formatos anteriores, lat ou lng ausente ou fora dos limites, ou lang com mais de 16 caracteres.
429	quota_exceeded	Os créditos de IA disponíveis não cobrem a chamada.

Migração dos endpoints descontinuados

GET /retrieval/poi/enrich e POST /chat/summary/stream estão obsoletos. Continuarão respondendo como antes até 2027-01-15 e poderão ser removidos em qualquer momento depois dessa data. Os cabeçalhos das respostas avisam sobre a descontinuação; Deprecation indica o dia da descontinuação, 2026-10-16, como horário Unix:

Deprecation: @1792108800
Sunset: Fri, 15 Jan 2027 00:00:00 GMT
Link: </inference-api/b2b/v1/spot>; rel="successor-version"

O cabeçalho Link de /chat/summary/stream aponta para /inference-api/b2b/v1/spot/overview/stream. Registre o cabeçalho Sunset para identificar as chamadas ainda usadas.

De GET /retrieval/poi/enrich para POST /spot:

Antes	Depois
lat, lon (consulta)	lat, lng (corpo). Observe a mudança do nome.
name, category	hint.name, hint.category
lang	lang, até 16 caracteres
Consulta completa	want: ["content"]
photos_only=true	want: ["photos"]
radius, dataSource, ta_location_id, regionLevel	Omita.
Corpo da resposta	content: mesmo objeto, com live_only acrescentado
attribution	content.attribution

A cobrança é a mesma ou menor: /spot não cobra pelo conteúdo já obtido para uma solicitação anterior. Uma consulta é cobrada pelo item mais caro de want; assim, quando o conteúdo é obtido para a chamada, adicionar entities, address ou regions os retorna na mesma chamada, sem custo extra.

De POST /chat/summary/stream para POST /spot/overview/stream:

Antes	Depois
Local: location, building_properties.name, .category	Chame /spot com o ponto e hint: { name, category }, depois transmita a visão geral do ref do local em entities, com os mesmos lat e lng. Se entities estiver vazio, envie ref: "place:" com o mesmo hint.
building_properties.pid	ref: "poi:<id>"
lang	lang, até 16 caracteres
max_tokens	Omita.
Edifício: type: "building" e seus campos	Sem sucessor. A descrição de edifícios não está disponível pela API.
Quadros	Quadros de resumo de um local, após um novo quadro place que nomeia o local.

GET /retrieval/poi/enrich

Obsoleto

Este endpoint está obsoleto e pode ser removido depois de 2027-01-15. Use POST /spot com want: ["content"]. Consulte Migração de endpoints obsoletos.

Retorna conteúdo descritivo de um local: título, resumo, fotos e link.

Autenticação: chave de servidor, token de sessão ou chave legada. Escopo: ai. Cobrança: créditos de IA, taxa fixa por chamada. A cobrança ocorre mesmo quando nenhum conteúdo é encontrado.

Parâmetro	Tipo	Obrigatório	Padrão	Observações
lat	número	Sim		Latitude do local.
lon	número	Sim		Longitude do local. Observe o nome lon, não lng.
name	string	Não		Nome do local. Recomendado: apenas um ponto frequentemente não encontra nada.
category	string	Não		Categoria do local, conforme o evento place.
radius	inteiro	Não	250	Raio de busca em metros em torno do ponto.
lang	string	Não	"en"	Idioma do conteúdo.
photos_only	booleano	Não	false	Retornar somente fotos (resposta menor, abaixo).
dataSource, ta_location_id, regionLevel	string	Não		Aceitos, mas são dicas para os próprios aplicativos Kaleidr; omita.

curl -s -G https://api.kaleidr.com/inference-api/b2b/v1/retrieval/poi/enrich \
  -H "Authorization: Bearer $KALEIDR_KEY" \
  --data-urlencode "lat=48.8606" \
  --data-urlencode "lon=2.3376" \
  --data-urlencode "name=Louvre Museum" \
  --data-urlencode "category=museum"

{
  "source": "wikipedia",
  "found": true,
  "title": "Louvre",
  "photos": ["https://upload.wikimedia.org/…/Louvre_Museum.jpg"],
  "summary": "The Louvre is a national art museum in Paris, France…",
  "rating": null,
  "phone": null,
  "hours": null,
  "reviews": [],
  "url": "https://en.wikipedia.org/wiki/Louvre",
  "attribution": ["Wikipedia"]
}

Campo	Tipo	Significado
source	string	Origem do conteúdo. "omitted" indica que existe conteúdo, mas ele não pode ser retornado pela API (abaixo).
found	booleano	false quando nada foi encontrado; os demais campos ficam vazios.
title	string	Título do local na fonte.
summary	string ou null	Descrição breve.
photos	array de URLs	Pode estar vazio.
url	string ou null	Link para a página de origem.
attribution	array de strings	Fontes a creditar, como ["Wikipedia"]. Exiba junto com o conteúdo.
rating, phone, hours, reviews		Podem ser null ou vazios. Notas e avaliações de fornecedores licenciados nunca são retornadas pela API.
unverified	booleano	Opcional. true quando a correspondência do local é incerta.

Com photos_only=true, a resposta é { "photos": […], "source": "…", "cached": false }.

Conteúdo não disponibilizado. Alguns conteúdos são licenciados somente para aplicativos do Kaleidr. Se esse for o único conteúdo disponível para um local, a resposta será 200, com "source": "omitted", "found": false e sem conteúdo. A chamada ainda é cobrada. Consulte Licenças de dados.

Status	Código	Quando ocorre
422	validação	lat ou lon está ausente ou não é número.
429	quota_exceeded	Os créditos de IA disponíveis não cobrem a chamada.
500	An internal error occurred. Please try again.	A busca falhou. A chamada continua sendo cobrada.

---

POST /chat/summary/stream

Obsoleto

Este endpoint está obsoleto e pode ser removido depois de 2027-01-15. Use POST /spot/overview/stream. Não há substituto para resumos de edifícios. Consulte Migração de endpoints obsoletos.

Transmite um breve resumo escrito de um local ou edifício. Ele alimenta o cartão de local no Kaleidr Chat.

Autenticação: chave de servidor, token de sessão ou chave legada. Escopo: ai. Cobrança: créditos de IA conforme os tokens usados. Cada resumo é gerado para a solicitação. Resposta: text/event-stream. Consulte Streams de resumo e botões.

O campo type do corpo escolhe o tipo de resumo.

Um edifício ("type": "building"):

Campo	Tipo	Obrigatório	Observações
type	string	Sim	"building".
address	string	Sim	Endereço completo do edifício. Até 500 caracteres.
lat, lng	número	Não	Posição do edifício.
building_levels	inteiro	Não	Número de andares, se conhecido.
building_height_m	número	Não	Altura do edifício em metros, se conhecida.
tenant_names	array de strings	Não	Empresas no edifício. Até 100 nomes de até 200 caracteres cada.
poi_count	inteiro	Não	Quantidade de locais no edifício.
lang	string	Não	Padrão "en". Até 35 caracteres.

curl -N https://api.kaleidr.com/inference-api/b2b/v1/chat/summary/stream \
  -H "Authorization: Bearer $KALEIDR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "building", "address": "20 W 34th St, New York, NY 10001", "lat": 40.7484, "lng": -73.9857}'

event: start
data: {"type": "start", "address": "20 W 34th St, New York, NY 10001"}

data: {"text": "A landmark office tower in Midtown Manhattan"}

event: end
data: {"type": "end", "full_text": "A landmark office tower in Midtown Manhattan…", "parsed": {"…": "…"}, "total_tokens": 910}

event: quota
data: {"type": "quota", "product": "b2b", "meter": "b2b.tokens", "tier": "pro", "used": 185133, "limit": 5000000, "reset_at": "2026-11-01T04:00:00+00:00", "period": "month"}

Um local (type ausente ou "poi"). O corpo aceita location (objeto { lat, lng }), building_properties (objeto), lang e max_tokens (inteiro). Essa variante foi concebida para o painel do próprio Kaleidr, e o significado de seus campos ainda não é um contrato público. Prefira /chat/control/stream para perguntar sobre um local a partir de código próprio.

Campo do local	Limite
building_properties.name, .type, .category, .poi_type	200 caracteres cada
building_properties.pid	128 caracteres
Cada campo de texto em building_properties.event	4.000 caracteres
lang	35 caracteres
max_tokens	Valor acima do padrão do endpoint é reduzido ao padrão. Não é possível pedir uma descrição mais longa.

As duas variantes leem apenas os campos listados aqui. Qualquer outro campo no corpo é ignorado. Um campo acima do seu limite de tamanho é rejeitado com 422 field_too_long, antes de qualquer resumo ser gerado.

Status	Código	Quando ocorre
413	request_too_large	O corpo supera 2 MiB.
422	field_too_long	Um campo ultrapassa seu limite ou tenant_names contém mais de 100 entradas. O corpo é {"detail": "field_too_long"}.
500	Summary stream error	O corpo não pôde ser lido ou a solicitação de edifício não tem address. Este endpoint retorna 500, não 422, para outros corpos incorretos.
429	quota_exceeded	Os créditos de IA disponíveis não cobrem a chamada.

POST /chat/button/stream

Transmite a resposta a uma única pergunta sobre um local, como “Quais são os horários de funcionamento?”. É o endpoint dos botões de perguntas no cartão de lugar do Kaleidr Chat. Não mantém uma conversa: cada chamada é independente.

Autenticação: chave de servidor, token de sessão ou chave legada. Escopo: ai. Cobrança: créditos de IA conforme os tokens usados. Resposta: text/event-stream. Consulte Streams de resumo e botões.

Campo	Tipo	Obrigatório	Padrão	Observações
query	string	Sim		Pergunta. Até 4.000 caracteres.
place_name	string	Não		Nome do local. Até 200 caracteres.
place_type	string	Não		Categoria do local. Até 200 caracteres.
address	string	Não		Endereço do local. Até 500 caracteres.
location	objeto { lat, lng }	Não		Posição do local.
lang	string	Não	"en"	Idioma da resposta. Até 35 caracteres.
description	string	Não		Descrição do local já conhecida. Até 4.000 caracteres.
website	string	Não		Site do local, se conhecido. Até 2.048 caracteres.
stores_preview	array de objetos { name }	Não		Estabelecimentos no local que você já conhece. Até 50 entradas; cada name com até 200 caracteres. Outros campos são ignorados.
button_id, session_id, place_id	string	Não		Identificadores próprios para correlacionar solicitações. Até 128 caracteres cada.

Campos que não aparecem nesta tabela são ignorados. Campos acima do comprimento máximo são recusados com 422 field_too_long antes da geração da resposta.

curl -N https://api.kaleidr.com/inference-api/b2b/v1/chat/button/stream \
  -H "Authorization: Bearer $KALEIDR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What is this place known for?",
    "place_name": "Louvre Museum",
    "place_type": "museum",
    "location": {"lat": 48.8606, "lng": 2.3376}
  }'

event: start
data: {"type": "start", "query_type": "…"}

data: {"text": "The Louvre is best known for"}

event: end
data: {"type": "end", "full_text": "The Louvre is best known for…", "reply": "The Louvre is best known for…", "query_type": "…", "first_token_ms": 820, "total_ms": 3900, "total_tokens": 640}

Status	Código	Quando ocorre
413	request_too_large	O corpo supera 2 MiB.
422	field_too_long	Campo longo demais ou stores_preview contém mais de 50 entradas. O corpo é {"detail": "field_too_long"}.
500	Button chat stream error	O corpo não pôde ser lido ou não contém query. Este endpoint responde 500, e não 422, para outros corpos incorretos.
429	quota_exceeded	Os créditos de IA disponíveis não cobrem a chamada.

---

POST /design/analyze

Examina as colunas e uma amostra da tabela e recomenda como representá-la no mapa.

O Editor incorporado não chama os endpoints de design. Eles formam uma interface REST para suas próprias ferramentas.

Autenticação: chave de servidor, token de sessão ou chave legada. Escopo: design. Cobrança: créditos de IA, taxa fixa por chamada bem-sucedida. Chamadas que falham não são cobradas.

Campo	Tipo	Obrigatório	Observações
columns	array de strings	Sim	De 1 a 256 nomes de coluna, todos únicos.
sampleRows	array de objetos	Não	Até 1.000 linhas, cada objeto com nomes das colunas como chaves.
datasetName	string	Não	Até 512 caracteres.
rowCount	inteiro	Não	Número total de linhas da tabela, igual ou superior a 0.
userGoal	string	Não	Até 1.000 caracteres: o que o mapa deve mostrar.
supportedStyles	array de strings	Não	IDs dos estilos disponíveis, em palavras minúsculas unidas por hífens.

Os nomes dos campos usam camelCase. Campos desconhecidos são ignorados.

curl -s https://api.kaleidr.com/inference-api/b2b/v1/design/analyze \
  -H "Authorization: Bearer $KALEIDR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "datasetName": "stores.csv",
    "columns": ["name", "lat", "lng", "revenue"],
    "sampleRows": [
      {"name": "Downtown", "lat": 40.7128, "lng": -74.0060, "revenue": 120000},
      {"name": "Uptown", "lat": 40.7831, "lng": -73.9712, "revenue": 86000}
    ],
    "rowCount": 240,
    "userGoal": "Show which stores earn the most"
  }'

{
  "datasetProfile": { "…": "what was detected in each column" },
  "designPlan": { "…": "the recommended style, theme and reasoning" },
  "issues": [],
  "recommendation": { "…": "…" },
  "suggestedConfig": { "…": "…" },
  "explanation": "…"
}

Leia designPlan. Ele pode ser null. recommendation, suggestedConfig e explanation são campos antigos mantidos para compatibilidade e previstos para remoção; não dependa deles. issues lista os problemas encontrados nos dados.

Status	Código	Quando ocorre
413	request_too_large	O corpo supera 5 MiB. O mesmo limite se aplica a /design/apply-direct.
422	validação	columns ausente, vazio, longo demais ou duplicado; ou outro limite acima excedido.
429	quota_exceeded	Os créditos de IA disponíveis não cobrem a chamada.
500	map_design_analyze_failed	Análise falhou. Não há cobrança.

POST /design/apply-direct

Cria uma camada de mapa a partir de uma tabela e de um estilo escolhido, sem análise.

Autenticação: chave de servidor, token de sessão ou chave legada. Escopo: design. Cobrança: nenhuma.

Campo	Tipo	Obrigatório	Observações
style	string	Sim	ID de estilo de 1 a 64 caracteres. IDs listados em /design/styles.
config	objeto	Sim	Objeto com location, metric e visual. location.mode ("coordinates" ou "region") e visual.layerName são obrigatórios; os demais subcampos ainda não estão documentados.
table	objeto	Sim	{ fileName?, columns[], rows[] }. Cada linha é um objeto que associa o nome de uma coluna a um valor, e cada valor deve ser string JSON: envie "120000", não 120000. Uma linha com número ou null é rejeitada com 422.
layerLabel	string	Sim	Nome visível da camada, de 1 a 512 caracteres.
themePackId	string	Não	ID de tema de /design/themes. IDs desconhecidos são ignorados.
datasetSource	objeto	Não	{ label, url? }: responsável pela publicação dos dados para a atribuição da camada.
datasetId	string	Não	Até 128 caracteres. Usado como ID da camada.
year	inteiro	Não	De 1800 a 2100.

A resposta sempre contém um status:

{ "status": "applied", "message": null, "spec": { "…": "a partial map specification" } }

status	Significado
applied	spec contém a camada.
unsupported-style	Este estilo não pode ser criado com os dados fornecidos. message informa o motivo.
insufficient-data	A tabela não contém dados necessários, como colunas de posição. message explica.

As três respostas têm status 200. Verifique status.

GET /design/styles, /design/samples, /design/themes

Três catálogos somente de leitura: estilos de mapa disponíveis, mapas de exemplo e pacotes de temas.

Autenticação: chave de servidor, token de sessão ou chave legada. Escopo: design. Cobrança: nenhuma. Essas chamadas contam para o limite de solicitações por minuto da chave, mas não para o limite de concorrência.

curl -s https://api.kaleidr.com/inference-api/b2b/v1/design/styles \
  -H "Authorization: Bearer $KALEIDR_KEY"

Cada resposta agrupa sua lista em uma única chave:

{ "styles": [ { "…": "…" } ] }

/design/samples retorna { "samples": [ … ] } e /design/themes retorna { "themes": [ … ] }.

---

Erros comuns a todos os endpoints de execução

Todos os endpoints, exceto os dois de troca de sessão, podem retornar estes erros antes do processamento específico. Eles são verificados nesta ordem.

Ordem	Status	Código	Quando ocorre
1	401	Invalid or missing API key	Credencial ausente ou chave desconhecida, revogada ou expirada.
2	401	publishable_requires_session	Chave publicável enviada diretamente. Troque por uma sessão primeiro.
2	403	server_key_in_browser	Chave de servidor enviada com cabeçalho Origin.
2	403	session_origin_mismatch	Token de sessão usado de outra origem.
2	403	ip_not_allowed	Chave de servidor ou legada com lista de IPs permitidos, chamada de um endereço fora da lista.
3	403	insufficient_scope	A chave não tem o escopo exigido pelo endpoint.
3	403	tier_capability_not_allowed	A chave tem o escopo, mas o plano atual não o inclui mais.
3	403	product_not_allowed	Chave de servidor ou legada limitada a determinados produtos chamou um endpoint de outro produto. Consulte Restrição de chaves.
4	429	quota_exceeded	Apenas endpoints com cobrança: reserva de créditos ou teto da chave não cobre a chamada.
5	429	visitor_limit_reached	Apenas sessões de mapas publicados: visitante fez solicitações demais.
6	429	rate_limited	Limite de solicitações por minuto da chave esgotado.
7	429	b2b_overloaded, org_overloaded	Chamadas simultâneas demais.

Um corpo acima do tamanho permitido é rejeitado com 413 request_too_large: 2 MiB em todos os endpoints, 5 MiB em /design/*. Se a solicitação declarar seu comprimento, a rejeição ocorre antes de todas as verificações acima.

Os corpos e o tratamento das respostas estão em Erros e Cotas e limites de taxa.

Conteúdo relacionado

• Início rápido no servidor: primeira chamada, passo a passo.
• Contrato de transmissão SSE: todos os eventos dos fluxos.
• Leitura do fluxo: exemplos completos de clientes.
• Licenças de dados: atribuições que devem ser exibidas.