Where did you hear about us?
1 of 6
Sleep

Read a day for a sleep

POST/api/v1/memory/sleep

In the SDKs: sleep_read · sleep

The raw text a sleep reads, a page at a time, with a receipt for each page.

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 Tablet 2 answers.

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". Use the id the store was created with: 1-64 ASCII letters, digits, ., _ or -, starting with a letter or digit. Ids that differ only by case name one store.

tz_offset_minutes integer

UTC offset in minutes; the store's time zone when absent.

days_ago integer 0–

Which day: 0 is today.

room string

Only this room.

today_start string

When today begins (RFC 3339).

now string

The time to read up to (RFC 3339).

budget_tokens integer 1–

Page size in tokens.

cursor object

The cursor the last page returned.

include_superseded boolean

Also read memories a later one replaced.

sleep_id string

The sleep this page belongs to.

since_last_sleep boolean

Start where the last sleep ended.

since string

Start here (RFC 3339).

Example

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

Status codes

StatusMeaning
200Success.
400A field is missing or out of range; the message names it.
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.
501Only Scroll 2 serves this endpoint. Send X-WOS-Model: scroll-2; the message names the model sent.

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.