Skip to content
DashboardGet API key

Write an item

View .md
PUT

Store a JSON document under a key. Creates the collection if it does not exist — with no indexes, which query then cannot use. Declare indexes with POST /v1/memory/collections first if you need them.

This replaces the whole document; it does not merge. Pass If-Match with the revision from a previous read to make the write conditional.

Authorization

  • Authorizationheaderrequired

    Bearer YOUR_API_KEY. Create a key in the dashboard.

Path parameters

  • collectionstringrequired

    Collection name.

  • keystringrequired

    Item key. 1-255 chars from A-Z a-z 0-9 . _ : @ -

Query parameters

  • scopestring

    Which scope to address: contact:<contactId>, conversation:<conversationId>, or omitted for the project scope.

    Note the asymmetry with POST /v1/memory and POST /v1/memory/search, which take the scope in the request BODY as scope plus contactId/conversationId. Every other Memory endpoint takes it here.

Headers

  • If-Matchstring

    Make the write conditional on the item's current revision, as returned by a previous read or write (plain 3 or ETag-quoted "3"). The write is refused with 409 revision_conflict if the item moved on in between. Without it, the write always wins and silently overwrites a concurrent one.

Body

application/json

  • valueanyrequired

    The document to store. Any JSON value, max 200KB serialized and 32 levels deep. This is a whole-document write, not a merge: it replaces whatever the key held.

  • ttlSecondsinteger

    Overrides the collection's defaultTtlSeconds for this item.

    Limitsmin 60 · max 63072000

Responses

200Existing item replaced.
  • itemobjectrequired

    One JSON document in a collection.

    6 properties
    • keystringrequired
    • valueany

      The stored JSON. Any JSON value.

    • revintegerrequired

      Revision, incremented on every write. Pass it as If-Match on a later write to make that write conditional.

    • createdAtstring<date-time>required
    • updatedAtstring<date-time>required
    • expiresAtstring<date-time>
201Item created.
  • itemobjectrequired

    One JSON document in a collection.

    6 properties
    • keystringrequired
    • valueany

      The stored JSON. Any JSON value.

    • revintegerrequired

      Revision, incremented on every write. Pass it as If-Match on a later write to make that write conditional.

    • createdAtstring<date-time>required
    • updatedAtstring<date-time>required
    • expiresAtstring<date-time>
400Invalid key, scope, TTL, or `If-Match`.
  • codestringrequired
  • messagestringrequired
  • detailsobject
401Unauthorized.
  • codestringrequired
  • messagestringrequired
  • detailsobject
409`revision_conflict`: the item changed since the revision in `If-Match`. Re-read it and retry.
  • codestringrequired
  • messagestringrequired
  • detailsobject
413`document_too_large`: the serialized value exceeds 200KB. Memory is not a blob store; put media in file storage and keep the URL here.
  • codestringrequired
  • messagestringrequired
  • detailsobject
429The plan's monthly unit quota is spent.
  • codestringrequired
  • messagestringrequired
  • detailsobject