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

# Create chat completion

`POST /v1/chat/completions`

## Request

- Base URL: `https://api.us-east-1.langdb.ai`
- URL: `https://api.us-east-1.langdb.ai/v1/chat/completions`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/langdb/apis/ai-gateway-api-2/docs/v1/chat/completions/post.ts> (a function with typed inputs; its response is checked against the schema)

## Headers

- `X-Project-Id` string, required

## Request body

- CreateChatCompletionRequest
  - `model` string, required: ID of the model to use. This can be either a specific model ID or a virtual model identifier.
  - `messages` object[], required: A list of messages in the conversation.
    - `role` 'system' | 'user' | 'assistant'
    - `content` string
  - `temperature` number: Sampling temperature.
  - `mcp_servers` object[]: Model Context Protocol servers to use during the request. These enable capabilities like web search.
    - `name` string, required: Identifier for the MCP server.
    - `type` string, required: Type of the MCP server.
  - `router` object: Router configuration for model selection or customization.
    - `name` string, required: Name of the router to use.
    - `type` string, required: Type of the router implementation.
    - `script` string: JavaScript code that defines the routing logic when type is "script".
  - `extra` object: Additional configuration options for the completion request.
    - `guards` string[]: List of guard identifiers to apply to this request. Guards provide content filtering and validation.
    - `user` object: User-specific information to associate with this request. This can be used for analytics and personalization.
      - `id` string: Unique identifier for the user.
      - `name` string: Name of the user.
      - `tags` string[]: List of tags associated with the user. Can be used for categorization or filtering.

## Response `200`

OK

- CreateChatCompletionResponse: Represents a chat completion response returned by model, based on the provided input.
  - `id` string, required: A unique identifier for the chat completion.
  - `choices` object[], required: A list of chat completion choices. Can be more than one if `n` is greater than 1.
    - `finish_reason` 'stop' | 'length' | 'tool_calls' | 'content_filter' | 'function_call', required: The reason the model stopped generating tokens. This will be `stop` if the model hit a natural stop point or a provided stop sequence, `length` if the maximum number of tokens specified in the request was reached, `content_filter` if content was omitted due to a flag from our content filters, `tool_calls` if the model called a tool, or `function_call` (deprecated) if the model called a function.
    - `index` integer, required: The index of the choice in the list of choices.
    - `message` object, required
      - `role` 'assistant', required
      - `content` string, required
    - `logprobs` object, nullable, required: Log probability information for the choice.
      - `content` object[], nullable, required: A list of message content tokens with log probability information.
        - `token` string
        - `logprob` number
      - `refusal` object[], nullable, required: A list of message refusal tokens with log probability information.
        - `token` string
        - `logprob` number
  - `created` integer, required: The Unix timestamp (in seconds) of when the chat completion was created.
  - `model` string, required: The model used for the chat completion.
  - `service_tier` 'scale' | 'default', nullable: The service tier used for processing the request. This field is only included if the `service_tier` parameter is specified in the request.
  - `system_fingerprint` string: This fingerprint represents the backend configuration that the model runs with. Can be used in conjunction with the `seed` request parameter to understand when backend changes have been made that might impact determinism.
  - `object` 'chat.completion', required: The object type, which is always `chat.completion`.
  - `usage` object: Usage statistics for the completion request.
    - `prompt_tokens` integer: Number of tokens in the prompt.
    - `completion_tokens` integer: Number of tokens in the completion.
    - `total_tokens` integer: Total number of tokens used.
    - `prompt_tokens_details` object
      - `cached_tokens` integer
    - `completion_tokens_details` object
      - `reasoning_tokens` integer
      - `accepted_prediction_tokens` integer
      - `rejected_prediction_tokens` integer

---

[API](https://skmtc.dev/langdb/apis/ai-gateway-api-2.md) - [All operations](https://skmtc.dev/langdb/apis/ai-gateway-api-2/llms.txt) - [OpenAPI document](https://skmtc.dev/langdb/apis/ai-gateway-api-2/revisions/2fc3660bf759?raw)