model_family, or grounded completions, migrate directly to the Responses API: the OpenAI-compatible Responses format, with guardrails and tradition included. If you do, follow this guide to Completions V2. The request/response mapping below adapts to either; see the Completions β Responses field mapping.
Why Migrate to Completions v2?
Values-Aligned Infrastructure
Access AI infrastructure built for human flourishing with values alignment and safety at every layer
Model Selection
Pin a model, choose a model family, or opt in to auto-routing
Full Control
Manage conversation storage, retention, history, and context exactly how your application needs it
Theological Alignment
Built-in 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
Quick Start: Minimal Migration Path
The fastest path to migrate is the four steps below. The Step-by-Step Migration Guide expands each one with full code, plus migrating your existing chat data.1
Update your endpoint
Change from
/ai/v1/message to /ai/v2/guarded/chat/completions2
Set up conversation storage
Create a database table for chat history
3
Build conversation history
Fetch messages from your database and format them for Completions v2
4
Call Completions v2 with a pinned model
Choose the model that handles your requests
Understanding the Changes
Architecture Comparison
- Before: Chat API
- After: Completions v2
Gloo managed:
- Chat session creation
- Message storage
- History retrieval
- Context management
Key Differences
Step-by-Step Migration Guide
Step 1: Design Your Conversation Storage
First, create your own storage for conversations. This recommended schema 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
Connect your conversation manager to the Completions v2 API:Step 4: Migrate Existing Chat Data
The Chat API was retired on 21 August 2026 and its endpoints no longer exist, so the export script below can no longer read existing conversations. It is kept for reference.Leveraging Completions v2 Features
1. Model Selection
Choose how the model is selected for each request. We recommend pinning a model so behavior stays predictable:- Pinned Model
- Model Family Selection
- Auto-Routing (opt-in)
Specify the exact model for your use case:Best for: Production use, benchmarking, specialized tasks, tool calling, and strict reproducibility requirements
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. Claude Opus 5.5 reasons before it answers, and its reasoning and the summary sharemax_tokens, so the example leaves room for both; see Set your output limit for reasoning models.
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
1
Planning & Design
- Review current Chat API usage patterns
- Design database schema for conversations
- Plan context window management strategy
- Decide on model routing strategy (pinning a model is recommended)
- Identify which chats need tradition parameter
- Create migration timeline
2
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 (see Error Handling and Retries)
- Add logging and monitoring
- Set up streaming support (optional)
3
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
4
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
5
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
6
Cutover
- Switch all traffic to new system
- Monitor for 48 hours
- Disable Chat API integrations
- Update documentation
- Communicate completion to team
- Celebrate! π
Next steps
For the retired endpoints, see the Chat API Reference. Chat threads kept the conversation for you; now your app holds the history. Conversations and Context Windows covers storing and trimming it, and Using the Completions API builds a working client step by step.Questions about migration? Open Support at the bottom of the Gloo AI Studio sidebar.
Completions v2 Docs
Complete API reference for Completions v2
Direct Responses
Send requests straight to the model when your app handles its own safety
Tool Use Guide
Enhance your completions with tool calling

