Writer Knowledge Graph API
Builds and queries graph-based retrieval indexes that connect enterprise data sources to agents for accurate, grounded responses.
OpenAPI Specification
openapi: 3.0.3
info:
title: API
version: '1.0'
servers:
- url: https://api.writer.com
security:
- bearerAuth: []
x-mint:
mcp:
enabled: true
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 \
--header "Authorization: Bearer <token>" \
--header "Content-Type: application/json" \
--data-raw '{"model":"palmyra-x5","messages":[{"content":"Write a
memo summarizing this earnings report.","role":"user"}]}'
- lang: JavaScript
source: |-
import Writer from 'writer-sdk';
const client = new Writer({
apiKey: process.env['WRITER_API_KEY'], // This is the default and can be omitted
});
async function main() {
const chat = await client.chat.chat({
messages: [{ content: 'Write a memo summarizing this earnings report.', role: 'user' }],
model: 'palmyra-x5',
});
console.log(chat.id);
}
main();
- lang: Python
source: |-
import os
from writerai import Writer
client = Writer(
# This is the default and can be omitted
api_key=os.environ.get("WRITER_API_KEY"),
)
chat = client.chat.chat(
messages=[{
"content": "Write a memo summarizing this earnings report.",
"role": "user",
}],
model="palmyra-x5",
)
print(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
\
--header "Authorization: Bearer <token>" \
--header "Content-Type: application/json" \
--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';
const client = new Writer({
apiKey: process.env['WRITER_API_KEY'], // This is the default and can be omitted
});
async function main() {
const completion = await client.completions.create({
model: 'palmyra-x-003-instruct',
prompt: 'Write me a short SEO article about camping gear',
});
console.log(completion.choices);
}
main();
- lang: Python
source: |-
import os
from writerai import Writer
client = Writer(
# This is the default and can be omitted
api_key=os.environ.get("WRITER_API_KEY"),
)
completion = client.completions.create(
model="palmyra-x-003-instruct",
prompt="Write me a short SEO article about camping gear",
)
print(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 \
--header "Authorization: Bearer <token>"
- lang: JavaScript
source: |-
import Writer from 'writer-sdk';
const client = new Writer({
apiKey: process.env['WRITER_API_KEY'], // This is the default and can be omitted
});
async function main() {
const model = await client.models.list();
console.log(model.models);
}
main();
- lang: Python
source: |-
import os
from writerai import Writer
client = Writer(
# This is the default and can be omitted
api_key=os.environ.get("WRITER_API_KEY"),
)
model = client.models.list()
print(model.models)
/v1/graphs:
get:
security:
- bearerAuth: []
summary: List graphs
description: Retrieve a list of Knowledge Graphs.
tags:
- KG API
operationId: findGraphsWithFileStatus
parameters:
- name: order
in: query
required: false
schema:
type: string
default: desc
enum:
- asc
- desc
description: >-
Specifies the order of the results. Valid values are asc for
ascending and desc for descending.
- name: before
in: query
required: false
schema:
type: string
format: uuid
description: >-
The ID of the first object in the previous page. This parameter
instructs the API to return the previous page of results.
- name: after
in: query
required: false
schema:
type: string
format: uuid
description: >-
The ID of the last object in the previous page. This parameter
instructs the API to return the next page of results.
- name: limit
in: query
required: false
schema:
type: integer
format: int32
default: 50
description: >-
Specifies the maximum number of objects returned in a page. The
default value is 50. The minimum value is 1, and the maximum value
is 100.
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/graphs_response'
example:
data:
- id: 50daa3d0-e7d9-44a4-be42-b53e2379ebf7
created_at: '2024-07-10T15:03:48.785843Z'
name: Example Knowledge Graph
description: Example description
file_status:
in_progress: 0
completed: 0
failed: 0
total: 11
type: manual
urls: null
- id: e7392337-1c4e-4bc9-aaf5-b719bf1e938a
created_at: '2024-07-10T15:03:39.881370Z'
name: Another example Knowledge Graph
description: Another example description
file_status:
in_progress: 0
completed: 0
failed: 0
total: 0
type: web
urls:
- url: https://docs.example.com
status:
status: success
error_type: null
type: single_page
first_id: 50daa3d0-e7d9-44a4-be42-b53e2379ebf7
last_id: e7392337-1c4e-4bc9-aaf5-b719bf1e938a
has_more: true
x-codeSamples:
- lang: cURL
source: |-
curl --location --request GET https://api.writer.com/v1/graphs \
--header "Authorization: Bearer <token>"
- lang: JavaScript
source: |-
import Writer from 'writer-sdk';
const client = new Writer({
apiKey: process.env['WRITER_API_KEY'], // This is the default and can be omitted
});
async function main() {
// Automatically fetches more pages as needed.
for await (const graph of client.graphs.list()) {
console.log(graph.id);
}
}
main();
- lang: Python
source: |-
import os
from writerai import Writer
client = Writer(
# This is the default and can be omitted
api_key=os.environ.get("WRITER_API_KEY"),
)
page = client.graphs.list()
page = page.data[0]
print(page.id)
post:
security:
- bearerAuth: []
summary: Create graph
description: Create a new Knowledge Graph.
tags:
- KG API
operationId: createGraph
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/graph_request'
required: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/graph_response'
example:
id: 50daa3d0-e7d9-44a4-be42-b53e2379ebf7
created_at: '2024-07-10T13:34:28.301201Z'
name: Example Knowledge Graph
description: Example description
urls: null
x-codeSamples:
- lang: cURL
source: |-
curl --location --request POST https://api.writer.com/v1/graphs \
--header "Authorization: Bearer <token>" \
--header "Content-Type: application/json" \
--data-raw '{"name":"string"}'
- lang: JavaScript
source: |-
import Writer from 'writer-sdk';
const client = new Writer({
apiKey: process.env['WRITER_API_KEY'], // This is the default and can be omitted
});
async function main() {
const graph = await client.graphs.create({ name: 'name' });
console.log(graph.id);
}
main();
- lang: Python
source: |-
import os
from writerai import Writer
client = Writer(
# This is the default and can be omitted
api_key=os.environ.get("WRITER_API_KEY"),
)
graph = client.graphs.create(
name="name",
)
print(graph.id)
/v1/graphs/question:
post:
security:
- bearerAuth: []
summary: Question
description: Ask a question to specified Knowledge Graphs.
tags:
- KG API
operationId: question
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/question_request'
required: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/question_response'
example:
question: What is the generic name for the drug Bavencio?
answer: avelumab
sources:
- file_id: '1234'
snippet: Bavencio is the brand name for avelumab.
text/event-stream:
schema:
$ref: '#/components/schemas/question_response_chunk'
example:
data:
- question: What is the generic name for the drug Bavencio?
answer: avelumab
sources:
- file_id: '1234'
snippet: Bavencio is the brand name for avelumab.
x-codeSamples:
- lang: cURL
source: >-
curl --location --request POST
https://api.writer.com/v1/graphs/question \
--header "Authorization: Bearer <token>" \
--header "Content-Type: application/json" \
--data-raw
'{"graph_ids":["182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"],"question":"What
is the generic name for the drug Bavencio?"}'
- lang: JavaScript
source: |-
import Writer from 'writer-sdk';
const client = new Writer({
apiKey: process.env['WRITER_API_KEY'], // This is the default and can be omitted
});
async function main() {
const question = await client.graphs.question({
graph_ids: ['182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e'],
question: 'What is the generic name for the drug Bavencio?'
});
console.log(question.answer);
}
main();
- lang: Python
source: |-
import os
from writerai import Writer
client = Writer(
# This is the default and can be omitted
api_key=os.environ.get("WRITER_API_KEY"),
)
question = client.graphs.question(
graph_ids=["182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"],
question="What is the generic name for the drug Bavencio?"
)
print(question.answer)
/v1/graphs/{graph_id}:
get:
security:
- bearerAuth: []
summary: Retrieve graph
description: Retrieve a Knowledge Graph.
tags:
- KG API
operationId: findGraphWithFileStatus
parameters:
- name: graph_id
in: path
required: true
schema:
type: string
format: uuid
description: The unique identifier of the Knowledge Graph.
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/graph'
example:
id: 50daa3d0-e7d9-44a4-be42-b53e2379ebf7
created_at: '2024-07-10T15:03:48.785843Z'
name: Example Knowledge Graph
description: Example description
file_status:
in_progress: 0
completed: 0
failed: 0
total: 0
type: web
urls:
- url: https://example.com/docs
status:
status: success
error_type: null
type: sub_pages
- url: https://docs.example.com
status:
status: error
error_type: invalid_url
type: single_page
x-codeSamples:
- lang: cURL
source: >-
curl --location --request GET
https://api.writer.com/v1/graphs/{graph_id} \
--header "Authorization: Bearer <token>"
- lang: JavaScript
source: |-
import Writer from 'writer-sdk';
const client = new Writer({
apiKey: process.env['WRITER_API_KEY'], // This is the default and can be omitted
});
async function main() {
const graph = await client.graphs.retrieve('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e');
console.log(graph.id);
}
main();
- lang: Python
source: |-
import os
from writerai import Writer
client = Writer(
# This is the default and can be omitted
api_key=os.environ.get("WRITER_API_KEY"),
)
graph = client.graphs.retrieve(
"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)
print(graph.id)
put:
security:
- bearerAuth: []
summary: Update graph
description: Update the name and description of a Knowledge Graph.
tags:
- KG API
operationId: updateGraph
parameters:
- name: graph_id
in: path
required: true
schema:
type: string
format: uuid
description: The unique identifier of the Knowledge Graph.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/update_graph_request'
required: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/graph_response'
example:
id: 50daa3d0-e7d9-44a4-be42-b53e2379ebf7
created_at: '2024-07-10T15:03:48.785843Z'
name: Updated graph name
description: Updated graph description
urls:
- url: https://example.com/docs
status:
status: success
error_type: null
type: sub_pages
x-codeSamples:
- lang: cURL
source: >-
curl --location --request PUT
https://api.writer.com/v1/graphs/{graph_id} \
--header "Authorization: Bearer <token>" \
--header "Content-Type: application/json" \
--data-raw '{"name":"string", "description":"string",
"urls":[{"url":"https://example.com/docs", "type":"sub_pages",
"exclude_urls":["https://example.com/docs/private"]}]}'
- lang: JavaScript
source: |-
import Writer from 'writer-sdk';
const client = new Writer({
apiKey: process.env['WRITER_API_KEY'], // This is the default and can be omitted
});
async function main() {
const graph = await client.graphs.update('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
{ name: 'name', description: 'description' }
);
console.log(graph.id);
}
main();
- lang: Python
source: |-
import os
from writerai import Writer
client = Writer(
# This is the default and can be omitted
api_key=os.environ.get("WRITER_API_KEY"),
)
graph = client.graphs.update(
graph_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
name="name",
description="description",
)
print(graph.id)
delete:
security:
- bearerAuth: []
summary: Delete graph
description: Delete a Knowledge Graph.
tags:
- KG API
operationId: deleteGraph
parameters:
- name: graph_id
in: path
required: true
schema:
type: string
format: uuid
description: The unique identifier of the Knowledge Graph.
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/delete_graph_response'
example:
id: e7392337-1c4e-4bc9-aaf5-b719bf1e938a
deleted: true
x-codeSamples:
- lang: cURL
source: >-
curl --location --request DELETE
https://api.writer.com/v1/graphs/{graph_id} \
--header "Authorization: Bearer <token>"
- lang: JavaScript
source: |-
import Writer from 'writer-sdk';
const client = new Writer({
apiKey: process.env['WRITER_API_KEY'], // This is the default and can be omitted
});
async function main() {
const graph = await client.graphs.delete('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e');
console.log(graph.id);
}
main();
- lang: Python
source: |-
import os
from writerai import Writer
client = Writer(
# This is the default and can be omitted
api_key=os.environ.get("WRITER_API_KEY"),
)
graph = client.graphs.delete(
"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)
print(graph.id)
/v1/graphs/{graph_id}/file:
post:
security:
- bearerAuth: []
summary: Add file to graph
description: Add a file to a Knowledge Graph.
tags:
- KG API
operationId: addFileToGraph
parameters:
- name: graph_id
in: path
required: true
schema:
type: string
format: uuid
description: The unique identifier of the Knowledge Graph.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/graph_file_request'
required: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/file_response'
example:
id: 7c36a365-392f-43ba-840d-8f3103b42572
created_at: '2024-07-10T15:16:10.684826Z'
name: example.pdf
graph_id:
- 50daa3d0-e7d9-44a4-be42-b53e2379ebf7
x-codeSamples:
- lang: cURL
source: >-
curl --location --request POST
https://api.writer.com/v1/graphs/{graph_id}/file \
--header "Authorization: Bearer <token>" \
--header "Content-Type: application/json" \
--data-raw '{"file_id":"string"}'
- lang: JavaScript
source: |-
import Writer from 'writer-sdk';
const client = new Writer({
apiKey: process.env['WRITER_API_KEY'], // This is the default and can be omitted
});
async function main() {
const file = await client.graphs.addFileToGraph('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', {
file_id: 'file_id',
});
console.log(file.id);
}
main();
- lang: Python
source: |-
import os
from writerai import Writer
client = Writer(
# This is the default and can be omitted
api_key=os.environ.get("WRITER_API_KEY"),
)
file = client.graphs.add_file_to_graph(
graph_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
file_id="file_id",
)
print(file.id)
/v1/graphs/{graph_id}/file/{file_id}:
delete:
security:
- bearerAuth: []
summary: Remove file from graph
description: Remove a file from a Knowledge Graph.
tags:
- KG API
operationId: removeFileFromGraph
parameters:
- name: graph_id
in: path
required: true
schema:
type: string
format: uuid
description: >-
The unique identifier of the Knowledge Graph to which the files
belong.
- name: file_id
in: path
required: true
schema:
type: string
description: The unique identifier of the file.
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/delete_file_response'
example:
id: 7c36a365-392f-43ba-840d-8f3103b42572
deleted: true
x-codeSamples:
- lang: cURL
source: >-
curl --location --request DELETE
https://api.writer.com/v1/graphs/{graph_id}/file/{file_id} \
--header "Authorization: Bearer <token>"
- lang: JavaScript
source: |-
import Writer from 'writer-sdk';
const client = new Writer({
apiKey: process.env['WRITER_API_KEY'], // This is the default and can be omitted
});
async function main() {
const response = await client.graphs.removeFileFromGraph('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', 'file_id');
console.log(response.id);
}
main();
- lang: Python
source: |-
import os
from writerai import Writer
client = Writer(
# This is the default and can be omitted
api_key=os.environ.get("WRITER_API_KEY"),
)
response = client.graphs.remove_file_from_graph(
file_id="file_id",
graph_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)
print(response.id)
/v1/files/{file_id}:
get:
security:
- bearerAuth: []
summary: Retrieve file
description: >-
Retrieve detailed information about a specific file, including its
metadata, status, and associated graphs.
tags:
- File API
operationId: gatewayGetFile
parameters:
- name: file_id
in: path
required: true
schema:
type: string
description: The unique identifier of the file.
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/file_response'
example:
id: 7c36a365-392f-43ba-840d-8f3103b42572
created_at: '2024-07-10T13:34:28.301201Z'
name: example.pdf
graph_ids:
- 704ffd94-de04-4de2-9f8b-f9fc04831edd
status: completed
x-codeSamples:
- lang: cURL
source: >-
curl --location --request GET
https://api.writer.com/v1/files/{file_id} \
--header "Authorization: Bearer <token>"
- lang: JavaScript
source: |-
import Writer from 'writer-sdk';
const client = new Writer({
apiKey: process.env['WRITER_API_KEY'], // This is the default and can be omitted
});
async function main() {
const file = await client.files.retrieve('file_id');
console.log(file.id);
}
main();
- lang: Python
source: |-
import os
from writerai import Writer
client = Writer(
# This is the default and can be omitted
api_key=os.environ.get("WRITER_API_KEY"),
)
file = client.files.retrieve(
"file_id",
)
print(file.id)
delete:
security:
- bearerAuth: []
summary: Delete file
description: Permanently delete a file from the system. This action cannot be undone.
tags:
- F
# --- truncated at 32 KB (167 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/writer/refs/heads/main/openapi/writer-openapi.yml