---
title: "Create chat completion"
method: POST
path: "/v1/chat/completions"
tags: ["Chat Completions"]
---

# Create chat completion

`POST /v1/chat/completions`

## Request

- Base URL: `https://api.sandbase.ai`
- URL: `https://api.sandbase.ai/v1/chat/completions`
- Auth: HTTP bearer

OpenAI-compatible chat completions endpoint. SandBase uses model and stream for routing and preserves additional provider-compatible fields when the selected route uses the same protocol. Support for provider-specific fields can vary when SandBase translates between protocols.

## Request body

- ChatCompletionRequest: OpenAI-compatible request. Additional provider-compatible fields are forwarded when supported by the selected route.
  - `model` string, required: Model identifier
  - `messages` object[], required
    - `role` string, required: Message role supported by the selected provider, such as system, developer, user, assistant, or tool.
    - `content` union
      - string
      - object[]
    - `name` string
    - `tool_calls` unknown[]
      - unknown
    - `tool_call_id` string
  - `temperature` number
  - `top_p` number
  - `max_tokens` integer
  - `stream` boolean
  - `stop` union
    - string
    - string[]
  - `tools` object[]
  - `mcp_servers` MCPServer[]
    - `name` string, required
    - `type` 'url', required
    - `url` string, uri, required
  - `tool_choice` union
    - string
    - object
  - `parallel_tool_calls` boolean
  - `user` string
  - `response_format` object
  - `reasoning_effort` string: Provider-compatible reasoning effort setting.
  - `reasoning` object: Reasoning configuration; common fields include effort and max_tokens.
  - `thinking` object: Thinking configuration; common fields include type and budget_tokens.
  - `extra_body` object: Provider-specific parameters used when SandBase translates the request between protocols.
  - `n` integer
  - `presence_penalty` number
  - `frequency_penalty` number
  - `stream_options` object
    - `include_usage` boolean

## Response `200`

Chat completion response

- ChatCompletionResponse
  - `id` string, required
  - `object` 'chat.completion', required
  - `created` integer, required
  - `model` string, required
  - `choices` object[], required
    - `index` integer, required
    - `message` object, required
      - `role` string, required
      - `content` string, nullable, required
      - `tool_calls` unknown[]
        - unknown
      - `reasoning_content` string, nullable
    - `finish_reason` string, nullable, required: Provider finish reason. Values can vary by model and provider.
    - `logprobs` unknown, required
  - `usage` object, required
    - `prompt_tokens` integer, required
    - `completion_tokens` integer, required
    - `total_tokens` integer, required
    - `prompt_tokens_details` object, required
      - `cached_tokens` integer, required
      - `cache_write_tokens` integer, required
    - `completion_tokens_details` object, required
      - `reasoning_tokens` integer, required

## Other responses

- `400`: Invalid JSON, missing model, or an invalid provider request
- `401`: Missing or invalid API key
- `402`: Organization spending limit reached
- `403`: Organization is disabled, or the API key scope does not authorize this endpoint
- `404`: Model not found or unavailable
- `429`: Rate limit exceeded
- `500`: Request persistence or organization lookup failed
- `502`: Invalid response from the selected provider
- `503`: No provider route succeeded

---

[API](https://skmtc.dev/sandbase/apis/sandbase-api.md) · [All operations](https://skmtc.dev/sandbase/apis/sandbase-api/llms.txt) · [OpenAPI document](https://skmtc.dev/sandbase/apis/sandbase-api/revisions/d40df2467ba2?raw)