Answers from your own data

Kaleidr takes your own data in two separate ways. They are different features with different purposes, and the one you use depends on what you want the data to do.

• Datasets on a map are files you add to a map in Kaleidr Studio: a spreadsheet of stores, a GeoJSON file of districts, a GPX track. They are available on every plan to a signed-in user, and they are what you build a map from. The published map shows them to its visitors, and Studio's AI assistant answers questions about them while you work.
• Business data in AI answers is your organization's own places, with their opening hours, rates, availability and documents, which Kaleidr looks up when it answers a question, in Kaleidr Studio and through your API keys. It is available to Enterprise organizations.

This page lays the two side by side, covers datasets on a map in full, and then walks the Enterprise path from uploading a file to seeing your own places arrive in an answer.

Two ways to bring your data

	Datasets on a map	Business data in AI answers
Plans	Free, Pro and Enterprise	Enterprise only
Who adds the data	A signed-in user, on a map they are editing	An owner or admin of the organization
What you upload	Files: tables (CSV, TSV, TXT, XLSX, XLS, ODS), geographic files (GeoJSON, JSON, KML, GPX, Shapefile) and GeoTIFF image overlays	Your organization's places, opening hours, room types, rate plans, nightly rates, availability and documents, as a .csv or .json file
Where	The Data panel of a map in Kaleidr Studio	The Data for AI Answers section of the same panel, or the upload API
What the data belongs to	The map you added it to	The organization, on every one of its maps
What it is used for	Drawing the data as a layer on that map, in Studio and for visitors of the published map, and answering your questions about the dataset in Studio's AI assistant while that map is open	Answers: Kaleidr looks the data up when a question is asked, in Kaleidr Studio and on calls made with a key that carries the vendor scope
Reached through an API key or the SDK	No	Yes
Limits	By plan: see Dataset limits	Set in the organization's agreement

The two do not feed each other. A dataset on a map is not looked up by answers made with an API key, and business data published for AI answers does not add a layer to a map.

Datasets on a map: Free, Pro and Enterprise

Sign in to Kaleidr Studio, open a map and open the Data panel. Choose + Upload Dataset, then Choose file and pick the file, check the preview, and choose Add Data. The file is stored with your account and belongs to that map.

Without an account there are no saved maps and no file uploads. Studio offers one unsaved draft in the browser, and asks you to sign up when you add a file.

Pasted JSON is stored inside the map. The uploader also takes JSON pasted as text: an object with columns and rows. There is no file to store, so the rows are written into the map itself. This is the same for every user, signed in or not: a guest can add pasted JSON to the browser draft without the sign-up prompt. Pasted JSON is not a stored dataset and is not counted against the dataset limits.

What you can add

Kind	File types
Tables	CSV, TSV, TXT, XLSX, XLS, ODS
Geographic files	GeoJSON, JSON, KML, GPX, Shapefile
Image overlays	GeoTIFF

What a dataset does

• It is drawn on the map you are editing. In Studio, the dataset appears as a layer of the map it was added to, and you style it like any other layer.
• Visitors of the published map see it. When you publish the map or create a share link, the datasets and image overlays the map draws are drawn for visitors too, in the embedded viewer and on the share link. A published map shows the map as it is currently saved, so a dataset you add to a map that is already published is public as soon as the map is saved, with no re-publish. Only data the published map includes is served. Deleting the dataset stops it everywhere, share links included; unpublishing the map stops its embeds and leaves share links working. Uploaded data on a published map has the rules.
• Studio's AI assistant answers questions about it while that map is open. The assistant works on every row of the dataset, not on a sample: it can filter, sort, count, total, average and group the rows, and find the rows near a point or inside an area. See Ask the assistant about a dataset.
• Studio detects which column names each row. After an upload, the dataset has a Name, a Category, a Description and an Address column where Studio found one, and you can correct them. See Column roles.
• It is not read through an API key or the SDK. Bringing your data into answers on your own site or backend is the Enterprise path below.
• Visitor AI Chat can answer from its rows, where that is available. On a published map, Visitor AI Chat can answer from the rows of the datasets the map draws when the dataset has a Name column and point coordinates. This is not on for every map: see Answers from the map's own places.

Ask the assistant about a dataset

Open the map in Studio and ask Studio's AI assistant in plain language. The assistant answers from the whole dataset, so a count is a count of every row and a ranking is a ranking of every row, whatever the size of the file.

You can ask it to	Example question
Describe the data	"What is in stores.csv, and which column should I color the map by?"
Filter the rows	"Which stores have revenue over 500,000?"
Sort and rank	"List the ten stores with the highest revenue."
Count, total and average	"How many stores are in Texas, and what is their average revenue?"
Group by a column	"How many stores are there per city?"
Find rows near a point or inside an area	"Which stores are within 2 kilometers of latitude 47.6062, longitude -122.3321?"

