Keep Text Beside a Record with Cold Storage
Cold storage holds text that belongs to a record but is not part of it: a book's table of contents, a review, a whole article, stock and supplier notes. It is not searched and not held in memory, so it costs the index nothing, and it is read when it is needed: by an agent answering a question, by a page showing a table of contents, by your own servers. A read of it may be slower than a search, which is what "cold" promises.
It survives a reload of the dataset, since it is kept beside the records, not in them. So text that comes from another system than the records themselves, such as tables of contents from a publishing system, is loaded by a sync of its own and stays put when the catalogue is replaced.
Indx Server only; the C# library does not have it.
An item
An item belongs to one record, by the record's key, and has a name (toc, review, bio) and,
if you like, a language. A record holds up to 50.
| Field | |
|---|---|
content | The text, up to 256 000 characters |
contentType | text/plain (the default), text/markdown or application/json |
description | One line an agent reads to decide whether to fetch it, such as Chapters |
visibility | Who may read it: public, answer or private (the default), below |
sourceRef, sourceUpdatedUtc | Your system's own id and time for it. A write older than what is stored is refused, so a slow or repeated sync cannot put back what has since changed |
Something that belongs to many records is a record of its own: an author's biography goes on the author's record, not on each of their books.
Write and read
All under /api/teams/{teamName}/datasets/{dataSetName}/:
| Method | Operation | |
|---|---|---|
PUT | documents/{key}/cold/{name} | Create or replace one item, whole: 201 created, 200 replaced. ?language=nb for a language |
GET | documents/{key}/cold/{name} | One item with its content, and its version as the ETag |
GET | documents/{key}/cold | The record's items, without content |
DELETE | documents/{key}/cold/{name} | Delete one item: 204 |
PUT | cold | A batch for a sync: a JSON array of items, each with its name and its record, as recordKey or id (below). With ?prune=true it also deletes what the same key wrote before and did not send now, and nobody else's |
curl -X PUT "https://your-host/api/teams/acme/datasets/books/documents/1/cold/toc?language=en" \
-H "Authorization: Bearer <full key>" -H "Content-Type: application/json" \
-d '{ "content": "1. The first part\n2. The second part", "contentType": "text/markdown",
"description": "Chapters", "visibility": "public" }'Name the record by your own id
A sync that runs in your own system knows its own ids, not Indx's keys. In a batch, give an item
id in place of recordKey: the id your Sanity or Contentful webhook sends for the record (often
_id), or the record's key as text when the dataset has a key field of its own. An id no record has
is refused for that item, with why, and the rest of the batch is written; each outcome says which
id it was for.
curl -X PUT "https://your-host/api/teams/acme/datasets/books/cold?prune=true" \
-H "Authorization: Bearer <full key>" -H "Content-Type: application/json" \
-d '[{ "id": "book-123", "name": "toc", "content": "1. The first part\n2. The second part",
"contentType": "text/markdown", "visibility": "public", "sourceUpdatedUtc": "2026-11-12T08:00:00Z" }]'From Sanity, a Sanity Function or your own job can send a document's long text this way when it
changes: its _id as id, rich text made plain with pt::text() in the query, and _updatedAt as
sourceUpdatedUtc. What goes to cold storage, under what name and who may read it stays your choice;
the webhook that keeps the records is not involved.
Writing takes a Full key or an Editor. Send If-Match with the version you read, and a write
against an item someone changed since is refused with 409 coldConflict. An item goes with its
record when the record is deleted, and with its dataset.
Who may read it
| Caller | Reads |
|---|---|
A Search key over HTTP, as a page uses it | public |
A Search key over MCP | nothing |
Search or ask's answer for a visitor | public and answer |
A Read key; a Viewer | public and answer |
A Read key with the private flag; a Full key; an Editor or Admin | every item |
publicis for what any page may show, such as a table of contents.answeris for text an answer may draw on but a page must not hand out, such as a licensed review.privateis for what only you and the servers you trust may read, such as customer data. Search or ask never reads it, since anything its answer reads can reach a visitor.
A Read key reads private items when it is created with Also reads private cold storage, for a server that may see that data, such as a support chatbot's backend. It still writes nothing.
Nobody is told about items they may not read: they are left out of every listing, without a count,
and asking for one by name answers 404 coldNotFound, as for an item that does not exist.
How a record says it has some
A search's answer carries cold, the names each listed record holds that the caller may read,
by record key. It is left out when no listed record holds any.
{
"records": [ { "documentKey": 1, "score": 61234 } ],
"cold": { "1": ["review", "toc"] }
}Over MCP, each search hit carries its record's names, describe_dataset lists the names in use
and how many records hold each, and get_cold reads them. Search or ask's answer on a catalogue
sees which records hold some and reads them when the question is about what they say. In the
console, the Records tab shows an opened record's cold storage below its fields.