---
title: "Create a collection"
method: POST
path: "/v1/memory/collections"
tags: ["Memory"]
---

# Create a collection

`POST /v1/memory/collections`

## Request

- Base URL: `https://api.zavu.dev`
- URL: `https://api.zavu.dev/v1/memory/collections`
- Auth: HTTP bearer

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.

## Request body

- MemoryCollectionCreateRequest
  - `name` string, required: 1-63 chars: lowercase letters, digits, `-` and `_`, starting with a letter or digit.
  - `indexes` object[]: 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.
    - `field` string, required: 1-64 chars: letters, digits and `_`, starting with a letter. Top-level field of the stored document.
  - `defaultTtlSeconds` integer

## Response `201`

Collection created.

- object
  - `collection` MemoryCollection, required: A namespace of JSON documents addressed by key.
    - `name` string, required
    - `indexes` object[], required: Fields that `POST /v1/memory/collections/{collection}/query` can filter on. Immutable after creation.
      - `field` string, required
    - `defaultTtlSeconds` integer, nullable, required: TTL applied to items written without their own `ttlSeconds`. Null means items are kept until deleted.
    - `status` string, required: `active`, or `deleting` while a delete drains in the background.
    - `createdAt` string, date-time, required
    - `updatedAt` string, date-time, required

## Other responses

- `400`: Invalid name, index field, or TTL.
- `401`: Unauthorized.
- `409`: A collection with that name already exists (`already_exists`), or one is still being deleted (`collection_deleting`).
- `429`: The plan's collection cap is reached.

## Changes

> 80 revisions in range; 1 not diffed.

- **2026-08-26** `6e8c555e1104`: 1 info
  - removed the non-success response with the status `403`
- **2026-08-26** `83caf7165722`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/zavudev/apis/zavu-unified-messaging-layer-api/changes/v1/memory/collections/post.md)

---

[API](https://skmtc.dev/zavudev/apis/zavu-unified-messaging-layer-api.md) - [All operations](https://skmtc.dev/zavudev/apis/zavu-unified-messaging-layer-api/llms.txt) - [OpenAPI document](https://skmtc.dev/zavudev/apis/zavu-unified-messaging-layer-api/revisions/75bc777b0ffb?raw)