---
title: "Create a chat completion."
method: POST
path: "/v1/chat/completions"
---

# Create a chat completion.

`POST /v1/chat/completions`

Set `stream: true` to receive Server-Sent Events instead of a single JSON response. The optional `X-Conversation-Id` request header reuses a server-side session across turns when --conversations-max is non-zero.

## Headers

- `X-Conversation-Id` string

## Request body

- ChatCompletionRequest
  - `model` string — Agent name to invoke. Defaults to the team's default agent when missing or unknown.
  - `messages` ChatCompletionMessage[], required
    - `role` 'system' | 'user' | 'assistant' | 'tool' | 'developer', required
    - `content` union — Either a plain string or an array of typed content parts (text or image_url).
      - string
      - ContentPart[]
        - `type` 'text' | 'image_url', required
        - `text` string
        - `image_url` object
          - `url` string, required
          - `detail` 'auto' | 'low' | 'high'
    - `name` string
    - `tool_call_id` string
    - `tool_calls` ToolCallReference[]
      - `index` integer
      - `id` string
      - `type` 'function'
      - `function` object, required
        - `name` string, required
        - `arguments` string — JSON-encoded arguments object.
  - `stream` boolean
  - `stream_options` object
    - `include_usage` boolean — When true and stream=true, emit an extra final chunk with usage and empty choices before [DONE].
  - `temperature` number — Validated; full runtime plumbing is in progress.
  - `top_p` number
  - `max_tokens` integer
  - `stop` union
    - string
    - string[]

## Response `200`

OK. Either a JSON ChatCompletion or a `text/event-stream` of `chat.completion.chunk` events.

- ChatCompletionResponse
  - `id` string, required
  - `object` 'chat.completion', required
  - `created` integer, required
  - `model` string, required
  - `choices` ChatCompletionChoice[], required
    - `index` integer, required
    - `message` ChatCompletionMessage, required
      - `role` 'system' | 'user' | 'assistant' | 'tool' | 'developer', required
      - `content` union — Either a plain string or an array of typed content parts (text or image_url).
        - string
        - ContentPart[]
          - `type` 'text' | 'image_url', required
          - `text` string
          - `image_url` object
            - `url` string, required
            - `detail` 'auto' | 'low' | 'high'
      - `name` string
      - `tool_call_id` string
      - `tool_calls` ToolCallReference[]
        - `index` integer
        - `id` string
        - `type` 'function'
        - `function` object, required
          - `name` string, required
          - `arguments` string — JSON-encoded arguments object.
    - `finish_reason` 'stop' | 'tool_calls' | 'error' | 'length'
  - `usage` ChatCompletionUsage
    - `prompt_tokens` integer
    - `completion_tokens` integer
    - `total_tokens` integer

## Other responses

- `400` — Bad request (malformed JSON, missing user message, invalid sampling parameters).
- `401` — Missing or invalid bearer token.
- `409` — Another request with the same X-Conversation-Id is in flight. Retry sequentially.
- `413` — Request body exceeds --max-request-size.
- `500` — Agent execution failed.

## Changes

- **2026-05-05** `df4ebeefaa60` — 1 info
  - added the new optional request property `stream_options`
- **2026-04-27** `6768d19ec03d` — 1 info
  - added the non-success response with the status `409`
- **2026-04-27** `5005084f1ab9` — 1 breaking, 1 info
  - response property `choices/items/message/content` list-of-types was widened by adding types `array` to media type `application/json` of response `200`
  - request property `messages/items/content` list-of-types was widened by adding types `array` to media type `application/json`
- **2026-04-27** `0deddbed852c` — 1 breaking, 1 warning, 2 info
  - request property `messages/items/content` list-of-types was narrowed by removing types `array` from media type `application/json`
  - removed the request property `stream_options`
  - removed the non-success response with the status `409`
  - response property `choices/items/message/content` list-of-types was narrowed by removing types `array` from media type `application/json` of response `200`

[Change history](https://skmtc.dev/docker/apis/docker-agent-chat-completions/changes/v1/chat/completions/post.md)

---

[API](https://skmtc.dev/docker/apis/docker-agent-chat-completions.md) · [All operations](https://skmtc.dev/docker/apis/docker-agent-chat-completions/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/docker/docker-agent-chat-completions/revisions/e5831c10954f/schema)