Cohere TypeScript SDK

Install the cohere-ai package using npm to access Cohere models across various platforms including Cohere, AWS, Azure, GCP, and Oracle OCI.

npm i -s cohere-ai

The SDK throws subclasses of CohereError when the API returns a non-success status code (4xx or 5xx). You can catch specific errors like CohereTimeoutError or use the base CohereError to access statusCode, message, and body.

import { CohereClientV2, CohereError, CohereTimeoutError } from "cohere-ai";

const cohere = new CohereClientV2({
    token: "YOUR_API_KEY",
});

(async () => {
    try {
        await cohere.chat({ /* ... */ });
    } catch (err) {
        if (err instanceof CohereTimeoutError) {
            console.log("Request timed out", err);
        } else if (err instanceof CohereError) {
            // catch all errors
            console.log(err.statusCode);
            console.log(err.message);
            console.log(err.body);
        }
    }
})();

To use Cohere models on AWS, import clients from the cohere-ai/aws subpath. You must manually install the required peer dependencies as they are not installed automatically.

Required Peer Dependencies:

npm install @aws-sdk/credential-providers @aws-crypto/sha256-js @smithy/protocol-http @smithy/signature-v4

Available AWS Clients:

• BedrockClient / BedrockClientV2 (for AWS Bedrock)
• SagemakerClient / SagemakerClientV2 (for AWS SageMaker)
• AwsClient / AwsClientV2 (Base AWS client)

Example usage with Bedrock:

import { BedrockClient } from "cohere-ai/aws";

const cohere = new BedrockClient({
  awsRegion: "us-east-1",
});

const response = await cohere.chat({
  model: "cohere.command-a-03-2025",
  messages: [{ role: "user", content: "hello world!" }],
});

A Connector is an abstraction used to integrate external data sources with the /chat endpoint. This enables grounded generations, where the model uses the data from the connector to answer user queries and provides citations to the source documents.

Key properties include:

• id: The unique identifier for the connector (automatically generated from the name during registration).
• url: The endpoint used to search for documents within the data source.
• authType: Defines the authentication method, supporting oauth or service_auth.
• continueOnFailure: A boolean flag that determines if a chat request should proceed even if the request to this specific connector fails.

The EmbedJobsClient can be configured via EmbedJobsClient.Options (passed to the constructor) and individual methods via EmbedJobsClient.RequestOptions.

• EmbedJobsClient.Options: Extends BaseClientOptions for global client configuration.
• EmbedJobsClient.RequestOptions: Extends BaseRequestOptions for request-specific overrides like headers, queryParams, timeoutInSeconds, maxRetries, and abortSignal.

The ModelsClient can be initialized with ModelsClient.Options (which extends BaseClientOptions) and individual requests can be customized using ModelsClient.RequestOptions (which extends BaseRequestOptions).

ModelsClient.Options: Used during client instantiation to set global configurations like baseUrl, environment, headers, timeoutInSeconds, maxRetries, and logging.

ModelsClient.RequestOptions: Used per-call to override or provide specific configurations such as headers, queryParams, timeoutInSeconds, maxRetries, abortSignal, and clientName.

Both V2Client and its individual methods accept RequestOptions to customize the behavior of specific calls. This includes:

• timeoutInSeconds: Override the default timeout.
• maxRetries: Number of retry attempts.
• abortSignal: An AbortSignal to cancel the request.
• headers: Additional HTTP headers for the specific request.
• queryParams: URL query parameters.

When calling V2 methods like embed or rerank, you can provide V2Client.RequestOptions to customize the request behavior.

Available options include:

• clientName: A string to identify the client (can also be set globally in the client options).
• headers: Custom HTTP headers for the specific request.
• queryParams: Query parameters to append to the URL.
• timeoutInSeconds: The request timeout in seconds (defaults to 300 if not specified).
• maxRetries: The number of retry attempts.
• abortSignal: An AbortSignal to cancel the request.
• fetchFn: A custom fetch function.
• logging: Logging configuration.

The CohereClient is the primary entry point for interacting with the Cohere API. You can initialize it by passing an options object of type CohereClient.Options. This object allows you to configure authentication, base URL, environment, and other client-level settings.

import { CohereClient } from 'cohere-ai';

const client = new CohereClient({
  // Options follow the BaseClientOptions schema
});

Use CohereClientV2 to interact with Cohere models. The .chat() method accepts a model string and an array of messages containing role and content.

import { CohereClientV2 } from "cohere-ai";

const cohere = new CohereClientV2({});

(async () => {
  const response = await cohere.chat({
    model: 'command-a-03-2025',
    messages: [
      {
        role: 'user',
        content: 'hello world!',
      },
    ],
  });

  console.log(response);
})();

To receive real-time updates from a chat completion, use the chatStream method. This returns an async iterable of chat events. You can check for chatEvent.type === 'content-delta' to access incremental message content via chatEvent.delta?.message.

import { CohereClientV2 } from "cohere-ai";

const cohere = new CohereClientV2({});

(async () => {
  const stream = await cohere.chatStream({
    model: 'command-a-03-2025',
    messages: [
      {
        role: 'user',
        content: 'hello world!',
      },
    ],
  });

  for await (const chatEvent of stream) {
    if (chatEvent.type === 'content-delta') {
      console.log(chatEvent.delta?.message);
    }
  }
})();