How the answers behave:

• A description covers every row. For each column the assistant knows its type, how many cells are empty, how many distinct values it holds, its smallest and largest value, and its most frequent values.
• A column is a number column only when every value in it is a plain number. A table you upload is stored with the spaces around its headers and values removed. A column then counts as a number column only when every non-empty value is a plain number with digits on both sides of any decimal point: one .5 or 5. in the column makes it a text column.
• An answer can say how many rows matched in all. When a question matches 4,200 rows, the assistant has the figure 4,200 even though the result lists only some of those rows.
• Text is compared without regard to case. "texas" finds "Texas".
• Near and inside questions need coordinates. They work on rows that have a point location. An area is a rectangle given by its west, south, east and north edges.
• The assistant can move the map to what it found. It answers from the rows and can move the map to them. To see the rows on the map, draw the dataset as a layer.

What it does not do:

• One dataset at a time. A question is answered from one dataset. The assistant does not join two datasets or compare rows across them in one step. On a map with several datasets, name the one you mean.
• At most 100 rows or groups in one result. A longer result is cut at 100; the count of matching rows still covers all of them. Ask for the following rows to continue, or narrow the question.
• The open map's data only. The assistant reads the datasets of the map you have open, not those of your other maps.
• It reads the data and never changes it. The assistant does not edit, add or delete rows. To change the data, upload the file again.

Column roles

A column role says what a column means for each row. After an upload, Studio detects four of them from the column headers and from what the columns hold:

Role	The column that holds	What it does
Name	What each row is called: a store name, a venue, a site	It is what Studio's AI assistant, and a published map's chat, call each place.
Category	The kind of thing the row is	Tells the assistant what kind of place a row is. A published map's chat reads it with the name.
Description	A sentence or two about the row	Tells the assistant what a row is about. A published map's chat reads it with the name.
Address	The row's street address	Tells the assistant which column is the address.

A role is empty when Studio found no column that fits. A dataset can have all four, some, or none.

To check or correct them:

1. Open the map's Data panel and find the dataset.
2. Open the Column Roles fold on the dataset's row. Under the line "The Name column is what the AI assistant calls each place." there are four menus: Name, Category, Description and Address.
3. In a menu, choose the column that holds that role, or None to leave the role empty. Each menu lists the dataset's own columns.

What you should see: "Saving...", then "Saved" beside the menu. A change is saved when you make it; there is no separate save button. If it cannot be saved you see "Could not save. Try again." and the menu goes back to the column it had.

Things to know:

• Set the Name column for a dataset of places. A published map's chat reads only datasets that have a Name column, because without one a row has nothing to be called by.
• A replacement upload keeps the roles you set. In Studio, uploading a file with the same name stores a new dataset in place of the earlier one. Studio detects the new dataset's roles, then carries over each role the earlier dataset had, as long as the new file still has that column. A role whose column is gone from the new file keeps what Studio detected: open the fold after the upload and check it.
• An image overlay has no columns, so it has no Column Roles fold.

Dataset limits

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. Only the total across the organization is set in an Enterprise agreement.

Two limits are the same on every plan:

Limit	Value
Features in one geographic file (GeoJSON, KML, GPX, Shapefile)	50,000
Size of one image overlay	16 MiB. This bounds the image Studio makes from a GeoTIFF and sends to be stored, not the GeoTIFF file you choose. The GeoTIFF file itself can be up to 64 MiB on every plan.

How the limits behave:

• A limit refuses a new upload only. Data that is already stored is kept, including when an organization moves to a plan with a lower limit.
• A refused upload tells you which limit it met. Studio shows the message with a link to upgrade. The response behind it is HTTP 402 quota_exceeded; Errors lists its fields.
• Two ceilings apply on every plan, and they are a different refusal. Whatever the plan, one dataset holds at most 100,000 rows and one file is at most 64 MiB. A file or a dataset over a ceiling is refused with HTTP 400 and a validation error, not with the 402: it is too large for Studio, and no plan change admits it. Split the file into smaller ones. A geographic file of more than 50,000 features and an image overlay over 16 MiB are refused the same way.
• The total counts rows, not files. It is the sum of the rows in all of the organization's datasets, and the upload being checked counts with its own rows. Deleting a dataset frees its rows.
• Data stored inside a map is not counted. JSON pasted into the uploader is written into the map itself, so it is not a stored dataset and none of these limits applies to it.

The plan is your organization's Kaleidr plan, the one you buy and change on kaleidr.com/billing. Studio has no plan of its own: the number of maps an organization can keep and the dataset limits above both follow that plan.

