# Lifetrace API Endpoints and Pydantic Schemas: A FastAPI Implementation Guide

> Explore Lifetrace API endpoints like /api/ and learn how Pydantic schemas such as TodoCreate and VisionChatRequest validate requests and serialize responses in this FastAPI implementation guide.

- Repository: [FreeU-group/lifetrace](https://github.com/freeu-group/lifetrace)
- Tags: api-reference
- Published: 2026-03-02

---

**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`](https://github.com/freeu-group/lifetrace/blob/main/lifetrace/routers/todo.py) and data contracts located in [`lifetrace/schemas/todo.py`](https://github.com/freeu-group/lifetrace/blob/main/lifetrace/schemas/todo.py). The service layer implementation resides in [`lifetrace/services/todo_service.py`](https://github.com/freeu-group/lifetrace/blob/main/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`](https://github.com/freeu-group/lifetrace/blob/main/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

```bash
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`](https://github.com/freeu-group/lifetrace/blob/main/lifetrace/routers/todo_extraction.py) with schemas defined in [`lifetrace/schemas/todo_extraction.py`](https://github.com/freeu-group/lifetrace/blob/main/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`](https://github.com/freeu-group/lifetrace/blob/main/lifetrace/services/todo_extraction_service.py).

```python
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`](https://github.com/freeu-group/lifetrace/blob/main/lifetrace/routers/vision.py) defines the chat interface, while [`lifetrace/schemas/vision.py`](https://github.com/freeu-group/lifetrace/blob/main/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`**.

```bash
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`](https://github.com/freeu-group/lifetrace/blob/main/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`](https://github.com/freeu-group/lifetrace/blob/main/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`](https://github.com/freeu-group/lifetrace/blob/main/lifetrace/schemas/todo.py), while vision models are in [`lifetrace/schemas/vision.py`](https://github.com/freeu-group/lifetrace/blob/main/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`](https://github.com/freeu-group/lifetrace/blob/main/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`](https://github.com/freeu-group/lifetrace/blob/main/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`](https://github.com/freeu-group/lifetrace/blob/main/lifetrace/core/dependencies.py). For instance, todo endpoints request the `get_todo_service` dependency to receive an instantiated `TodoService` without manual construction.