Upsert a memory by external ID
Create or update a memory that mirrors a record your system owns.
Identity is (endUserId, source, externalId); bump version whenever
the source record changes.
- Retrying the same version and payload returns the same durable receipt — re-sending after a crash is safe.
- A different payload for an existing version returns
409. - Delayed older versions return
409and never overwrite newer content or undo a delete.
Authorizations
A scoped Integration key, prefixed cint_. Send as
Authorization: Bearer cint_... on every request. Server-side only.
Legacy personal cmem_... keys remain accepted during migration;
team/org-scoped cmem_... keys are not valid on this API.
Headers
Optional event key; reuse with a different mutation returns 409. Optional stable source-event key.
^[A-Za-z0-9][A-Za-z0-9._:-]{0,199}$Path Parameters
Stable ID of this record in the source system. Stable record ID inside the named source.
^[A-Za-z0-9][A-Za-z0-9._:-]{0,255}$"profile_123"
Body
Your stable internal user ID. No colon allowed.
1 - 128^[A-Za-z0-9@._-]{1,128}$"u_123"
Stable source-system name, such as caeros-profile or conversation.
^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"caeros-profile"
Monotonically increasing version for this source record.
x >= 1When the source event happened, not when the retry ran.
Correct current content (max 65536 UTF-8 bytes).
1