# Niwa Notes

> A personal notebook. Notes are bullets written on a day; a #topic collects everything written about it across days. Bullets can be to-dos (open or done). Work and Personal are two separate spaces.

This is a private, single-owner notebook. Everything except this file, the API guide and the sign-in page needs a key that the owner creates for each assistant (in the app, under Assistants). If you are an assistant and have no key, ask the owner for one; do not try to sign in through the web page.

## Connect

- Base URL: https://niwanotes.app/api/v1
- Auth: send `Authorization: Bearer <key>` on every request.
- First call: `GET https://niwanotes.app/api/v1/me` shows which spaces the key can see and whether it may write.
- [API guide (JSON)](https://niwanotes.app/api/v1): the same information as this file, machine-readable.
- [OpenAPI description](https://niwanotes.app/api/v1/openapi.json)
- [API guide for people](https://niwanotes.app/api/docs)

## How the notebook is organised

- Days are YYYY-MM-DD in the owner's local date. Leave 'day' out to mean the owner's today.
- Topic names are a single word: letters, digits, - and _, starting with a letter or digit, at most 60 characters. Capitals are lower-cased for you ('Budget' becomes 'budget') and a leading # is ignored. Anything else, such as a name with a space, is refused with code 'invalid_topic'; nothing is written. A topic that does not exist yet is created when you first write to it.
- Every bullet has a stable id that survives edits. Nesting is stored as 'depth' (0 = top level). When you read a whole day, topic or single bullet, each bullet also carries 'parent_id', worked out from the depths; lists that mix bullets from many places (to-dos, search, recent) do not.
- Writes return the bullets they created, with their ids, so you can confirm what landed.
- To make a write safe to retry, send an 'Idempotency-Key' header with any unique string. Sending the same key again returns the first answer (with header 'Idempotent-Replay: true') and writes nothing new. Use a new key for each distinct write.
- Errors are JSON: 'ok' false, a short fixed 'code' to act on, an 'error' sentence for a person, and 'retry' true when sending the same request again can help.
- Lists take 'limit' and 'offset'. A 'next_offset' of null means there is no more.
- What you may change depends on the key's 'access' (see GET /me). 'read': nothing. 'write': add bullets, tick any to-do, and edit, move or delete only the bullets your own key added (a bullet's 'added_by' equals your 'key_id'); anything else returns code 'not_yours'. 'full': edit, move and delete any bullet in your spaces, as the owner could. Every edit, move and delete you make is recorded with the bullet as it was, and the owner can undo it, so prefer editing over deleting and never delete in bulk without being asked.
- If the owner is typing on the same day at the same moment, their copy can win and your addition can be lost. If it matters, read the day back and send it again with a new Idempotency-Key.

## What you can do

- `GET /me`: What this key may do, and today's date for the owner.
- `GET /todos?space=&status=open|done|all&limit=&offset=`: The to-do list, newest day first. Default status is open.
- `POST /todos {text, space?, day?, topic?}`: Adds a to-do to that day's page, or inside a topic. Returns it with its id.
- `PATCH /todos/{id} {status: 'done'|'open'}`: Ticks or unticks a to-do. Safe to repeat.
- `GET /days?space=`: The days that have notes, oldest first.
- `GET /days/{day}?space=`: Everything written on a day: the day page, then each topic's entry, with parent_id on each bullet. Use 'today' for the owner's today.
- `POST /notes {text, space?, day?, topic?, todo?}`: Adds notes. One bullet per line; indent two spaces per level to nest; start a line with '[] ' to make it a to-do. Returns the bullets with their ids.
- `GET /bullets/{id}`: One bullet, with its parent_id and the bullets nested directly under it.
- `PATCH /bullets/{id} {text?, todo?, topic?, day?, space?}`: Edits a bullet your key added. 'text' rewrites it; 'todo' is 'open', 'done' or null (a plain note). 'topic', 'day' and 'space' move it: give only the ones that change; topic null puts it on the day page itself. A moved bullet lands at the end of its new place as a top-level bullet. A bullet with others nested under it can't be moved ('has_children'). Nesting under a chosen parent is not supported: to nest, add the lines again with POST /notes using indentation.
- `DELETE /bullets/{id}`: Deletes a bullet your key added. Refused with 'has_children' while other bullets are nested under it. There is no undo.
- `GET /topics?space=`: All topics, with when each was last written in.
- `GET /topics/{name}?space=`: Everything written in one topic, newest day first.
- `GET /search?q=&space=&topic=&from=&to=&limit=&offset=`: Bullets whose text contains q (not case-sensitive, no ranking), newest first. Narrow by topic or by a range of days.
- `GET /recent?since=&space=&limit=&offset=`: Bullets added or changed after 'since' (an ISO time), oldest change first. The answer includes 'now': pass it as 'since' next time. Deletions are not reported.
- `POST /recordings?space=&title=`: Sends an audio recording (as the raw request body, or a form with a 'file' field) to be transcribed. Returns its id. The owner reviews the drafted notes before anything is added.
- `GET /recordings/{id}`: Where a recording has got to: processing, awaiting_review, added_to_notes (with the day) or failed (with why). 404 means the owner discarded it. GET /recordings lists recent ones.

All responses are JSON. Errors have `ok: false` and an `error` message written to be read.
