Choose your path

Find the line that matches what you want to build. Each one names the product to use, the key it needs, the lowest plan it runs on and the page to read first. The sections below the table say what you get on each path and what you do not.

I want to…

I want to…	Use	Key	Minimum plan	Read first
Add an AI assistant to a map my site already shows	Chat, attached to your map	Publishable	Free	Quickstart
Add a place-aware chat panel with no map	Chat, without a map	Publishable	Free	Chat attach
Embed a map I designed in Kaleidr Studio	Viewer	None	Free	Embed a map
Let visitors ask questions on a map I published	Viewer and Chat on the same share id	None	Free	Chat on a published map
Show a Kaleidr basemap on my page	Tile	Publishable	Free	Use Tile
Show a Kaleidr basemap with an AI assistant on it	Tile and Chat	Publishable	Free	Chat attach
Put a map editor inside my product	Editor	Publishable	Free	Attach the editor
Get answers, places and routes from my backend	Server API	Server	Pro	Server quickstart
Put my own spreadsheet or geographic file on a map I design	A dataset in Kaleidr Studio's Data panel	None	Free	Datasets on a map
Have Kaleidr Studio's assistant answer from my own business data	Business data upload	None	Enterprise	Your data
Have answers on my own site or backend draw on my own business data	Business data upload and a key with the vendor scope	Publishable or server	Enterprise	Your data
Use Kaleidr in a mobile app	A web view, or the Server API from your backend	Publishable or server	Free or Pro	Mobile apps
Use the SDK in React, Next.js or Vue	Any product	As above	Free	Frameworks

New to Kaleidr altogether? How Kaleidr works explains the pieces this table refers to.

An AI assistant on a map you already run

Use: Chat, mounted with Kaleidr.mount and your live map object. Key: publishable. Plan: Free and up.

You keep your map, your style and your data layers. Chat adds a panel where a visitor asks questions about places in plain language. The answer streams in as text, and Chat puts it on your map: a pin for each place, a camera move to show them, a route line when the question is about getting somewhere.

Guides exist for Mapbox GL JS, MapLibre GL JS, the Google Maps JavaScript API and Leaflet. Supported maps lists what Chat can do on each library.

What you do not get today:

• Chat adds its own pins and lines. It does not change your layers, sources or markers, and the assistant cannot see them.
• Your page gets no events or callbacks from the panel. You cannot be told what was asked, which places were returned or which pin was selected.
• You cannot give the assistant your own instructions, context or tools, or limit the topics it answers.
• You can set the language of the answers, the panel's title and its input placeholder (lang, title, placeholder). The panel's other labels are in English.

Capabilities and limits has the full list. If you need to control what happens with each answer, use the Server API and build the interface yourself.

A chat panel without a map

Use: Chat, mounted without the map option. Key: publishable. Plan: Free and up.

The same panel answers the same questions, and place results appear as cards in the conversation. Nothing is drawn on a map because there is none. This suits a help page, a booking flow or a sidebar. See Chat attach.

A map you designed in Studio

Use: Viewer, as a <kaleidr-map product="viewer"> element or a plain iframe. Key: none. Plan: Free and up.

Design the map in Kaleidr Studio, publish it, and embed it with its id. The plain iframe works on site builders where you cannot add a script. You can restrict the domains a published map may appear on.

Each view of a published map on a site counts as a map load against the map owner's organization. See Embed a map.

Visitors asking questions on your published map

Use: Viewer, plus Chat mounted with the same share-id and a map-target that points at the Viewer element. Key: none. Plan: Free and up.

Switch Visitor AI Chat on for the map in Studio. Anyone who can see the map can then ask it questions, and the answers appear on the published map. No API key is in the page.

Know these before you switch it on:

