Every endpoint, one base URL.
No SDK required - any HTTP client works. Base URL https://api.wontopos.com, auth via the X-API-Key header, JSON in and out. Memory ops are POST; managing stores uses POST / GET / DELETE on /collection. A store must exist first (see Stores) or in-store ops return 404.
Headers
| Header | What it does |
|---|---|
| X-API-Key | Required on every call. Your key, issued in the console. |
| X-WOS-Model | Optional. Which engine answers. Omit it and the account default is used. GET /api/v1/models lists the models your key may select; an endpoint an older engine cannot serve answers 501 and names that model. |
| Idempotency-Key | Optional, on writes. The same key with the same body replays the first response instead of storing again - see the note below. |
Endpoint
| Endpoint | Purpose | Body fields |
|---|---|---|
| POST /api/v1/memory/collection | create a store | user_id |
| GET /api/v1/memory/collections | list your stores | (none) |
| DELETE /api/v1/memory/collection | delete a store + its memories | user_id |
| /api/v1/memory/store | store one memory | user_id · content · metadata? (event_date · speaker) · image? |
| /api/v1/memory/store-turn | store a conversation turn | user_id · user_msg · assistant_msg |
| POST /api/v1/memory/speakers | register a speaker (explicit, up to 50) | user_id · speaker |
| GET /api/v1/memory/speakers | list registered speakers + memory counts | user_id |
| DELETE /api/v1/memory/speakers | unregister a speaker (memories stay) | user_id · speaker |
| /api/v1/memory/by-speaker | what one person said, newest first ("me" = the agent) | user_id · speaker · limit? · before? · skip_ids? |
| POST /api/v1/memory/image | the picture we hold for an image memory - not your original | user_id · memory_id |
| DELETE /api/v1/memory/image | remove the image, keep the caption | user_id · memory_id · preview? |
| /api/v1/memory/images | a store's images, newest first (+ the store total) | user_id · limit? · before? · skip_ids? |
| /api/v1/memory/lineage | one memory's chain of edits, oldest first | user_id · memory_id |
| GET /api/v1/won/usage | What this key has spent and what is left — so a model can decide whether to keep going. Free. | days? |
| GET /api/v1/memory/usage | What this key has spent and what is left — so a model can decide whether to keep going. Free. | days? |
| /api/v1/won/revisions | how much of a store has been rewritten. Free | user_id · include? · limit? · before? · skip_ids? |
| /api/v1/memory/revisions | the same call under the memory plane. Free | user_id · include? · limit? · before? · skip_ids? |
| /api/v1/memory/bulk-store | backfill a text blob | user_id · content · category? · timestamp? |
| /api/v1/memory/search | semantic search | user_id · query · max_results? · speaker? · cache_control? · filters? · verify? · max_images? |
| /api/v1/memory/recall | short + long + context | user_id · query · limit? · context_limit? |
| /api/v1/memory/get | one memory by id | user_id · memory_id |
| /api/v1/memory/list | page through a store | user_id · limit? · cursor? |
| /api/v1/memory/history | recent turns | user_id |
| /api/v1/memory/stats | memory counts | user_id |
| /api/v1/memory/supersede | replace a changed fact | user_id · old_memory_id · new_content |
| /api/v1/memory/forget | delete one (or all) | user_id · memory_id? (omit = delete all) |
| GET /api/v1/engram | engrams this model can run | (none) |
| POST /api/v1/engram/run | run one engram | name · user_id · query · form? · tz? |
| GET /api/v1/models | available models | (none) |
Writes accept an
Idempotency-Key header. Send the same key with the same body and the first response is replayed instead of storing again (10 minutes); the same key with a different body answers 422. Only 2xx are cached, so a failed call is retryable at once.# create the store once (stores are explicit) curl -X POST https://api.wontopos.com/api/v1/memory/collection \ -H "X-API-Key: $WOS_API_KEY" -H "Content-Type: application/json" \ -d '{"user_id":"alice"}' # store a memory curl -X POST https://api.wontopos.com/api/v1/memory/store \ -H "X-API-Key: $WOS_API_KEY" -H "Content-Type: application/json" \ -d '{"user_id":"alice","content":"she prefers tea over coffee"}' # recall - one call, ready for your prompt curl -X POST https://api.wontopos.com/api/v1/memory/recall \ -H "X-API-Key: $WOS_API_KEY" -H "Content-Type: application/json" \ -d '{"user_id":"alice","query":"what does alice drink?"}'
Actual response - store
{"id": "576700aa-f0e0-4c26-99a0-10e2d5b0d624", "status": "stored (1 chunks)"}