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

# Chat completion

`POST /v1/chat`

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`, `translation`, or `vision` tools. Note that you can only use one built-in tool type in the array (only one of `graph`, `llm`, `translation`, or `vision`). 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 — A tool that uses Palmyra Translate to translate text. Note that this tool does not stream results. The response is returned after the translation is complete.
        - `type` 'translation', required — The type of tool.
        - `function` TranslationFunction, required — A tool that uses Palmyra Translate to translate text.
          - `model` 'palmyra-translate', required — The model to use for translation.
          - `source_language_code` string — Optional. The [ISO-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes) language code of the original text to translate. For example, `en` for English, `zh` for Chinese, `fr` for French, `es` for Spanish. If the language has a variant, the code appends the two-digit [ISO-3166 country code](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes). If you do not provide a language code, the LLM detects the language of the text.
          - `target_language_code` string — Optional. The [ISO-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes) language code of the target language for the translation. For example, `en` for English, `zh` for Chinese, `fr` for French, `es` for Spanish. If the language has a variant, the code appends the two-digit [ISO-3166 country code](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes). If you do not provide a language code, the LLM uses the content of the chat message to determine the target language.
          - `formality` boolean, required — Whether to use formal or informal language in the translation. See the [list of languages that support formality](https://dev.writer.com/api-reference/translation-api/language-support#formality). If the language does not support formality, this parameter is ignored.
          - `length_control` boolean, required — Whether to control the length of the translated text. See the [list of languages that support length control](https://dev.writer.com/api-reference/translation-api/language-support#length-control). If the language does not support length control, this parameter is ignored.
          - `mask_profanity` boolean, required — Whether to mask profane words in the translated text. See the [list of languages that do not support profanity masking](https://dev.writer.com/api-reference/translation-api/language-support#profanity-masking). If the language does not support profanity masking, this parameter is ignored.
      - object
        - `type` 'vision', required — The type of tool.
        - `function` VisionFunction, required — A tool that uses Palmyra Vision to analyze images and documents. Supports JPG, PNG, PDF, and TXT files up to 7MB each.
          - `variables` VisionToolRequestFileVariable[], required
            - `name` string, required — The name of the file variable. You must reference this name in the `message.content` field of the request to the chat completions endpoint. Use double curly braces (`{{}}`) to reference the file. For example, `Describe the difference between the image {{image_1}} and the image {{image_2}}`.
            - `file_id` string, required — The File ID of the file to analyze. The file must be uploaded to the Writer platform before you use it with the Vision tool. Supported file types: JPG, PNG, PDF, TXT. The maximum allowed file size is 7MB.
          - `model` 'palmyra-vision', required — The model to use for image analysis.
      - 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.
      - `translation_data` TranslationData
        - `source_text` string, required — The text the tool translated.
        - `source_language_code` string, required — The language code of the source text.
        - `target_language_code` string, required — The language code of the target text.
      - `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.

---

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