Won

Won is for whoever reads the memory.

Most of this API answers with memories. Won answers about them: how much a store has been revised, and how far it can be trusted. Read-only, free, and separate from search.

Wontopos is Won + Topos, one place where memory lives. Won is the part of that place that reports on the memory instead of returning it. These calls are free, read-only, and never touch retrieval: asking costs your user nothing and changes nothing about what is remembered.

What is on it today

One call today.

CallWhat it does
POST /won/revisionsHow much of this store has been altered since it was written. Two numbers and two sentences explaining them.

A worked example

Use the ratio, not the raw count. 3 of 40 and 30 of 40 need different handling.

r = mem.revisions()
# {"revised": 3, "total": 40, "counts": "…", "excludes": "…"}

if r["revised"] / r["total"] > 0.1:
    system += "Some of what you remember here has been corrected since."
const r = await mem.revisions();
// { revised: 3, total: 40, counts: "…", excludes: "…" }

if (r.revised / r.total > 0.1) {
  system += "Some of what you remember here has been corrected since.";
}
let r = mem.revisions(None).await?;
let (rev, tot) = (r["revised"].as_f64().unwrap_or(0.0),
                r["total"].as_f64().unwrap_or(1.0));
if rev / tot > 0.1 { /* say so in the system prompt */ }
curl -X POST https://api.wontopos.com/api/v1/won/revisions \
  -H "X-API-Key: $WOS_KEY" -H "Content-Type: application/json" \
  -d '{"user_id":"alice"}'

# → {"user_id":"alice","revised":3,"total":40,
#     "counts":"memories a transform has touched (supersede, update, retract, image removed)",
#     "excludes":"deletions — a deleted memory leaves nothing to count"}

counts and excludes are returned as sentences rather than flags, since the caller is often a model. Deletions are not counted.

Price and limits

RuleValue
PriceNone. Free calls skip the billing gates - no token charge, no per-request fee, and no usage recorded.
Per minute10 per minute, per account and per endpoint. Spending one endpoint's minute does not spend another's.
Per hour300 per hour, per account, shared by every free call. This one ignores the path, so adding free endpoints does not raise the total an account can spend.
Against paid trafficSeparate in both directions. These calls cannot slow your searches and your searches cannot exhaust these. Keys on one account share the buckets, so holding more keys does not multiply the allowance.

Both ceilings answer 429 with Retry-After in seconds and a message naming which one you hit.

429 rate_limit_error
Retry-After: 41

{ "error": { "type": "rate_limit_error",
    "message": "This endpoint is free and limited to 10 requests per
                minute, counted per endpoint. Retry in 41s." } }
The same call also answers at /api/v1/memory/revisions, for clients published before the Won surface existed. It is the same handler and the same budget, not a second allowance. New code should use the Won address.