To get more: move from Free to Pro. On Pro or Enterprise, contact Kaleidr and a higher total is set for your organization. Only the total can be raised that way: the rows in one dataset and the size of one file stay within the ceilings on every plan.

When an upload does not go through

Studio reads the file in your browser to show the preview, then sends the file to be stored.

Studio checks the file against your plan first. As soon as you choose a file, before anything is sent, a file over your plan's size is refused with "<name>" is 40.0 MB — the limit is 32 MB. and a table with too many rows with "<name>" has 60,000 rows — your plan allows 50,000 per dataset., each with an Upgrade Plan link. The link appears only when a higher plan would admit the file. A file over a ceiling is refused the same way on every plan, with no link: a file over 64 MiB gets the size sentence, and a table of more than 100,000 rows gets "<name>" has 120,000 rows — the maximum is 100,000 per dataset. The sentences from the server in the table below are therefore what you see mainly for the total across your organization.

What happens when sending the file fails depends on why. A refusal is the server's answer about your account or your file, and nothing is added to the map. Only when the server could not be reached does Studio keep the data another way.

What happened	What Studio does
The upload is over a plan limit (HTTP 402)	Refuses the file. The server's sentence, which names the limit, is shown next to the upload control with an Upgrade Plan link. Nothing is added to the map.
You are signed out (401)	Refuses the file: "Your session expired. Sign in again, then add the file." Nothing is added.
Your account may not add data to this map (403)	Refuses the file: "You don't have permission to add data to this map." Nothing is added.
The file is too large to send (413)	Refuses the file: "<name>" is too large to upload. Nothing is added.
Too many uploads at once (429)	Refuses the file: "Too many uploads right now. Wait a moment, then try again." Nothing is added.
Any other refusal, including the 400 for a file or dataset over a ceiling	Refuses the file with the server's sentence, or "<name>" was not added: the server did not accept the file. Nothing is added.
No answer from the server, a timeout or a server fault	If the table is within your plan's limits (its rows fit one dataset and fit the rows your organization has left), the rows are stored inside the map instead, with the warning "Stored in the map instead of on the server. Large files will make editing slower." If it is not, or the limits are not known at that moment, nothing is added: Couldn't reach the server to store "<name>". Check your connection, then try again. An image overlay is stored inside the map in this case.

Data stored inside the map this way behaves like pasted JSON: it travels with the map, including to visitors of the published map, and it is not a stored dataset. To move it to your account, delete it from the map and upload the file again when the server can be reached.

Delete or replace a dataset

Each dataset in the Data panel has a trash control on its row.

• A stored dataset is deleted for good. Studio asks first: "Delete this dataset for good? Its data is removed from the server and stops showing on the published map and its share links. This cannot be undone." Choose Delete to go ahead or Cancel to leave it. Studio shows "Deleting…", then removes the dataset and the layers that draw it from the map.
• Its rows are freed from the organization's total.
• It stops being served on the published map and on every share link that drew it. A browser that already loaded the data keeps it, and a download link already issued can stay readable for up to one hour.
• If the delete fails, Studio says "Couldn't delete this dataset. Nothing was changed." and the dataset stays on the map.
• Data stored inside the map (pasted JSON, or rows kept in the map after a failed upload) is removed from the map at once, with no confirmation: there is nothing stored on the server to delete.

Uploading a file with the same name replaces the earlier dataset. The new dataset takes the place of the old one on the map, and the earlier one is deleted once the new one is stored and read, never before. The column roles you set on the earlier dataset are carried over to the new one. What Studio tells you when the replacement does not complete:

What happened	What Studio does
The new file cannot be read	The map goes back to the earlier data, and the new file is discarded. Studio shows the reason, then The earlier copy of "<name>" was kept, and the map shows it again.
The new file is still being read when Studio stops waiting for it	Nothing is deleted yet. Studio shows The earlier copy of "<name>" is still stored and still counts toward your plan's rows. The earlier copy is deleted once the new file has been read.
The earlier copy cannot be deleted	Studio shows The earlier copy of "<name>" could not be deleted and still counts toward your plan's rows.

Undo does not bring the data back. Undo in Studio can restore the map's reference to a dataset you deleted. The data is gone, so that layer is not drawn.

Business data in AI answers: Enterprise

The rest of this page is the Enterprise path. Kaleidr can draw on data your organization uploads (your places, their opening hours, room types, rates, availability and documents) when it answers a question.

Five facts first:

