OpenAI

ChatBotKit exposes an OpenAI-compatible Chat Completions endpoint. Any client, SDK, or framework that speaks the OpenAI Chat Completions format can talk to ChatBotKit by changing two things: the base URL and the API key. Your existing request and response handling stays the same.

Base URL and Authentication

Point your OpenAI client at the ChatBotKit compatible base URL and authenticate with a ChatBotKit secret key in place of an OpenAI API key. Authentication uses the standard Authorization: Bearer <key> header that OpenAI clients already send.

https://api.chatbotkit.com/v1/openai

The chat completions endpoint is then available at:

POST https://api.chatbotkit.com/v1/openai/chat/completions

Selecting a Model or Agent

In a standard OpenAI request the model field names a model. Here it is a selector that tells ChatBotKit what to talk to:

Bare model names (for example glm-5.2 on its own) are not accepted - always use a selector. The conversation/* selector is reserved for future use.

Making a Request

Using the official OpenAI Node SDK:

import OpenAI from 'openai'

const client = new OpenAI({
  apiKey: 'YOUR_CHATBOTKIT_SECRET',
  baseURL: 'https://api.chatbotkit.com/v1/openai',
})

const completion = await client.chat.completions.create({
  model: 'model/name=glm-5.2',
  messages: [
    { role: 'system', content: 'You are a helpful assistant.' },
    { role: 'user', content: 'Hello!' },
  ],
})

console.log(completion.choices[0].message.content)

The same request with curl:

curl https://api.chatbotkit.com/v1/openai/chat/completions \
  -H "Authorization: Bearer YOUR_CHATBOTKIT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "model/name=glm-5.2",
    "messages": [{ "role": "user", "content": "Hello!" }]
  }'

A successful call returns a standard chat.completion object with choices, usage, and the other fields OpenAI clients expect.

Streaming

Set stream: true to receive partial deltas as server-sent events, terminated by the usual [DONE] sentinel:

const stream = await client.chat.completions.create({
  model: 'bot/id=YOUR_AGENT_ID',
  stream: true,
  messages: [{ role: 'user', content: 'Tell me a short story.' }],
})

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? '')
}

Tools and Function Calling

Both the current tools format and the legacy functions format are supported. Define your tools as you would with OpenAI:

const completion = await client.chat.completions.create({
  model: 'model/name=glm-5.2',
  messages: [{ role: 'user', content: "What's the weather in Tokyo?" }],
  tools: [
    {
      type: 'function',
      function: {
        name: 'get_weather',
        description: 'Get the current weather for a city',
        parameters: {
          type: 'object',
          properties: { city: { type: 'string' } },
          required: ['city'],
        },
      },
    },
  ],
})

When the model decides to call a tool, the response finishes with finish_reason: "tool_calls" and the tool_calls are returned on the assistant message. Execute the call in your application and send the result back as a tool message on the next request, exactly as with OpenAI.

System Prompts

A system message is applied on top of the selected target. With model/name= it becomes the instruction set for the completion. With bot/id= it extends the agent's existing backstory rather than replacing it, so per-request guidance composes with the configuration you already built.

Unsupported Parameters

Parameters that ChatBotKit does not map - such as temperature, top_p, max_tokens, and user - are accepted and ignored rather than rejected, so existing OpenAI client code runs without modification.

Systems as Models

Because bot/id=... can point at a full agent, a single "model" can bundle a backstory, datasets, skillsets, tools, built-in web search, and even a team of coordinated agents. To the calling client it behaves like one model; behind the endpoint it is an entire ChatBotKit system. This lets you ship sophisticated, grounded, tool-using agents to any OpenAI-compatible client without asking it to learn anything new. See the OpenAI-Compatible API feature page for more on this idea.

Errors

Errors follow the OpenAI error envelope:

{
  "error": {
    "message": "Unsupported model selector \"glm-5.2\" - expected one of model/*, bot/*",
    "type": "server_error",
    "code": null
  }
}

Invalid requests (for example an unsupported model selector) return a 400 status, and OpenAI SDKs surface these as the usual API errors.