How much of this store has been altered

POST/api/v1/won/revisions

In the SDKs: revisions

How many memories in this store have been changed since they were written. Intended to be asked freely — by your app and by a model reading its own store — so it carries NO charge: no tokens, no per-request fee. Rate limited to 10 requests per minute, counted per endpoint per account, separately from your paid limit. Counts transforms (supersede); does not count deletions — a deleted memory leaves nothing to count — and counts only the memories you stored, not anything the engine keeps for itself. By default the answer is COUNTS ONLY, and its size does not depend on how much memory you have: a store of a hundred and a store of a hundred million get the same few numbers back. Send include to also receive one page of the memories behind a number — at most 20 per call, and never both lists at once. Page with before / skip_ids from the previous response, as /api/v1/memory/images does. Also served at /api/v1/memory/revisions, which is where clients published before 2026-08-18 call it; the two share one rate-limit budget.

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

include "revised" | "unrevised"

Omit for counts only. Set it to also receive ONE page of the memories behind that number. Only one of the two per call — there is no way to ask for both lists in a single response. An unrecognised value is rejected rather than silently ignored, because a typo that quietly drops the list looks exactly like an empty store.

limit integer 5–20 · default 20

Memories per page, when include is set. 20 is both the default and the ceiling; a larger value is rejected, not clamped.

before string

Cursor: next_before from the previous page. RFC3339 — an epoch number is rejected, because silently ignoring it would hand back page 1 forever.

skip_ids string[]

Cursor: next_skip_ids from the previous page. Hand back what you were given — these are the ids already seen at the boundary timestamp, and dropping them makes the pager repeat itself.

Returns

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

revised integer

Memories a transform has touched.

unrevised integer

Memories nothing has touched since they were written.

total integer

Memories in the store. Always revised + unrevised.

counts string

excludes string

include string

Echoed back only when a page was requested.

matched integer

TOTAL memories behind this page (equal to revised or unrevised), not the size of the page. Only present with include.

memories object[]

One page, at most 20. Only present with include.

has_more boolean

next_before string

next_skip_ids string[]

ordered_by string

Which order the page is in — by when each memory was STORED, not when it was edited. Stated because assuming the latter would read the page wrong.

Example

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

Status codes

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.

Related

• Revisions (alias)
• Lineage