Coze API SDK

Official Node.js and Browser SDK for Coze（or 扣子） API platform.

Quick Start

1. Installation

npm install @coze/api
# or
pnpm install @coze/api

2. Basic Usage

import { CozeAPI, COZE_COM_BASE_URL, ChatStatus } from '@coze/api';

// Initialize client with your Personal Access Token
const client = new CozeAPI({
  token: 'your_pat_token', // Get your PAT from https://www.coze.com/open/oauth/pats
  baseURL: COZE_COM_BASE_URL,
});

// Simple chat example
async function quickChat() {
  const v = await client.chat.createAndPoll({
    bot_id: 'your_bot_id',
    additional_messages: [{
      role: 'user',
      content: 'Hello!',
      content_type: 'text',
    }],
  });

    if (v.chat.status === ChatStatus.COMPLETED) {
    for (const item of v.messages) {
      console.log('[%s]:[%s]:%s', item.role, item.type, item.content);
    }
    console.log('usage', v.chat.usage);
  }
}

Key Features

• 🌐 Full API Support: Covers all Coze Open Platform APIs
• 🔐 Multiple Auth Methods: PAT, OAuth, JWT, OAuth PKCE
• 🔄 Streaming Support: Real-time responses for chat and workflow
• 🌍 Cross-Platform: Works in Node.js (≥14) and modern browsers
• ⚙️ Configurable: Timeout, headers, signal, debug options

Authentication Options

1. Personal Access Token (Simplest)

const client = new CozeAPI({
  token: 'your_pat_token',
  baseURL: COZE_COM_BASE_URL, // Use COZE_CN_BASE_URL for China region
});

2. Other Auth Methods

• OAuth Web Application
• OAuth PKCE
• JWT
• Device Code Flow

View authentication examples →

Advanced Usage

Streaming Chat

import { CozeAPI, ChatEventType } from '@coze/api';

async function streamChat() {
  const stream = await client.chat.stream({
    bot_id: 'your_bot_id',
    additional_messages: [{
      role: 'user',
      content: 'Hello!',
      content_type: 'text',
    }],
  });

  for await (const part of stream) {
    if (part.event === ChatEventType.CONVERSATION_MESSAGE_DELTA) {
      process.stdout.write(part.data.content); // Real-time response
    }
  }
}

More Examples

| Feature | Description | Example | |---------|-------------|----------| | Chat | Text conversations | chat.mjs | | Bot Management | Create and manage bots | bot.mjs | | Knowledge | Document management | knowledge.mjs | | Workflow | Run workflow | workflow.mjs | | Voice | Speech synthesis | voice.mjs |

View all examples →

Development

# Install dependencies
rush update  # If `rush` command is not installed, see ../../README.md

# Run tests
npm run test

Try Examples

Node.js

cd examples/coze-js-node
cp config.default.js config.js  # Edit config.js with your credentials
node chat.mjs

Browser

cd examples/coze-js-web
npm run start

Documentation

For detailed API documentation and guides, visit:

• API Overview
• Authentication Guide