API Reference

API Reference

All endpoints require an Authorization: Bearer YOUR_TOKEN header except /mcp and CORS preflight.

---

POST /capture

Store an entry. Duplicate detection runs synchronously. Embedding happens in the background so the response is instant.

Request body:

{
  "content": "your note here",
  "tags": ["work", "idea"],
  "source": "api"
}

content is required. tags and source are optional. source defaults to "api".

Responses:

Stored successfully:

{ "ok": true, "id": "uuid-v4" }

Stored but similar entry exists (tagged duplicate-candidate):

{
  "ok": true,
  "id": "uuid-v4",
  "warning": "similar",
  "matchId": "existing-uuid",
  "score": 88.5,
  "message": "Stored but similar entry exists — tagged as duplicate-candidate"
}

Blocked — near-exact duplicate:

{
  "ok": false,
  "duplicate": true,
  "matchId": "existing-uuid",
  "score": 97.2,
  "message": "Near-exact duplicate detected — not stored"
}

Status	Meaning
200 ok:true	Stored
200 ok:false duplicate:true	Blocked — near-exact duplicate
400	Missing or invalid content
401	Invalid auth token

---

POST /append

Append new information to an existing entry. The original content is preserved and the update is added with a timestamp.

Request body:

{
  "id": "existing-entry-uuid",
  "addition": "New information to append"
}

Both id and addition are required.

Responses:

Success:

{
  "ok": true,
  "id": "existing-entry-uuid",
  "message": "Update appended successfully with timestamp"
}

Entry not found:

{
  "ok": false,
  "error": "No entry found with ID: existing-entry-uuid"
}

Append failed:

{
  "ok": false,
  "error": "Append failed: <error details>"
}

Status	Meaning
200 ok:true	Update appended successfully
404 ok:false	Entry not found
500 ok:false	Append operation failed
400	Missing or invalid id or addition
401	Invalid auth token

---

GET /list

List recent entries in reverse chronological order.

curl "https://<your-worker-url>/list?n=20" \
  -H "Authorization: Bearer YOUR_TOKEN"

Query param	Default	Max	Description
n	20	100	Number of entries to return

---

GET+POST /mcp

MCP server endpoint using the Streamable HTTP transport. No auth token required.

Connect any MCP-compatible client using:

https://<your-worker-url>/mcp

MCP tools

Tool	Parameters	Description
remember	content, tags?, source?	Store a note with duplicate detection
append	id, addition	Append an update to an existing entry
recall	query, topK? (default 5), tag?	Semantic search with chunk deduplication
list_recent	n? (default 10), tag?	Chronological listing
forget	id	Delete entry and all chunks from D1 and Vectorize

---

GET /

Returns the web dashboard (single-page HTML app). No auth required — auth is handled client-side via localStorage.