API

Backend

Record versions

Record versioning is opt-in on pgvector namespaces. Each logical record keeps its usual string id (numeric IDs are not supported in this slice). Each accepted full upsert creates an immutable revision with a unique version_id. One revision is active at a time. Search, scans and normal reads use only the active record; inactive revisions never enter the candidate set. Other stores return 422 for this configuration and these endpoints.

Enable versioning on an empty namespace with a write containing:

{"_hevlayer":{"versioning":{"enabled":true,"activation":"explicit"}}}

The setting persists across restarts. automatic activates every accepted write; explicit retains the revision without publishing it. Once enabled, versioning cannot be disabled or its mode changed. Omit the configuration on later writes. Namespaces without versioning keep their existing write and search behavior.

Stage, publish and restore

Use POST /v2/namespaces/{namespace} for full row or column upserts. The response includes versions, with logical id, immutable version_id and active. Supply _hevlayer.version_id for a single-row upsert when retries must return the same revision. Reusing that ID with different content or a different logical ID returns 409. A successful retry never reactivates a superseded revision. Without a supplied ID, each retry creates another revision.

NS=scratch-lyr319-example
BASE="${LAYER_URL}/v2/namespaces/${NS}"
curl --fail-with-body "$BASE" -H "Authorization: Bearer $LAYER_API_KEY" \
  -H 'Content-Type: application/json' -d '{"_hevlayer":{"versioning":{"enabled":true,"activation":"explicit"},"version_id":"v1"},"upsert_rows":[{"id":"guide","text":"First edition"}]}'
curl --fail-with-body "$BASE/records/guide/activate" -H "Authorization: Bearer $LAYER_API_KEY" \
  -H 'Content-Type: application/json' -d '{"version_id":"v1","expected_current_version":null}'
curl --fail-with-body "$BASE" -H "Authorization: Bearer $LAYER_API_KEY" \
  -H 'Content-Type: application/json' -d '{"_hevlayer":{"version_id":"v2"},"upsert_rows":[{"id":"guide","text":"Second edition"}]}'
# Normal queries still return First edition.
curl --fail-with-body "$BASE/query" -H "Authorization: Bearer $LAYER_API_KEY" \
  -H 'Content-Type: application/json' -d '{"rank_by":["id","asc"],"top_k":10,"include_attributes":true}'
curl --fail-with-body "$BASE/records/guide/activate" -H "Authorization: Bearer $LAYER_API_KEY" \
  -H 'Content-Type: application/json' -d '{"version_id":"v2","expected_current_version":"v1"}'
# Restore v1 without changing either immutable revision.
curl --fail-with-body "$BASE/records/guide/activate" -H "Authorization: Bearer $LAYER_API_KEY" \
  -H 'Content-Type: application/json' -d '{"version_id":"v1","expected_current_version":"v2"}'
for SUFFIX in versions versions/v1 versions/v2 activations; do
  curl --fail-with-body "$BASE/records/guide/$SUFFIX" -H "Authorization: Bearer $LAYER_API_KEY"
done
curl --fail-with-body -X DELETE "$BASE" -H "Authorization: Bearer $LAYER_API_KEY"

expected_current_version is required on activation. Use null for no active revision. A stale expectation returns 409 and changes nothing. Repeating an activation whose target is already active succeeds without adding an event when the expectation matches. Activation and its separate activation event commit in one transaction with the searchable row. SQL indexing errors roll back the transaction, leaving the previous revision searchable. Pgvector indexing is synchronous: there is no pending revision exposed before a successful commit. Automatic writes use this same transaction; explicit activation works in both modes. Restoring is an activation, not a new content revision.

History, retention and deletion

GET /v2/namespaces/{namespace}/records/{id}/versions returns versions and active_version_id; each entry includes id, version_id, row, and created_at. GET .../versions/{version_id} retrieves one immutable revision. GET .../activations returns the separate ordered activations log with previous_version_id, version_id, sequence, and created_at. List endpoints accept after (exclusive version ID for versions, integer sequence for activations) and limit (1–100, default 100), returning next_cursor when more results exist. Version IDs sort lexicographically; activation sequences increase.

Full upserts and named deletes are supported. A delete clears the active pointer and removes the searchable row, logging a null target; retained revisions remain available for restoration. Patches, conditional writes, filtered writes and branch/copy operations are refused on versioned namespaces. Do not write directly to the backing database. Enable versioning before adding records; adopting existing unversioned rows is refused.

Revisions and activation events are retained indefinitely. There is no TTL or per-version deletion in this slice. Deleting the namespace removes its current rows, revisions, activation log and versioning configuration together. Use namespace deletion for complete erasure. A failed transaction retains neither a new revision nor an activation event. Embeddings computed by the gateway are part of the retained row; restoring a revision does not rerun an embedding model.

esc