daily-journal-prompt/API_DOCUMENTATION.md

Daily Journal Prompt Generator - API Documentation

Overview

The Daily Journal Prompt Generator API provides endpoints for generating, managing, and interacting with AI-powered journal writing prompts. The API is built with FastAPI and provides automatic OpenAPI documentation.

Base URL

• Development: http://localhost:8000
• Production: https://your-domain.com

API Version

All endpoints are prefixed with /api/v1

Authentication

Currently, the API does not require authentication as it's designed for single-user use. Future versions may add authentication for multi-user support.

Error Handling

All endpoints return appropriate HTTP status codes:

• 200: Success
• 400: Bad Request (validation errors)
• 404: Resource Not Found
• 422: Unprocessable Entity (request validation failed)
• 500: Internal Server Error

Error responses follow this format:

{
  "error": {
    "type": "ErrorType",
    "message": "Human-readable error message",
    "details": {}, // Optional additional details
    "status_code": 400
  }
}

Endpoints

Prompt Operations

1. Draw Prompts from Pool

GET /api/v1/prompts/draw

Draw prompts from the existing pool without making API calls.

Query Parameters:

• count (optional, integer): Number of prompts to draw (default: 6)

Response:

{
  "prompts": [
    "Write about a time when...",
    "Imagine you could..."
  ],
  "count": 2,
  "remaining_in_pool": 18
}

2. Fill Prompt Pool

POST /api/v1/prompts/fill-pool

Fill the prompt pool to target volume using AI.

Response:

{
  "added": 5,
  "total_in_pool": 20,
  "target_volume": 20
}

3. Get Pool Statistics

GET /api/v1/prompts/stats

Get statistics about the prompt pool.

Response:

{
  "total_prompts": 15,
  "prompts_per_session": 6,
  "target_pool_size": 20,
  "available_sessions": 2,
  "needs_refill": true
}

4. Get History Statistics

GET /api/v1/prompts/history/stats

Get statistics about prompt history.

Response:

{
  "total_prompts": 8,
  "history_capacity": 60,
  "available_slots": 52,
  "is_full": false
}

5. Get Prompt History

GET /api/v1/prompts/history

Get prompt history with optional limit.

Query Parameters:

• limit (optional, integer): Maximum number of history items to return

Response:

[
  {
    "key": "prompt00",
    "text": "Most recent prompt text...",
    "position": 0
  },
  {
    "key": "prompt01",
    "text": "Previous prompt text...",
    "position": 1
  }
]

6. Select Prompt (Add to History)

POST /api/v1/prompts/select/{prompt_index}

Select a prompt from drawn prompts to add to history.

Path Parameters:

• prompt_index (integer): Index of the prompt to select (0-based)

Note: This endpoint requires session management and is not fully implemented in the initial version.

Feedback Operations

7. Generate Theme Feedback Words

GET /api/v1/feedback/generate

Generate 6 theme feedback words using AI based on historic prompts.

Response:

{
  "theme_words": ["creativity", "reflection", "growth", "memory", "imagination", "emotion"],
  "count": 6
}

8. Rate Feedback Words

POST /api/v1/feedback/rate

Rate feedback words and update feedback system.

Request Body:

{
  "ratings": {
    "creativity": 5,
    "reflection": 6,
    "growth": 4,
    "memory": 3,
    "imagination": 5,
    "emotion": 4
  }
}

Response:

{
  "feedback_words": [
    {
      "key": "feedback00",
      "word": "creativity",
      "weight": 5
    },
    // ... 5 more items
  ],
  "added_to_history": true
}

9. Get Current Feedback Words

GET /api/v1/feedback/current

Get current feedback words with weights.

Response:

[
  {
    "key": "feedback00",
    "word": "creativity",
    "weight": 5
  }
]

10. Get Feedback History

GET /api/v1/feedback/history

Get feedback word history.

Response:

[
  {
    "key": "feedback00",
    "word": "creativity"
  }
]

Data Models

PromptResponse

{
  "key": "string",      // e.g., "prompt00"
  "text": "string",     // Prompt text content
  "position": "integer" // Position in history (0 = most recent)
}

PoolStatsResponse

{
  "total_prompts": "integer",
  "prompts_per_session": "integer",
  "target_pool_size": "integer",
  "available_sessions": "integer",
  "needs_refill": "boolean"
}

HistoryStatsResponse

{
  "total_prompts": "integer",
  "history_capacity": "integer",
  "available_slots": "integer",
  "is_full": "boolean"
}

FeedbackWord

{
  "key": "string",    // e.g., "feedback00"
  "word": "string",   // Feedback word
  "weight": "integer" // Weight from 0-6
}

Configuration

Environment Variables

Variable	Description	Default
DEEPSEEK_API_KEY	DeepSeek API key	(required)
OPENAI_API_KEY	OpenAI API key	(optional)
API_BASE_URL	API base URL	https://api.deepseek.com
MODEL	AI model to use	deepseek-chat
DEBUG	Debug mode	false
ENVIRONMENT	Environment	development
HOST	Server host	0.0.0.0
PORT	Server port	8000
MIN_PROMPT_LENGTH	Minimum prompt length	500
MAX_PROMPT_LENGTH	Maximum prompt length	1000
NUM_PROMPTS_PER_SESSION	Prompts per session	6
CACHED_POOL_VOLUME	Target pool size	20
HISTORY_BUFFER_SIZE	History capacity	60
FEEDBACK_HISTORY_SIZE	Feedback history capacity	30

File Structure

data/
├── prompts_historic.json    # Historic prompts (cyclic buffer)
├── prompts_pool.json        # Prompt pool
├── feedback_words.json      # Current feedback words with weights
├── feedback_historic.json   # Historic feedback words
├── ds_prompt.txt           # Prompt generation template
├── ds_feedback.txt         # Feedback analysis template
└── settings.cfg            # Application settings

Running the API

Development

cd backend
uvicorn main:app --reload

Production

cd backend
uvicorn main:app --host 0.0.0.0 --port 8000

Docker

docker-compose up --build

Interactive Documentation

FastAPI provides automatic interactive documentation:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

Rate Limiting

Currently, the API does not implement rate limiting. Consider implementing rate limiting in production if needed.

CORS

CORS is configured to allow requests from:

• http://localhost:3000 (frontend dev server)
• http://localhost:80 (frontend production)

Additional origins can be configured via the BACKEND_CORS_ORIGINS environment variable.

Health Check

GET /health

Returns:

{
  "status": "healthy",
  "service": "daily-journal-prompt-api"
}

Root Endpoint

GET /

Returns API information:

{
  "name": "Daily Journal Prompt Generator API",
  "version": "1.0.0",
  "description": "API for generating and managing journal writing prompts",
  "docs": "/docs",
  "health": "/health"
}

Future Enhancements

1. Authentication: Add JWT or session-based authentication
2. Rate Limiting: Implement request rate limiting
3. WebSocket Support: Real-time prompt generation updates
4. Export Functionality: Export prompts to PDF/Markdown
5. Prompt Customization: User-defined prompt templates
6. Multi-language Support: Generate prompts in different languages
7. Analytics: Track prompt usage and user engagement
8. Social Features: Share prompts, community prompts