---
title: "Write Batch"
method: POST
path: "/api/v1/memory/write_batch"
tags: ["memory"]
---

# Write Batch

`POST /api/v1/memory/write_batch`

## Request

- Base URL: `https://core.mnemoverse.com`
- URL: `https://core.mnemoverse.com/api/v1/memory/write_batch`
- Auth: one of:
  - API key in header `X-Api-Key`
  - HTTP bearer

Store multiple memory atoms in one request. Each atom is processed sequentially.

`supersedes` is refused here (422) — see `_reject_supersedes_in_batch`.

## Request body

- WriteBatchRequestSchema: Request body for writing multiple atoms in one request.
  - `items` WriteRequestSchema[], required: List of atoms to write.
    - `content` string, required: The insight, pattern, or lesson to remember.
    - `concepts` string[]: Key concepts (used for Hebbian associations). At most 256 items — the write-time association pass is quadratic in this count.
    - `domain` string: Namespace: 'general', 'user:X', 'room:Y', 'project:Z'.
    - `fingerprint` string, nullable: Optional SHA256-like fingerprint for exact episodic match (e.g. task hash). At most 512 characters.
    - `metadata` object: Arbitrary key-value metadata. The serialized JSON must be at most 65536 bytes.
    - `external_ref` string, nullable: Client-provided unique reference for idempotent writes and cross-system correlation. May not start with `secret:`, the namespace of Vault secret aliases (400 VALIDATION_ERROR).
    - `supersedes` string[], nullable: Ids of atoms this write REPLACES. The successor is stored and every listed atom is marked as superseded by it, in one transaction — all of it or none. At most 32 ids, all distinct. Supersession is caller-asserted: the engine never infers that two atoms describe the same fact. Not accepted on write_batch, and not accepted alongside an `xroom:` domain.
    - `author` ProvenanceWriteSchema: SUPPLIER-vouched authorship sent in a write body (CN-001b). The reserved, optional ``author`` object a SERVICE/supplier caller may send to VOUCH for the participant behind a write (e.g. the supplier's own end user). It is HONORED ONLY for supplier/service tokens and IGNORED (silently dropped) for OIDC end-users — an end-user can never set authorship (see routes._get_provenance). Even for a supplier the shape is not blindly trusted: the route re-normalizes every field via auth._normalize_supplier_ author (client_env allow-list, length caps, is_external→bool). All fields are optional and loosely typed here so an odd supplier value is normalized rather than 422-ing the whole write; ``extra="forbid"`` still blocks unknown keys INSIDE the author object.
      - `principal` string, nullable: Participant the supplier vouches for.
      - `agent` string, nullable: Stable agent identifier, if any.
      - `agent_name` string, nullable: Human-readable agent name, if any.
      - `client_env` string, nullable: Calling client environment (cursor·claude·chatgpt·chat·api·unknown); anything else normalizes to null.
      - `is_external` boolean: True when the vouched principal is external to the org.

## Response `200`

Successful Response

- WriteBatchResponseSchema: Response after batch write.
  - `total_count` integer, required: Total number of atoms processed.
  - `stored_count` integer, required: Number of atoms stored (passed importance gate).
  - `results` WriteBatchItemResult[], required: Per-atom results in request order.
    - `index` integer, required: Position in the request items list.
    - `stored` boolean, required: True if the atom was stored.
    - `atom_id` string, uuid, nullable: UUID of stored atom, or None.
    - `importance` number: Computed importance score.
    - `reason` string: Engine-provided reason when the item was filtered instead of stored.
    - `error` string, nullable: Error message if item failed.

## Other responses

- `400`: Validation error
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not found
- `422`: Validation Error
- `429`: Rate limited
- `500`: Internal server error
- `503`: Engine not initialized

---

[API](https://skmtc.dev/mnemoverse/apis/mnemoverse-core.md) · [All operations](https://skmtc.dev/mnemoverse/apis/mnemoverse-core/llms.txt) · [OpenAPI document](https://skmtc.dev/mnemoverse/apis/mnemoverse-core/revisions/1f5e0048f017?raw)