Concepts

A handful of concepts cover almost all of EZType. Learn them and the API reference falls into place.

Services

A service is the container for your indexes. It holds one or more indexes and the configuration they share — region placement, sizing, replication.

Pricing scales with regions, sizing, and total storage. See the pricing page for the formula.

Indexes

An index is the searchable dataset. Records have a small set of top-level fields plus a free-form data object for everything else:

• title (string, required) — the searchable text. Prefix-matched for autocomplete; full-token-matched when scope=all.
• id (string, optional) — your stable record id. If omitted on upload, the server generates a UUID and returns it in search results so you can address the record later.
• weight (integer, optional) — ranks more important records higher when weighted=true.
• images (array of strings, optional) — URLs. images[0] is the autocomplete-row primary thumbnail; the rest are gallery.
• latitude / longitude (strings, optional) — geo coordinates; enables latitude / longitude query bias.
• data (object, optional) — arbitrary tenant-defined JSON. Every text field inside data is full-token searchable when scope=all; every numeric / boolean field is filterable. Returned verbatim with each result so renderers and agents can read the whole record.

{
  "id": "sku-9182",
  "title": "Sony WH-1000XM5",
  "weight": 18432,
  "images": ["https://example.com/headphones-1.jpg"],
  "data": {
    "brand": "Sony",
    "price": 349.99,
    "rating": 4.4,
    "specs": { "bluetoothVersion": "5.2", "batteryLifeHours": 30 }
  }
}

Uploads can be CSV, JSON Lines, or a JSON Array. CSV columns map to typed fields by name (title, weight, images, latitude, longitude); any extra column rolls into data automatically. EZType indexes in the background; new records are queryable within seconds for most dataset sizes.

Versions

Every change to an index produces a new version, addressed by a monotonic id (v1, v2, v3, ...). Bulk uploads, per-record updates, and deletes all version through the same path. Any version is queryable, and any version can be made active.

Coalesce (POST /v1/indexes/{name}/coalesce, also scheduled automatically) consolidates accumulated changes into a checkpoint version — useful as a rollback point after a burst of updates. Earlier versions remain queryable subject to retention.

The model gives you rollback, time-travel, and audit out of the box. Workflows that need determinism can pin to a specific version (MCP integration).

Multi-protocol queries

Three ways to query the same index:

• GET /v1/search — REST. Low-latency, prefix matching for autocomplete, full-phrase support for richer queries, optional geo bias.
• POST /mcp — JSON-RPC 2.0 endpoint exposing search and lookupById tools to MCP clients (Claude Desktop, MCP Inspector, any compliant agent).
• Records endpoints — GET / PUT / DELETE /v1/indexes/{name}/records/{id} for direct addressing once you know an id.

All three see the same underlying data, the same versioning, the same geo and weight signals.

Regions

EZType runs in 11 regions worldwide: Fremont, Dallas, Atlanta, Newark, Toronto, London, Frankfurt, Mumbai, Singapore, Tokyo, Sydney.

When a query arrives at api.eztype.io, it's routed to the region closest to the caller by measured latency. Callers can override the region by passing regionId explicitly — usually only useful for debugging.

Cross-region redundancy is automatic. A region failure reroutes traffic to the next-closest region transparently.

Weighted search

Add weight (any positive integer) to a record to boost its ranking:

{ "title": "Amazon", "weight": 100 }
{ "title": "Amazing grace", "weight": 1 }

On a query for ama, Amazon outranks Amazing grace because of its higher weight. Pass weighted=true on the query to activate this behavior; omit it for pure lexical ranking.

Geosearch

If records carry latitude / longitude, callers can pass their own coordinates and EZType folds distance into the rank:

curl 'https://api.eztype.io/v1/search?serviceName=svc&indexName=stores&query=cof&latitude=37.77&longitude=-122.42'

Closer stores appear above distant ones even when lexical match scores are equal. Weight and geo can be combined — geo breaks ties when lexical scores match.