API Reference

Version: v2.6 | Updated: 2026-06-06

Base URL

Default: http://localhost:8080

All API endpoints return JSON. Authentication uses Bearer tokens.

Authentication

Protected endpoints require:

Authorization: Bearer <access_token>

Access Token: 24 hours
Refresh Token: 7 days

POST /api/auth/login

{ "username": "admin", "password": "admin123" }

Response:

{
  "accessToken": "eyJ...",
  "refreshToken": "eyJ...",
  "user": { "id": "uuid", "username": "admin", "avatarUrl": null }
}

POST /api/auth/refresh

{ "refreshToken": "eyJ..." }

GET /api/auth/me

Returns current user info.

POST /api/auth/change-password

{ "oldPassword": "old", "newPassword": "new" }

PUT /api/auth/update-user

Update username and/or avatar URL.

{ "username": "new-name", "avatarUrl": "/api/avatars/{id}/download" }

POST /api/auth/update-avatar

Update avatar by URL (non-upload).

{ "avatarUrl": "/api/avatars/{id}/download" }

Memos

POST /api/memos

{ "content": "# My note", "tags": ["work"], "diaryDate": "2026-05-16", "resourceIds": [], "aiSummary": null }

GET /api/memos

Query: page, pageSize, archived, diaryDate, search

GET /api/memos/:id

Returns MemoWithResources.

GET /api/memos/:id/detail

Returns memo with revision history and bot replies.

PUT /api/memos/:id

{ "content": "updated", "tags": ["edited"], "isArchived": false, "diaryDate": null }

Supports null to clear diaryDate and aiSummary.

DELETE /api/memos/:id

PUT /api/memos/:id/archive

{ "diaryDate": "2026-05-16" }

PUT /api/memos/:id/unarchive

GET /api/memos/date/:date

Query: archived

GET /api/memos/search

Query: query, tags, startDate, endDate, isArchived, page, pageSize

Returns { memos, total, page, pageSize, semanticEnabled } with scoring fields.

GET /api/memos/tags

Returns all user tags with counts.

POST /api/memos/clip

Clip web content into a memo.

{ "clipType": "url", "url": "https://example.com/article", "userNote": null }

GET /api/memos/:id/revisions

View memo version history.

DELETE /api/memos/:id/revisions/:revisionId

Delete a specific revision.

Bot System

GET /api/bots

List all configured bots.

POST /api/bots

{ "name": "Assistant", "description": "My bot", "tags": ["helper"], "autoReply": true }

GET /api/bots/:id

Get bot detail.

PUT /api/bots/:id

Update bot configuration. Supports null to clear avatarUrl, model, aiConfig.

DELETE /api/bots/:id

PUT /api/bots/reorder

{ "order": ["bot-id-1", "bot-id-2"] }

GET /api/memos/:id/bot-replies

Get bot responses for a memo (nested tree with thread counts).

GET /api/bot-replies/:id/thread

Get full conversation thread with thinking content.

POST /api/memos/:id/trigger-replies

Manually trigger auto-replies for a memo.

POST /api/bot-replies/:id/reply

Reply to a bot in a thread.

{ "question": "Tell me more", "resourceIds": ["img-uuid"] }

Memory System

GET /api/memory/stats

Embedding statistics (totalMemos, indexedMemos).

GET /api/memory/activity

Memory retrieval activity log. Query: limit (default 20).

GET /api/memory/context

Retrieved memos for debugging. Query: memoId, botId (required), limit.

GET /api/memos/:id/memory-contexts

Consolidated memory contexts for all bots that replied to a memo. Query: limit.

Sync

POST /api/sync/pull

Pull changes with cursor-based pagination.

{ "clientId": "device-id", "cursors": { "memo": 0, "diary": 0 } }

Returns changes for memo, diary, resource, bot entity types.

Diaries

GET /api/diaries

Query: page, pageSize, startDate, endDate

GET /api/diaries/:date

Returns diary with memos for that date.

POST /api/diaries/:date

{ "moodKey": "joy", "moodScore": 80, "summary": "Great day!" }

PUT /api/diaries/:date

Partial update. Fields: summary, moodKey, moodScore.

PUT /api/diaries/:date/summary

Update diary summary only.

{ "summary": "New summary" }

PUT /api/diaries/:date/mood

Update diary mood only.

{ "moodKey": "calm", "moodScore": 72 }

Resources

GET /api/resources

Query: page, pageSize

POST /api/resources/upload

Multipart upload (max 100MB). Returns resource metadata.

POST /api/resources/presigned-upload

Get R2 presigned upload URL (r2 storage only).

{ "filename": "image.png", "mimeType": "image/png", "fileSize": 12345 }

POST /api/resources/confirm-upload

Confirm presigned upload and get metadata.

{ "resourceId": "uuid" }

POST /api/resources/upload-avatar

Multipart avatar upload (max 10MB). Returns updated user.

GET /api/resources/:id/download

Download resource (supports Range, ETag, ?variant=thumb|opt).

GET /api/resources/:id/thumbnail

Download resource thumbnail.

GET /api/avatars/:id/download

Download avatar.

DELETE /api/resources/:id

AI

POST /api/ai/summarize

AI summarization.

{ "content": "Long text to summarize" }

Returns: { "summary": "..." }

POST /api/ai/suggest-tags

AI tag suggestion.

{ "content": "Memo content", "existingTags": ["work"] }

Returns: { "tags": ["tag1", "tag2"] }

Stats

GET /api/stats/heatmap

Query: startDate, endDate. Returns mood and count heatmap data.

GET /api/stats/timeline

Query: startDate, endDate. Returns timeline entries.

GET /api/stats/trends

Query: startDate, endDate. Returns mood and tag trends.

GET /api/stats/summary

Query: year, month. Returns monthly totals (memos, diaries, resources).

Admin

GET /admin/api/health

Admin health with uptime, storage, DB stats.

GET /admin/api/stats

Admin usage statistics.

GET /admin/api/activity

Recent activity log. Query: limit.

GET /admin/api/config

Server config (port, storage type).

GET /admin/api/ai-config

Get AI provider configs (bot and embedding keys).

PUT /admin/api/ai-config/:key

Update AI config. Key: bot or embedding.

POST /admin/api/clear-cache

Clear server cache.

POST /admin/api/backfill-memory

Backfill memory embeddings (admin only).

GET /admin/api/settings

Get app settings (auto-tag, auto-diary, timezone, etc.).

PUT /admin/api/settings

Update app settings.

API Reference

On this page