---
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.

---

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