Skip to content
DashboardGet API key

Create a collection

View .md
POST

Declare a collection of JSON documents addressed by key. This is the counterpart to facts: POST /v1/memory recalls by meaning, a collection recalls by key.

Create it explicitly when you need query. Writing to an unknown collection creates it implicitly, but with no indexes — and indexes cannot be added afterwards. If you will ever look items up by a field rather than by key, declare that field here, before the first write.

A collection is defined once for the project. Its ITEMS are per-scope, so the same collection holds a separate set of documents for the project, for each contact, and for each conversation.

Authorization

  • Authorizationheaderrequired

    Bearer YOUR_API_KEY. Create a key in the dashboard.

Body

application/json

  • namestringrequired

    1-63 chars: lowercase letters, digits, - and _, starting with a letter or digit.

  • indexesobject[]

    Up to 2 fields to index for query. This is the only way to declare them — a collection created implicitly by its first write has none, and querying an unindexed field returns 400 field_not_indexed. Indexes cannot be added later, so declare them here before the first write.

    Limitsmax items 2
    1 properties
    • fieldstringrequired

      1-64 chars: letters, digits and _, starting with a letter. Top-level field of the stored document.

  • defaultTtlSecondsinteger
    Limitsmin 60 · max 63072000

Responses

201Collection created.
  • collectionobjectrequired

    A namespace of JSON documents addressed by key.

    6 properties
    • namestringrequired
    • indexesobject[]required

      Fields that POST /v1/memory/collections/{collection}/query can filter on. Immutable after creation.

      1 properties
      • fieldstringrequired
    • defaultTtlSecondsintegerrequirednullable

      TTL applied to items written without their own ttlSeconds. Null means items are kept until deleted.

    • statusstringrequired

      active, or deleting while a delete drains in the background.

    • createdAtstring<date-time>required
    • updatedAtstring<date-time>required
400Invalid name, index field, or TTL.
  • codestringrequired
  • messagestringrequired
  • detailsobject
401Unauthorized.
  • codestringrequired
  • messagestringrequired
  • detailsobject
409A collection with that name already exists (`already_exists`), or one is still being deleted (`collection_deleting`).
  • codestringrequired
  • messagestringrequired
  • detailsobject
429The plan's collection cap is reached.
  • codestringrequired
  • messagestringrequired
  • detailsobject