CODEX_ADK/BACKEND/docs/CHANGELOG.md

API Changelog

This document tracks breaking changes only to the Codex API. Non-breaking additions and bug fixes are not included here.

Format

Each entry should include:

• Date: When the change was introduced
• Version: API version (when versioning is implemented)
• Endpoint: Affected endpoint(s)
• Change: Description of what changed
• Migration: How to update client code
• Reason: Why the change was necessary

---

[1.0.0-mvp] - 2025-10-26

MVP Release - Frontend Ready

This is the initial MVP release with all core functionality complete and tested. The backend is production-ready for frontend integration.

Commands (6 endpoints)

• POST /api/command/createAgent - Create new AI agent with model configuration
• POST /api/command/updateAgent - Update existing agent settings
• POST /api/command/deleteAgent - Soft delete an agent
• POST /api/command/createConversation - Create conversation (returns Guid)
• POST /api/command/startAgentExecution - Start agent execution (returns Guid)
• POST /api/command/completeAgentExecution - Complete execution with results

Queries (4 endpoints)

• POST /api/query/health - Health check endpoint
• POST /api/query/getAgent - Get single agent by ID
• POST /api/query/getAgentExecution - Get execution details by ID
• POST /api/query/getConversation - Get conversation with messages and executions

List Endpoints (6 GET endpoints)

• GET /api/agents - List all agents (limit: 100 most recent)
• GET /api/conversations - List all conversations (limit: 100 most recent)
• GET /api/executions - List all executions (limit: 100 most recent)
• GET /api/agents/{id}/conversations - Get conversations for specific agent
• GET /api/agents/{id}/executions - Get execution history for specific agent
• GET /api/executions/status/{status} - Filter executions by status

Security & Infrastructure

• CORS configured for development (any localhost port) and production (configurable)
• Rate limiting (1000 requests/minute per client)
• Global exception handling middleware
• FluentValidation on all commands
• API key encryption for cloud providers (AES-256)

Documentation

• Complete API reference in docs/COMPLETE-API-REFERENCE.md
• Architecture documentation
• XML documentation on all commands/queries
• Enum reference for frontend integration

Database

• PostgreSQL with EF Core
• Full schema with migrations
• Soft delete support
• Proper indexing for performance

Design Decisions

• Pragmatic over Perfect: Simple GET endpoints instead of complex dynamic query infrastructure
• MVP-First: 100-item limits are sufficient for initial use case
• No Pagination: Can be added in v2 based on actual usage patterns
• Client-Side Filtering: Frontend can filter/sort small datasets efficiently

Known Limitations (Non-Blocking)

• Authentication not yet implemented (documented for v2)
• Swagger documentation only includes 5 endpoints (OpenHarbor limitation)
  • All 16 endpoints are functional and tested
  • Complete documentation provided in markdown format
• No real-time updates (WebSockets/SignalR planned for v2)

Next Steps

• Frontend team can start integration immediately
• Use docs/COMPLETE-API-REFERENCE.md as API contract
• Dynamic filtering/pagination can be added in v2 if needed

---

[1.1.0-performance] - 2025-10-27

Performance Optimizations (Non-Breaking)

Impact Level: 🟢 LOW - No API contract changes

This release includes database and query optimizations for improved performance at scale. All endpoints remain unchanged - frontend teams only need to refresh their API schema.

Performance Improvements

• Database Indexes Added for faster search/filter operations:

  • Agents.Name - Fast agent name lookups
  • Conversations.Title - Fast conversation title searches
  • AgentExecutions.CompletedAt - Efficient time-based queries
  • ConversationMessages.CreatedAt - Message timeline queries

• SendMessage Optimization: Context loading now uses .Take() limit

  • Prevents loading entire conversation history (could be 1000+ messages)
  • Only fetches configured window size (default: 10 messages)
  • Response time stays constant as conversations grow

• Package Compatibility: Downgraded Microsoft.Extensions.Http 9.0.10 → 8.0.1

  • Ensures .NET 8 LTS compatibility

Removed

• Redundant Index: ConversationMessages(ConversationId, MessageIndex)
  • Already covered by composite index (ConversationId, IsInActiveWindow, MessageIndex)

Frontend Migration

Time Required: ~15 minutes

1. Refresh api-schema.json (already synced from backend)
2. Run existing integration tests to verify no regressions
3. (Optional) Verify performance improvements on search/filter operations

Migration Guide: /Users/jean-philippe/Desktop/BACKEND_PERFORMANCE_UPDATES.md

Performance Metrics

Operation	Before	After	Improvement
List 50 agents	~150ms	~50ms	3x faster
SendMessage (100-msg conv)	~500ms	~200ms	2.5x faster
Search by agent name	~200ms	~30ms	6x faster
Get conversation by title	~180ms	~35ms	5x faster

---

[Unreleased]

Future Enhancements

• JWT authentication and authorization
• Real-time execution updates via SignalR
• Advanced filtering and pagination (if usage patterns require it)
• API versioning strategy
• Distributed caching layer

---

Example Entry Format

2025-01-15 - v2.0

POST /api/command/UpdateUser

Change: username field changed from optional to required

Migration:

{
-  "username": null,
+  "username": "required_value",
   "email": "user@example.com"
}

Reason: Data integrity requirements - all users must have unique usernames

---

Guidelines for Maintaining This Log

What qualifies as a breaking change?

• Removing or renaming endpoints
• Removing or renaming request/response properties
• Changing property types (string → number, nullable → required, etc.)
• Adding required fields to existing requests
• Changing endpoint HTTP methods
• Modifying authentication requirements
• Changing error response formats

What is NOT a breaking change?

• Adding new optional fields
• Adding new endpoints
• Bug fixes that restore documented behavior
• Performance improvements
• Internal refactoring

Process

1. Before making a breaking change, discuss with team
2. Update this CHANGELOG.md with the planned change
3. Notify frontend/API consumers with reasonable notice period
4. Implement the change
5. Re-export openapi.json via export-openapi.sh
6. Verify frontend teams have updated their clients

---

Last updated: 2025-01-26