# Ideaflow

> Ideaflow is a notes / second-brain app. Web app at ideaflow.app, REST API
> at prod-api.ideaflow.app/v1. Agents can access user data via long-lived
> API keys (`ts_` prefix) minted by the user in Settings → API Keys.

## For agents

- [Agent brief](/AGENTS.md): how to authenticate, full endpoint list,
  request shapes, common recipes, failure modes
- [Open the app](https://ideaflow.app): users sign in here and manage API
  keys at Settings → API Keys

## API surface (summary)

- Base: `https://prod-api.ideaflow.app/v1`
- Auth: `Authorization: Bearer ts_<key>`
- Read: `/user`, `/userDelta?checkpoint=0` (full export), `/userSettings`, `/notesByUserId?limit=N&offset=M`, `/noteIds`
- Search: `/simon/search`, `/simon/query` (both require `userId` in body; backend can be flaky)
- Write: `/notes/top` (single create), `/notes` (batch upsert), `/folders`, `/files`, `/transcripts`
- Delete: upsert with `deletedAt` set (soft delete; no DELETE endpoint)
- Import: same as Write — `POST /notes` with `importSource` / `importBatch` / `importForeignId` set on each note. Idempotent on `id`.
- Smoke test: `curl -H "Authorization: Bearer $KEY" https://prod-api.ideaflow.app/v1/user`

## Verified working (2026-06-08)

- GET /user → 200
- POST /notes/top (create) → 200 (omit `serverUpdateTimestamp`)
- POST /notes (edit existing) → 200
- POST /notesByNoteIds → 200 (reads back the edited note)
- GET /userDelta?checkpoint=0 → 200 (full export)
- POST /notes with `deletedAt` set → 200 (soft delete)
- POST /notes batch with importSource/importBatch/importForeignId → 200 (import)
- POST /notes idempotent re-run with same IDs → 200 (no duplicates)
- POST /simon/search → 500 (NLP backend degraded; treat as best-effort)

## DO NOT skim this if you're going to write notes

- Block tokens have `content: [...]` for their inline children. NOT `tokens: [...]`. The server's Zod schema is permissive on write but the client's renderer crashes on the wrong field name, breaking the owner's whole feed on next sync.
- Block tokens need `tokenId: "<short-random>"` and optionally `depth: 0`.
- Notes need `directUrlOnly: false` to appear in the feed (server default is effectively `true`).
- Read the "Field gotchas" table in AGENTS.md before writing your first note.

## What lives where

- Web app source: github.com/IdeaFlowCo/thoughtstream-web (private)
- Server source: same repo, `server/` subdirectory
- Note schema: same repo, `shared/types.ts`