• Uploading is part of the Enterprise plan. An organization owner or admin uploads the data. An organization on Free or Pro cannot upload it.
• The data is used in two places. Kaleidr Studio's assistant answers from it for the organization's signed-in members, while the organization is on Enterprise. Reading it through an API key or the SDK needs a key that carries the vendor scope, which only an Enterprise organization can create.
• The data is looked up when a question is answered. Unpublishing a release stops answers from drawing on it at once.
• Answers use your data alongside Kaleidr's general knowledge. They are not restricted to it.
• Your data is yours alone, and you can take it back out. It is isolated per organization and is never used in answers on Kaleidr's own consumer map or for any other organization. An owner or admin can unpublish and delete a release on any plan.

Availability by plan

Plan	Upload business data, and use it in Kaleidr Studio	Use the data through an API key or the SDK (the vendor scope)
Free	No	No
Pro	No	No
Enterprise	Yes, within the limits set in your agreement	Yes

In words: business data in AI answers is an Enterprise feature, in both halves. Free and Pro bring their own data to Kaleidr as datasets on a map.

More availability facts:

• The plan that counts is the organization's Kaleidr plan, the one you buy and change on kaleidr.com/billing. Studio has no plan of its own.
• There is one upload screen, and it is in Kaleidr Studio: the Data for AI Answers section at the bottom of the Data panel of any map. An owner or admin of an organization that may upload sees the whole screen. Upload in Kaleidr Studio walks through it, and What the section shows when you cannot upload covers everyone else.
• The upload API does the same thing. The screen and the API are one pipeline with the same checks, limits and releases, so you can stage a file in one and publish or inspect it in the other.
• Uploading is done by a person with the owner or admin role in the organization, signed in to their Kaleidr account. It is not done with an API key.
• You can ask what your organization may upload. GET /shared-api/datahub/limits answers on every plan: it returns whether the organization may upload, its plan and its limits, with can_upload: false below Enterprise.

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 path, end to end

 1. Upload and publish          2. Mint a key with            3. Ask                 4. See it worked
    (owner/admin, in Studio        the vendor scope              (chat or stream,       (place events with
     or by API)                                                  with that key)          source: "vendor")

 file ──► preview ──► release ──► key ──────────────────────► request ─────────────► stream
          (draft)     (published)  kld_pk_… or kld_sk_…         /chat/control/stream

All four steps need Enterprise. Inside Kaleidr Studio, the path is step 1: once a release is published, members of your organization who are signed in to Kaleidr Studio can ask Studio's assistant about the data on any of the organization's maps. Steps 2 to 4 bring the data into your own site or backend through an API key.

For the API and the SDK, all four steps must hold. If any one is missing, answers still arrive; they are built from general knowledge only, and nothing in the response says your data was skipped.

Step 1: Upload and publish a release

Who: an owner or admin of an Enterprise organization. On Free and Pro the upload calls return 403 vendor_data_not_on_plan.

An upload creates a draft release. Nothing reads a draft. A release has to be published before any answer can use it, and publishing replaces the previously published release as a whole.

You can do this step on a screen or with the API. Both stage a preview, show what was understood, and publish as a second, separate action.

Upload in Kaleidr Studio

1. Sign in to Kaleidr Studio and open any map. The data belongs to your organization, not to the map you open, so it does not matter which one.

2. Open the Data panel and scroll to the bottom. Open the section titled Data for AI Answers.

   What you should see: a Choose a File box and a Releases list. In the box, one line states your organization's limits: how many places and documents it can upload, and the largest file it accepts. It is followed by "Need more than your plan includes?" and a Contact Us link. If the section is missing, or shows a one-line note or only the Releases list instead of the box, see What the section shows when you cannot upload.

3. Under Choose a File, choose Choose File and pick a .csv or a .json file no larger than the size in that line.

   What you should see: the file's name on the button, and a line that says which kind of file it is. A .csv is "A spreadsheet. Propose a mapping, correct it if needed, then preview." A .json is "A data bundle. No mapping is needed, so go straight to preview." A file over your limit is not read, and you see a message that gives the file's size and your limit.

4. For a .csv only: under Column Mapping, choose Propose Mapping. Kaleidr reads your header row and a few sample rows and proposes which column means what. Each proposal spends some of your organization's AI credits.

   What you should see: "From the sample rows:" followed by how many items the mapping produced from those rows (Places, Room Types, Rate Plans, Nightly Rates, Availability), and the mapping itself under Edit Mapping, as JSON. Review it. If a count is missing or a column is wrong, correct the JSON. Your rows are never rewritten; only the mapping changes. A places CSV that already uses the fixed column names needs no mapping: skip this step.

   If the organization's AI credits are used up you see "Your organization's AI credits for this period are used up. You can still write the mapping by hand." with an Upgrade Plan link. Open Edit Mapping and write the JSON yourself; previewing and publishing do not spend AI credits.

