---
title: "Store one memory"
method: POST
path: "/api/v1/memory/store"
tags: ["memory"]
---

# Store one memory

`POST /api/v1/memory/store`

## Request

- Base URL: `https://api.wontopos.com`
- URL: `https://api.wontopos.com/api/v1/memory/store`
- Auth: API key in header `X-API-Key`

## Headers

- `X-WOS-Model` string
- `Idempotency-Key` string

## Request body

- object
  - `user_id` string, required: The store to operate on. Stores are explicit: create one first or use the built-in "default". Use the id the store was created with: 1-64 ASCII letters, digits, ., _ or -, starting with a letter or digit. Ids that differ only by case name one store.
  - `content` string, required
  - `metadata` object: Optional. Known keys: event_date (RFC3339 — when it actually happened), speaker ("me" for the agent’s own words, or a REGISTERED person’s name). Unknown keys are dropped.
    - `event_date` string
    - `speaker` string
  - `image` object: An image to store with the text (Tablet 2 and newer; an older model refuses the write rather than keeping the caption and dropping the image). `content` may be EMPTY when you pass one — then the image IS the memory and is searchable on its own. Billed in tokens, the same unit as text: pixel area / 556.7, counted with the long edge capped at 1568px — so a 2500px image and a 1568px one cost the same. That works out to about 1.35x what the same area of text would cost, and to a ceiling of 4,417 tokens for any single image. The ceiling is reserved against your balance before the call; the measured value is charged after and is never higher. What we keep is NOT your original. A long edge from 1568px up to 2500px is downscaled to 1568 on the way in, and that smaller picture is what gets embedded, stored and handed back. Downscaling re-encodes: lossless formats are written as WebP, so a 2500px PNG usually comes back at 1568px as image/webp (a re-encode that would be bigger is dropped and your bytes kept); JPEG stays JPEG, and below 1568px the bytes are untouched. Keep your own copy, or put its URL in `reference`, if you need the full-resolution file. Size window: both edges >= 700px, long edge <= 2500px, image file <= 7MB; outside it the call is a 400 that says why. Below 700px a flat minimum applies, so a smaller image would cost the same as a 700px one; above 2500px we will not decode the file at all. Base64 runs ~33% larger than the file and the body cap is 10MB.
    - `data` string, required: The image, base64. A `data:` URL prefix is accepted and stripped.
    - `reference` string: Where YOUR copy of the original lives. Stored as an opaque string; we never fetch it.
    - `taken_at` string: RFC3339, usually from EXIF. Fills `event_date` when that is empty, so the memory sorts by when the image was TAKEN rather than when it was uploaded.

## Response `200`

Success.

- object
  - `id` string: Empty when status is "duplicate".
  - `status` string: "stored" on success — match on the prefix, since the string may carry a suffix, usually 1 — or "duplicate" when the write was dropped because a memory close enough IN MEANING already exists. Match on the prefix, not on equality.
  - `note` string: Present when something non-fatal was dropped (e.g. a speaker tag on a duplicate).

## Other responses

- `400`: Invalid body — or an UNREGISTERED speaker name (register it first: POST /api/v1/memory/speakers; the error carries a "speaker" field). Nothing is stored.
- `401`: Missing or invalid API key.
- `404`: Store (user_id) does not exist. Create it first: POST /api/v1/memory/collection.
- `429`: Rate limited (per-account, per-tier RPM). Retry after the indicated delay.

---

[API](https://skmtc.dev/wontopos/apis/wontopos-memory-api.md) · [All operations](https://skmtc.dev/wontopos/apis/wontopos-memory-api/llms.txt) · [OpenAPI document](https://skmtc.dev/wontopos/apis/wontopos-memory-api/revisions/48dda7326a33?raw)