Lifetrace API Endpoints and Pydantic Schemas: A FastAPI Implementation Guide

The freeu-group/lifetrace repository defines its main API endpoints under the /api/ prefix, utilizing Pydantic schemas such as TodoCreate, VisionChatRequest, and TodoExtractionRequest to validate requests and serialize JSON responses.

The Lifetrace project implements a clean architecture using FastAPI, where HTTP routes are declared in dedicated router modules and strictly typed with Pydantic models. Understanding the relationship between these main API endpoints and their Pydantic schemas is essential for integrating with the platform's todo management, multimodal AI, and calendar extraction capabilities.

Core Todo Endpoints and Schemas

The todo management system is the primary domain in Lifetrace, with all routes defined in lifetrace/routers/todo.py and data contracts located in lifetrace/schemas/todo.py. The service layer implementation resides in lifetrace/services/todo_service.py.

CRUD Operations

The following endpoints handle basic todo lifecycle management:

• GET /api/todos – Returns a paginated list of todos using the TodoListResponse schema, with optional status filtering via query parameters.

• GET /api/todos/{todo_id}`` – Retrieves a single todo entity, returning a **TodoResponse` object.

• POST /api/todos – Creates a new todo. The request body must conform to the TodoCreate schema, and the endpoint returns a TodoResponse.

• PUT /api/todos/{todo_id} – Updates an existing todo. Accepts a TodoUpdate payload and returns the updated TodoResponse.

• DELETE /api/todos/{todo_id} – Removes a todo and returns HTTP 204 No Content with no response body.

Attachment Handling

File attachments are managed through multipart/form-data endpoints:

• POST /api/todos/{todo_id}/attachments – Uploads one or more files, accepting a list of UploadFile objects and returning list[TodoAttachmentResponse].

• DELETE /api/todos/{todo_id}/attachments/{attachment_id} – Unlinks an attachment from the todo (without deleting the underlying file), returning HTTP 204.

• GET /api/todos/attachments/{attachment_id}/file – Streams the raw binary file using FastAPI's FileResponse.

Batch and Import/Export Operations

• POST /api/todos/reorder – Performs batch updates to ordering and parent-child relationships using the TodoReorderRequest schema.

• GET /api/todos/export/ics – Exports todos as an iCalendar file. Query parameters include limit, offset, and status. The implementation uses lifetrace/services/icalendar_service.py.

• POST /api/todos/import/ics – Imports todos from an uploaded iCalendar file, accepting multipart/form-data with an UploadFile and returning list[TodoResponse].

Example: Creating a Todo

curl -X POST https://api.example.com/api/todos \
  -H "Content-Type: application/json" \
  -d '{
        "name": "Write article",
        "description": "Prepare the Lifetrace knowledge-base article",
        "status": "active",
        "priority": "high",
        "tags": ["documentation","api"]
      }'

Todo Extraction Endpoint

The extraction pipeline converts external events (such as WeChat or Feishu captures) into structured todo items. This functionality is implemented in lifetrace/routers/todo_extraction.py with schemas defined in lifetrace/schemas/todo_extraction.py.

• POST /api/todo-extraction/extract – Processes an event to generate todos. The request body uses TodoExtractionRequest, which includes fields like event_id and screenshot_sample_ratio. The response is validated against TodoExtractionResponse. The business logic is handled by lifetrace/services/todo_extraction_service.py.

import httpx

payload = {
    "event_id": 12345,
    "screenshot_sample_ratio": 3
}
resp = httpx.post(
    "https://api.example.com/api/todo-extraction/extract",
    json=payload,
    timeout=30
)
print(resp.json())

Vision Multimodal Endpoint

Lifetrace integrates vision-language models for analyzing screenshots. The router at lifetrace/routers/vision.py defines the chat interface, while lifetrace/schemas/vision.py contains the validation models.

• POST /api/vision/chat – Sends up to 20 screenshots with a text prompt to a vision LLM. The request uses VisionChatRequest (fields include screenshot_ids, prompt, model, temperature, and max_tokens). The response conforms to VisionChatResponse.

curl -X POST https://api.example.com/api/vision/chat \
  -H "Content-Type: application/json" \
  -d '{
        "screenshot_ids": [101, 102],
        "prompt": "Summarize the meeting notes from these screenshots.",
        "model": "qwen-vl-plus",
        "temperature": 0.7,
        "max_tokens": 500
      }'

Additional Domain Endpoints

Beyond the core todo system, Lifetrace exposes several other endpoint groups following the same architectural pattern:

• /api/journal – Journal entry management with corresponding Pydantic schemas in the schemas directory.
• /api/event – Event tracking and management endpoints.
• /api/search – Full-text search capabilities.
• /api/config – Runtime configuration retrieval and updates.
• /api/health – Liveness and readiness probes for monitoring.

Each router injects its service layer via FastAPI's dependency injection system, utilizing provider functions defined in lifetrace/core/dependencies.py such as get_todo_service and get_rag_service.

Summary

• All HTTP routes are mounted under /api/ and defined in modules within lifetrace/routers/.
• Pydantic schemas in lifetrace/schemas/ strictly validate every request payload and response, including TodoCreate, TodoUpdate, VisionChatRequest, and TodoExtractionRequest.
• File attachments are handled via multipart/form-data uploads, returning structured TodoAttachmentResponse objects.
• Service layer separation ensures routers delegate business logic to specialized classes like TodoService and ICalendarService.
• Dependency injection through lifetrace/core/dependencies.py provides clean instantiation of service objects across all endpoints.

Frequently Asked Questions

Where are the Pydantic schemas defined in the Lifetrace repository?

The Pydantic models are organized by domain within the lifetrace/schemas/ directory. For example, todo-related schemas like TodoCreate and TodoResponse reside in lifetrace/schemas/todo.py, while vision models are in lifetrace/schemas/vision.py.

How does the Todo Extraction endpoint process external events?

The POST /api/todo-extraction/extract endpoint accepts a TodoExtractionRequest containing an event_id and optional processing parameters. It delegates to lifetrace/services/todo_extraction_service.py to analyze the event data and return structured todo items in a TodoExtractionResponse.

What is the maximum number of screenshots supported by the Vision API?

According to the implementation in lifetrace/routers/vision.py, the /api/vision/chat endpoint accepts up to 20 screenshot identifiers in a single request, validated through the VisionChatRequest schema's screenshot_ids field.

How are services injected into the API endpoints?

Lifetrace uses FastAPI's Depends mechanism with provider functions located in lifetrace/core/dependencies.py. For instance, todo endpoints request the get_todo_service dependency to receive an instantiated TodoService without manual construction.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}