Skip to main content
Retired: The Chat and Message API was retired on 21 August 2026, and its endpoints no longer exist. If you are still calling them, migrate using this guide, then follow any other applicable migration guides to stay current, such as moving from Completions to Responses.
The Chat and Message API offered a stateful approach to conversational AI, with automatic session management and history tracking. Gloo is moving to the Completions v2 API, a layered, production-ready architecture that gives you full control, values-aligned AI and flexible model selection. This guide moves your Chat API integrations to Completions v2 while keeping the conversational capabilities you need. Choosing your migration target: If you don’t need routing, 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/completions
2

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

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.
Important: Run your migration script as soon as you can so all data is safely transferred. Test with a subset of users first.

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:
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 share max_tokens, so the example leaves room for both; see Set your output limit for reasoning models.

Testing Your Migration

Unit Tests

Integration Tests

Troubleshooting

Problem: API returns error about token limitSolution: Implement proper context truncation in your getConversationHistory method:
For models with smaller context windows, consider conversation summarization to maintain essential context while reducing token count.
Problem: Messages appearing in wrong chronological orderSolution: Ensure your database queries always sort by created_at ascending:
Also use transactions when writing multiple messages to prevent race conditions.
Problem: Responses don’t reflect the specified theological traditionSolution: Verify tradition is being passed to Completions v2:
Problem: Responses taking too longSolutions:
  1. Use Streaming: Provides immediate feedback to users
  2. Optimize Context: Only send necessary messages
  3. Cache Recent Conversations: Use Redis for hot data
  4. Choose Appropriate Models: Use model family selection
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