deardiary/docs/api.md

API Reference

Base URL: /api/v1

Authentication: All requests require an API key in the Authorization header:

Authorization: Bearer <api_key>

Authentication

Register User

curl -X POST http://localhost:3000/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "password123"}'

Login

curl -X POST http://localhost:3000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "password123"}'

Response:

{
  "data": {
    "token": "jwt_token",
    "userId": "user_id"
  },
  "error": null
}

Create API Key

curl -X POST http://localhost:3000/api/v1/auth/api-key \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{"name": "my-app"}'

Events

Create Event

curl -X POST http://localhost:3000/api/v1/events \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <api_key>" \
  -d '{
    "date": "2026-03-27",
    "type": "event",
    "content": "Had a great meeting about the new project"
  }'

Valid types: event, text, photo, voice, health

Get Event

curl http://localhost:3000/api/v1/events/<event_id> \
  -H "Authorization: Bearer <api_key>"

Update Event

curl -X PUT http://localhost:3000/api/v1/events/<event_id> \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <api_key>" \
  -d '{"content": "Updated content"}'

Note: Events cannot be updated if a diary page has been generated for that date.

Delete Event

curl -X DELETE http://localhost:3000/api/v1/events/<event_id> \
  -H "Authorization: Bearer <api_key>"

Note: Events cannot be deleted if a diary page has been generated for that date.

Days

List Days

curl http://localhost:3000/api/v1/days \
  -H "Authorization: Bearer <api_key>"

Response:

{
  "data": [
    {
      "date": "2026-03-27",
      "eventCount": 5,
      "hasJournal": true
    }
  ],
  "error": null
}

Get Day Details

curl http://localhost:3000/api/v1/days/2026-03-27 \
  -H "Authorization: Bearer <api_key>"

Response:

{
  "data": {
    "date": "2026-03-27",
    "events": [...],
    "journal": {...}
  },
  "error": null
}

Delete Day (and journal)

curl -X DELETE http://localhost:3000/api/v1/days/2026-03-27 \
  -H "Authorization: Bearer <api_key>"

Journal

Generate Diary Page

curl -X POST http://localhost:3000/api/v1/journal/generate/2026-03-27 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <api_key>" \
  -d '{"instructions": "Focus more on the technical aspects"}'

The instructions field is optional. If provided, it will be appended to the prompt for regeneration.

Response:

{
  "data": {
    "journal": {
      "id": "...",
      "date": "2026-03-27",
      "content": "Generated diary content...",
      "eventCount": 5,
      "generatedAt": "2026-03-27T10:30:00Z"
    },
    "task": {
      "id": "...",
      "type": "journal_generate",
      "status": "completed",
      "provider": "groq",
      "model": "llama-3.3-70b-versatile"
    }
  },
  "error": null
}

Get Journal

curl http://localhost:3000/api/v1/journal/2026-03-27 \
  -H "Authorization: Bearer <api_key>"

Delete Journal

curl -X DELETE http://localhost:3000/api/v1/journal/2026-03-27 \
  -H "Authorization: Bearer <api_key>"

Deleting the journal unlocks events for editing.

Get Journal Tasks

curl http://localhost:3000/api/v1/journal/2026-03-27/tasks \
  -H "Authorization: Bearer <api_key>"

Tasks

Get Task

curl http://localhost:3000/api/v1/tasks/<task_id> \
  -H "Authorization: Bearer <api_key>"

Response includes full request/response JSON for debugging.

Settings

Get Settings

curl http://localhost:3000/api/v1/settings \
  -H "Authorization: Bearer <api_key>"

Update Settings

curl -X PUT http://localhost:3000/api/v1/settings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <api_key>" \
  -d '{
    "aiProvider": "groq",
    "providerSettings": {
      "groq": {
        "apiKey": "your-api-key",
        "model": "llama-3.3-70b-versatile"
      }
    }
  }'

AI Providers

Test Connection

curl -X POST http://localhost:3000/api/v1/ai/test \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <api_key>" \
  -d '{
    "provider": "groq",
    "apiKey": "your-api-key",
    "model": "llama-3.3-70b-versatile"
  }'

Supported providers: groq, openai, anthropic, ollama, lmstudio

Error Responses

All endpoints return errors in this format:

{
  "data": null,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human readable message"
  }
}

Common error codes:

• UNAUTHORIZED - Invalid or missing API key
• NOT_FOUND - Resource not found
• NO_EVENTS - No events for diary generation
• NO_AI_CONFIG - AI provider not configured
• EVENT_IMMUTABLE - Cannot modify event (diary exists)