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" }