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
```bash
curl -X POST http://localhost:3000/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "password123"}'
```

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

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

### Create API Key
```bash
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
```bash
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
```bash
curl http://localhost:3000/api/v1/events/<event_id> \
  -H "Authorization: Bearer <api_key>"
```

### Update Event
```bash
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
```bash
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
```bash
curl http://localhost:3000/api/v1/days \
  -H "Authorization: Bearer <api_key>"
```

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

### Get Day Details
```bash
curl http://localhost:3000/api/v1/days/2026-03-27 \
  -H "Authorization: Bearer <api_key>"
```

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

### Delete Day (and journal)
```bash
curl -X DELETE http://localhost:3000/api/v1/days/2026-03-27 \
  -H "Authorization: Bearer <api_key>"
```

## Journal

### Generate Diary Page
```bash
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:
```json
{
  "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
```bash
curl http://localhost:3000/api/v1/journal/2026-03-27 \
  -H "Authorization: Bearer <api_key>"
```

### Delete Journal
```bash
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
```bash
curl http://localhost:3000/api/v1/journal/2026-03-27/tasks \
  -H "Authorization: Bearer <api_key>"
```

## Tasks

### Get Task
```bash
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
```bash
curl http://localhost:3000/api/v1/settings \
  -H "Authorization: Bearer <api_key>"
```

### Update Settings
```bash
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
```bash
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:
```json
{
  "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)