• You pay for your visitors. Every answer spends your organization's AI credits. You can set a monthly AI credit limit for the map.
• Visitors are rate-limited, per visitor and per map.
• Switching it off takes up to five minutes to reach pages that are already open.
• Answers about your own places depend on availability. The chat can answer from the named places the published map shows, including rows of its uploaded datasets, only where Kaleidr has switched that on. It is off by default. See Answers from the map's own places.

See Chat on a published map.

A Kaleidr basemap

Use: Tile. Key: publishable. Plan: Free and up.

Tile gives you a finished, interactive basemap in an iframe. You choose a style by id, set the camera and can switch the style while the page is open. Chat can be attached to a Tile element, which gives you a designed map with an assistant on it and no map library of your own. Each Tile session counts as one map load.

What you do not get: Tile is the supported way to show a Kaleidr basemap. Loading Kaleidr's styles or tiles into your own MapLibre or Mapbox map is not supported, and because Tile runs in an iframe you cannot add your own layers or markers to it. If you need your own layers, keep your own map and attach Chat to it.

See Use Tile.

A map editor in your product

Use: Editor. Key: publishable. Plan: Free and up.

Editor mounts Kaleidr's map editor in your page: a basemap with tools to add text, images, markers and popups, adjust labels and draw.

Read this before you plan around it: the work lives in the page's memory. Nothing is saved, exported or published from the embedded editor, and your page is not told when the map changes. When the page reloads, the work is gone. One editor can be mounted per page.

That makes the embedded editor suitable for a demo, a try-it-out surface or a sketchpad. It is not a way to give your users a workflow that produces and stores maps. To make maps that persist, use Kaleidr Studio and embed the result with Viewer.

See Attach the editor.

Answers, places and routes from your backend

Use: the Server API over HTTPS. Key: server. Plan: Pro and up.

Your server sends a conversation and receives a stream of events: the answer text as it is written, each place with its name and coordinates, map actions such as fitting a set of places, and routes. Other endpoints return details for one place, geocode an address and plan a route. You decide what to show and how.

Choose this path when you want your own interface, when you need to act on each result in code, or when the client is not a web page.

What to know:

• A server key must stay on your server. Requests that carry an Origin header are refused, so a server key does not work from a browser at all.
• There is no client library and no npm package. You make HTTP requests and read a server-sent event stream; Reading the stream has complete Node and Python clients.
• Messages with the system role are ignored. You cannot change the assistant's instructions.
• The conversation is yours to keep. Send the earlier messages again with each request, and send your own stable session_id for each conversation.

Start at Server quickstart.

Answers that draw on your own data

Kaleidr takes your own data in two ways, and they are separate features. Choose by what you want the data to do:

	Datasets on a map	Business data in AI answers
Plans	Free, Pro and Enterprise	Enterprise only
What you upload	Files: spreadsheets (CSV, TSV, TXT, XLSX, XLS, ODS), geographic files (GeoJSON, JSON, KML, GPX, Shapefile) and GeoTIFF image overlays	Your organization's places, opening hours, rates, availability and documents
Where	The Data panel of a map in Kaleidr Studio, signed in	The Data for AI Answers section of the same panel, or the upload API, as an owner or admin
What it is used for	A layer on the map you are building, shown to visitors of the published map; Studio's AI assistant answers questions about every row of the dataset while the map is open	Answers in Kaleidr Studio, and answers on your own site or backend through a key with the vendor scope
Reached through an API key or the SDK	No	Yes
Limits	By plan	Set in the organization's agreement

Datasets on a map

Use: the Data panel of a map in Kaleidr Studio.

Plan: Free, Pro or Enterprise. You need an account to upload a file: without one, Studio offers one unsaved draft in the browser and asks you to sign up when you add a file. JSON pasted into the uploader is the exception: it is stored inside the map itself, with or without an account, and is not counted against the limits below.

Limit	Free	Pro	Enterprise
Rows in one dataset	50,000	100,000	100,000
Size of one uploaded file	32 MiB	64 MiB	64 MiB
Rows across all of the organization's datasets	250,000	5,000,000	Set in your agreement

