API Reference
+ +The DearDiary API is REST-based with JSON responses. All endpoints return a consistent format.
+ +Response Format
+All responses follow this structure:
+{
+ "data": { ... } | null,
+ "error": { "code": "ERROR_CODE", "message": "..." } | null
+}Authentication
+Include your API key in the Authorization header:
+Authorization: Bearer <your-api-key>Endpoints
+ +Events
+ +GET /api/v1/events?date=YYYY-MM-DD
+List events for a specific date.
+// Response
+{
+ "data": [
+ {
+ "id": "evt_xxx",
+ "date": "2026-03-27",
+ "type": "text",
+ "content": "Had coffee with Sarah",
+ "latitude": 40.7128,
+ "longitude": -74.0060,
+ "placeName": "New York, NY",
+ "createdAt": "2026-03-27T08:30:00Z"
+ }
+ ]
+}POST /api/v1/events
+Create a new event.
+// Request body
+{
+ "date": "2026-03-27",
+ "type": "text", // text, photo, voice, health
+ "content": "Event content"
+}
+
+// Response
+{
+ "data": {
+ "id": "evt_xxx",
+ "date": "2026-03-27",
+ "type": "text",
+ "content": "Event content",
+ "createdAt": "2026-03-27T10:00:00Z"
+ }
+}DELETE /api/v1/events/:id
+Delete an event. Only works if no journal exists for that date.
+ +Journals
+ +GET /api/v1/journal/:date
+Get diary page for a specific date.
+{
+ "data": {
+ "id": "jrn_xxx",
+ "date": "2026-03-27",
+ "title": "A Productive Tuesday",
+ "content": "Today was filled with...",
+ "eventCount": 8,
+ "generatedAt": "2026-03-27T20:00:00Z"
+ }
+}POST /api/v1/journal/generate/:date
+Generate a diary page from events. Starts an async task.
+// Request body (optional)
+{
+ "instructions": "Focus on the meeting with the client"
+}
+
+// Response
+{
+ "data": {
+ "taskId": "tsk_xxx",
+ "status": "pending"
+ }
+}PUT /api/v1/journal/:date
+Update journal title and content.
+// Request body
+{
+ "title": "New Title",
+ "content": "Updated content..."
+}DELETE /api/v1/journal/:date
+Delete journal. This unlocks events so they can be modified.
+ +Tasks
+ +GET /api/v1/journal/:date/tasks
+Get generation tasks for a journal.
+{
+ "data": [
+ {
+ "id": "tsk_xxx",
+ "type": "generate",
+ "status": "completed", // pending, processing, completed, failed
+ "title": "A Great Day",
+ "provider": "groq",
+ "model": "llama-3.3-70b-versatile",
+ "createdAt": "2026-03-27T20:00:00Z",
+ "completedAt": "2026-03-27T20:00:30Z"
+ }
+ ]
+}Journals List
+ +GET /api/v1/journals?page=1&limit=10
+List all diary pages with pagination.
+ +GET /api/v1/days
+List days with journal info and excerpts.
+ +Settings
+ +GET /api/v1/settings
+Get current user settings.
+ +PUT /api/v1/settings
+Update user settings.
+{
+ "aiProvider": "groq",
+ "aiApiKey": "gsk_xxx",
+ "aiModel": "llama-3.3-70b-versatile",
+ "useSystemDefault": false
+}Data Management
+ +GET /api/v1/export
+Export all user data as JSON.
+{
+ "data": {
+ "version": "0.1.0",
+ "exportedAt": "2026-03-27T12:00:00Z",
+ "events": [...],
+ "journals": [...],
+ "tasks": [...],
+ "settings": {...}
+ }
+}POST /api/v1/import
+Import data from export file.
+ +GET /api/v1/health
+Health check endpoint (no auth required).
+{ "status": "ok" }