---
title: "Chat completion"
method: POST
path: "/v1/chat"
tags: ["Generation API"]
---

# Chat completion

`POST /v1/chat`

## Request

- Base URL: `https://api.writer.com`
- URL: `https://api.writer.com/v1/chat`
- Auth: HTTP bearer

Generate a chat completion based on the provided messages. The response shown below is for non-streaming. To learn about streaming responses, see the [chat completion guide](https://dev.writer.com/home/chat-completion).

## Request body

- ChatRequest
  - `model` string, required: The [ID of the model](https://dev.writer.com/home/models) to use for creating the chat completion. This can be a Palmyra model such as `palmyra-x5` or `palmyra-x4`, or the ID of an [external model](https://dev.writer.com/home/external-models) configured for your organization.
  - `messages` ChatMessage[], required: An array of message objects that form the conversation history or context for the model to respond to. The array must contain at least one message.
    - `content` union: The content of the message. Can be either a string (for text-only messages) or an array of content fragments (for mixed text and image messages).
      - string
      - CompositeContent[]
        - union: A union type that can contain either text or image content fragments. This enables chat messages to include mixed content types, allowing users to send both text and images in a single message. Note: Image fragments are only supported with the Palmyra X5 model.
          - TextFragment: Represents a text content fragment within a chat message.
            - `type` 'text', required: The type of content fragment. Must be `text` for text fragments.
            - `text` string, required: The actual text content of the message fragment.
          - ImageFragment: Represents an image content fragment within a chat message. Note: This content type is only supported with the Palmyra X5 model.
            - `type` 'image_url', required: The type of content fragment. Must be `image_url` for image fragments.
            - `image_url` object, required: The image URL object containing the location of the image.
              - …
    - `role` 'user' | 'assistant' | 'system' | 'tool', required: The role of the chat message. You can provide a system prompt by setting the role to `system`, or specify that a message is the result of a [tool call](https://dev.writer.com/home/tool-calling) by setting the role to `tool`.
    - `name` string, nullable: An optional name for the message sender. Useful for identifying different users, personas, or tools in multi-participant conversations.
    - `tool_call_id` string, nullable
    - `tool_calls` ToolCall[], nullable
      - `index` integer
      - `id` string, required
      - `type` 'function', required
      - `function` Function, required
        - `name` string, required
        - `arguments` string, required
    - `graph_data` GraphData
      - `sources` Source[]
        - `file_id` string, required: The unique identifier of the file in your Writer account.
        - `snippet` string, required: The exact text snippet from the source document that was used to support the response.
      - `status` 'processing' | 'finished', nullable
      - `subqueries` SubQuery[]
        - `query` string, required: The subquery that was generated to help answer the main question.
        - `answer` string, required: The answer to the subquery based on Knowledge Graph content.
        - `sources` Source[], required: Array of source snippets that were used to answer this subquery.
          - `file_id` string, required: The unique identifier of the file in your Writer account.
          - `snippet` string, required: The exact text snippet from the source document that was used to support the response.
      - `references` References: Detailed source information organized by reference type, providing comprehensive metadata about the sources used to generate the response.
        - `files` File[]: Array of file-based references from uploaded documents in the Knowledge Graph.
          - `text` string, required: The exact text snippet from the source document that was used to support the response.
          - `fileId` string, required: The unique identifier of the file in your Writer account.
          - `score` number, required: Internal score used during the retrieval process for ranking and selecting relevant snippets.
          - `page` integer: Page number where this snippet was found in the source document.
          - `cite` string: Unique citation ID that appears in inline citations within the response text (null if not cited).
        - `web` Web[]: Array of web-based references from online sources accessed during the query.
          - `text` string, required: The exact text snippet from the web source that was used to support the response.
          - `url` string, uri, required: The URL of the web page where this content was found.
          - `title` string, required: The title of the web page where this content was found.
          - `score` number, required: Internal score used during the retrieval process for ranking and selecting relevant snippets.
    - `refusal` string, nullable
  - `max_tokens` integer: Defines the maximum number of tokens (words and characters) that the model can generate in the response. This can be adjusted to allow for longer or shorter responses as needed. The maximum value varies by model. See the [models overview](/home/models) for more information about the maximum number of tokens for each model.
  - `temperature` number, double: Controls the randomness or creativity of the model's responses. A higher temperature results in more varied and less predictable text, while a lower temperature produces more deterministic and conservative outputs.
  - `top_p` number, double: Sets the threshold for "nucleus sampling," a technique to focus the model's token generation on the most likely subset of tokens. Only tokens with cumulative probability above this threshold are considered, controlling the trade-off between creativity and coherence.
  - `n` integer: Specifies the number of completions (responses) to generate from the model in a single request. This parameter allows for generating multiple responses, offering a variety of potential replies from which to choose.
  - `stop` union: A token or sequence of tokens that, when generated, will cause the model to stop producing further content. This can be a single token or an array of tokens, acting as a signal to end the output.
    - string[]
    - string
  - `logprobs` boolean: Specifies whether to return log probabilities of the output tokens.
  - `stream` boolean: Indicates whether the response should be streamed incrementally as it is generated or only returned once fully complete. Streaming can be useful for providing real-time feedback in interactive applications.
  - `tools` Tool[]: An array containing tool definitions for tools that the model can use to generate responses. The tool definitions use JSON schema. You can define your own functions or use one of the built-in `graph`, `llm`, or `web_search` tools. Note that you can only use one built-in tool type in the array (only one of `graph`, `llm`, or `web_search`). You can pass multiple [custom tools](https://dev.writer.com/home/tool-calling) of type `function` in the same request.
    - union
      - object
        - `type` 'function', required: The type of tool.
        - `function` ToolFunction, required: A tool that uses a custom function.
          - `description` string: Description of the function.
          - `name` string, required: Name of the function.
          - `parameters` object: The parameters of the function.
      - object
        - `type` 'graph', required: The type of tool.
        - `function` GraphFunction, required: A tool that uses Knowledge Graphs as context for responses.
          - `description` string: A description of the graph content.
          - `graph_ids` string[], required: An array of graph IDs to use in the tool.
          - `subqueries` boolean, required: Boolean to indicate whether to include subqueries in the response.
          - `query_config` GraphQueryConfig: Configuration options for Knowledge Graph queries.
            - `max_subquestions` integer: Maximum number of subquestions to generate when processing complex queries. Set higher to improve detail, set lower to reduce response time. Range: 1-10, Default: 6.
            - `search_weight` integer: Weight given to search results when ranking and selecting relevant information. Higher values (closer to 100) prioritize keyword-based matching, while lower values (closer to 0) prioritize semantic similarity matching. Use higher values for exact keyword searches, lower values for conceptual similarity searches. Range: 0-100, Default: 50.
            - `grounding_level` number, double: Level of grounding required for responses, controlling how closely answers must be tied to source material. Set lower for grounded outputs, higher for creativity. Higher values (closer to 1.0) allow more creative interpretation, while lower values (closer to 0.0) stick more closely to source material. Range: 0.0-1.0, Default: 0.0.
            - `max_snippets` integer: Maximum number of text snippets to retrieve from the Knowledge Graph for context. Works in concert with `search_weight` to control best matches vs broader coverage. While technically supports 1-60, values below 5 may return no results due to RAG implementation. Recommended range: 5-25. Due to RAG system behavior, you may see more snippets than requested. Range: 1-60, Default: 30.
            - `max_tokens` integer: Maximum number of tokens the model can generate in the response. This controls the length of the AI's answer. Set higher for longer answers, set lower for shorter, faster answers. Range: 100-8000, Default: 4000.
            - `keyword_threshold` number, double: Threshold for keyword-based matching when searching Knowledge Graph content. Set higher for stricter relevance, lower for broader range. Higher values (closer to 1.0) require stronger keyword matches, while lower values (closer to 0.0) allow more lenient matching. Range: 0.0-1.0, Default: 0.7.
            - `semantic_threshold` number, double: Threshold for semantic similarity matching when searching Knowledge Graph content. Set higher for stricter relevance, lower for broader range. Higher values (closer to 1.0) require stronger semantic similarity, while lower values (closer to 0.0) allow more lenient semantic matching. Range: 0.0-1.0, Default: 0.7.
            - `inline_citations` boolean: Whether to include inline citations in the response, showing which Knowledge Graph sources were used. Default: false.
      - object
        - `type` 'llm', required: The type of tool.
        - `function` LlmFunction, required: A tool that uses another model to generate a response.
          - `description` string, required: A description of the model to use.
          - `model` string, required: The model to use.
      - object
        - `type` 'web_search', required: The type of tool.
        - `function` WebSearchFunction, required: A tool that uses web search to find information.
          - `exclude_domains` string[], required: An array of domains to exclude from the search results.
          - `include_domains` string[], required: An array of domains to include in the search results.
  - `tool_choice` union: Configure how the model will call functions: - `auto`: allows the model to automatically choose the tool to use, or not call a tool - `none`: disables tool calling; the model will instead generate a message - `required`: requires the model to call one or more tools You can also use a JSON object to force the model to call a specific tool. For example, `{"type": "function", "function": {"name": "get_current_weather"}}` requires the model to call the `get_current_weather` function, regardless of the prompt.
    - StringToolChoice
      - `value` 'none' | 'auto' | 'required', required
    - JsonObjectToolChoice
      - `value` object, required: A JSON object that specifies the tool to call. For example, `{"type": "function", "function": {"name": "get_current_weather"}}`
  - `stream_options` StreamOptions: Additional options for streaming.
    - `include_usage` boolean, required: Indicate whether to include usage information.
  - `response_format` ResponseFormat: The response format to use for the chat completion, available with `palmyra-x4` and `palmyra-x5`. `text` is the default response format. [JSON Schema](https://json-schema.org/) is supported for structured responses. If you specify `json_schema`, you must also provide a `json_schema` object.
    - `type` 'text' | 'json_schema', required: The type of response format to use.
    - `json_schema` object: The JSON schema to use for the response format.

## Response `200`

Successful response

- ChatResponse
  - `id` string, uuid, required: A globally unique identifier (UUID) for the response generated by the API. This ID can be used to reference the specific operation or transaction within the system for tracking or debugging purposes.
  - `object` 'chat.completion', required: The type of object returned, which is always `chat.completion` for chat responses.
  - `choices` ChatCompletionChoice[], required: An array of objects representing the different outcomes or results produced by the model based on the input provided.
    - `index` integer, required: The index of the choice in the list of completions generated by the model.
    - `finish_reason` 'stop' | 'length' | 'content_filter' | 'tool_calls', required
    - `message` ChatCompletionResponseMessage, required: The chat completion message from the model. Note: this field is deprecated for streaming. Use `delta` instead.
      - `content` string, required: The text content produced by the model. This field contains the actual output generated, reflecting the model's response to the input query or command.
      - `role` 'assistant', required: Specifies the role associated with the content.
      - `tool_calls` ToolCall[]
        - `index` integer
        - `id` string, required
        - `type` 'function', required
        - `function` Function, required
          - `name` string, required
          - `arguments` string, required
      - `graph_data` GraphData
        - `sources` Source[]
          - `file_id` string, required: The unique identifier of the file in your Writer account.
          - `snippet` string, required: The exact text snippet from the source document that was used to support the response.
        - `status` 'processing' | 'finished', nullable
        - `subqueries` SubQuery[]
          - `query` string, required: The subquery that was generated to help answer the main question.
          - `answer` string, required: The answer to the subquery based on Knowledge Graph content.
          - `sources` Source[], required: Array of source snippets that were used to answer this subquery.
            - `file_id` string, required: The unique identifier of the file in your Writer account.
            - `snippet` string, required: The exact text snippet from the source document that was used to support the response.
        - `references` References: Detailed source information organized by reference type, providing comprehensive metadata about the sources used to generate the response.
          - `files` File[]: Array of file-based references from uploaded documents in the Knowledge Graph.
            - `text` string, required: The exact text snippet from the source document that was used to support the response.
            - `fileId` string, required: The unique identifier of the file in your Writer account.
            - `score` number, required: Internal score used during the retrieval process for ranking and selecting relevant snippets.
            - `page` integer: Page number where this snippet was found in the source document.
            - `cite` string: Unique citation ID that appears in inline citations within the response text (null if not cited).
          - `web` Web[]: Array of web-based references from online sources accessed during the query.
            - `text` string, required: The exact text snippet from the web source that was used to support the response.
            - `url` string, uri, required: The URL of the web page where this content was found.
            - `title` string, required: The title of the web page where this content was found.
            - `score` number, required: Internal score used during the retrieval process for ranking and selecting relevant snippets.
      - `llm_data` LlmData, nullable
        - `prompt` string, required: The prompt processed by the model.
        - `model` string, required: The model used by the tool.
      - `web_search_data` WebSearchData
        - `sources` object[], required
          - `url` string
          - `raw_content` string
      - `refusal` string, nullable, required
    - `logprobs` Logprobs, nullable
      - `content` LogprobsToken[], nullable, required
        - `token` string, required
        - `logprob` number, double, required
        - `bytes` integer[]
        - `top_logprobs` TopLogProb[], required
          - `token` string, required
          - `logprob` number, double, required
          - `bytes` integer[]
      - `refusal` LogprobsToken[], nullable, required
        - `token` string, required
        - `logprob` number, double, required
        - `bytes` integer[]
        - `top_logprobs` TopLogProb[], required
          - `token` string, required
          - `logprob` number, double, required
          - `bytes` integer[]
  - `created` integer, required: The Unix timestamp (in seconds) when the response was created. This timestamp can be used to verify the timing of the response relative to other events or operations.
  - `model` string, required: Identifies the specific model used to generate the response.
  - `usage` ChatCompletionUsage: Usage information for the chat completion response. Please note that at this time Knowledge Graph tool usage is not included in this object.
    - `prompt_tokens` integer, required
    - `total_tokens` integer, required
    - `completion_tokens` integer, required
    - `prompt_token_details` PromptTokenDetails
      - `cached_tokens` integer, required
    - `completion_tokens_details` CompletionTokenDetails
      - `reasoning_tokens` integer, required
  - `system_fingerprint` string: A string representing the backend configuration that the model runs with.
  - `service_tier` string: The service tier used for processing the request.

## Changes

- **2026-10-29** `59865afc5779`: 1 breaking, 3 warning, 1 info
  - removed `#/components/schemas/translation_tool, #/components/schemas/vision_tool` from the `tools/items/` request property `oneOf` list
  - removed the optional property `choices/items/message/translation_data` from the response with the `200` status (media type: application/json)
  - removed the optional property `items/choices/items/delta/translation_data` from the response with the `200` status (media type: text/event-stream)
  - removed the optional property `items/choices/items/message/translation_data` from the response with the `200` status (media type: text/event-stream)
  - …1 more
- **2026-10-16** `5e8521484e1e`: 1 breaking, 4 info
  - the request property `messages/items/tool_calls/items/function/name` became required
  - the `logprobs` request property default value `false` was added
  - the response property `choices/items/message/tool_calls/items/function/name` became required for the status `200` (media type: application/json)
  - the response property `items/choices/items/delta/tool_calls/items/function/name` became required for the status `200` (media type: text/event-stream)
  - …1 more
- …earlier changes not shown

[Operation history](https://skmtc.dev/writer/apis/writer-api/changes/v1/chat/post.md)

---

[API](https://skmtc.dev/writer/apis/writer-api.md) - [All operations](https://skmtc.dev/writer/apis/writer-api/llms.txt) - [OpenAPI document](https://skmtc.dev/writer/apis/writer-api/revisions/59865afc5779?raw)