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

# Create a chat completion

`POST /v1/chat/completions`

Apply changes from big models into your files. Find your [API key](https://morphllm.com/dashboard). The endpoint is OpenAI-compatible and serves two request shapes, selected by `model`: Morph Apply (`morph-v3-fast`, `morph-v3-large`, `auto`) merges an edit snippet into an original file, and Warp Grep (`morph-warp-grep-v1`) runs an agentic repository search. Set `stream: true` to receive the completion as a `text/event-stream` of `chat.completion.chunk` deltas; the 200 response below documents the non-streaming shape.

## Request body

- union — Either a Morph Apply request or a Warp Grep request, discriminated by `model`.
  - ChatCompletionRequest — Apply request — merges an edit snippet into the original file with a Morph Apply model.
    - `model` 'morph-v3-fast' | 'morph-v3-large' | 'auto', required — ID of the Apply model to use, or `auto` to let the router choose
    - `messages` Message[], required — Array containing a single user message with structured content using instruction-guided format
      - `role` 'system' | 'user' | 'assistant', required — Which participant produced this chat message
      - `content` string, required — The content of the message, containing code and update snippets. An Apply message uses the format: <instruction>First-person description</instruction><code>Complete original file content</code><update>Code snippet with // ... existing code ... markers</update>
    - `stream` boolean — Enable streaming response. When true the response is a `text/event-stream` of OpenAI-style `chat.completion.chunk` deltas terminated by `data: [DONE]`.
    - `max_tokens` integer — Maximum number of tokens the Apply model may generate
    - `temperature` number — Sampling temperature for the Apply request (0.0 for deterministic output)
  - WarpGrepRequest — Warp Grep request — an agentic repository search turn driven by XML tool calls.
    - `model` 'morph-warp-grep-v1', required — ID of the Warp Grep model
    - `messages` WarpGrepMessage[], required — Multi-turn conversation with system prompt, user queries, assistant tool calls, and tool results
      - `role` 'system' | 'user' | 'assistant', required — Which participant produced this Warp Grep turn
      - `content` string, required — Message content. User messages use <repo_structure> and <search_string> XML. Assistant messages contain <think> reasoning and XML tool calls (<grep>, <read>, <list_directory>, <finish>).
    - `temperature` number — Sampling temperature (0.0 recommended for deterministic search)
    - `max_tokens` integer — Maximum tokens per response

## Response `200`

Chat completion response

- ChatCompletionResponse — Completion returned by a Morph chat model.
  - `id` string, required — Unique identifier for the completion
  - `object` string, required — Always `chat.completion`
  - `created` integer, required — Unix timestamp of when the completion was created
  - `choices` Choice[], required — List of completion choices
    - `index` integer, required — Index of the choice in the list
    - `message` object, required — The message generated by the model
      - `role` string — Author of the generated message, always `assistant`
      - `content` string — Text generated by the model for this choice
    - `finish_reason` string, required — The reason the model stopped generating tokens
  - `usage` ResponseUsage, required — 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

## Other responses

- `400` — Malformed request — missing or invalid fields.
- `401` — Missing or invalid API key.
- `429` — Rate limited — retry after the interval in the Retry-After header.
- `500` — Internal error — safe to retry with backoff.

---

[API](https://skmtc.dev/morphllm/apis/morph-api.md) · [All operations](https://skmtc.dev/morphllm/apis/morph-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/morphllm/morph-api/revisions/b9a74274b2ab/schema)