100,000 rows in one dataset and 64 MiB for one file are ceilings on every plan, Enterprise included.

A limit refuses a new upload only; data already stored is kept. The plan is the organization's Kaleidr plan, the one bought on kaleidr.com/billing.

What to know:

• The published map shows the data. The datasets and image overlays a map draws are drawn for visitors of the published map and of its share links. A published map is public, so publish only data that anyone may read. See Uploaded data on a published map.
• Studio's AI assistant answers from the whole dataset. It can filter, sort, count, total, average and group the rows and find the rows near a point, one dataset at a time, on the map that is open. See Ask the assistant about a dataset.
• Studio detects the Name, Category, Description and Address columns, and you can correct them. See Column roles.

Datasets on a map has the file types and the limits that are the same on every plan.

Business data in AI answers

Use: business data upload, then Kaleidr Studio's assistant, or Chat or the Server API with a key that carries the vendor scope.

Plan: Enterprise, for uploading and for reading through a key.

On Free and Pro the upload calls return 403 vendor_data_not_on_plan, and a request to create a key with vendor is refused with 403 tier_capability_not_allowed. The upload limits are set in the organization's agreement, and never above the platform's own ceilings: see Your data.

How it works: an owner or admin of an Enterprise organization uploads a file of places and related details and publishes it. They do that in Kaleidr Studio, in the Data for AI Answers section at the bottom of the Data panel of any map, or with the upload API; the two are the same pipeline. From then on, and for as long as the organization is on Enterprise, members of the organization who are signed in to Kaleidr Studio can ask Studio's assistant about the data. A key created with the vendor scope may also draw on that data, and so may a Chat session mounted with that key. Places from your data arrive in the answer marked as yours.

What to know:

• Answers draw on your data alongside Kaleidr's general knowledge. You cannot restrict answers to your data only.
• Upload is by file, in Studio or through the API. There is no connector to a live database and no incremental sync.
• An owner or admin can unpublish and delete a release at any time, on any plan. Releases that are no longer current are removed automatically after 30 days.
• Your data is looked up when a question is answered.
• Your data is isolated to your organization.
• The vendor scope cannot be added on the API Keys page; it is requested through the key API. See Get an API key.

Start at Your data.

Mobile apps

There is no native SDK for iOS or Android, and none for React Native or Flutter. The SDK is for web pages. You have two options:

• A web view. Load a page you host over HTTPS inside your app's web view, and mount the product on that page with a publishable key. Put the page's origin in the key's allowed origins. Host the page instead of bundling it into the app: a local file has no origin that a key can list.
• Your backend. Have your app talk to your own server, and have the server call the Server API with a server key. Your app draws the results with whatever map it uses. This needs Pro.

Never put a server key in an app binary: it can be extracted. Security model covers both options.

What you can control

If your decision depends on governance, this is what a customer controls today:

• Which sites may use a publishable key (allowed origins).
• Which products and scopes a key carries, a monthly AI credit limit for one key, and an expiry date, set through the key API.
• Revoking or rotating a key.
• Holding every embed until a visitor consents, with the page flag window.__KALEIDR_EMBED_ENABLED__ = false set before the loader. Kaleidr.enable(false) holds only mounts made after the call, not <kaleidr-map> elements already in the HTML.
• For a published map: which domains may show it, whether Visitor AI Chat is on, and its monthly AI credit limit.

Not available today: your own instructions or persona for the assistant, topic restrictions, restricting answers to your data, identifying individual end users or giving them different permissions, limiting which map actions the assistant may take, transcripts or audit logs of conversations, and usage events sent to your page.

Security model describes each control.

Next steps

• Quickstart: the three shortest working pages.
• Get an API key: create the key your path needs.
• How Kaleidr works: the model behind all of the above.
• Production checklist: what to settle before you ship.