Question

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your Writer API key.

Body

application/json

graph_ids

string<uuid>[]

required

The unique identifiers of the Knowledge Graphs to query.

Minimum array length: 1

question

string

required

The question to answer using the Knowledge Graph.

subqueries

boolean

default:false

Specify whether to include subqueries.

stream

boolean

default:false

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.

query_config

graph_query_config · object

Configuration options for Knowledge Graph queries, including search parameters and citation settings.

Show child attributes

query_config.max_subquestions

integer<int32>

default:6

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.

Required range: 1 <= x <= 10

query_config.search_weight

integer<int32>

default:50

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.

Required range: 0 <= x <= 100

query_config.grounding_level

number<double>

default:0

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.

Required range: 0 <= x <= 1

query_config.max_snippets

integer<int32>

default:30

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.

Required range: 1 <= x <= 60

query_config.max_tokens

integer<int32>

default:4000

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.

Required range: 100 <= x <= 8000

query_config.keyword_threshold

number<double>

default:0.7

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.

Required range: 0 <= x <= 1

query_config.semantic_threshold

number<double>

default:0.7

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.

Required range: 0 <= x <= 1

query_config.inline_citations

boolean

default:false

Whether to include inline citations in the response, showing which Knowledge Graph sources were used. Default: false.

Response

question

string

required

The question that was asked.

answer

string

required

The answer to the question.

sources

(source · object | null)[]

required

A source snippet containing text and fileId from Knowledge Graph content.

Show child attributes

sources.file_id

string

required

The unique identifier of the file in your Writer account.

sources.snippet

string

required

The exact text snippet from the source document that was used to support the response.

subqueries

(sub_query · object | null)[]

A sub-question generated to break down complex queries into more manageable parts, along with its answer and supporting sources.

Show child attributes

subqueries.query

string

required

The subquery that was generated to help answer the main question.

subqueries.answer

string

required

The answer to the subquery based on Knowledge Graph content.

subqueries.sources

(source · object | null)[]

required

Array of source snippets that were used to answer this subquery.

A source snippet containing text and fileId from Knowledge Graph content.

Show child attributes

subqueries.sources.file_id

string

required

The unique identifier of the file in your Writer account.

subqueries.sources.snippet

string

required

The exact text snippet from the source document that was used to support the response.

references

references · object

Detailed source information organized by reference type, providing comprehensive metadata about the sources used to generate the response.

Show child attributes

references.files

file · object[]

Array of file-based references from uploaded documents in the Knowledge Graph.

Minimum array length: 1

Show child attributes

references.files.text

string

required

The exact text snippet from the source document that was used to support the response.

references.files.fileId

string

required

The unique identifier of the file in your Writer account.

references.files.score

number

required

Internal score used during the retrieval process for ranking and selecting relevant snippets.

references.files.page

integer<int32>

Page number where this snippet was found in the source document.

references.files.cite

string

Unique citation ID that appears in inline citations within the response text (null if not cited).

references.web

web · object[]

Array of web-based references from online sources accessed during the query.

Minimum array length: 1

Show child attributes

references.web.text

string

required

The exact text snippet from the web source that was used to support the response.

references.web.url

string<uri>

required

The URL of the web page where this content was found.

references.web.title

string

required

The title of the web page where this content was found.

references.web.score

number

required

Internal score used during the retrieval process for ranking and selecting relevant snippets.

General usage

Applications API

Completions API

Files API

Knowledge Graphs API

Tools API

Translation API

Vision API

Migration guides

Authorizations

Body

Response