Developer API
The Notedog API
The same on-device HTTPS server that powers browser editing exposes a small REST API under /api/v2. Point your own scripts — or an AI agent — at it over your local network or the tunnel. Your journal stays on your phone; the API just reads and writes the same Markdown files.
Building for an AI agent? You usually don’t need to touch this API directly — the Notedog MCP server wraps it as ready-made tools. This page is the raw contract underneath.
Authentication
Every /api/v2/* request carries a token in the Authorization header. There are two kinds of token, and both are sent the same way:
Authorization: Bearer <token>Paired browser tokens
When you open the web editor and approve the pairing prompt, the browser receives a short-lived access token (12 hours) plus a refresh token (30 days, rotated on use). This is what the web UI uses; it’s also stored as an HttpOnly cookie.
API keys (for scripts & agents)
For anything that isn’t a browser, mint a dedicated key in the app: open the drawer → API keys → Create key. Keys are long-lived (no expiry) and you can revoke any of them at any time from the same screen.
- Read-only (default) — can read the whole journal, but every write is rejected with
403. - Read-write — turn on Allow writes when creating the key to also allow create, edit, and delete. On a Git-backed journal, each write becomes its own commit (with the key’s name in the message), so agent changes are easy to review and revert.
An API key is a bearer token: anyone holding it has that level of access over your LAN or tunnel. Keep it secret (don’t commit it to a repo), prefer read-only unless you need writes, and revoke it in the app if it leaks. Scope is enforced on the phone — a read-only key simply can’t mutate anything.
Base URL
- Tunnel —
https://<your-subdomain>.t.notedog.run. Real TLS, works from anywhere. (See remote access.) - LAN —
https://<phone-ip>:<port>, the address shown under On this network. It uses a self-signed certificate, so a command-line client needs to accept it (e.g.curl --insecure).
Entry shape
Most endpoints return entries in this form:
{
"path": "entries/2026-05-24.md", // path inside the journal
"content": "# ...", // markdown (preview in lists, full when fetched by path)
"timestamp": 1748044800000, // last modified, ms since epoch
"createdAt": 1748000000000 // created, ms since epoch
}Endpoints
All paths are under /api/v2. Endpoints marked write require a read-write key (a read-only key gets 403).
Entries
| Method & path | Description |
|---|---|
GET /entries | List entries (preview content), newest first. Query: q (search), from/to (YYYY-MM-DD), limit (default 50, max 200), cursor. Returns { entries, nextCursor }; nextCursor: null is the last page. |
GET /entries/{path} | One entry with full content. 404 if missing. |
POST /entries write | Create. Body { path?, content } (blank path uses your filename template). 201 { path }; 409 on collision; 422 on validation failure. |
PUT /entries/{path} write | Update content, optionally rename. Body { content, newPath? }. 200 { path }; 409 on rename collision. |
DELETE /entries/{path} write | Delete. 204 (also if already gone). |
When q or from/to are present, results are ranked by relevance (BM25 + a filename-match bonus, ties broken by recency); otherwise newest-first by createdAt.
Related entries
| Method & path | Description |
|---|---|
GET /related?path={path} | Entries with content similar to the entry at path, even when nothing links them. 400 if path is missing, 404 if it doesn’t exist. |
Similarity is computed on the phone itself, not by an external service. Results are sorted by score, best match first. An empty list means no good match was found:
{
"related": [
{ "path": "entries/kenya-aa.md", "score": 0.82, "preview": "Dialing in a light roast — grind finer, ..." }
]
}The first call after an edit rebuilds the index, which can take a few seconds on a large journal. The web editor requests related entries in the background, after the entry itself has loaded.
Directories
| Method & path | Description |
|---|---|
GET /directories | Journal root: { dirs, files }. |
GET /directories/{path} | A subfolder, same shape. Rejects .. with 400. |
POST /directories write | Create a folder. Body { parent, name } (single segment). 201 { path }; 400/404/409. |
Attachments
| Method & path | Description |
|---|---|
GET /attachments/{path} | Serve an image. Sends ETag/Cache-Control; 304 on a matching If-None-Match. |
POST /attachments write | Upload an image (multipart, field file; png/jpg/gif/webp, max 10 MB). 200 { path }. |
PUT /attachments/{path} write | Overwrite an existing attachment. 200 { path }; 404 if absent. |
DELETE /attachments/{path} write | Delete. 204. |
Recents, preferences & journal
| Method & path | Description |
|---|---|
GET /journal | Active journal: { name } (null if none). |
GET /recent-entries | Recently opened entries (MRU order). |
POST /recent-entries write | Mark an entry opened. Body { path }. |
GET /recent-searches | Up to 5 recent keywords. |
POST /recent-searches write | Track a keyword. Body { keyword }. |
GET /preferences | Editor preferences: { [key]: string }. |
PUT /preferences write | Replace the whole preferences object. |
POST /export | Stream the journal as a ZIP (application/zip). |
Status codes
200/201/204— success.400— bad request (e.g. invalid cursor or a..path segment).401— missing, invalid, or revoked token (“Not paired”).403— a read-only key attempted a write.404— entry or attachment not found.409— path collision on create/rename.422— validation failure.
Examples
Read — search the journal:
curl -H "Authorization: Bearer $NOTEDOG_KEY" \
"https://your-name.t.notedog.run/api/v2/entries?q=domain%20driven%20design"Write — create an entry (needs a read-write key):
curl -X POST -H "Authorization: Bearer $NOTEDOG_KEY" \
-H "Content-Type: application/json" \
-d '{"content":"# Meeting notes\n..."}' \
"https://your-name.t.notedog.run/api/v2/entries"For AI agents, the Notedog MCP server exposes these as tools so you don’t have to wire up HTTP yourself.