Cohere Upgrade Migration

Cohere Upgrade & Migration

Overview

Guide for migrating from Cohere API v1 to v2 and upgrading the cohere-ai TypeScript / cohere Python SDK. Covers every breaking change with before/after code.

Prerequisites

• Current Cohere SDK installed
• Git for version control
• Test suite available

Instructions

Step 1: Check Current Version

# TypeScript
npm list cohere-ai

# Python
pip show cohere

# Latest versions
npm view cohere-ai version
pip index versions cohere

Step 2: Create Upgrade Branch

git checkout -b upgrade/cohere-v2-migration
npm install cohere-ai@latest
# or: pip install cohere --upgrade

Step 3: API v1 to v2 Breaking Changes

Client Import

// v1
import { CohereClient } from 'cohere-ai';
const cohere = new CohereClient({ token: '...' });

// v2
import { CohereClientV2 } from 'cohere-ai';
const cohere = new CohereClientV2({ token: '...' });

Chat Endpoint — Messages Format

// v1 — single message string
const response = await cohere.chat({
  message: 'Hello',
  preamble: 'You are helpful.',
  chatHistory: [
    { role: 'USER', message: 'Hi' },
    { role: 'CHATBOT', message: 'Hello!' },
  ],
});
console.log(response.text);

// v2 — OpenAI-compatible messages array, model required
const response = await cohere.chat({
  model: 'command-a-03-2025',  // REQUIRED in v2
  messages: [
    { role: 'system', content: 'You are helpful.' },
    { role: 'user', content: 'Hi' },
    { role: 'assistant', content: 'Hello!' },
    { role: 'user', content: 'Hello' },
  ],
});
console.log(response.message?.content?.[0]?.text);

Role Names

Embed Endpoint — Required Fields

// v1 — model optional, no embedding_types
const response = await cohere.embed({
  texts: ['hello'],
});

// v2 — model, inputType, embeddingTypes all REQUIRED
const response = await cohere.embed({
  model: 'embed-v4.0',          // Required
  texts: ['hello'],
  inputType: 'search_document', // Required for v3+ models
  embeddingTypes: ['float'],    // Required for v3+ models
});

Rerank Endpoint — Model Required

// v1
const response = await cohere.rerank({
  query: 'best language',
  documents: ['Python', 'Rust'],
});

// v2
const response = await cohere.rerank({
  model: 'rerank-v3.5',  // Required
  query: 'best language',
  documents: ['Python', 'Rust'],
  topN: 2,
});

Classify Endpoint — Model Required

// v1
const response = await cohere.classify({
  inputs: ['great product'],
  examples: [/*...*/],
});

// v2
const response = await cohere.classify({
  model: 'embed-english-v3.0',  // Required
  inputs: ['great product'],
  examples: [/*...*/],
});

Streaming Changes

// v1
const stream = cohere.chatStream({ message: 'hello' });
for await (const event of stream) {
  if (event.eventType === 'text-generation') {
    process.stdout.write(event.text);
  }
}

// v2
const stream = await cohere.chatStream({
  model: 'command-a-03-2025',
  messages: [{ role: 'user', content: 'hello' }],
});
for await (const event of stream) {
  if (event.type === 'content-delta') {
    process.stdout.write(event.delta?.message?.content?.text ?? '');
  }
}

RAG / Documents

// v1 — connectors or documents as strings
const response = await cohere.chat({
  message: 'question',
  documents: [{ title: 'Doc', snippet: 'content' }],
  connectors: [{ id: 'web-search' }],
});
// citations via response.citations

// v2 — documents as data objects
const response = await cohere.chat({
  model: 'command-a-03-2025',
  messages: [{ role: 'user', content: 'question' }],
  documents: [
    { id: 'doc1', data: { text: 'content' } },
  ],
});
// citations via response.message?.citations

Tool Use

// v1 — Cohere-specific format
const tools = [{
  name: 'get_weather',
  description: 'Get weather',
  parameterDefinitions: {
    city: { type: 'str', required: true },
  },
}];

// v2 — OpenAI-compatible format
const tools = [{
  type: 'function',
  function: {
    name: 'get_weather',
    description: 'Get weather',
    parameters: {
      type: 'object',
      properties: { city: { type: 'string' } },
      required: ['city'],
    },
  },
}];

Step 4: Model Name Updates

Step 5: Python Migration

# v1
import cohere
co = cohere.Client(api_key="...")
response = co.chat(message="hello")
print(response.text)

# v2
import cohere
co = cohere.ClientV2()  # reads CO_API_KEY
response = co.chat(
    model="command-a-03-2025",
    messages=[{"role": "user", "content": "hello"}],
)
print(response.message.content[0].text)

Step 6: Run Tests and Verify

npm test
# Fix any type errors from changed response shapes
# Key changes: response.text → response.message?.content?.[0]?.text
#              response.citations → response.message?.citations

git add -A
git commit -m "chore: migrate to Cohere API v2"

Migration Codemod (Find & Replace)

# Find all v1 imports
grep -rn "CohereClient\b" src/ --include="*.ts" | grep -v "CohereClientV2"

# Find v1 chat calls
grep -rn "\.chat({" src/ --include="*.ts" -A2 | grep "message:"

# Find v1 response access
grep -rn "response\.text\b" src/ --include="*.ts"

# Find v1 streaming events
grep -rn "eventType.*text-generation" src/ --include="*.ts"

Output

• Updated SDK to latest version
• Migrated all endpoints from v1 to v2 format
• Updated model IDs to current names
• All tests passing against v2 API

Error Handling

Examples

Run the v2 adapter against sanitized staging fixtures, compare the normalized chat/embed result to the v1 baseline, and promote only after model IDs, streaming, and error behavior are verified. If a response shape or model contract differs, restore the pinned prior path and correct the migration before routing live traffic.

Resources

• API v1 to v2 Migration Guide
• Cohere Deprecations
• Cohere Models Overview

Next Steps

For CI integration during upgrades, see cohere-ci-integration.