Overview
The Chat and Message API provided a convenient stateful approach to building conversational AI, with automatic session management and history tracking. As we evolve the Gloo platform, weβre transitioning to the Completions v2 API powered by a layered, production-ready AI architecture. This is a more flexible architecture that gives you complete control while delivering values-aligned AI with intelligent model routing. This guide will help you migrate your existing Chat API integrations to Completions v2, maintaining all the conversational capabilities you need while gaining access to powerful new features.Why Migrate to Completions v2?
Values-Aligned Infrastructure
Access AI infrastructure built for human flourishing with values alignment and safety at every layer
Intelligent Routing
Auto-routing, model family selection, or direct model choiceβoptimize for quality, cost, and intent
Full Control
Manage conversation state, history, and context exactly how your application needs it
Theological Alignment
Built-in support for tradition-aware responses (evangelical, catholic, mainline)
Quick Start: Minimal Migration Path
If you want to get started quickly, hereβs the fastest path to migrate:Understanding the Changes
Architecture Comparison
- Before: Chat API
- After: Completions v2
Gloo managed:
- Chat session creation
- Message storage
- History retrieval
- Context management
Key Differences
| Feature | Chat API | Completions v2 |
|---|---|---|
| State Management | Server-managed by Gloo | Client-managed (your database) |
| Message History | Automatic tracking | You build and send full context |
| Chat Sessions | Auto-generated chat_id | You generate session IDs |
| API Calls | Incremental (one message at a time) | Full conversation context each time |
| Model Selection | Fixed model | Auto-routing, family selection, or direct choice |
| Tradition Support | Not available | Built-in (evangelical, catholic, mainline) |
| Tool Use | Limited | Full support |
| Streaming | Available | Enhanced streaming support |
Step-by-Step Migration Guide
Step 1: Design Your Conversation Storage
The first step is creating your own storage for conversations. Hereβs a recommended schema that mirrors the Chat APIβs capabilities:Pro Tip: Include fields for
tradition, model, and tokens_used to track theological alignment, model usage patterns, and costs over time.Step 2: Build Conversation Management
Create functions to manage chat sessions and messages:Step 3: Integrate with Completions v2
Now integrate your conversation manager with the Completions v2 API:Step 4: Migrate Existing Chat Data
Before the Chat API is deprecated, export your existing conversations:Leveraging Completions v2 Features
1. Intelligent Model Routing
Take advantage of Glooβs routing capabilities:- Auto-Routing (Recommended)
- Model Family Selection
- Direct Model Selection
Let Gloo automatically select the optimal model:Best for: Most use cases where you want optimal balance of quality, speed, and cost
2. Tradition-Aware Responses
Maintain theological alignment throughout conversations:3. Streaming Responses
Implement real-time streaming for better UX:Advanced Patterns
Pattern 1: Conversation Branching
Create alternative conversation paths:Pattern 2: Multi-Source Integration
Leverage multiple content publishers:Pattern 3: Conversation Summarization
Auto-summarize long conversations:Testing Your Migration
Unit Tests
Integration Tests
Troubleshooting
Context Window Exceeded
Context Window Exceeded
Problem: API returns error about token limitSolution: Implement proper context truncation in your For models with smaller context windows, consider conversation summarization to maintain essential context while reducing token count.
getConversationHistory method:Messages Out of Order
Messages Out of Order
Problem: Messages appearing in wrong chronological orderSolution: Ensure your database queries always sort by Also use transactions when writing multiple messages to prevent race conditions.
created_at ascending:Tradition Not Being Applied
Tradition Not Being Applied
Problem: Responses donβt reflect the specified theological traditionSolution: Verify tradition is being passed to Completions v2:
High Latency
High Latency
Problem: Responses taking too longSolutions:
-
Use Streaming: Provides immediate feedback to users
-
Optimize Context: Only send necessary messages
-
Cache Recent Conversations: Use Redis for hot data
-
Choose Appropriate Models: Use model family selection
Concurrent Request Issues
Concurrent Request Issues
Problem: Race conditions with simultaneous messagesSolution: Use database transactions and row-level locking:
Migration Checklist
Planning & Design
- Review current Chat API usage patterns
- Design database schema for conversations
- Plan context window management strategy
- Decide on model routing strategy (auto-routing recommended)
- Identify which chats need tradition parameter
- Create migration timeline
Development
- Set up conversation storage (PostgreSQL/MongoDB)
- Implement ConversationManager class
- Integrate GlooCompletionsV2Client
- Build ChatService combining both
- Add context window management
- Implement error handling and retries
- Add logging and monitoring
- Set up streaming support (optional)
Testing
- Write unit tests for conversation management
- Write integration tests for full chat flows
- Test with various message lengths
- Test context window truncation
- Test concurrent request handling
- Verify tradition parameter works correctly
- Load test with production-like volumes
Data Migration
- Create data export script
- Export existing chats from Chat API
- Validate exported data
- Import into new system
- Verify data integrity
- Test sample conversations work correctly
Deployment
- Deploy new infrastructure
- Run migration script for all users
- Enable new system for subset of users
- Monitor performance and errors closely
- Gradually roll out to all users
- Keep Chat API as fallback initially
Benefits of Migrating
Values-Aligned AI
Built-in values alignment and safety at every layer
Intelligent Routing
Auto-routing optimizes every query for quality, cost, and intent automatically
Full Control
Complete control over storage, retention, context management, and conversation workflows
Theological Alignment
Native support for tradition-aware responses (evangelical, catholic, mainline)
Advanced Features
Build sophisticated UX with branching, editing, summarization, and more
Cost Optimization
Control what context you send and optimize token usage based on your needs
Better Performance
Optimize with caching, indexing, and custom logic for your specific use case
Enhanced Privacy
Keep sensitive conversations in your own infrastructure with full control
Support and Resources
Migration Support
Email our team for migration assistance
Completions v2 Docs
Complete API reference for Completions v2
Chat API Reference
Reference for the deprecated Chat API
Tool Use Guide
Enhance your completions with tool calling
Next Steps
Review Architecture
Understand the architectural changes
Follow Migration Steps
Work through the detailed migration guide
Test Your Integration
Set up testing before going to production
Questions about migration? Weβre here to help! Reach out to hello@gloo.us or use the support link in the top navigation.

