Speakers

Register a person

POST/api/v1/memory/speakers

In the SDKs: add_speaker

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.

Authentication

Every call carries your API key in an X-API-Key header. Keys are created in the console.

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

Returns

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

user_id string
speaker string
status "exists"

Example

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

Status codes

StatusMeaning
200Already registered (idempotent).
201Registered.
400Reserved name ("me" in any casing), invalid name, or the store is at its cap — the error carries speaker_limit (50).
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.

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.