API Reference

Baseline: Go server server-v1.1.5 · Updated: 2026-10-06 · Source adds the GET /openapi.json entry

The production backend is the Go server (server-go/). The same contract is served as an OpenAPI 3.1 document at http://localhost:8080/openapi.json; see OpenAPI.

Base URL

Default: http://localhost:8080

Most endpoints return JSON (application/json); uploads use multipart/form-data, and the download endpoints (/api/resources/:id/download, /api/resources/:id/thumbnail, /api/avatars/:id/download) return binary data with Range and ETag support. 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,
    "role": "admin",
    "mustChangePassword": false,
    "createdAt": 1700000000000,
    "updatedAt": 1700000000000
  },
  "mustChangePassword": false
}

user.role is admin or user. While mustChangePassword is true, authenticated /api/* access is limited to GET /api/auth/me and POST /api/auth/change-password. The other application endpoints return 403. Admin API access uses a separate administrator-role check.

POST /api/auth/refresh

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

GET /api/auth/me

Returns current user info (UserResponse, including role and mustChangePassword).

POST /api/auth/change-password

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

Returns 200 with new accessToken and refreshToken; save the replacement tokens.

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 }

Creates a bot. Returns 201 Created.

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

Returns 204 No Content.

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. Returns 202 Accepted.

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

Reply to a bot in a thread.

{
  "question": "Tell me more",
  "resourceIds": ["img-uuid"],
  "clientRequestId": "4f0c8e1a-7b2d-4c6e-9f3a-1d2b3c4d5e6f"
}

clientRequestId is an optional stable UUID per send. Retries with the same value return the existing reply instead of generating again. Returns 201 Created for a completed reply, 202 Accepted while generation is in progress, and 200 OK for a replayed row.

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

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

{ "moodKey": "joy", "moodScore": 8, "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": 7 }

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

POST /api/resources/confirm-upload

Confirm presigned upload and get metadata.

{ "resourceId": "uuid" }

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

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

POST /api/ai/suggest-tags

AI tag suggestion.

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

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

API Reference

On this page