---
title: "Run deterministic utility chat completion"
method: POST
path: "/v1/chat/completions"
tags: ["LLM API"]
---

# Run deterministic utility chat completion

`POST /v1/chat/completions`

## Request

- Base URL: `https://api.algenta.ai`
- URL: `https://api.algenta.ai/v1/chat/completions`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

Runs the selected model over a chat transcript and returns an assistant message. Tokenizer-backed utility chat remains deterministic, while configured provider-backed models are routed through the provider service when advertised in GET /v1/models.

## Request body

- ChatCompletionsRequest
  - `model` string: Chat-capable utility model identifier from GET /v1/models.
  - `messages` ChatCompletionInputMessage[], required: Ordered chat transcript processed by the selected utility model.
    - `role` 'system' | 'user' | 'assistant' | 'developer' | 'tool', required
    - `content` string, nullable: UTF-8 message content. May be omitted/null on an assistant message that only calls tools.
    - `tool_calls` ChatCompletionToolCall[], nullable: Tool calls requested by a prior assistant turn (assistant role only).
      - `id` string, required
      - `type` 'function'
      - `function` ChatCompletionToolCallFunction, required
        - `name` string, required
        - `arguments` string, required: JSON-encoded arguments for the function call (a string, per the OpenAI wire shape).
    - `tool_call_id` string, nullable: The id of the tool call this message answers (tool role only).
    - `name` string, nullable: Optional participant name, echoed by some clients on any role.
  - `stream` boolean: When true, return Server-Sent Events with deterministic completion chunks.
  - `tools` ChatCompletionToolDef[], nullable: Function tools the model may call. Forwarded to provider-backed chat models that support tool calling, and to algenta_local (rendered into the Qwen3 chat template's tools preamble); unsupported on the deterministic tokenizer utility model and on an algenta_local checkpoint with no chat template.
    - `type` 'function'
    - `function` ChatCompletionToolFunctionDef, required
      - `name` string, required
      - `description` string, nullable
      - `parameters` object, nullable: JSON Schema object describing the function's parameters.
      - `strict` boolean, nullable
  - `tool_choice` union: Controls whether/which tool the model must call. Ignored unless 'tools' is set. algenta_local supports 'auto' (default) and 'none' only -- its tools preamble is a hint the model may act on, not a mechanism that can force a call, so 'required' and a named-function choice are refused (model_capability_unsupported) on that backend.
    - 'auto' | 'none' | 'required'
    - ChatCompletionNamedToolChoice
      - `type` 'function'
      - `function` ChatCompletionToolChoiceFunctionName, required
        - `name` string, required
  - `parallel_tool_calls` boolean, nullable: Hint to allow/disallow multiple tool calls in one turn. Best-effort: honored where the provider's API exposes an equivalent knob, otherwise ignored.
  - `max_tokens` integer, nullable: Maximum tokens to generate. Applies to algenta_local backend models (default 256) and forwarded providers that accept an output budget; ignored otherwise.
  - `temperature` number, nullable: Sampling temperature. Applies to algenta_local backend models: 0 or omitted is greedy (argmax), > 0 draws from the model distribution. Remote providers use their server-side defaults.
  - `top_p` number, nullable: Nucleus sampling threshold for algenta_local backend models. Remote providers use their server-side defaults.
  - `seed` integer, nullable: Sampling seed for algenta_local backend models: same prompt + parameters + seed reproduce the identical completion. Remote providers use their server-side defaults.

## Response `200`

JSON chat completion by default, or Server-Sent Events chunks when stream=true.

- ChatCompletionsResponse
  - `id` string, required
  - `object` 'chat.completion'
  - `model` string, required
  - `provider_backend` string, nullable: Concrete provider backend that served this chat completion when routed.
  - `provider_model_id` string, nullable: Concrete configured provider model that served this chat completion when routed.
  - `provider_attempts` ProviderAttemptResponse[]: Ordered provider attempts made while serving this chat completion.
    - `provider_backend` string, required
    - `provider_model_id` string, required
    - `outcome` 'selected' | 'failed', required
    - `error_code` string, nullable
  - `choices` ChatCompletionChoice[], required
    - `index` integer, required
    - `finish_reason` 'stop' | 'tool_calls' | 'length' | 'content_filter'
    - `message` ChatCompletionOutputMessage, required
      - `role` 'assistant'
      - `content` string, nullable
      - `tool_calls` ChatCompletionToolCall[], nullable: Tool calls the model made this turn, present when finish_reason is 'tool_calls'.
        - `id` string, required
        - `type` 'function'
        - `function` ChatCompletionToolCallFunction, required
          - `name` string, required
          - `arguments` string, required: JSON-encoded arguments for the function call (a string, per the OpenAI wire shape).
  - `usage` ChatCompletionUsage, required
    - `prompt_tokens` integer, required
    - `completion_tokens` integer, required
    - `total_tokens` integer, required

## Other responses

- `422`: Validation Error

---

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