Valori LogoValori
PATCH/v1/records/{id}/metadataREAD / WRITE

Update metadata

Replaces a record's stored metadata wholesale. Not a merge.

The request body replaces the record's stored metadata wholesale — this is not a merge. Any key not present in the new body is gone after this call, even if it existed before.

For example, if record 42 currently has metadata { "source": "a", "page": 3 } and you PATCH with { "source": "b" }, the result is { "source": "b" } — page is not preserved. To add a field without losing existing ones, fetch the current metadata with Get a record first, merge client-side, then send the full merged object.

The vector itself is untouched — only metadata changes. The change is committed to the BLAKE3 audit chain like any other write.

Parameters

idintegerrequired

Record id (path parameter).

collectionstringoptional

Collection the record belongs to (query parameter). Optional at the HTTP level — pass it explicitly.

Request body

The request body is the new metadata object — any JSON object, with no fixed schema (additionalProperties is open). There is no wrapper field; the body you send becomes the record's metadata exactly.

Response fields

okbooleanrequired

true on success.

idintegerrequired

The record's id.

Errors

StatuscodeMeaning
401unauthorizedMissing or invalid API key.
403forbiddenThe key's scope doesn't include read_write.
404record_not_foundNo such record in this collection.
500internal_errorCommit or audit-chain failure.

Related endpoints

PATCH /v1/records/{id}/metadata
curl -X PATCH "https://app.valori.systems/v1/records/42/metadata?collection=documents" \
  -H "Authorization: Bearer vlk_your_project_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "handbook-v2.pdf"
  }'
200
{
  "ok": true,
  "id": 42
}