Docs/API Reference

API Reference

Chat API

Last updated May 28, 2026

Reference for Cencori chat completions across the official SDK and OpenAI-compatible HTTP endpoints.

Overview

Cencori exposes chat completions through two public HTTP surfaces:

EndpointPathBest For
Cencori Nativehttps://cencori.com/api/ai/chatOfficial SDKs and direct Cencori calls
OpenAI-Compatiblehttps://api.cencori.com/v1/chat/completionsExisting OpenAI-compatible clients and agent frameworks

Both surfaces authenticate with your Cencori project key and log requests to the same project dashboard.

When to Use Which Endpoint

Choose based on your use case:

Use CaseRecommended Endpoint
Using the Cencori SDK (cencori)Native endpoint. The SDK uses it automatically.
Building a new Next.js or Node routeNative endpoint or SDK.
Migrating from OpenAI directlyOpenAI-compatible endpoint.
Using agent tools that ask for an OpenAI base URLOpenAI-compatible endpoint with base URL https://api.cencori.com/v1.
Debugging whether Cencori auth and provider routing workNative endpoint with curl.

The OpenAI-compatible base URL should usually stop at /v1; most clients append /chat/completions themselves.

Official TypeScript SDK

Codetext
import { Cencori } from 'cencori';
 
const cencori = new Cencori({
  apiKey: process.env.CENCORI_API_KEY,
});
 
const response = await cencori.ai.chat({
  model: 'gpt-4o',
  messages: [
    { role: 'system', content: 'You are a helpful assistant.' },
    { role: 'user', content: 'What is the capital of France?' },
  ],
  temperature: 0.2,
  maxTokens: 300,
});
 
console.log(response.content);
console.log(response.toolCalls);
console.log(response.usage.totalTokens);

SDK Response Shape

Codetext
{
  "id": "chatcmpl_123",
  "model": "gpt-4o",
  "content": "The capital of France is Paris.",
  "toolCalls": null,
  "finishReason": "stop",
  "usage": {
    "promptTokens": 13,
    "completionTokens": 7,
    "totalTokens": 20
  }
}

Native Cencori HTTP Endpoint

Use the native endpoint when you want direct access to /api/ai/chat:

Codetext
curl https://cencori.com/api/ai/chat \
  -H "CENCORI_API_KEY: csk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Hello!"}],
    "stream": false
  }'

This endpoint returns the OpenAI-compatible choices[0].message shape and also includes Cencori convenience fields such as content, toolCalls, and cost_usd.

OpenAI-Compatible Endpoint

Use this when a client or framework already expects the OpenAI Chat Completions API:

Codetext
curl https://api.cencori.com/v1/chat/completions \
  -H "Authorization: Bearer csk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

When configuring an SDK, set the base URL to https://api.cencori.com/v1, not the full /chat/completions URL.

Request Parameters

FieldTypeRequiredNotes
modelstringYesAny model routed through Cencori
messagesarrayYesConversation history
temperaturenumberNoSampling temperature
maxTokensnumberNoMax output tokens
streambooleanNoStream the response
toolsarrayNoFunction/tool definitions
toolChoicestring or objectNoTool selection mode
userId or userstringNoEnd-user identifier for attribution and end-user billing

OpenAI-Compatible Response Shape

Codetext
{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1677652288,
  "model": "gpt-4o",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "The capital of France is Paris."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 13,
    "completion_tokens": 7,
    "total_tokens": 20
  }
}

Streaming

SDK Streaming

Codetext
const stream = cencori.ai.chatStream({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'Tell me a story.' }],
});
 
for await (const chunk of stream) {
  process.stdout.write(chunk.delta);
}

HTTP Streaming

Codetext
curl -N https://api.cencori.com/v1/chat/completions \
  -H "Authorization: Bearer csk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Tell me a story."}],
    "stream": true
  }'

Tool Calling

Codetext
const response = await cencori.ai.chat({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'What is the weather in Tokyo?' }],
  tools: [
    {
      type: 'function',
      function: {
        name: 'get_weather',
        description: 'Get weather for a location',
        parameters: {
          type: 'object',
          properties: {
            location: { type: 'string' },
          },
          required: ['location'],
        },
      },
    },
  ],
});
 
console.log(response.toolCalls);

Error Handling

Handle transient errors, security blocks, and rate limits in your application:

Codetext
try {
  await cencori.ai.chat({
    model: 'gpt-4o',
    messages: [{ role: 'user', content: 'Hello!' }],
  });
} catch (error) {
  console.error(error);
}