POST/v1/records/encryptedREAD / WRITE

Insert an encrypted record

Store a crypto-shreddable record — encrypted under a per-record key held in the node's vault.

Special storage — not a normal vector record. This endpoint stores an opaque, base64-encoded payload — not a searchable vector — encrypted with a per-record key the node holds in its vault. Use it for payloads that must be individually, permanently destroyable (crypto-shredding) without rewriting the audit chain.

Request body

payloadstringrequired

Base64-encoded plaintext. The vault encrypts it before storage — you never send plaintext bytes over the wire unencoded, and the node never stores the plaintext.

collectionstringoptional

Target collection name. Optional at the HTTP level — pass it explicitly.

key_idstringoptional

Optional pre-chosen key id (hex). Omit it to have the vault generate a fresh one — this is the normal case.

tagintegeroptional

Opaque numeric tag stored with the record.

Response fields

idintegerrequired

The stored record's id.

key_idstringrequired

The vault key id this record is encrypted under. Keep it if you intend to shred this specific record later — you'll need it to identify the key.

This operation's own contract description states that deleting the record's key via DELETE /v1/crypto/shred/{key_id} makes it permanently unreadable without rewriting the audit chain. That shred endpoint is not yet part of the published OpenAPI contract (api/openapi/valori-v1.yaml's paths: section) even though it exists and is live on the node and in both SDKs (shred_key() / a REST call to DELETE /v1/crypto/shred/{key_id}) — flagged here rather than linked to a page, since Phase A's whole navigation and inventory system is generated from operations that actually appear in the contract. GET /v1/crypto/status/{key_id} — the one crypto operation that is in the published contract today — lets you check whether a key still exists; its own reference page is out of scope for this phase (Crypto is a later family).

Errors

Status	`code`	Meaning
`400`	`validation_error`	Bad base64 payload, bad `key_id`, or unknown collection.
`401`	`unauthorized`	Missing or invalid API key.
`403`	`forbidden`	The key's scope doesn't include `read_write`.
`500`	`internal_error`	Encryption or commit failure.

Related endpoints

Insert a record — normal, searchable vector insert