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 <token>\" \\\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 <token>\" \\\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 <token>\""
- 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 <token>\""
- 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 <token>\""
- 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 <token>\" \\\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:
choic
# --- truncated at 32 KB (68 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/writer/refs/heads/main/openapi/writer-generation-api-api-openapi.yml