You can specify the API version you want to use by supplying a URL in the header. For example, the URL for the stable version of Generate would be https://api.cohere.ai/v1/generate.

If no version is supplied in the header, then the API will default to no version, meaning pre-2021-11-08. Important note that the SDKs will default you to the most recent version, which is currently 2022-12-06.

Other Methods

Previously, Cohere used very simple dated versioning in the format YYYY-MM-DD, not to be confused with our independent model-versioning. As of March 17, 2023, this versioning method is still available, but the URL method is preferred. All model versions are compatible with all API versions. The version must match absolutely to be applied, eg if 2022-12-06 is a version and you input 2022-12-07, the API will return an error.

The version is supplied via a Cohere-Version header and is used as following;

import cohere
co = cohere.Client('{apiKey}', '2022-12-06')
response = co.generate(
  prompt='Once upon a time in a magical land called',
  max_tokens=50)
print('Prediction: {}'.format(response.generations[0].text))
const cohere = require('cohere-ai');
cohere.init('{apiKey}', '2021-11-08');
(async () => {
  const response = await cohere.generate({
    prompt: 'Once upon a time in a magical land called',
    max_tokens: 50
  });
  console.log(`Prediction: ${response.body.generations[0].text}`);
})();
package main
import (
  "fmt"

  cohere "github.com/cohere-ai/cohere-go"
)
func main() {
  co, err := cohere.CreateClient("{apiKey}")
  if err != nil {
    fmt.Println(err)
    return
  }
  co.Version = "2021-11-08"
  response, err := co.Generate(cohere.GenerateOptions{
    Prompt:      `Once upon a time in a magical land called`,
    MaxTokens:   50,
  })
  if err != nil {
    fmt.Println(err)
    return
  }

  fmt.Println("Prediction:", response.Generations[0].text)
}
curl --location --request POST 'https://api.cohere.ai/generate' \
  --header 'Authorization: BEARER {apiKey}' \
  --header 'Content-Type: application/json' \
  --header 'Cohere-Version: 2021-11-08' \
  --data-raw '{
      "prompt": "Once upon a time in a magical land called",
      "max_tokens": 50
    }'

Versions

2022-12-06

Removes the confidences array from the response of Classify in favor of the labels map.

2021-11-08

This version introduces multiple generations, meaning that the generations endpoint will now accept a num_generations argument in the JSON and will always return an array of generations. See generate reference for details.

No version (deprecated)

See specific endpoint documentation for details on how no version behaves.

Moreover, API versions come in two flavours: stable and experimental. Stable versions have been tested and work as intended. Experimental versions contain new features that may break the functionality of previous versions. Users should use the stable versions for the best experience. The experimental version should only be used if users want to try out a specific feature that’s only available with the experimental version.
Currently, we only offer 1 stable version: v1 which has the same features of 2022-12-06 and 2021-11-08 combined. We currently don’t offer any experimental version.