Migration Guide

This guide contains all the information you need to migrate between different versions of the ZeebeeAI Chat SDK. We strive to maintain backward compatibility whenever possible, but sometimes breaking changes are necessary to improve the platform. This guide will help you navigate these changes smoothly.

Migrating from v1.x to v2.x v1.x → v2.x

Version 2.0 includes several significant changes to the API structure and functionality. This is a major version update with breaking changes.

Key Changes

• Completely redesigned authentication flow
• New endpoint structure for all API endpoints
• Enhanced error handling with more detailed error responses
• New streaming capabilities via HTTP and WebSockets
• Updated SDKs with new methods and parameters

Authentication Changes

Code Example

// JavaScript Example
fetch('https://api.zeebee.ai/v1/chat?api_key=YOUR_API_KEY', {
  method: 'POST',
  body: JSON.stringify({
    message: 'Hello, world!'
  })
});

// JavaScript Example
fetch('https://api.zeebee.ai/v2/chat', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify({
    message: 'Hello, world!'
  })
});

Endpoint Structure Changes

Request/Response Format Changes

{
  "message": "Hello, how are you?",
  "conversation_id": "optional-conversation-id",
  "model": "gpt-3.5-turbo"
}

{
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful assistant."
    },
    {
      "role": "user",
      "content": "Hello, how are you?"
    }
  ],
  "model": "gpt-4-turbo",
  "conversation_id": "optional-conversation-id",
  "temperature": 0.7,
  "max_tokens": 1000
}

Error Handling Changes

In v2.x, errors now follow a more consistent format with clearer error codes:

{
  "error": {
    "code": "invalid_request_error",
    "message": "The model 'gpt-5' does not exist or you don't have access to it.",
    "param": "model",
    "type": "invalid_request_error"
  }
}

SDK Changes

If you're using our official SDKs, you'll need to update to the latest versions:

// npm
npm uninstall zeebee-ai-sdk
npm install @zeebee-ai/sdk@2.0.0

// yarn
yarn remove zeebee-ai-sdk
yarn add @zeebee-ai/sdk@2.0.0

pip uninstall zeebee-ai
pip install zeebee-ai==2.0.0

Migrating from v2.0 to v2.2 v2.0 → v2.2

Version 2.2 adds new features without breaking existing functionality. This is a minor update with no breaking changes.

New Features

• Voice chat capabilities via WebSocket API
• Improved server-sent events in HTTP streaming
• New policy engine for content moderation
• Support for latest AI models

Deprecation Notices

While no features are being removed in v2.2, the following features are planned for deprecation in v3.0:

• The /v2/legacy endpoints
• Support for older model versions
• The simple_message parameter (use messages array instead)

Upgrade Checklist

Use this checklist to ensure a smooth migration:

• Update API endpoints in all your API calls
• Change authentication method from query parameters to Authorization header
• Update request body format to use the messages array
• Update error handling to work with the new error format
• Update SDK dependencies to the latest versions
• Test your integration thoroughly

Support

If you encounter any issues during migration, please don't hesitate to contact our support team:

• Email: support@zeebee.ai
• GitHub Issues: Create an issue
• Documentation: Documentation