cohere-upgrade-migration

Migrate from Cohere API v1 to v2 and upgrade SDK versions. Use when upgrading cohere-ai SDK, migrating from CohereClient to CohereClientV2, or handling breaking changes between API versions. Trigger with phrases like "upgrade cohere", "cohere migration", "cohere v1 to v2", "update cohere SDK", "cohere breaking changes".

Jump to install

Repository: jeremylongshore/claude-code-plugins-plus-skills
Last source activity: July 17, 2026 at 22:18
Detected SKILL.md language: English
Stars: 2,604
Forks: 378

Install options

The review-first prompt is selected by default. You can switch to a direct command or download a local copy.

Review the source files

Read SKILL.md and any companion files shown by SkillsMP before deciding whether to install.

Back to search Back to installation

name	cohere-upgrade-migration
description	Migrate from Cohere API v1 to v2 and upgrade SDK versions. Use when upgrading cohere-ai SDK, migrating from CohereClient to CohereClientV2, or handling breaking changes between API versions. Trigger with phrases like "upgrade cohere", "cohere migration", "cohere v1 to v2", "update cohere SDK", "cohere breaking changes".
allowed-tools	Read, Write, Edit, Bash(npm:), Bash(git:)
version	1.5.0
license	MIT
author	Jeremy Longshore <jeremy@intentsolutions.io>
tags	["saas","ai","nlp","cohere"]
compatibility	Designed for Claude Code

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: [
    { : , :  },
    { : , :  },
  ],
});
.(response.);


 response =  cohere.({
  : ,  
  : [
    { : , :  },
    { : , :  },
    { : , :  },
    { : , :  },
  ],
});
.(response.?.?.[]?.);

// 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
});

// 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,
});

// 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: [/*...*/],
});

// 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 ?? '');
  }
}

// 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

// 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'],
    },
  },
}];

Old Name	Current Name	Status
`command`	`command-r7b-12-2024`	Use new ID
`command-r`	`command-r-08-2024`	Use new ID
`command-r-plus`	`command-r-plus-08-2024`	Use new ID
`command-nightly`	`command-a-03-2025`	Use Command A
`embed-english-v3.0`	`embed-v4.0`	Upgrade recommended
`rerank-english-v3.0`	`rerank-v3.5`	Upgrade recommended

# 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)

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"

# 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"

Error After Migration	Cause	Fix
`model is required`	Missed adding model param	Add model to every call
`response.text is undefined`	v1 response shape	Use `response.message?.content?.[0]?.text`
`embedding_types required`	v2 embed requirement	Add `embeddingTypes: ['float']`
`input_type required`	v2 embed requirement	Add `inputType: 'search_document'`