Get a key, search the global knowledge base, then index and search your own documents. Every example runs as-is once you drop in your key.
Create a free account and copy your key from the dashboard. Keys start with cs_live_ and go in the Authorization header of every request. The free plan needs no credit card; quotas for each plan are on the pricing page.
You can also register over the API. The response includes your first key:
curl -X POST https://cold-api.coldstate.ai/v1/auth/register \
-H "Content-Type: application/json" \
-d '{"email": "you@example.com", "password": "at-least-8-chars", "company_name": "Acme"}'No setup needed: the global knowledge base holds 48.4M entries across 35 domains and is searchable on every plan.
curl -X POST https://cold-api.coldstate.ai/v1/search/global \
-H "Authorization: Bearer cs_live_..." \
-H "Content-Type: application/json" \
-d '{"query": "photosynthesis", "limit": 5}'querystring, required, max 2000 chars — What to search for.domainstring — Optional domain filter, e.g. MEDICINE (case-insensitive).limitinteger, 1–100, default 10 — Results per page.offsetinteger, default 0 — Offset for pagination.The response is a ranked list. Each result carries a stable id, a score and a state:
{
"source": "global",
"query": "photosynthesis",
"kb_snapshot": "…",
"results": [
{
"id": "nr_9d4e19c502794f1d",
"title": "anoxygenic photosynthesis [related-to] photosynthesis",
"snippet": "\"anoxygenic photosynthesis\" is related to \"photosynthesis\"",
"metadata": { "domain": "LINGUISTICS", "source": "conceptnet" },
"score": { "Ψ": 0.6055 },
"state": "FLUID"
}
],
"diagnostics": { "execution_time_ms": …, "results_count": …, "state_distribution": { … } },
"pagination": { "offset": 0, "limit": 5, "total": …, "has_more": true }
}kb_snapshotstring — The knowledge-base version that answered. Pin it to reproduce results later.results[].idstring — Stable entry id. Pass it to fetch, cite, related and the other knowledge endpoints.results[].score.Ψnumber, 0–1 — Relevance score. Identical for identical inputs.results[].statestring — Result state, e.g. CRYSTALLINE, FLUID or REACTIVE.paginationobject — offset, limit, total and has_more.Run the same request again against the same snapshot and you get the same results in the same order. To turn a result into something an agent can cite and re-check, continue with fetch, cite, verify.
Send your documents once and ColdState builds a searchable index. Builds are asynchronous: the call returns 202 and the index moves from queued to processing to ready.
curl -X POST https://cold-api.coldstate.ai/v1/indexes \
-H "Authorization: Bearer cs_live_..." \
-H "Content-Type: application/json" \
-d '{
"name": "Support articles",
"collection_name": "support",
"documents": [
{ "ref_id": "kb-101", "content": "How to reset your password …" },
{ "ref_id": "kb-102", "content": "Exporting invoices as PDF …" }
]
}'namestring, required, max 200 chars — Display name for the index.collection_namestring, max 100 chars — A name you can search by instead of the index id.documents[].contentstring, required — The text to index.documents[].ref_idstring — Your own reference id. It is the only identifier stored.documents[].metadataobject — Optional metadata returned with results.domain_presetstring — general, medical, biomedical, scientific, technical, legal, financial or ecommerce.modehosted | iaas, default hosted — Use iaas to build the index and download it instead of hosting it.Custom indexes are zero-knowledge: your document text is not stored, only a derived index keyed by your reference ids. Poll the index until it is ready:
curl https://cold-api.coldstate.ai/v1/indexes/idx_... \ -H "Authorization: Bearer cs_live_..."
Search by index id, or by the collection name you chose:
curl -X POST https://cold-api.coldstate.ai/v1/search \
-H "Authorization: Bearer cs_live_..." \
-H "Content-Type: application/json" \
-d '{"collection": "support", "query": "reset password", "limit": 5}'Each result returns your ref_id and metadata with a score and state, so you can look the document up in your own system. The index-id form is POST /v1/indexes/:id/search and takes query, limit and offset.
The explain endpoint returns a term-by-term breakdown of why a document ranked for a query. It is deterministic, so the explanation is the same every time you ask.
curl -X POST https://cold-api.coldstate.ai/v1/indexes/idx_.../explain \
-H "Authorization: Bearer cs_live_..." \
-H "Content-Type: application/json" \
-d '{"query": "reset password", "doc_id": "doc_42"}'Connect the MCP server to use the same key from Claude and other assistants, fetch, cite and verify facts from the knowledge base, or browse every endpoint in the API reference.