Speakers

What one person said, newest first

POST/api/v1/memory/by-speaker

In the SDKs: by_speaker

speaker is the tag written at store time — "me" for the assistant’s own words, otherwise a registered name. Same cursor paging as /images. chunks and records_to_delete say how much a delete would actually remove, which is usually more than returned — worth showing someone before they confirm one. (points_to_delete is the same number under a deprecated name.)

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

speaker string required

"me" for the assistant, or a registered person.

limit integer 5–20

Per page, 5–20 (default 20).

before string

Cursor: next_before from the previous page.

skip_ids string[]

Cursor: next_skip_ids, accumulated.

Returns

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

user_id string
speaker string
memories Memory[]
memories.id string
memories.content string
memories.category string

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

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

memories.importance number

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

memories.time_bucket string

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

memories.is_superseded boolean

True if a later memory has superseded this one.

memories.superseded_by string,null

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

memories.created_at string

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

memories.event_date string

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

memories.speaker string

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

returned integer
chunks integer

How much a delete here would remove — usually more than returned.

records_to_delete integer

The same count. Prefer this name.

points_to_delete integer

Deprecated alias of records_to_delete; both carry the same value. Read records_to_delete.

has_more boolean
next_before string
next_skip_ids string[]

Example

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

Status codes

StatusMeaning
200Success.
400speaker missing or empty.
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.