Integration Guide
Chat completions
Standard (non-streaming)
curl http://localhost:8001/chatgpt/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4o-mini",
"messages": [{"role": "user", "content": "Hello"}],
"temperature": 1,
"stream": false
}'{
"id": "chatcmpl-6sf37lXn5paUcuf8UaurpMIKRMsTe",
"object": "chat.completion",
"created": 1678485525,
"model": "gpt-4o-mini",
"usage": {"prompt_tokens": 10, "completion_tokens": 5, "total_tokens": 15},
"choices": [{"message": {"role": "assistant", "content": "Generated response"}}]
}model echoes the request's model (the preset's model when the request has none), and usage is estimated at about 4 characters per token: the request's messages in, the reply text out.
Streaming
Send "stream": true to the same endpoint (or set stream: true in the preset for requests that don't say):
curl -N http://localhost:8001/chatgpt/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4o-mini",
"messages": [{"role": "user", "content": "Hello"}],
"stream": true
}'Responses API (OpenAI)
A preset with the openai template (such as chatgpt or streaming) also serves the Responses API, which client.responses.create() in the OpenAI SDKs calls. It is at /v1/responses, and also at /<prefix>/responses when the chat endpoint is /<prefix>/chat/completions, so one base URL works for both:
import OpenAI from 'openai';
// The stock chatgpt preset: chat at /chatgpt/chat/completions, responses at /chatgpt/responses
const client = new OpenAI({ apiKey: 'mock', baseURL: 'http://localhost:8001/chatgpt' });
const response = await client.responses.create({
model: 'gpt-5.1',
instructions: 'Answer briefly.',
input: 'Classify this ticket',
});
console.log(response.output_text);- The reply is one assistant
messageoutput item with oneoutput_textpart.model,instructions,max_output_tokens,metadata,tools,temperatureand the other request settings are echoed back, andusageis estimated at about 4 characters per token (instructionsandinputin, the reply out). "stream": truestreams the API's events:response.created,response.in_progress,response.output_item.added,response.content_part.added,response.output_text.delta(several),response.output_text.done,response.content_part.done,response.output_item.doneandresponse.completedwith the whole response. Each has asequence_number. There is no[DONE]. A request with nostreamgoes by the preset'sstreamsetting, as on the chat route.- Response rules,
stopReason,fail, chaos, the delay, validation (modelandinput), the request log and the recorded requests all work as they do on the chat route. A rule matches text anywhere in the body,instructionsincluded. With"in": "last"it looks only at the lastinputitem (itscontent, or a tool result'soutput), or atinputitself when it is a string. stopReason: "max_tokens"makes the responseincompletewithincomplete_details: { "reason": "max_output_tokens" }, and a stream ends withresponse.incomplete.stopReason: "refusal"puts the text in arefusalpart, streamed asresponse.refusal.deltaevents.- A chaos
stream-errorsends the opening events andafterChunksdeltas, then anerrorevent ({ "type": "error", "code", "message", "param", "sequence_number" }), and ends the stream. An HTTP failure has the chat route's OpenAI error body. - Not mocked: tool calls (
function_calloutput items), reasoning items, conversation state (previous_response_idis echoed but not used), and the other Responses routes (GET /v1/responses/<id>, cancel, input items).
Embeddings API
The mock server provides an OpenAI-compatible embeddings endpoint at /v1/embeddings:
curl http://localhost:8001/v1/embeddings \
-H "Content-Type: application/json" \
-d '{
"model": "text-embedding-3-small",
"input": "Your text string goes here"
}'Pass an array of strings for multiple embeddings in one call:
-d '{"model": "text-embedding-ada-002", "input": ["First text", "Second text"]}'Response format:
{
"object": "list",
"data": [
{
"object": "embedding",
"index": 0,
"embedding": [0.1234, -0.5678, 0.9012]
}
],
"model": "text-embedding-3-small",
"usage": { "prompt_tokens": 6, "total_tokens": 6 }
}Key characteristics of mock embeddings: deterministic (same input always returns the same vector), configurable dimensions, model-name-sensitive, and OpenAI-compatible in shape. Note that vectors are pseudo-random — they have the correct shape for testing but are not real semantic embeddings.
Using with LangChain
Point your ChatOpenAI client at the mock server when TEST_MODE is enabled:
import { ChatOpenAI } from '@langchain/openai';
const chatModel = new ChatOpenAI({
openAIApiKey: process.env.OPENAI_API_KEY,
modelName: 'gpt-3.5-turbo',
configuration:
process.env.TEST_MODE === 'true'
? { baseURL: process.env.TEST_BASE_URL } // http://localhost:8001/chatgpt
: {},
});For embeddings, use LangChain's built-in fake embeddings or call the mock endpoint directly:
class MockEmbeddingsAPI {
async embedDocuments(texts) {
return Promise.all(texts.map(text => this.embedQuery(text)));
}
async embedQuery(text) {
const response = await fetch(process.env.TEST_EMBEDDING_URL, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ input: text, model: 'text-embedding-ada-002' }),
});
const data = await response.json();
return data.data[0].embedding;
}
}
const embeddings =
process.env.TEST_MODE === 'true'
? new MockEmbeddingsAPI()
: new OpenAIEmbeddings({ openAIApiKey: process.env.OPENAI_API_KEY });