Fetch

Fetch is a Layer-only surface. The NVMe cache is checked first; on miss or error the gateway falls through to Turbopuffer and backfills the cache best-effort.

Single fetch

GET /v2/namespaces/products/documents/asin-B08N5WRWNW?include_attributes=title,category

Outcome	Status	Header
Cached hit	200	x-layer-cache: hit
Cache miss, upstream hit, cache backfilled	200	x-layer-cache: miss
Cache unavailable, upstream hit	200	x-layer-cache: miss-on-error
Missing from both layers	404	—

Batch fetch

POST /v2/namespaces/products/documents
Content-Type: application/json

{
  "ids": ["asin-1", "asin-2", "asin-3"],
  "include_attributes": ["title"]
}

{
  "documents": [
    {"id": "asin-1", "attributes": {"title": "..."}},
    {"id": "asin-3", "attributes": {"title": "..."}}
  ],
  "missing": ["asin-2"]
}

Batch fetch returns found documents and missing ids inline instead of a partial 404. documents preserves request order; ids the gateway could not find anywhere land in missing.

Behavior matrix

Cache state	Single fetch	Batch fetch
Hit	cache	cache
Miss, upstream present	upstream + backfill	upstream + backfill
Miss, upstream absent	404	inline missing
Cache unavailable	upstream, miss-on-error	upstream, miss-on-error