Glossary

The terms these docs use, in alphabetical order. Each entry says what the term means in Kaleidr and links to the page that covers it in depth.

Two pairs are easy to confuse, so they are compared first.

	Allowed origin	Allowed domain
Set on	A publishable key	A published map
Set where	kaleidr.com/api-keys	Kaleidr Studio
Controls	Which sites may use the key	Which sites may show the map
Written as	A full origin: https://www.example.com	A bare host: example.com
Matching	Exact	The host and its subdomains
Checked against	The Origin header of the session exchange	The referrer of the page that embeds the map

	Share id	Style id
Identifies	One published map, with its data and design	One basemap design
Used by	Viewer, and Chat on a published map	Tile and Editor
Example	The id in a Studio embed snippet	kaleidr-morning

Add-on pack

A one-time purchase that adds AI credits or map loads to an organization's pool without changing its plan. See the pricing page.

AI credit

The unit Kaleidr meters AI usage in. Each organization has one pool of AI credits for each billing period. Chat answers and server API calls spend from it, and so do Visitor AI Chat on the organization's published maps and its members' own use of Kaleidr's apps. In API responses the pool is named b2b.tokens. When the pool cannot cover a request, the request is refused with HTTP 429 and "error": "quota_exceeded". See Quota and rate limits.

Allowed domain

A host a published map may be shown on, set by the map's owner in Studio. A bare domain such as example.com also covers its subdomains. A map with no allowed domains can be embedded anywhere. The check uses the referrer of the embedding page, so a page that sends no referrer cannot show a domain-restricted map. Not the same as an allowed origin. See Embed a map.

Allowed origin

A site a publishable key may be used from, written as scheme, host and optional port: https://www.example.com. The match is exact, with no wildcards. A key with no allowed origins works from every site. Not the same as an allowed domain. See Get an API key.

Billing period

The interval after which an organization's AI credits and map loads reset: its subscription cycle when it has a subscription, otherwise the calendar month.

Chat

The product that adds a chat panel to a page. It answers questions about places and shows the answers on a map. See Chat.

Editor

The product that mounts Kaleidr's map editor in a page. Work done in the embedded editor is held in the page's memory and is not saved. See Editor.

Enable gate

The loader's switch for holding mounts, used to wait for a visitor's consent. While the gate is off, a mount loads nothing and returns a handle that does nothing. It has three controls: the page flag window.__KALEIDR_EMBED_ENABLED__, Kaleidr.enable(), and the per-mount enabled option. See Production checklist.

Handle

The object Kaleidr.mount returns. It always has destroy(). setCamera, setTheme and setStyle each work on some products; calling one on a product that does not support it logs a warning and does nothing. A call made before the product is ready is kept and applied when it is. See the handle matrix.

Key API

The HTTP API for creating and managing API keys, at https://api.kaleidr.com/shared-api/api-keys. It is authenticated with the access token of a signed-in organization owner or admin, not with an API key. It offers settings the API Keys page does not. See Get an API key.

Legacy key

An API key created before publishable and server keys existed. It starts with kld_live_, still works, and is sent directly on requests like a server key.

Loader

The script https://cdn.kaleidr.com/embed/v1/kaleidr.js. It defines window.Kaleidr and the <kaleidr-map> element, and fetches each product's code when that product is mounted. See kaleidr.js.

Map load

One start of a Kaleidr map: a published map viewed on a site, a shared map link opened, or a Tile session. Individual map tiles are not counted. Each organization has one pool of map loads for each billing period. See Quota and rate limits.

Mount

To start a product in a page, with Kaleidr.mount(target, options) or by placing a <kaleidr-map> element. Also the running instance that results. Removing it is done with destroy() on its handle or by removing the element.

Organization

The account that owns API keys, published maps, a plan and the usage counted against that plan. Usage is counted for the organization as a whole, not for each key or each member. Owners and admins of an organization manage its keys. See How Kaleidr works.

Origin

A web page's scheme, host and port, as the browser sends it in the Origin header: https://www.example.com or http://localhost:8000. It has no path. Two pages have the same origin only if all three parts match.

Plan

An organization's subscription level: Free, Pro or Enterprise. The plan decides which key types the organization can create, which scopes its keys may carry, how many keys it may hold, and the size of its AI credit and map-load pools. Enterprise allowances are custom and set in a contract. See Get an API key.

Product

One of the four things the SDK mounts: chat, viewer, tile or editor. The word is also the value of the product option and attribute. A key can be restricted to some products.

Publishable key

An API key for use in web pages. It starts with kld_pk_live_ (or kld_pk_test_). It is safe in page source because it cannot call the API directly: the SDK exchanges it for a session token. It can be restricted to allowed origins. Available on every plan. See Get an API key.

Release

One version of the business data an organization has uploaded. A release is a draft, published, superseded or failed; one whose deletion is under way has the status deleting and is left out of lists. Only the published release is read: nothing draws on a release until it is published, and publishing a new one supersedes the one before it. Releases are created and published by an owner or admin of an Enterprise organization, in the Data for AI Answers section of Kaleidr Studio's Data panel or with the upload API. An owner or admin can unpublish the published release and delete any other, on any plan; a release that is no longer current is removed automatically after 30 days. See Your data.

Scope

A permission carried by a key. A product or endpoint requires one scope.

Scope	Allows
ai	Chat, and the server API's chat, place and geocoding endpoints
maps	Tile basemap sessions
design	Editor, and the server API's design endpoints
vendor	Lets Chat answers made with the key draw on the organization's published business data. Never included by default; Enterprise only. Uploading the data is a separate permission, also Enterprise only.

Scopes are set when a key is created and cannot be edited. See Auth and scopes.

Server key

An API key for backend code. It starts with kld_sk_live_ (or kld_sk_test_). It is a secret, sent directly on each request as Authorization: Bearer or X-Api-Key. A request that carries an Origin header is refused, so it does not work from a browser. Available on Pro and Enterprise. See Server quickstart.

Session exchange

The request in which the SDK trades a publishable key, or a published map's share id, for a session token. It happens when a keyed product mounts and again shortly before each session expires. See How Kaleidr works.

Session token

A short-lived credential that starts with kld_sess_. The SDK obtains it through a session exchange and uses it for a product's calls. A session lasts about 15 minutes (five minutes for chat on a published map), is bound to the origin and the product it was issued for, and is renewed by the SDK while the product stays mounted.

Share id

The public id of a map published from Kaleidr Studio. It appears in the map's embed address, https://map-embed.kaleidr.com/embed/<share id>, and is the value of the share-id attribute. It is not a secret: anyone with the id can view the map, subject to the map's allowed domains.

Stream event

One message in the response of a streaming endpoint. The response is a server-sent event stream; each event has a name, such as place or end, and a JSON payload. Pieces of answer text arrive as events with no name. See The stream contract.

Style id

The name of a Kaleidr basemap design, such as kaleidr-morning. It is the value of the style-id attribute on Tile and Editor. A full style address can be given in its place.

Test key

A publishable or server key created for a test environment; its prefix contains test in place of live. It is not a sandbox: it calls the same API and spends the same allowances as a live key. It cannot load basemap tiles. See Get an API key.

Tile

The product that shows a Kaleidr-designed basemap as an interactive map in an iframe. See Tile.

Viewer

The product that shows a map published from Kaleidr Studio, in an iframe. It needs no key. See Viewer.

Visitor AI Chat

A setting on a published map that lets anyone viewing the map use Chat on it with no API key in the page. Answers spend the map owner's AI credits, up to an optional monthly limit the owner sets for that map. See Chat on a published map.