5. Choose Preview. The file is uploaded and staged as a draft.

   What you should see: the counts of what Kaleidr understood, per kind of data, and "Staged as a draft. Nothing is live until you publish. Publishing replaces the data your organization has published now." If the file could not be read you see "Staging failed. Nothing was published." with the problems listed by row. Fix the file or the mapping and preview again.

6. Choose Publish.

   What you should see: "Publishing…", then "Published. Kaleidr AI now answers from this data."

7. Check the Releases list under the steps. The release you published is at the top, marked Published, with its date. The Releases list explains the other labels and what each row offers.

Things the screen does on purpose:

• Publish is never part of Preview. Nothing is live until you choose Publish.
• Changing the mapping after a preview discards that preview. You see "The mapping changed. Preview again before you publish." and Publish is unavailable until you do.
• A preview counts as an upload toward the hourly limit in Limits. If you reach it you see "Your organization has reached the hourly upload limit. Previews count toward it. Wait, then try again."
• A long-running upload is not lost. If you see "Still working. Check again in a few minutes.", choose Check Again.
• A file over a count limit is refused when you preview it. You see "The upload was rejected:" followed by the reason, which names the limit that was exceeded and the plan.

The Releases list

The list shows your organization's releases, the published one first and then the newest first. Each row has a date, a label and, where one applies, an action.

Label	Meaning	The row offers
Published	The release answers are built from.	Unpublish
Draft	A preview that was staged and is waiting for you to publish it.	Delete
Processing	An upload that is still being read.	Nothing until it finishes
Superseded	A release that was replaced by a newer one, was unpublished, or is a preview that expired.	Delete
Failed	An upload that could not be read.	Delete

A release whose deletion is under way is left out of the list.

The row of the file you are previewing or publishing right now offers no action until that step ends.

Unpublish asks first: "Unpublish this release? Kaleidr AI stops answering from this data until you publish another release. This release cannot be published again." Choose Unpublish to go ahead or Cancel to leave it. You see "Unpublishing…", then "Unpublished. Kaleidr AI no longer answers from this data." The row changes to Superseded and now offers Delete. Your organization has no published release until you publish another one, and to bring the same data back you upload the file again.

Delete asks first: "Delete this release? This removes the release and everything made from it, and cannot be undone." Choose Delete to go ahead or Cancel to leave it. You see "Deleting…", then "Release deleted.", and the row leaves the list. A published release has no Delete: unpublish it first.

Unpublish and delete a release states what the two actions do and what deletion does not reach.

After a move off Enterprise, the list stays for the organization's owners and admins, with Unpublish and Delete only: the table below has each case. Once the organization holds no releases, the section no longer appears the next time the Data panel opens. The API accepts the same two calls on any plan.

What the section shows when you cannot upload

You are	What you see
An owner or admin of an Enterprise organization	The whole section: the upload steps, the organization's limits in one line (how many places and documents it can upload, and the largest file it accepts), and the Releases list.
A member of an Enterprise organization who is not an owner or admin	"Only an owner or admin of your organization can upload this data." No upload controls and no release list.
An owner or admin of an organization that has left Enterprise and still holds releases	"Uploading is part of the Enterprise plan." and the Releases list, with Unpublish and Delete only. No upload controls.
An owner or admin of an organization below Enterprise that holds no releases	No Data for AI Answers section.
Any other member of an organization below Enterprise	No Data for AI Answers section.
Not signed in	No section.

To add your own data to a map on any plan, use the panel's ordinary upload: see Datasets on a map.

The section reads what your organization may do when the Data panel opens. If that cannot be read, the section does not appear; reload the page to try again.

Upload with the API

Authentication: the access token of your signed-in Kaleidr account, sent as Authorization: Bearer. An API key does not work here.

The API takes the same steps as the screen: stage a preview, check what was understood, then publish. A release you stage with the API appears in Studio's Releases list, and one you publish in Studio is returned by GET /shared-api/datahub/releases.

# Stage a preview. The artifact is the raw text of your file.
curl -X POST https://api.kaleidr.com/shared-api/datahub/ingests \
  -H "Authorization: Bearer $KALEIDR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: places-2026-10-10-a" \
  -d '{
    "filename": "places.csv",
    "source": "csv",
    "preview": true,
    "artifact": "name,timezone,lat,lng,address,category\nHarbor Hotel,Europe/London,51.5079,-0.0877,\"1 Example Street, London\",hotel\n"
  }'

{
  "ingest_id": "5f0c…",
  "release_id": "a81d…",
  "status": "pending",
  "status_url": "/shared-api/datahub/ingests/5f0c…",
  "dispatched": true
}

