Images

A store’s image memories, newest first

POST/api/v1/memory/images

In the SDKs: list_images · iter_images

Cursor paging, never an offset: hand next_before and next_skip_ids back as before and skip_ids. A bulk write stamps many memories with the SAME instant, so cutting on time alone silently drops the rest of that instant. count is the store total, so you can show “142 images” without walking every page.

Authentication

Every call carries your API key in an X-API-Key header. Keys are created in the console.

X-WOS-Modeloptional

Picks the memory model that answers. Omit it and the account default is used.

Request body

JSON, required. Out-of-range values are refused with a 400 rather than quietly clamped.

user_id string required

The store to operate on. Stores are explicit: create one first or use the built-in "default".

limit integer 5–20

Per page, 5–20 (default 20). Out of range is refused, not clamped.

before string

Cursor: next_before from the previous page (RFC3339).

skip_ids string[]

Cursor: next_skip_ids from the previous page. Accumulates across pages.

Returns

The 200 body. Fields nested one level are shown as parent.child.

user_id string
images Memory[]
images.id string
images.content string
images.category string

Category of the memory, e.g. "general".

images.similarity number

How close this memory is to the query (0–1), higher is closer. It is NOT the ranking key — results already arrive best-first, and ordering by this field instead produces a WORSE order, not the same one. Take memories in the order given. There is no score field.

images.importance number

How much weight this memory carries, as the engine assigned it.

images.time_bucket string

Month bucket, e.g. "2026-07". Omitted when temporal fields are stripped.

images.is_superseded boolean

True if a later memory has superseded this one.

images.superseded_by string,null

Id of the memory that superseded this one, or null.

images.created_at string

When the memory was stored (RFC3339). Omitted when temporal fields are stripped.

images.event_date string

When the content actually happened (RFC3339), if known.

images.speaker string

WHO said it: "me" (the agent itself) or a registered person. Absent = untagged.

count integer

Image memories in the whole store, not on this page.

has_more boolean
next_before string
next_skip_ids string[]

Example

cURL
curl -X POST https://api.wontopos.com/api/v1/memory/images \
  -H "X-API-Key: $WOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Status codes

StatusMeaning
200Success.
401Missing or invalid API key.
404Store (user_id) does not exist. Create it first: POST /api/v1/memory/collection.
429Rate limited (per-account, per-tier RPM). Retry after the indicated delay.
501The selected model’s engine does not implement this endpoint (Tablet 2 and newer do). The message names the model.

Rate limits per tier and the full status list are in Errors & limits.

In the SDKs

The Python, TypeScript, and Rust SDKs wrap this endpoint so you do not build the request by hand — pip install wontopos, npm i wontopos, or cargo add wontopos, then the method list is on the SDK reference. A coding agent can take the whole API in one file at llms.txt, or over MCP with npx -y wontopos-mcp.