Fetch guide

Endpoints

Endpoint	Use
GET /v2/namespaces/{namespace}/documents/{doc_id}	Fetch one document by id.
POST /v2/namespaces/{namespace}/documents	Fetch many documents by id.

import hevpuffer

client = hevpuffer.Client(api_url="http://localhost:8080")
ns = client.namespace("my-docs")

doc = ns.fetch("doc-123")
batch = ns.fetch_many(["doc-123", "doc-456"])

Semantics

• Cache hit returns from the NVMe cache with x-layer-cache: hit.
• Cache miss fetches Turbopuffer, best-effort backfills the NVMe cache, and returns x-layer-cache: miss.
• Cache error fetches Turbopuffer and returns x-layer-cache: miss-on-error.
• Single fetch returns 404 when Turbopuffer has no row.
• Batch fetch returns documents in request order plus a missing list.