# Poll until status is "succeeded", and read row_counts.
curl https://api.kaleidr.com/shared-api/datahub/ingests/5f0c… \
  -H "Authorization: Bearer $KALEIDR_ACCESS_TOKEN"

# Publish the preview.
curl -X POST https://api.kaleidr.com/shared-api/datahub/ingests/5f0c…/publish \
  -H "Authorization: Bearer $KALEIDR_ACCESS_TOKEN"

After the publish call the ingest runs once more. Poll the same status URL; when it reports succeeded again, the release is published.

Send one upload at a time. While an ingest of your organization is running, a new upload or a publish call returns 409 org_ingest_in_progress; wait for the first to finish. An organization can start 30 uploads an hour, after which the call returns 429 ingest_rate_limited. The optional mapping-proposal call for a sheet is open to the same accounts as the upload, an owner or admin of an Enterprise organization, and each proposal spends the organization's AI credits. Upload your business data is the reference for every request, field, status and error in this step, including sheets that need a column mapping, the limits call and the calls that unpublish and delete a release.

Step 2: Mint a key that may read it

Who: an owner or admin of an Enterprise organization.

The vendor scope is never on a key by default, and the API Keys page cannot add it. You mint the key through the key-management API, again with your account access token.

A server key for your backend:

curl -X POST https://api.kaleidr.com/shared-api/api-keys \
  -H "Authorization: Bearer $KALEIDR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "backend-with-our-data",
    "key_type": "server",
    "scopes": ["ai", "vendor"]
  }'

A publishable key for the chat panel on your site needs one more field, vendor_acknowledged:

curl -X POST https://api.kaleidr.com/shared-api/api-keys \
  -H "Authorization: Bearer $KALEIDR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "site-chat-with-our-data",
    "key_type": "publishable",
    "scopes": ["ai", "vendor"],
    "vendor_acknowledged": true,
    "allowed_origins": ["https://www.example.com"]
  }'

The response is 201 with the key object and a plaintext_key field. The full key is shown once; store it then. Check that scopes in the response contains vendor.

Outcome	Meaning
201, and scopes contains vendor	The key can read your data.
403 tier_capability_not_allowed	The organization is on Free or Pro, which do not admit vendor. No key is created. Sending vendor_acknowledged does not change this.
422 vendor_scope_requires_acknowledgement	A publishable key was requested with vendor but without "vendor_acknowledged": true.
403 free_plan_publishable_only	A server key was requested on Free.
403 org_admin_required	The signed-in account is not an owner or admin of the organization.

A publishable key with the vendor scope makes the data public to that page's visitors

A publishable key sits in your page source. Anyone who can load the page can ask the chat questions and receive answers built from your uploaded data. The allowed-origins list limits which sites can use the key from a browser; it is not a confidentiality boundary. That is why the acknowledgement is required. Only put vendor on a publishable key for data you are content to publish. For anything else, keep the key on your server.

A key's scopes cannot be edited afterwards. To withdraw vendor, revoke the key and mint a new one. Auth and scopes documents the key-management API.

Step 3: Ask

Your data is consulted on one kind of call: the chat stream, made with a credential that carries vendor.

From a backend, with the server key:

curl -N https://api.kaleidr.com/inference-api/b2b/v1/chat/control/stream \
  -H "Authorization: Bearer $KALEIDR_SERVER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "demo-conversation-1",
    "messages": [{ "role": "user", "content": "Which of our hotels has rooms this Friday?" }],
    "location": { "lat": 51.5079, "lng": -0.0877 }
  }'

From a web page, mount Kaleidr Chat with the publishable key. The chat session the SDK obtains carries vendor when the key does:

Kaleidr.mount('#chat', {
  product: 'chat',
  publishableKey: 'kld_pk_live_…', // the key minted with vendor
  map,
  contained: true,
});

What does not consult your data:

• A key without vendor, including every key made on the API Keys page.
• Tile, editor and viewer sessions. Only a chat session carries the scope.
• The overview and follow-up requests the chat panel makes for a place card.
• A published map's Visitor AI Chat, which runs without a key.

Step 4: See that it worked

The stream opens with place events for places from your published release, each marked "source": "vendor". They arrive before the first phase event and before any answer text.

event: place
data: {"id":"0b9e…","name":"Harbor Hotel","coordinates":{"lat":51.5079,"lng":-0.0877},"address":"1 Example Street, London","category":"hotel","source":"vendor"}

event: phase
data: {"type":"phase","phase":"thinking","session_id":"demo-conversation-1"}

What to know about these events:

