{"openapi":"3.1.0","info":{"title":"Wontopos Memory API","version":"1.0.0","description":"Long-term memory for AI agents. Pure semantic retrieval — identical recall in every language, no LLM in the store/search path. Store under a user_id (a \"store\"), recall with one call. Machine-readable companion of https://wontopos.com/en/why and https://wontopos.com/llms.txt.","contact":{"url":"https://wontopos.com"}},"servers":[{"url":"https://api.wontopos.com"}],"security":[{"ApiKey":[]}],"tags":[{"name":"memory","description":"Store, search, and manage memories."},{"name":"stores","description":"Explicit stores (user_id namespaces)."},{"name":"speakers","description":"WHO said each memory: \"me\" or registered people (50 per store to start)."},{"name":"engram","description":"Built-in multi-hop retrieval pipelines."},{"name":"meta","description":"Models and service health."}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Your Wontopos API key (wos-live-...). Create one in the console at wontopos.com."}},"parameters":{"XWosModel":{"name":"X-WOS-Model","in":"header","required":false,"schema":{"type":"string","default":"tablet-1"},"description":"Which engine reads the memory (see GET /api/v1/models). All live models share one memory per account, so you can store with one and recall with another."},"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{1,128}$"},"description":"Makes repeating THIS EXACT write safe: the first response is replayed instead of storing again (10 minutes), and the same key with a different body answers 422. Use it when the retry is yours — a job that died and was re-run, a queue that redelivers. Derive the key from the thing being stored (\"import:row-42\"), never a constant: reusing one key for two different writes replays the first and the second is silently lost. Only 2xx responses are cached, so a failed call is retryable at once. The window is in-memory, so a deploy clears it early — it guards against a retry storm, it is not a durable ledger."}},"schemas":{"Error":{"type":"object","description":"Standard error envelope. Branch on the HTTP status and typed fields (e.g. speaker, speaker_limit), never on message text.","properties":{"type":{"type":"string","enum":["error"]},"error":{"type":"object","properties":{"type":{"type":"string","description":"Machine-readable error type, e.g. invalid_request_error."},"message":{"type":"string"},"request_id":{"type":"string","description":"Echo this when contacting support."}},"additionalProperties":true}},"additionalProperties":true},"Memory":{"type":"object","description":"A memory as returned by search / recall. Rank by `similarity`. Temporal fields (time_bucket, created_at, event_date) are omitted when the caller strips them.","properties":{"id":{"type":"string","format":"uuid"},"content":{"type":"string"},"category":{"type":"string","description":"Cognitive category, e.g. \"general\"."},"similarity":{"type":"number","description":"Raw embedding similarity to the query (0–1), higher is closer. NOT the ranking key: results already arrive best-first, ordered by the engine’s reranker, which is internal and not returned. Re-sorting by `similarity` therefore overrides the ranking and makes results worse — take `memories` in the order given. There is no `score` field."},"importance":{"type":"number","description":"Learned importance weight of the memory."},"time_bucket":{"type":"string","description":"Month bucket, e.g. \"2026-07\". Omitted when temporal fields are stripped."},"is_superseded":{"type":"boolean","description":"True if a later memory has superseded this one."},"superseded_by":{"type":["string","null"],"description":"Id of the memory that superseded this one, or null."},"created_at":{"type":"string","format":"date-time","description":"When the memory was stored (RFC3339). Omitted when temporal fields are stripped."},"event_date":{"type":"string","format":"date-time","description":"When the content actually happened (RFC3339), if known."},"speaker":{"type":"string","description":"WHO said it: \"me\" (the agent itself) or a registered person. Absent = untagged."}},"additionalProperties":true},"Usage":{"type":"object","properties":{"input_tokens":{"type":"integer"},"output_tokens":{"type":"integer"}},"additionalProperties":true}}},"paths":{"/health":{"get":{"tags":["meta"],"summary":"Service health","security":[],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"service":{"type":"string"},"ts":{"type":"string"}},"additionalProperties":true}}}}}}},"/api/v1/models":{"get":{"tags":["meta"],"summary":"List models","description":"Available engines. memory: \"shared\" reads the common per-account pool; \"isolated\" has its own.","security":[],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"models":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"available":{"type":"boolean"},"memory":{"type":"string","enum":["shared","isolated"]}},"additionalProperties":true}}},"additionalProperties":true}}}}}}},"/api/v1/memory/store":{"post":{"tags":["memory"],"summary":"Store one memory","parameters":[{"$ref":"#/components/parameters/XWosModel"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["user_id","content"],"properties":{"user_id":{"type":"string","description":"The store to operate on. Stores are explicit: create one first or use the built-in \"default\"."},"content":{"type":"string"},"metadata":{"type":"object","description":"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.","properties":{"event_date":{"type":"string"},"speaker":{"type":"string"}},"additionalProperties":true}},"additionalProperties":true}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Empty when status is \"duplicate\"."},"status":{"type":"string","enum":["stored","stored (async)","duplicate"]},"note":{"type":"string","description":"Present when something non-fatal was dropped (e.g. a speaker tag on a duplicate)."},"duplicate_of":{"type":"string","description":"Present when status is \"duplicate\": the id of the memory this write collided with. Use it to decide whether to merge the two into one sentence or supersede the existing one — a dropped write that does not say what it hit gives the caller nothing to act on."}},"additionalProperties":true}}}},"400":{"description":"Invalid body — or an UNREGISTERED speaker name (register it first: POST /api/v1/memory/speakers; the error carries a \"speaker\" field). Nothing is stored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Store (user_id) does not exist. Create it first: POST /api/v1/memory/collection.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (per-account, per-tier RPM). Retry after the indicated delay.","headers":{"Retry-After":{"schema":{"type":"string"},"description":"Seconds until the next request is accepted."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/memory/search":{"post":{"tags":["memory"],"summary":"Semantic search","parameters":[{"$ref":"#/components/parameters/XWosModel"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["user_id","query"],"properties":{"user_id":{"type":"string","description":"The store to operate on. Stores are explicit: create one first or use the built-in \"default\"."},"query":{"type":"string"},"max_results":{"type":"integer","default":10},"speaker":{"type":"string","description":"Recall only this person’s words (\"me\" or a registered name). Unregistered → 404."},"cache_control":{"type":"object","description":"Opt-in recall caching: first call writes the cache (billed 2x query tokens for 5m TTL, 3x for 1h), hits within the TTL bill 0.1x. Any write to the store invalidates instantly.","properties":{"ttl":{"type":"string","enum":["5m","1h"]}},"additionalProperties":false},"filters":{"type":"object","description":"Narrow the search to part of the store. Applied BEFORE ranking, so you get the best matches within the filter rather than a filtered top-N. Retrieval stays purely semantic, so filtering behaves identically in every language. Unlisted keys are dropped rather than rejected — a typo silently widens the search.","properties":{"categories":{"type":"array","items":{"type":"string"},"description":"Only these categories (the `category` you see on /list results)."},"event_from":{"type":"string","description":"WHEN THE CONTENT HAPPENED (metadata.event_date), not when it was written — usually the one you want. RFC3339, or a plain YYYY-MM-DD."},"event_to":{"type":"string","description":"Upper bound of the same event-date window."},"time_from":{"type":"string","description":"Ingestion-time window, matched as given."},"time_to":{"type":"string","description":"Upper bound of the ingestion-time window."},"min_importance":{"type":"number","description":"Drop matches the engine scored below this importance (0–1)."}},"additionalProperties":false}},"additionalProperties":true}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"memories":{"type":"array","items":{"$ref":"#/components/schemas/Memory"}}},"additionalProperties":true}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Store does not exist — or the speaker filter names an unregistered person.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (per-account, per-tier RPM). Retry after the indicated delay.","headers":{"Retry-After":{"schema":{"type":"string"},"description":"Seconds until the next request is accepted."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/memory/recall":{"post":{"tags":["memory"],"summary":"One-call LLM context","description":"Short-term turns + long-term matches + surrounding context in one bounded call.","parameters":[{"$ref":"#/components/parameters/XWosModel"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["user_id","query"],"properties":{"user_id":{"type":"string","description":"The store to operate on. Stores are explicit: create one first or use the built-in \"default\"."},"query":{"type":"string"}},"additionalProperties":true}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"short_term":{"type":"object","additionalProperties":true},"long_term":{"type":"object","properties":{"memories":{"type":"array","items":{"$ref":"#/components/schemas/Memory"}},"count":{"type":"integer"}},"additionalProperties":true},"context":{"type":"object","additionalProperties":true}},"additionalProperties":true}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Store (user_id) does not exist. Create it first: POST /api/v1/memory/collection.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (per-account, per-tier RPM). Retry after the indicated delay.","headers":{"Retry-After":{"schema":{"type":"string"},"description":"Seconds until the next request is accepted."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/memory/store-turn":{"post":{"tags":["memory"],"summary":"Store a conversation turn","description":"One user + assistant exchange into short-term and long-term memory.","parameters":[{"$ref":"#/components/parameters/XWosModel"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["user_id"],"properties":{"user_id":{"type":"string","description":"The store to operate on. Stores are explicit: create one first or use the built-in \"default\"."},"user_msg":{"type":"string"},"assistant_msg":{"type":"string"}},"additionalProperties":true}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"}},"additionalProperties":true}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Store (user_id) does not exist. Create it first: POST /api/v1/memory/collection.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (per-account, per-tier RPM). Retry after the indicated delay.","headers":{"Retry-After":{"schema":{"type":"string"},"description":"Seconds until the next request is accepted."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/memory/history":{"post":{"tags":["memory"],"summary":"Recent turns (short-term memory)","parameters":[{"$ref":"#/components/parameters/XWosModel"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["user_id"],"properties":{"user_id":{"type":"string","description":"The store to operate on. Stores are explicit: create one first or use the built-in \"default\"."}},"additionalProperties":true}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"turns":{"type":"array","items":{"type":"object","additionalProperties":true}}},"additionalProperties":true}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Store (user_id) does not exist. Create it first: POST /api/v1/memory/collection.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (per-account, per-tier RPM). Retry after the indicated delay.","headers":{"Retry-After":{"schema":{"type":"string"},"description":"Seconds until the next request is accepted."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/memory/list":{"post":{"tags":["memory"],"summary":"List a store’s memories (original text, no vectors)","description":"Paginates the raw memories in a store — the text you stored plus its metadata, never the vector. Use it to browse or export a store. Pass the returned `next_cursor` back as `cursor` for the next page; a null cursor means the last page.","parameters":[{"$ref":"#/components/parameters/XWosModel"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["user_id"],"properties":{"user_id":{"type":"string","description":"The store to operate on. Stores are explicit: create one first or use the built-in \"default\"."},"limit":{"type":"integer","minimum":1,"maximum":500,"default":100},"cursor":{"type":"string","description":"Opaque page cursor from a previous response’s next_cursor."}},"additionalProperties":true}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"memories":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"content":{"type":"string"},"category":{"type":"string"},"source_type":{"type":"string","nullable":true},"created_at":{"type":"string","nullable":true},"event_date":{"type":"string","nullable":true},"is_superseded":{"type":"boolean"}},"additionalProperties":true}},"count":{"type":"integer"},"next_cursor":{"type":"string","nullable":true}},"additionalProperties":true}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Store (user_id) does not exist. Create it first: POST /api/v1/memory/collection.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (per-account, per-tier RPM). Retry after the indicated delay.","headers":{"Retry-After":{"schema":{"type":"string"},"description":"Seconds until the next request is accepted."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/memory/get":{"post":{"tags":["memory"],"summary":"Fetch one memory by id (original text, no vector)","description":"Returns a single stored memory by the id that /store or /list returned — the original text plus its metadata, never the vector. Same visibility as /list: a decomposed atom sentence, an invalidated memory, or an id from another store is a 404.","parameters":[{"$ref":"#/components/parameters/XWosModel"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["user_id","memory_id"],"properties":{"user_id":{"type":"string","description":"The store to operate on. Stores are explicit: create one first or use the built-in \"default\"."},"memory_id":{"type":"string","format":"uuid","description":"The memory id from /store or /list."}},"additionalProperties":true}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"user_id":{"type":"string"},"memory":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"content":{"type":"string"},"category":{"type":"string"},"source_type":{"type":"string","nullable":true},"created_at":{"type":"string","nullable":true},"event_date":{"type":"string","nullable":true},"is_superseded":{"type":"boolean"}},"additionalProperties":true}},"additionalProperties":true}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Store (user_id) does not exist. Create it first: POST /api/v1/memory/collection.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (per-account, per-tier RPM). Retry after the indicated delay.","headers":{"Retry-After":{"schema":{"type":"string"},"description":"Seconds until the next request is accepted."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/memory/bulk-store":{"post":{"tags":["memory"],"summary":"Bulk-ingest a large blob","description":"Chunked and embedded server-side. For backfilling long histories.","parameters":[{"$ref":"#/components/parameters/XWosModel"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["user_id","content"],"properties":{"user_id":{"type":"string","description":"The store to operate on. Stores are explicit: create one first or use the built-in \"default\"."},"content":{"type":"string"},"category":{"type":"string","default":"general"},"timestamp":{"type":"string","description":"RFC3339 — when the content happened."}},"additionalProperties":true}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"}},"additionalProperties":true}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Store (user_id) does not exist. Create it first: POST /api/v1/memory/collection.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (per-account, per-tier RPM). Retry after the indicated delay.","headers":{"Retry-After":{"schema":{"type":"string"},"description":"Seconds until the next request is accepted."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/memory/supersede":{"post":{"tags":["memory"],"summary":"Supersede an out-of-date memory","description":"Replaces old content with new; the old memory stops answering. Speaker tags follow.","parameters":[{"$ref":"#/components/parameters/XWosModel"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["user_id","old_memory_id","new_content"],"properties":{"user_id":{"type":"string","description":"The store to operate on. Stores are explicit: create one first or use the built-in \"default\"."},"old_memory_id":{"type":"string","format":"uuid"},"new_content":{"type":"string"}},"additionalProperties":true}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"old_memory_id":{"type":"string"},"new_memory_id":{"type":"string"},"status":{"type":"string"}},"additionalProperties":true}}}},"400":{"description":"Invalid or missing old_memory_id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Store (user_id) does not exist. Create it first: POST /api/v1/memory/collection.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (per-account, per-tier RPM). Retry after the indicated delay.","headers":{"Retry-After":{"schema":{"type":"string"},"description":"Seconds until the next request is accepted."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/memory/forget":{"post":{"tags":["memory"],"summary":"Delete one memory — or every memory in the store","description":"With memory_id: delete that memory. WITHOUT memory_id: delete EVERY memory in the store (GDPR erase). Omitting the id is destructive by design — send it explicitly for single deletes.","parameters":[{"$ref":"#/components/parameters/XWosModel"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["user_id"],"properties":{"user_id":{"type":"string","description":"The store to operate on. Stores are explicit: create one first or use the built-in \"default\"."},"memory_id":{"type":"string","format":"uuid","description":"Omit to erase the whole store."}},"additionalProperties":true}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"}},"additionalProperties":true}}}},"400":{"description":"memory_id present but not a valid id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Store (user_id) does not exist. Create it first: POST /api/v1/memory/collection.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (per-account, per-tier RPM). Retry after the indicated delay.","headers":{"Retry-After":{"schema":{"type":"string"},"description":"Seconds until the next request is accepted."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/memory/stats":{"post":{"tags":["memory"],"summary":"Memory counts for a store","parameters":[{"$ref":"#/components/parameters/XWosModel"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["user_id"],"properties":{"user_id":{"type":"string","description":"The store to operate on. Stores are explicit: create one first or use the built-in \"default\"."}},"additionalProperties":true}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"total_memories":{"type":"integer"},"short_term_turns":{"type":"integer"}},"additionalProperties":true}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Store (user_id) does not exist. Create it first: POST /api/v1/memory/collection.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (per-account, per-tier RPM). Retry after the indicated delay.","headers":{"Retry-After":{"schema":{"type":"string"},"description":"Seconds until the next request is accepted."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/memory/collection":{"post":{"tags":["stores"],"summary":"Create a store","description":"Stores are explicit: a store must exist before you write to or read it. Idempotent. Every account starts with a built-in \"default\" store.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["user_id"],"properties":{"user_id":{"type":"string","description":"The store to operate on. Stores are explicit: create one first or use the built-in \"default\".","maxLength":128}},"additionalProperties":true}}}},"responses":{"200":{"description":"Already existed (idempotent).","content":{"application/json":{"schema":{"type":"object","properties":{"user_id":{"type":"string"},"status":{"type":"string","enum":["exists"]}},"additionalProperties":true}}}},"201":{"description":"Created.","content":{"application/json":{"schema":{"type":"object","properties":{"user_id":{"type":"string"},"status":{"type":"string","enum":["created"]}},"additionalProperties":true}}}},"400":{"description":"user_id longer than 128 characters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (per-account, per-tier RPM). Retry after the indicated delay.","headers":{"Retry-After":{"schema":{"type":"string"},"description":"Seconds until the next request is accepted."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["stores"],"summary":"Delete a store and ALL its memories","description":"Destructive. Also drops the store’s registered speakers and their tags.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["user_id"],"properties":{"user_id":{"type":"string","description":"The store to operate on. Stores are explicit: create one first or use the built-in \"default\"."}},"additionalProperties":true}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"user_id":{"type":"string"},"status":{"type":"string","enum":["deleted"]}},"additionalProperties":true}}}},"400":{"description":"user_id missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Store (user_id) does not exist. Create it first: POST /api/v1/memory/collection.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (per-account, per-tier RPM). Retry after the indicated delay.","headers":{"Retry-After":{"schema":{"type":"string"},"description":"Seconds until the next request is accepted."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/memory/collections":{"get":{"tags":["stores"],"summary":"List your stores","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"collections":{"type":"array","items":{"type":"object","properties":{"user_id":{"type":"string"},"created_at":{"type":"string"}},"additionalProperties":true}},"count":{"type":"integer"}},"additionalProperties":true}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (per-account, per-tier RPM). Retry after the indicated delay.","headers":{"Retry-After":{"schema":{"type":"string"},"description":"Seconds until the next request is accepted."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/memory/speakers":{"post":{"tags":["speakers"],"summary":"Register a person","description":"Speakers are explicit, like stores: register once, then store with metadata.speaker. \"me\" (the agent itself) is reserved, exact lowercase, never registered and never counted. Up to 50 people per store to start.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["user_id","speaker"],"properties":{"user_id":{"type":"string","description":"The store to operate on. Stores are explicit: create one first or use the built-in \"default\"."},"speaker":{"type":"string","maxLength":80}},"additionalProperties":true}}}},"responses":{"200":{"description":"Already registered (idempotent).","content":{"application/json":{"schema":{"type":"object","properties":{"user_id":{"type":"string"},"speaker":{"type":"string"},"status":{"type":"string","enum":["exists"]}},"additionalProperties":true}}}},"201":{"description":"Registered.","content":{"application/json":{"schema":{"type":"object","properties":{"user_id":{"type":"string"},"speaker":{"type":"string"},"status":{"type":"string","enum":["registered"]}},"additionalProperties":true}}}},"400":{"description":"Reserved name (\"me\" in any casing), invalid name, or the store is at its cap — the error carries speaker_limit (50).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Store (user_id) does not exist. Create it first: POST /api/v1/memory/collection.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (per-account, per-tier RPM). Retry after the indicated delay.","headers":{"Retry-After":{"schema":{"type":"string"},"description":"Seconds until the next request is accepted."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"tags":["speakers"],"summary":"List registered people","parameters":[{"name":"user_id","in":"query","required":false,"schema":{"type":"string"},"description":"Defaults to \"default\"."}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"user_id":{"type":"string"},"speakers":{"type":"array","items":{"type":"object","properties":{"speaker":{"type":"string"},"memories":{"type":"integer"},"created_at":{"type":"string"}},"additionalProperties":true}},"count":{"type":"integer"},"limit":{"type":"integer","description":"Registration cap for this store (50 to start)."}},"additionalProperties":true}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Store (user_id) does not exist. Create it first: POST /api/v1/memory/collection.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (per-account, per-tier RPM). Retry after the indicated delay.","headers":{"Retry-After":{"schema":{"type":"string"},"description":"Seconds until the next request is accepted."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["speakers"],"summary":"Unregister a person","description":"Their memories stay; the name tag goes. Re-registering does not restore old tags.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["user_id","speaker"],"properties":{"user_id":{"type":"string","description":"The store to operate on. Stores are explicit: create one first or use the built-in \"default\"."},"speaker":{"type":"string"}},"additionalProperties":true}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"user_id":{"type":"string"},"speaker":{"type":"string"},"status":{"type":"string","enum":["removed"]}},"additionalProperties":true}}}},"400":{"description":"speaker missing or empty.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Store does not exist, or the speaker was never registered.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (per-account, per-tier RPM). Retry after the indicated delay.","headers":{"Retry-After":{"schema":{"type":"string"},"description":"Seconds until the next request is accepted."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/engram":{"get":{"tags":["engram"],"summary":"List engrams the selected model can run","parameters":[{"$ref":"#/components/parameters/XWosModel"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"engrams":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"}},"additionalProperties":true}},"forms":{"type":"array","items":{"type":"string"}}},"additionalProperties":true}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (per-account, per-tier RPM). Retry after the indicated delay.","headers":{"Retry-After":{"schema":{"type":"string"},"description":"Seconds until the next request is accepted."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/engram/run":{"post":{"tags":["engram"],"summary":"Run an engram","description":"Built-in multi-hop retrieval in one call. Call GET /api/v1/engram for the catalog the selected model can run, with a description of each. Available: deep_recall, timeline, equilibrium, tone_stabilizer, gather. Input is billed per engine hop the engram performs, output by what it returns.","parameters":[{"$ref":"#/components/parameters/XWosModel"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","user_id","query"],"properties":{"name":{"type":"string","enum":["deep_recall","timeline","equilibrium","tone_stabilizer","gather"]},"user_id":{"type":"string","description":"The store to operate on. Stores are explicit: create one first or use the built-in \"default\"."},"query":{"type":"string"},"form":{"type":"string","description":"Delivery form (model-dependent; see GET /api/v1/engram)."},"tz":{"type":"integer","description":"UTC offset hours for time-aware forms."}},"additionalProperties":true}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"engram":{"type":"string"},"form":{"type":"string"},"user_id":{"type":"string"},"hops":{"type":"integer"},"count":{"type":"integer"},"memories":{"type":"array","items":{"$ref":"#/components/schemas/Memory"}},"usage":{"$ref":"#/components/schemas/Usage"}},"additionalProperties":true}}}},"400":{"description":"Unknown engram name, or the selected model cannot run it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Store (user_id) does not exist. Create it first: POST /api/v1/memory/collection.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (per-account, per-tier RPM). Retry after the indicated delay.","headers":{"Retry-After":{"schema":{"type":"string"},"description":"Seconds until the next request is accepted."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}