Write

Upsert and delete

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

{
  "upserts": [
    {
      "id": "asin-B08N5WRWNW",
      "vector": [0.0012, -0.043],
      "attributes": {"title": "Wireless headphones", "category": "Electronics"}
    }
  ],
  "deletes": ["asin-old-001"]
}

Status semantics:

• 200 OK once the upstream Turbopuffer write succeeds.
• 400 when both upserts and deletes are empty.
• 502 when the upstream write/delete fails.

NVMe cache writes happen before the upstream call as a best-effort side effect. They never block the response — they’re how Layer keeps reads fast through the cache.

Every upsert is server-stamped with a hidden _hevlayer_upserted_at attribute (epoch milliseconds). Any caller-supplied value is overwritten — this stamp powers the consistency watermark on the query path.

Patch

PATCH /v2/namespaces/products
Content-Type: application/json

{
  "patches": [
    {"id": "asin-B08N5WRWNW", "attributes": {"category": "Audio"}}
  ]
}

Patch preserves unspecified attributes and maps to Turbopuffer patch_rows. Vectors cannot be patched — update a vector by reading the row and upserting the full document.

_hevlayer_upserted_at is bumped on every patch, so reads through the watermark filter see the patched row only after it’s indexed.

Pipeline stage

When a document is part of a pipeline, the writer doesn’t talk to the namespace directly. The CPU worker hands chunks off to the pipeline, the GPU worker writes vectors back, and the gateway is the one calling the namespace upsert.

PUT /v2/pipelines/product-images/documents/asin-B08N5WRWNW
Content-Type: application/json

{
  "chunks": [
    {"id": "asin-B08N5WRWNW-0", "text": "Wireless noise-cancelling headphones"},
    {"id": "asin-B08N5WRWNW-1", "text": "40-hour battery life", "metadata": {"page": 2}}
  ]
}

Staging stores chunks in the NVMe cache and marks the document pending. Re-staging the same document ID replaces the chunks and resets state to pending. The full pipeline API is documented under Pipelines.

Side effects

Side effect	Behavior
NVMe cache mirror	Best-effort, written before the upstream call. A failure here doesn’t roll back; the gateway can briefly cache a doc that didn’t reach the upstream index. Re-sending the upsert resolves it.
Snapshot watcher	Re-evaluates freshness on the next poll. Stable namespaces materialize a new snapshot if the histogram shape changed (see Snapshots).