• There are at most three.
• They are not the answer to the question. Treat them as confirmation that this key reaches your published data, and as pins to draw. The places an answer is about arrive separately, as described below.
• A place event from your data always has coordinates. address and category appear when you supplied them.
• Places the answer itself names arrive later in the stream as place events without source: "vendor".

In the chat panel, the same events become pins on the map as soon as the visitor sends a question. To inspect them, open the Network tab, select the control/stream request and read its event stream.

The full event list is in the SSE wire contract.

What data is supported

Data	What you provide	Format
Places	Name, time zone, and coordinates or an address; optionally a category	CSV or JSON
Opening hours	Per place: a weekday or a date range, opening and closing times, or a closed marker	JSON
Room types and rate plans	Per place: a name for each	JSON, or a CSV sheet with a column mapping
Nightly rates	Per place, room type and rate plan: the stay date, the price and its currency	JSON, or a CSV sheet with a column mapping
Availability	Per place and room type: the stay date and the units available	JSON, or a CSV sheet with a column mapping
Documents	A title and the text	JSON

Every upload must contain at least one place. Hours, rates and availability attach to a place in the same upload. Dates in rate and availability answers are read in the place's own time zone, which is why every place needs one.

Limits

These are the limits of business data in AI answers. The limits of a dataset on a map are in Dataset limits.

Three limits are set in your organization's agreement, and never above what an upload itself can accept: the platform has its own ceiling for each, and an agreement cannot go above it. They are per organization, and because a publish replaces the previous release as a whole, each one bounds a single upload and the published data alike.

Limit	Enterprise
Places per upload	Set in your agreement
Documents per upload, as inline text	Set in your agreement
Size of one upload, as text	Set in your agreement

For a CSV, the places limit counts data rows, whatever the rows describe. An upload over one of these limits returns 422, and the reason names the limit and the plan. To read your organization's own numbers, call GET /shared-api/datahub/limits or open the Studio section.

The rest are the same for every organization that may upload:

Limit	Value
File types	.csv and .json
Size of the request that carries an upload	32 MiB. A larger one returns 413 request_body_too_large.
Room types, and rate plans, per upload	10,000 each
Hours rows per upload	25,000
Length of a name	200 characters for a place, a room type or a rate plan; 300 for a document title. Every field has a limit: see Field limits.
Column mapping	64 KB. It can set only the fields listed for each section, and only some of them may be a constant.
Uploads being processed	One per organization at a time. A second upload, or a publish call made meanwhile, returns 409 org_ingest_in_progress.
New uploads	30 per organization per hour, previews included. Over that, 429 ingest_rate_limited.
Mapping proposals	30 per account per hour. Each one also spends the organization's AI credits.
Published releases	One at a time. Publishing a release replaces the previous one as a whole.
A preview that is never published	Expires 14 days after it finished staging
A release that is no longer current	Deleted automatically after 30 days. See How long releases are kept.
Places sent as source: "vendor" events	3 per stream

How answers use your data

• Looked up when a question is answered. Your published release is consulted at that moment, and revoking the key stops answers made with it from using your data.
• Alongside general knowledge. A question about your hotel's rates can be answered from your upload; a question about the neighborhood is answered from general sources; one answer can use both.
• Not exclusively. There is no setting that confines answers to your data, and none that forbids general knowledge about your places.
• Silently, either way. When your data has nothing relevant, the answer is built from general sources. No error, event or field says whether your data contributed to a given answer. The source: "vendor" place events show that the data was reachable, not that the prose used it.
• From the published release only. Drafts, previews and superseded releases are never read.
• As uploaded. Kaleidr does not fetch updates from your systems. An answer about tonight's availability reflects the last release you published.

A plan change takes effect without an error on the read side. If an organization moves from Enterprise to Pro or Free:

• Kaleidr Studio's assistant stops answering from the data, for every member. The published release stays stored and stays in the Releases list as Published until an owner or admin unpublishes it. It then stays in the list as Superseded until it is deleted, or removed after 30 days.
• Its keys keep working but stop reaching the data. The source: "vendor" events stop arriving and answers continue from general knowledge. No status, code or field reports the change.
• Browser sessions that were open are ended. Their next request returns 401 and the SDK obtains a new session, which does not carry vendor.
• Rotating a key that carried vendor succeeds and returns a replacement without it. On Free, the replacement of a publishable key carries the whole Free surface (ai, maps, design and all four products) whatever the old key held, and rotating a server or legacy key is refused with 403 free_plan_publishable_only.
• Creating a key with vendor is refused with 403 tier_capability_not_allowed.

Uploading stops too, and taking data out does not:

