# Create a collection

> 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.

`POST https://api.zavu.dev/v1/memory/collections`

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.

## Body

- `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)

## Responses

### 201

Collection created.

- `collection` (object, 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, required, nullable): 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)

### 400

Invalid name, index field, or TTL.

- `code` (string, required)
- `message` (string, required)
- `details` (object)

### 401

Unauthorized.

- `code` (string, required)
- `message` (string, required)
- `details` (object)

### 409

A collection with that name already exists (`already_exists`), or one is still being deleted (`collection_deleting`).

- `code` (string, required)
- `message` (string, required)
- `details` (object)

### 429

The plan's collection cap is reached.

- `code` (string, required)
- `message` (string, required)
- `details` (object)

## Example

```bash
curl -X POST "https://api.zavu.dev/v1/memory/collections" \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "orders",
  "indexes": [
    {
      "field": "status"
    }
  ]
}'
```

```typescript
import Zavudev from "@zavudev/sdk";

const zavu = new Zavudev({ apiKey: process.env.ZAVUDEV_API_KEY });

const result = await zavu.memory.collections.create({
  name: "orders",
  indexes: [
    {
      field: "status",
    },
  ],
});

console.log(result);
```