POST/v1/recordsREAD / WRITE

Insert a record

Inserts one vector into a collection. Supplying a request_id makes the call idempotent — a replay returns the original record instead of inserting twice.

The example vector above is 8-dimensional purely for readability — your collection's actual dimension is whatever you gave Create a collection.

Request body

valuesnumber[]required

The vector to insert. Must match the collection's dimension exactly.

collectionstringoptional

Target collection name. Optional at the raw HTTP level (omitting it uses the node's default namespace) — but every Cloud project starts with zero collections, so both official SDKs expect you to pass one explicitly.

request_idstring | integer[]optional

Idempotency token — either a 32-hex-character string or a 16-byte integer array. Replaying the same token within the dedup window returns the record the first request created (deduplicated: true) and performs no second write. Recommended for every write your application might retry.

metadatainteger[]optional

Opaque per-record bytes, committed into the same BLAKE3 audit chain as the vector itself. In practice this is JSON metadata, UTF-8-encoded: the TypeScript SDK's insert() accepts a plain object for metadata and encodes it for you. The Python SDK's insert() does not currently expose this parameter — set metadata after inserting with Update metadata, or use Batch insert, which does take a metadata list.

textstringoptional

Optional raw text stored alongside the vector for hybrid term-frequency reranking on search.

tagintegeroptional

Opaque numeric tag stored with the record.

Response fields

idintegerrequired

The inserted record's id.

deduplicatedbooleanrequired

true when this request replayed an already-applied request_id — no new record was created, and id is the original one.

receiptobjectrequired

A BLAKE3-chained audit receipt for this write.

receipt.record_idintegerrequired

The id this receipt covers.

receipt.old_rootstringrequired

State root before the write.

receipt.new_rootstringrequired

State root after the write.

receipt.proofstringrequired

Inclusion proof for this write.

receipt.sequenceintegerrequired

Audit log sequence number.

receipt.timestampintegerrequired

Unix timestamp of the write.

receipt.state_hashstringrequired

BLAKE3 hash of the resulting kernel state.

insert() returns the full response above on the TypeScript SDK. On Python, insert() returns only the new record's id — call insert_with_receipt() if you need the receipt.

Errors

Status	`code`	Meaning
`400`	`dimension_mismatch`, `validation_error`	The vector's length doesn't match the collection's configured dimension, or the request body is malformed.
`401`	`unauthorized`	Missing or invalid API key.
`403`	`forbidden`	The key's scope doesn't include `read_write`.
`404`	`collection_not_found`	The target collection doesn't exist.
`500`	`internal_error`	Commit or audit-chain failure.
`507`	`capacity_exceeded`	The project's record capacity is exhausted.

Related endpoints

Batch insert — insert many vectors in one call
Get a record
Update metadata
Vector search