• On Free and Pro, the upload, publish, re-dispatch and mapping-proposal calls return 403 vendor_data_not_on_plan, and the upload controls leave the Data for AI Answers section in Studio.
• On any plan, owners and admins can still list the organization's uploads and releases, read its limits, and unpublish and delete what it uploaded: in Studio's Releases list, which stays for as long as the organization holds a release, and with the API.
• Datasets on a map are not affected. They follow the dataset limits of the new plan, and nothing already stored is removed.

Unpublish and delete a release

An owner or admin can take the organization's data back out at any time, on any plan, including after a move to a plan that may not upload. There are two separate actions, in Studio's Releases list and in the API, both on any plan.

Action	What it does	When it takes effect
Unpublish	Takes the published release out of service. Answers stop drawing on it.	At once
Delete	Removes a release that is not published, together with the file you uploaded for it and everything Kaleidr made from it. It cannot be undone.	Shortly after the call returns

Four rules:

• After an unpublish, your organization has no published release until it publishes another one. Answers continue from general knowledge, and nothing in a response says so. The earlier release does not come back.
• An unpublished release cannot be published again. To restore the same data, upload the file again and publish that.
• A published release must be unpublished before it can be deleted. Taking data out of service is always its own, deliberate step.
• Replacing is not deleting. Publishing a new release supersedes the previous one; the previous one stays in your release list until you delete it or it is removed automatically.

How long releases are kept

Kaleidr keeps the published release for as long as it is published. Everything else is removed without any action from you:

Release	Removed automatically
Superseded: replaced by a newer publish, or unpublished	30 days after it was replaced or unpublished
A preview that was never published	It expires 14 days after it finished staging, and is removed 30 days after that
Failed	30 days after its last processing attempt ended

Automatic removal does the same thing as Delete. To remove a release sooner, delete it yourself.

What deletion does not reach

Deleting a release removes it from every answer made after the deletion completes. It does not reach these:

• Cached answers. An answer that was produced while the release was published can be served again from a cache for a limited time.
• Saved chat transcripts. A saved conversation that already quoted your data, such as one in Kaleidr Studio, keeps its text.
• Backups. Backups taken before the deletion.
• Text already sent to a model provider. Text from your data that was sent to a model provider when it was processed is not recalled by a deletion.

To ask about any of these, contact Kaleidr.

Isolation

• Uploaded data belongs to one organization and is readable only through that organization's credentials.
• Through the API and the SDK, it is used only on calls made with a key that carries vendor. It is never used on Kaleidr's consumer map or for another organization's keys.
• Members of your organization who are signed in to Kaleidr Studio can ask Studio's assistant about the published data while they build a map, for as long as the organization is on Enterprise.
• Owners and admins can list their own uploads and releases at any time, on any plan, including after a downgrade, and can unpublish and delete them.

Not available today

• Connectors. There is no connection to a live database, a property-management system, a booking engine or a spreadsheet service. You export a file and upload it.
• Incremental sync. There is no upsert, no way to delete single records and no change feed. Each published release is a complete replacement, so a file must contain everything you want answers to use. You can unpublish or delete a whole release.
• Publishing an earlier release again. A superseded or unpublished release cannot be made current. Upload the file again.
• Restricting answers to your data, or excluding general knowledge.
• Per-user or per-visitor permissions on the data. A key either carries vendor or it does not.
• Binary documents. Documents are inline text; PDF and office files are not accepted.
• Passing data in the request. You cannot attach records to a single question. Data reaches answers only through a published release.

If your data does not show up

Work down this list. Each line is one of the conditions above.

Check	How
Is there a published release?	The Releases list in Studio shows one marked Published, or GET /shared-api/datahub/releases?status=published returns one item.
Did the publish run finish?	GET /shared-api/datahub/ingests/{ingest_id} shows status: "succeeded" after the publish call.
Does the key carry vendor?	GET /shared-api/api-keys lists the key with vendor in scopes.
Was the release unpublished or removed?	An unpublish leaves no published release, and a release that is no longer current is removed after 30 days. Publish again.
Is the organization on Enterprise?	On Pro or Free the scope stops applying and Studio's assistant stops answering from the data, both without an error.
Is it the chat stream?	Only POST …/chat/control/stream, or the chat panel, consults the data.
Is the session new?	In a browser, reload the page so the SDK obtains a session from the right key.
Are you looking at the right place in the stream?	The events are the first ones, before phase.

If every line holds and the stream still opens without a source: "vendor" event, contact Kaleidr support with the ingest id and the time of the request.

Related pages

• Upload your business data: the upload API reference for the Enterprise path, with every field, limit and error. The Studio screen applies the same ones.
• Auth and scopes: keys, the vendor scope and the key-management API.
• Server quickstart and Reading the stream: calling the stream from a backend.
• Security model: what a publishable key does and does not protect.