openapi: 3.0.3 info: title: File API Generation API API version: '1.0' servers: - url: https://api.writer.com security: - bearerAuth: [] tags: - name: Generation API paths: /v1/chat: post: security: - bearerAuth: [] tags: - Generation API summary: Chat completion description: 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). operationId: chat requestBody: content: application/json: schema: $ref: '#/components/schemas/chat_request' required: true responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/chat_response' example: id: 57e4f58f-f7b1-41d8-be17-a6279c073aad object: chat.completion choices: - index: 0 finish_reason: stop message: content: The earnings report shows... role: assistant refusal: null tool_calls: [] graph_data: sources: [] status: finished subqueries: [] llm_data: prompt: Write a memo summarizing this earnings report. model: palmyra-x5 translation_data: null web_search_data: null created: 1715361795 model: palmyra-x5 usage: prompt_tokens: 40 total_tokens: 340 completion_tokens: 300 prompt_token_details: cached_tokens: 0 completion_token_details: reasoning_tokens: 0 system_fingerprint: v1 service_tier: standard text/event-stream: schema: type: array items: $ref: '#/components/schemas/chat_completion_chunk' examples: '200': value: id: 57e4f58f-f7b1-41d8-be17-a6279c073aad object: chat.completion choices: - index: 0 finish_reason: length message: content: The earnings report shows... role: assistant tool_calls: [] refusal: null graph_data: sources: [] status: finished subqueries: [] llm_data: prompt: Write a memo summarizing this earnings report. model: palmyra-x5 translation_data: null web_search_data: null delta: content: The earnings report shows... role: assistant tool_calls: [] refusal: null graph_data: sources: [] status: finished subqueries: [] llm_data: prompt: Write a memo summarizing this earnings report. model: palmyra-x5 translation_data: null web_search_data: null created: 1715361795 model: palmyra-x5 usage: prompt_tokens: 40 total_tokens: 340 completion_tokens: 300 prompt_token_details: cached_tokens: 0 completion_token_details: reasoning_tokens: 0 system_fingerprint: v1 service_tier: standard x-codeSamples: - lang: cURL source: "curl --location --request POST https://api.writer.com/v1/chat \\\n --header \"Authorization: Bearer \" \\\n --header \"Content-Type: application/json\" \\\n--data-raw '{\"model\":\"palmyra-x5\",\"messages\":[{\"content\":\"Write a memo summarizing this earnings report.\",\"role\":\"user\"}]}'" - lang: JavaScript source: "import Writer from 'writer-sdk';\n\nconst client = new Writer({\n apiKey: process.env['WRITER_API_KEY'], // This is the default and can be omitted\n});\n\nasync function main() {\n const chat = await client.chat.chat({\n messages: [{ content: 'Write a memo summarizing this earnings report.', role: 'user' }],\n model: 'palmyra-x5',\n });\n\n console.log(chat.id);\n}\n\nmain();" - lang: Python source: "import os\nfrom writerai import Writer\n\nclient = Writer(\n # This is the default and can be omitted\n api_key=os.environ.get(\"WRITER_API_KEY\"),\n)\nchat = client.chat.chat(\n messages=[{\n \"content\": \"Write a memo summarizing this earnings report.\",\n \"role\": \"user\",\n }],\n model=\"palmyra-x5\",\n)\nprint(chat.id)" /v1/completions: post: security: - bearerAuth: [] tags: - Generation API summary: Text generation description: Generate text completions using the specified model and prompt. This endpoint is useful for text generation tasks that don't require conversational context. operationId: completions requestBody: content: application/json: schema: $ref: '#/components/schemas/completions_request' required: true responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/completions_response' text/event-stream: schema: type: array items: $ref: '#/components/schemas/streaming_data' x-codeSamples: - lang: cURL source: "curl --location --request POST https://api.writer.com/v1/completions \\\n --header \"Authorization: Bearer \" \\\n --header \"Content-Type: application/json\" \\\n--data-raw '{\"model\":\"palmyra-x-003-instruct\",\"prompt\":\"Write me a short SEO article about camping gear\",\"max_tokens\":150,\"temperature\":0.7,\"top_p\":0.9,\"stop\":[\".\"],\"best_of\":1,\"random_seed\":42,\"stream\":false}'" - lang: JavaScript source: "import Writer from 'writer-sdk';\n\nconst client = new Writer({\n apiKey: process.env['WRITER_API_KEY'], // This is the default and can be omitted\n});\n\nasync function main() {\n const completion = await client.completions.create({\n model: 'palmyra-x-003-instruct',\n prompt: 'Write me a short SEO article about camping gear',\n });\n\n console.log(completion.choices);\n}\n\nmain();" - lang: Python source: "import os\nfrom writerai import Writer\n\nclient = Writer(\n # This is the default and can be omitted\n api_key=os.environ.get(\"WRITER_API_KEY\"),\n)\ncompletion = client.completions.create(\n model=\"palmyra-x-003-instruct\",\n prompt=\"Write me a short SEO article about camping gear\",\n)\nprint(completion.choices)" /v1/models: get: security: - bearerAuth: [] tags: - Generation API summary: List models description: Retrieve a list of available models that can be used for text generation, chat completions, and other AI tasks. operationId: models x-mint: mcp: enabled: true name: list-models description: Get a list of available Writer AI models responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/models_response' x-codeSamples: - lang: cURL source: "curl --location --request GET https://api.writer.com/v1/models \\\n --header \"Authorization: Bearer \"" - lang: JavaScript source: "import Writer from 'writer-sdk';\n\nconst client = new Writer({\n apiKey: process.env['WRITER_API_KEY'], // This is the default and can be omitted\n});\n\nasync function main() {\n const model = await client.models.list();\n\n console.log(model.models);\n}\n\nmain();" - lang: Python source: "import os\nfrom writerai import Writer\n\nclient = Writer(\n # This is the default and can be omitted\n api_key=os.environ.get(\"WRITER_API_KEY\"),\n)\nmodel = client.models.list()\nprint(model.models)" /v1/applications: get: security: - bearerAuth: [] tags: - Generation API summary: List applications description: Retrieves a paginated list of no-code agents (formerly called no-code applications) with optional filtering and sorting capabilities. parameters: - name: order in: query required: false description: Sort order for the results based on creation time. schema: type: string default: desc enum: - asc - desc - name: before in: query required: false description: Return results before this application ID for pagination. schema: type: string format: uuid - name: after in: query required: false description: Return results after this application ID for pagination. schema: type: string format: uuid - name: limit in: query required: false description: Maximum number of applications to return in the response. schema: type: integer format: int32 default: 50 - name: type in: query required: false description: Filter applications by their type. schema: $ref: '#/components/schemas/application_type' default: generation responses: '200': description: Successfully retrieved list of applications. content: application/json: schema: $ref: '#/components/schemas/get_applications_response' x-codeSamples: - lang: cURL source: "curl --location --request GET https://api.writer.com/v1/applications \\\n --header \"Authorization: Bearer \"" - lang: JavaScript source: "import Writer from 'writer-sdk';\n\nconst client = new Writer({\n apiKey: process.env['WRITER_API_KEY'], // This is the default and can be omitted\n});\n\nasync function main() {\n // Automatically fetches more pages as needed.\n for await (const applicationListResponse of client.applications.list()) {\n console.log(applicationListResponse.id);\n }\n}\n\nmain();" - lang: Python source: "import os\nfrom writerai import Writer\n\nclient = Writer(\n api_key=os.environ.get(\"WRITER_API_KEY\"), # This is the default and can be omitted\n)\npage = client.applications.list()\npage = page.data[0]\nprint(page.id)" /v1/applications/{application_id}: get: security: - bearerAuth: [] tags: - Generation API summary: Application details description: Retrieves detailed information for a specific no-code agent (formerly called no-code applications), including its configuration and current status. parameters: - name: application_id in: path required: true description: Unique identifier of the application to retrieve. schema: type: string responses: '200': description: Successfully retrieved application details. content: application/json: schema: $ref: '#/components/schemas/application_with_inputs' x-codeSamples: - lang: cURL source: "curl --location --request GET https://api.writer.com/v1/applications/{application_id} \\\n --header \"Authorization: Bearer \"" - lang: JavaScript source: "import Writer from 'writer-sdk';\n\nconst client = new Writer({\n apiKey: process.env['WRITER_API_KEY'], // This is the default and can be omitted\n});\n\nasync function main() {\n const application = await client.applications.retrieve('application_id');\n\n console.log(application.id);\n}\n\nmain();" - lang: Python source: "import os\nfrom writerai import Writer\n\nclient = Writer(\n api_key=os.environ.get(\"WRITER_API_KEY\"), # This is the default and can be omitted\n)\napplication = client.applications.retrieve(\n \"application_id\",\n)\nprint(application.id)" post: security: - bearerAuth: [] tags: - Generation API summary: Generate from application description: Generate content from an existing no-code agent (formerly called no-code applications) with inputs. operationId: generateContent parameters: - name: application_id in: path required: true schema: type: string format: uuid description: The unique identifier of a [no-code agent](/no-code/introduction) in AI Studio. requestBody: content: application/json: schema: $ref: '#/components/schemas/generate_application_request' required: true responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/generate_application_response' example: title: Alt text suggestion: A modern dining room with a minimalist design. text/event-stream: schema: type: array items: $ref: '#/components/schemas/generate_application_response_chunk' x-codeSamples: - lang: cURL source: "curl --location --request POST https://api.writer.com/v1/applications/{application_id} \\\n --header \"Authorization: Bearer \" \\\n --header \"Content-Type: application/json\" \\\n--data-raw '{\"inputs\":[{\"id\": \"Image ID\", \"value\": [\"12345\"]}]}'" - lang: JavaScript source: "import Writer from 'writer-sdk';\n\nconst client = new Writer({\n apiKey: process.env['WRITER_API_KEY'], // This is the default and can be omitted\n});\n\nasync function main() {\n const response = await client.applications.generateContent('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', {\n inputs: [\n { id: 'id', value: ['string', 'string', 'string'] },\n { id: 'id', value: ['string', 'string', 'string'] },\n { id: 'id', value: ['string', 'string', 'string'] },\n ],\n });\n\n console.log(response.suggestion);\n}\n\nmain();" - lang: Python source: "import os\nfrom writerai import Writer\n\nclient = Writer(\n # This is the default and can be omitted\n api_key=os.environ.get(\"WRITER_API_KEY\"),\n)\nresponse = client.applications.generate_content(\n application_id=\"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\",\n inputs=[{\n \"id\": \"id\",\n \"value\": [\"string\", \"string\", \"string\"],\n }, {\n \"id\": \"id\",\n \"value\": [\"string\", \"string\", \"string\"],\n }, {\n \"id\": \"id\",\n \"value\": [\"string\", \"string\", \"string\"],\n }],\n)\nprint(response.suggestion)" components: schemas: graph_tool: title: Graph tool required: - function - type type: object properties: type: type: string description: The type of tool. enum: - graph function: $ref: '#/components/schemas/graph_function' top_log_prob: title: top_log_prob description: An array of mappings for each token to its top log probabilities, showing detailed prediction probabilities. required: - token - logprob type: object properties: token: type: string logprob: type: number format: double bytes: type: array items: type: integer format: int32 string_tool_choice_options: title: string_tool_choice_options type: string enum: - none - auto - required generate_application_delta: title: generate_application_delta type: object properties: title: type: string description: The name of the output. content: type: string description: The main text output. stages: type: array nullable: true description: A list of stages that show the 'thinking process'. items: $ref: '#/components/schemas/generate_application_chunk_stage' minItems: 1 vision_tool: title: Vision tool required: - function - type type: object properties: type: type: string description: The type of tool. enum: - vision function: $ref: '#/components/schemas/vision_function' llm_data: title: llm_data required: - prompt - model type: object nullable: true properties: prompt: type: string description: The prompt processed by the model. model: type: string description: The model used by the tool. chat_completion_chunk: required: - id - object - created - choices - model type: object properties: id: type: string format: uuid description: 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: type: string description: The type of object returned, which is always `chat.completion.chunk` for streaming chat responses. enum: - chat.completion.chunk choices: type: array items: $ref: '#/components/schemas/chat_completion_streaming_choice' minItems: 1 description: An array of objects representing the different outcomes or results produced by the model based on the input provided. created: type: integer format: int64 description: 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: type: string description: Identifies the specific model used to generate the response. usage: $ref: '#/components/schemas/chat_completion_usage' system_fingerprint: type: string service_tier: type: string example: id: 3c90c3cc-0d44-4b50-8888-8dd25736052a choices: - finish_reason: stop message: content: Hello! How can I assist you today? role: user created: 1678587532773 model: palmyra-x5 application_input_text_options: title: Text description: Configuration options specific to text input fields. required: - max_fields - min_fields type: object properties: max_fields: type: integer format: int32 description: Maximum number of text fields allowed. min_fields: type: integer format: int32 description: Minimum number of text fields required. text_fragment: title: Text description: Represents a text content fragment within a chat message. required: - type - text type: object properties: type: type: string description: The type of content fragment. Must be `text` for text fragments. enum: - text text: type: string description: The actual text content of the message fragment. llm_tool: title: LLM tool required: - function - type type: object properties: type: type: string description: The type of tool. enum: - llm function: $ref: '#/components/schemas/llm_function' tool_function: title: tool_function description: A tool that uses a custom function. required: - name type: object properties: description: type: string description: Description of the function. name: type: string description: Name of the function. parameters: type: object additionalProperties: true description: The parameters of the function. application_input_file_options: title: File description: Configuration options specific to file upload input fields. required: - max_files - file_types - max_word_count - max_file_size_mb - upload_types type: object properties: max_files: type: integer format: int32 description: Maximum number of files that can be uploaded. file_types: type: array description: List of allowed file extensions. items: type: string max_word_count: type: integer format: int32 description: Maximum number of words allowed in text files. max_file_size_mb: type: integer format: int32 description: Maximum file size allowed in megabytes. upload_types: type: array description: List of allowed upload types for file inputs. items: $ref: '#/components/schemas/file_upload_type' file: title: file description: A file-based reference containing text snippets from uploaded documents in the Knowledge Graph. required: - text - fileId - score type: object properties: text: type: string description: The exact text snippet from the source document that was used to support the response. fileId: type: string description: The unique identifier of the file in your Writer account. score: type: number description: Internal score used during the retrieval process for ranking and selecting relevant snippets. page: type: integer format: int32 description: Page number where this snippet was found in the source document. cite: type: string description: Unique citation ID that appears in inline citations within the response text (null if not cited). models_response: required: - models type: object properties: models: type: array description: The [ID of the model](https://dev.writer.com/home/models) to use for processing the request. items: $ref: '#/components/schemas/model_info' example: models: - name: Palmyra X 003 Instruct id: palmyra-x-003-instruct - name: Palmyra Med id: palmyra-med - name: Palmyra Financial id: palmyra-fin - name: Palmyra X4 id: palmyra-x4 - name: Palmyra X5 id: palmyra-x5 - name: Palmyra Creative id: palmyra-creative streaming_data: required: - value type: object properties: value: type: string tool_call_streaming: title: tool_call type: object required: - index properties: index: type: integer format: int32 id: type: string type: type: string enum: - function function: $ref: '#/components/schemas/function' chat_message_role: type: string enum: - user - assistant - system sub_query: title: sub_query description: A sub-question generated to break down complex queries into more manageable parts, along with its answer and supporting sources. required: - query - answer - sources type: object nullable: true properties: query: type: string description: The subquery that was generated to help answer the main question. answer: type: string description: The answer to the subquery based on Knowledge Graph content. sources: type: array description: Array of source snippets that were used to answer this subquery. items: $ref: '#/components/schemas/source' logprobs_token: title: logprobs_token required: - token - logprob - top_logprobs type: object properties: token: type: string logprob: type: number format: double bytes: type: array items: type: integer format: int32 top_logprobs: type: array items: $ref: '#/components/schemas/top_log_prob' generate_application_request: title: generate_application_request required: - inputs type: object properties: inputs: type: array items: $ref: '#/components/schemas/generate_application_input' stream: type: boolean description: Indicates whether the response should be streamed. Currently only supported for research assistant applications. image_fragment: title: Image description: 'Represents an image content fragment within a chat message. Note: This content type is only supported with the Palmyra X5 model.' required: - type - image_url type: object properties: type: type: string description: The type of content fragment. Must be `image_url` for image fragments. enum: - image_url image_url: type: object description: The image URL object containing the location of the image. required: - url properties: url: type: string description: The URL pointing to the image file. Supports common image formats like JPEG, PNG, GIF, etc. function: title: function type: object required: - name - arguments properties: name: type: string arguments: type: string completion_token_details: title: completion_token_details required: - reasoning_tokens type: object properties: reasoning_tokens: type: integer format: int32 tool_call: title: tool_call type: object required: - id - type - function properties: index: type: integer format: int32 id: type: string type: type: string enum: - function function: $ref: '#/components/schemas/function' graph_function: title: graph_function description: A tool that uses Knowledge Graphs as context for responses. required: - graph_ids - subqueries type: object properties: description: type: string description: A description of the graph content. graph_ids: type: array description: An array of graph IDs to use in the tool. items: type: string format: uuid minItems: 1 subqueries: type: boolean description: Boolean to indicate whether to include subqueries in the response. query_config: $ref: '#/components/schemas/graph_query_config' description: Configuration options for Knowledge Graph queries, including search parameters and citation settings. application_status: title: application_status description: 'Current deployment status of the application. Note: currently only `deployed` applications are returned.' type: string enum: - deployed - draft web: title: web description: A web-based reference containing text snippets from online sources accessed during the query. required: - text - url - title - score type: object properties: text: type: string description: The exact text snippet from the web source that was used to support the response. url: type: string description: The URL of the web page where this content was found. format: uri title: type: string description: The title of the web page where this content was found. score: type: number description: Internal score used during the retrieval process for ranking and selecting relevant snippets. tool: type: object discriminator: propertyName: type mapping: function: '#/components/schemas/function_tool' graph: '#/components/schemas/graph_tool' llm: '#/components/schemas/llm_tool' translation: '#/components/schemas/translation_tool' vision: '#/components/schemas/vision_tool' web_search: '#/components/schemas/web_search_tool' oneOf: - $ref: '#/components/schemas/function_tool' - $ref: '#/components/schemas/graph_tool' - $ref: '#/components/schemas/llm_tool' - $ref: '#/components/schemas/translation_tool' - $ref: '#/components/schemas/vision_tool' - $ref: '#/components/schemas/web_search_tool' llm_function: title: LLM function description: A tool that uses another Writer model to generate a response. required: - description - model type: object properties: description: type: string description: A description of the model to use. model: type: string description: The model to use. graph_data: title: graph_data type: object properties: sources: type: array items: $ref: '#/components/schemas/source' status: $ref: '#/components/schemas/graph_stage_status' subqueries: type: array items: $ref: '#/components/schemas/sub_query' references: $ref: '#/components/schemas/references' get_applications_response: title: get_applications_response description: Response object containing a paginated list of applications. required: - data - has_more type: object properties: data: type: array description: List of application objects with their configurations. items: $ref: '#/components/schemas/application_with_inputs' first_id: type: string format: uuid description: UUID of the first application in the current page. last_id: type: string format: uuid description: UUID of the last application in the current page. has_more: type: boolean description: Indicates if there are more results available in subsequent pages. stream_options: title: stream_options description: Additional options for streaming. required: - include_usage type: object properties: include_usage: type: boolean description: Indicate whether to include usage information. completions_response: required: - choices type: object properties: choices: type: array items: $ref: '#/components/schemas/completions_choice' minItems: 1 description: A list of choices generated by the model, each containing the text of the completion and associated metadata such as log probabilities. model: type: string description: The identifier of the model that was used to generate the responses in the 'choices' array. example: choices: - text: Sure! Here's a search engine optimized article about... log_probs: null model: palmyra-x-003-instruct web_search_tool: title: Web search tool required: - function - type type: object properties: type: type: string description: The type of tool. enum: - web_search function: $ref: '#/components/schemas/web_search_function' chat_completion_streaming_choice: required: - index - finish_reason - delta type: object properties: index: type: integer format: int32 description: The index of the choice in the list of completions generated by the model. finish_reason: $ref: '#/components/schemas/chat_completion_finish_reason' description: Describes the condition under which the model ceased generating content. Common reasons include 'length' (reached the maximum output size), 'stop' (encountered a stop sequence), 'content_filter' (harmful content filtered out), or 'tool_calls' (encountered tool calls). nullable: true message: $ref: '#/components/schemas/chat_completion_response_message' delta: description: A chat completion delta generated by streamed model responses. $ref: '#/components/schemas/chat_completion_streaming_delta' logprobs: description: Log probability information for the choice. $ref: '#/components/schemas/logprobs' application_input_media_options: title: Media description: Configuration options specific to media upload input fields. required: - file_types - max_image_size_mb type: object properties: file_types: type: array description: List of allowed media file types. items: type: string max_image_size_mb: type: integer format: int32 description: Maximum media file size allowed in megabytes. chat_completion_choice: required: - index - finish_reason - message type: object properties: index: type: integer format: int32 description: The index of the choice in the list of completions generated by the model. finish_reason: $ref: '#/components/schemas/chat_completion_finish_reason' description: Describes the condition under which the model ceased generating content. Common reasons include 'length' (reached the maximum output size), 'stop' (encountered a stop sequence), 'content_filter' (harmful content filtered out), or 'tool_calls' (encountered tool calls). message: $ref: '#/components/schemas/chat_completion_response_message' logprobs: description: Log probability information for the choice. $ref: '#/components/schemas/logprobs' completions_choice: required: - text type: object properties: text: type: string description: The generated text output from the model, which forms the main content of the response. log_probs: $ref: '#/components/schemas/logprobs' vision_tool_request_file_variable: title: Vision Tool Request File Variable required: - name - file_id type: object properties: name: type: string description: 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: type: string description: '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.' file_upload_type: title: file_upload_type description: Type of file upload method supported by the application. type: string enum: - url - file_id chat_message_request_role: type: string description: 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`. enum: - user - assistant - system - tool application_input_type: title: application_input_type description: Type of input field determining its behavior and validation rules. type: string enum: - text - dropdown - file - media generate_application_input: title: generate_application_input required: - id - value type: object properties: id: type: string description: The unique identifier for the input field from the application. All input types from the No-code application are supported (i.e. Text input, Dropdown, File upload, Image input). The identifier should be the name of the input type. value: type: array items: type: string description: "The value for the input field. \n\nIf the input type is \"File upload\", you must pass the `file_id` of an uploaded file. You cannot pass a file object directly. See the [file upload endpoint](https://dev.writer.com/api-reference/file-api/upload-files) for instructions on uploading files or the [list files endpoint](https://dev.writer.com/api-reference/file-api/get-all-files) for how to see a list of uploaded files and their IDs." composite_content: title: composite_content description: '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.' oneOf: - $ref: '#/components/schemas/text_fragment' - $ref: '#/components/schemas/image_fragment' json_object_tool_choice: title: JSON object required: - value type: object properties: value: type: object description: 'A JSON object that specifies the tool to call. For example, `{"type": "function", "function": {"name": "get_current_weather"}}`' additionalProperties: true prompt_token_details: title: prompt_token_details required: - cached_tokens type: object properties: cached_tokens: type: integer format: int32 string_tool_choice: title: String required: - value type: object properties: value: $ref: '#/components/schemas/string_tool_choice_options' graph_stage_status: title: graph_stage_status type: string nullable: true enum: - processing - finished completions_request: required: - model - prompt type: object properties: model: type: string description: The [ID of the model](https://dev.writer.com/home/models) to use for generating text. Supports `palmyra-x5`, `palmyra-x4`, `palmyra-fin`, `palmyra-med`, `palmyra-creative`, and `palmyra-x-003-instruct`. prompt: type: string description: The input text that the model will process to generate a response. max_tokens: type: integer format: int64 description: The maximum number of tokens that the model can generate in the response. temperature: type: number format: double description: Controls the randomness of the model's outputs. Higher values lead to more random outputs, while lower values make the model more deterministic. top_p: type: number format: double description: Used to control the nucleus sampling, where only the most probable tokens with a cumulative probability of top_p are considered for sampling, providing a way to fine-tune the randomness of predictions. stop: oneOf: - type: array items: type: string - type: string description: Specifies stopping conditions for the model's output generation. This can be an array of strings or a single string that the model will look for as a signal to stop generating further tokens. best_of: type: integer format: int32 description: Specifies the number of completions to generate and return the best one. Useful for generating multiple outputs and choosing the best based on some criteria. random_seed: type: integer format: int32 description: A seed used to initialize the random number generator for the model, ensuring reproducibility of the output when the same inputs are provided. stream: type: boolean description: Determines whether the model's output should be streamed. If true, the output is generated and sent incrementally, which can be useful for real-time applications. example: model: palmyra-x-003-instruct prompt: Write me an SEO article about... max_tokens: 150 temperature: 0.7 top_p: 0.9 stop: - . best_of: 1 random_seed: 42 stream: false application_input_options: description: Type-specific configuration options for input fields. oneOf: - $ref: '#/components/schemas/application_input_dropdown_options' - $ref: '#/components/schemas/application_input_file_options' - $ref: '#/components/schemas/application_input_media_options' - $ref: '#/components/schemas/application_input_text_options' chat_request: required: - model - messages type: object properties: model: type: string description: The [ID of the model](https://dev.writer.com/home/models) to use for creating the chat completion. Supports `palmyra-x5`, `palmyra-x4`, `palmyra-fin`, `palmyra-med`, `palmyra-creative`, and `palmyra-x-003-instruct`. messages: type: array items: $ref: '#/components/schemas/chat_message' minItems: 1 description: 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. max_tokens: type: integer format: int32 description: 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: type: number format: double default: 1 description: 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: type: number format: double description: 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: type: integer format: int32 description: 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: oneOf: - type: array items: type: string - type: string description: 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. logprobs: type: boolean default: 'false' description: Specifies whether to return log probabilities of the output tokens. stream: type: boolean description: 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. default: false tools: type: array description: 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. items: $ref: '#/components/schemas/tool' minItems: 1 tool_choice: $ref: '#/components/schemas/tool_choice' stream_options: $ref: '#/components/schemas/stream_options' response_format: $ref: '#/components/schemas/response_format' example: model: palmyra-x5 messages: - content: Write a memo summarizing this earnings report. role: user generate_application_chunk_stage: title: generate_application_chunk_stage required: - id - content type: object properties: id: type: string description: The unique identifier for the stage. format: uuid content: type: string description: The text content of the stage. sources: type: array nullable: true description: A list of sources (URLs) that that stage used to process that particular step. items: type: string minItems: 1 chat_completion_response_message: required: - content - role - refusal type: object description: 'The chat completion message from the model. Note: this field is deprecated for streaming. Use `delta` instead.' properties: content: type: string description: 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: type: string enum: - assistant description: Specifies the role associated with the content. tool_calls: type: array items: $ref: '#/components/schemas/tool_call' minItems: 1 graph_data: $ref: '#/components/schemas/graph_data' llm_data: $ref: '#/components/schemas/llm_data' translation_data: $ref: '#/components/schemas/translation_data' web_search_data: $ref: '#/components/schemas/web_search_data' refusal: type: string nullable: true source: title: source description: A source snippet containing text and fileId from Knowledge Graph content. required: - file_id - snippet type: object nullable: true properties: file_id: type: string description: The unique identifier of the file in your Writer account. snippet: type: string description: The exact text snippet from the source document that was used to support the response. references: title: references description: Detailed source information organized by reference type, providing comprehensive metadata about the sources used to generate the response. type: object properties: files: type: array description: Array of file-based references from uploaded documents in the Knowledge Graph. items: $ref: '#/components/schemas/file' minItems: 1 web: type: array description: Array of web-based references from online sources accessed during the query. items: $ref: '#/components/schemas/web' minItems: 1 web_search_function: title: web_search_function description: A tool that uses web search to find information. required: - exclude_domains - include_domains type: object properties: exclude_domains: type: array description: An array of domains to exclude from the search results. items: type: string include_domains: type: array description: An array of domains to include in the search results. items: type: string vision_function: title: Vision function description: A tool that uses Palmyra Vision to analyze images and documents. Supports JPG, PNG, PDF, and TXT files up to 7MB each. required: - model - variables type: object properties: variables: type: array items: $ref: '#/components/schemas/vision_tool_request_file_variable' model: type: string description: The model to use for image analysis. enum: - palmyra-vision application_type: title: application_type description: The type of no-code application. type: string enum: - generation web_search_data: title: web_search_data required: - sources type: object properties: sources: type: array items: type: object properties: url: type: string raw_content: type: string function_tool: title: Function tool required: - function - type type: object properties: type: type: string description: The type of tool. enum: - function function: $ref: '#/components/schemas/tool_function' translation_function: title: Translation function description: A tool that uses Palmyra Translate to translate text. required: - model - formality - length_control - mask_profanity type: object properties: model: type: string description: The model to use for translation. enum: - palmyra-translate source_language_code: type: string description: 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: type: string description: 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: type: boolean description: 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: type: boolean description: 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: type: boolean description: 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. translation_data: title: translation_data required: - source_text - source_language_code - target_language_code type: object properties: source_text: type: string description: The text the tool translated. source_language_code: type: string description: The language code of the source text. target_language_code: type: string description: The language code of the target text. chat_response: required: - id - object - choices - created - model type: object properties: id: type: string format: uuid description: 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: type: string description: The type of object returned, which is always `chat.completion` for chat responses. enum: - chat.completion choices: type: array items: $ref: '#/components/schemas/chat_completion_choice' minItems: 1 description: An array of objects representing the different outcomes or results produced by the model based on the input provided. created: type: integer format: int64 description: 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: type: string description: Identifies the specific model used to generate the response. usage: $ref: '#/components/schemas/chat_completion_usage' system_fingerprint: type: string description: A string representing the backend configuration that the model runs with. service_tier: type: string description: The service tier used for processing the request. example: id: 3c90c3cc-0d44-4b50-8888-8dd25736052a choices: - finish_reason: stop message: content: Hello! How can I assist you today? role: user created: 1678587532773 model: palmyra-x5 tool_choice: description: '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.' oneOf: - $ref: '#/components/schemas/string_tool_choice' - $ref: '#/components/schemas/json_object_tool_choice' chat_completion_usage: title: chat_completion_usage description: Usage information for the chat completion response. Please note that at this time Knowledge Graph tool usage is not included in this object. required: - prompt_tokens - total_tokens - completion_tokens type: object properties: prompt_tokens: type: integer format: int32 total_tokens: type: integer format: int32 completion_tokens: type: integer format: int32 prompt_token_details: $ref: '#/components/schemas/prompt_token_details' completion_tokens_details: $ref: '#/components/schemas/completion_token_details' application_input_dropdown_options: title: Dropdown description: Configuration options specific to dropdown-type input fields. required: - list type: object properties: list: type: array description: List of available options in the dropdown menu. items: type: string application_input: title: application_input description: Configuration for an individual input field in the application. required: - name - input_type - required type: object properties: name: type: string description: Identifier for the input field. input_type: $ref: '#/components/schemas/application_input_type' description: type: string description: Human-readable description of the input field's purpose. required: type: boolean description: Indicates if this input field is mandatory. options: $ref: '#/components/schemas/application_input_options' translation_tool: title: Translation tool description: 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. required: - function - type type: object properties: type: type: string description: The type of tool. enum: - translation function: $ref: '#/components/schemas/translation_function' chat_completion_streaming_delta: type: object description: 'The chat completion message from the model. Note: this field is deprecated for streaming. Use `delta` instead.' properties: content: type: string description: 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: $ref: '#/components/schemas/chat_message_role' description: Specifies the role associated with the content, indicating whether the message is from the 'assistant' or another defined role, helping to contextualize the output within the interaction flow. tool_calls: type: array items: $ref: '#/components/schemas/tool_call_streaming' minItems: 1 graph_data: $ref: '#/components/schemas/graph_data' llm_data: $ref: '#/components/schemas/llm_data' translation_data: $ref: '#/components/schemas/translation_data' refusal: type: string nullable: true chat_message: title: chat_message required: - role type: object properties: content: description: 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). nullable: true oneOf: - type: string title: TextContent - type: array title: MixedContent items: $ref: '#/components/schemas/composite_content' minItems: 1 role: $ref: '#/components/schemas/chat_message_request_role' name: type: string description: An optional name for the message sender. Useful for identifying different users, personas, or tools in multi-participant conversations. nullable: true tool_call_id: type: string nullable: true tool_calls: type: array items: $ref: '#/components/schemas/tool_call' nullable: true minItems: 1 graph_data: $ref: '#/components/schemas/graph_data' nullable: true refusal: type: string nullable: true application_with_inputs: title: application_with_inputs description: Detailed application object including its input configuration. required: - id - name - type - status - inputs - created_at - updated_at type: object properties: id: type: string format: uuid description: Unique identifier for the application. name: type: string description: Display name of the application. type: $ref: '#/components/schemas/application_type' status: $ref: '#/components/schemas/application_status' inputs: type: array description: List of input configurations for the application. items: $ref: '#/components/schemas/application_input' created_at: type: string format: date-time description: Timestamp when the application was created. updated_at: type: string format: date-time description: Timestamp when the application was last updated. last_deployed_at: type: string format: date-time description: Timestamp when the application was last deployed. graph_query_config: title: graph_query_config description: Configuration options for Knowledge Graph queries. type: object properties: max_subquestions: type: integer format: int32 minimum: 1 maximum: 10 default: 6 description: '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: type: integer format: int32 minimum: 0 maximum: 100 default: 50 description: '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: type: number format: double minimum: 0 maximum: 1 default: 0 description: '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: type: integer format: int32 minimum: 1 maximum: 60 default: 30 description: '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: type: integer format: int32 minimum: 100 maximum: 8000 default: 4000 description: '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: type: number format: double minimum: 0 maximum: 1 default: 0.7 description: '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: type: number format: double minimum: 0 maximum: 1 default: 0.7 description: '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: type: boolean default: false description: 'Whether to include inline citations in the response, showing which Knowledge Graph sources were used. Default: false.' generate_application_response_chunk: title: generate_application_response_chunk required: - delta type: object properties: delta: $ref: '#/components/schemas/generate_application_delta' model_info: required: - name - id type: object properties: name: type: string description: The name of the particular LLM that you want to use. id: type: string description: The ID of the particular LLM that you want to use chat_completion_finish_reason: type: string enum: - stop - length - content_filter - tool_calls response_format: title: response_format description: '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.' required: - type type: object properties: type: type: string description: The type of response format to use. enum: - text - json_schema json_schema: type: object description: The JSON schema to use for the response format. generate_application_response: title: generate_application_response required: - suggestion type: object properties: title: type: string description: The name of the output field. suggestion: type: string description: The response from the model specified in the application. logprobs: type: object required: - content - refusal nullable: true properties: content: type: array items: $ref: '#/components/schemas/logprobs_token' nullable: true refusal: type: array items: $ref: '#/components/schemas/logprobs_token' nullable: true securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: Bearer authentication header of the form `Bearer `, where `` is your [Writer API key](https://dev.writer.com/api-reference/api-keys). x-mint: mcp: enabled: true