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.
The chat completions endpoint is then available at:
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:
| Selector | Description |
|---|---|
model/name=<model> | Talk to a specific model directly, for plain stateless completions. |
bot/id=<id> | Use one of your configured agents, together with its backstory, datasets, skillsets, and tools. |
Bare model names (for example gpt-4o 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:
The same request with curl:
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:
Tools and Function Calling
Both the current tools format and the legacy functions format are supported. Define your tools as you would with OpenAI:
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:
Invalid requests (for example an unsupported model selector) return a 400 status, and OpenAI SDKs surface these as the usual API errors.