Documentation

Search API Reference

Search 64.6M knowledge entries or bring your own data for indexing. Tokenized with a 3.8M whole-word vocabulary. Zero storage on our end.

Base URL
https://cold-api.coldstate.ai
Authentication

All authenticated endpoints require a Bearer token in the Authorization header:

Authorization: Bearer cs_live_...

Authentication

POST/v1/auth/register
Create account and get initial API key
POST/v1/auth/login
Log in and generate new API key
GET/v1/auth/keys
List all API keysauth
POST/v1/auth/keys/rotate
Deactivate old keys, generate new oneauth

Indexes

POST/v1/indexes
Create index with documents (async). Pass mode: 'iaas' for build & download.auth
GET/v1/indexes
List all indexesauth
GET/v1/indexes/:id
Get index details and metricsauth
GET/v1/indexes/:id/download
Download IaaS index file (marks as delivered)auth
DELETE/v1/indexes/:id
Delete an indexauth

Search

POST/v1/indexes/:id/search
Search an index with E-scored resultsauth
POST/v1/search
Search by collection nameauth

Usage

GET/v1/usage
Current usage and limitsauth
GET/v1/usage/history
Monthly usage history (last 12 months)auth
Routing States

Every search response includes a routing state that describes the topology of the results:

CRYSTALLINEHigh confidence — single clear cluster of matches
FLUIDCross-domain — multiple relevant document groups
REACTIVENovel connections — many potential matches across domains
Indexing as a Service (IaaS)

Build an index on our infrastructure, download the .db file, and run searches locally. Zero storage on our end — we wipe the file after download or after the 24-hour TTL.

3-Step Flow
1.POST /v1/indexes with mode: "iaas" and your documents. Status: queued → processing
2.Poll GET /v1/indexes/:id until status is ready. Response includes download_url and download_expires_at.
3.GET /v1/indexes/:id/download to stream the .db file. Server copy is deleted immediately. Status: delivered
Status Lifecycle
queued → processing → ready (24h download window) → delivered / expired
Scoring Metrics
EEntropic relevance — primary score. Average of top 30% token TF-IDF scores. Range 0–1.
SDSemantic depth — unique tokens divided by total tokens. Higher = more diverse vocabulary.
LCLambda coherence — fraction of tokens appearing in other documents. Higher = more connected.