--- title: "Query Completion" method: POST path: "/query" --- # Query Completion `POST /query` Generate completion using relevant chunks as context. When graph_name is provided, the query will leverage the knowledge graph to enhance retrieval by finding relevant entities and their connected documents. Args: request: CompletionQueryRequest containing: - query: Query text - filters: Optional metadata filters - k: Number of chunks to use as context (default: 4) - min_score: Minimum similarity threshold (default: 0.0) - max_tokens: Maximum tokens in completion - temperature: Model temperature - use_reranking: Whether to use reranking - use_colpali: Whether to use ColPali-style embedding model - graph_name: Optional name of the graph to use for knowledge graph-enhanced retrieval - hop_depth: Number of relationship hops to traverse in the graph (1-3) - include_paths: Whether to include relationship paths in the response - prompt_overrides: Optional customizations for entity extraction, resolution, and query prompts - folder_name: Optional folder to scope the operation to - end_user_id: Optional end-user ID to scope the operation to - schema: Optional schema for structured output - chat_id: Optional chat conversation identifier for maintaining history auth: Authentication context Returns: CompletionResponse: Generated text completion or structured output ## Headers - `authorization` string ## Request body - CompletionQueryRequest — Request model for completion generation - `query` string, required - `filters` object, nullable - `k` integer - `min_score` number - `use_reranking` boolean, nullable - `use_colpali` boolean, nullable - `padding` integer — Number of additional chunks/pages to retrieve before and after matched chunks (ColPali only) - `graph_name` string, nullable — Name of the graph to use for knowledge graph-enhanced retrieval - `hop_depth` integer, nullable — Number of relationship hops to traverse in the graph - `include_paths` boolean, nullable — Whether to include relationship paths in the response - `folder_name` union — Optional folder scope for the operation. Accepts a single folder name or a list of folder names. - string - string[] - `end_user_id` string, nullable — Optional end-user scope for the operation - `max_tokens` integer, nullable - `temperature` number, nullable - `prompt_overrides` QueryPromptOverrides — Container for query-related prompt overrides. Use this class when customizing prompts for query operations, which may include customizations for entity extraction, entity resolution, and the query/response generation itself. This is the most feature-complete override class, supporting all customization types. Available customizations: - entity_extraction: Customize how entities are identified in text - entity_resolution: Customize how entity variants are grouped - query: Customize response generation style, format, and tone Each type has its own required placeholders. See the specific class documentation for details and examples. - `entity_extraction` EntityExtractionPromptOverride — Configuration for customizing entity extraction prompts. This allows you to override both the prompt template used for entity extraction and provide domain-specific examples of entities to be extracted. If only examples are provided (without a prompt_template), they will be incorporated into the default prompt. If only prompt_template is provided, it will be used with default examples (if any). Required placeholders: - {content}: Will be replaced with the text to analyze for entity extraction - {examples}: Will be replaced with formatted examples of entities to extract Example prompt template: ``` Extract entities from the following text. Look for entities similar to these examples: {examples} Text to analyze: {content} Extracted entities (in JSON format): ``` - `prompt_template` string, nullable — Custom prompt template, MUST include both {content} and {examples} placeholders. The {content} placeholder will be replaced with the text to analyze, and {examples} will be replaced with formatted examples. - `examples` EntityExtractionExample[], nullable — Examples of entities to extract, used to guide the LLM toward domain-specific entity types and patterns. - `label` string, required — The entity label (e.g., 'John Doe', 'Apple Inc.') - `type` string, required — The entity type (e.g., 'PERSON', 'ORGANIZATION', 'PRODUCT') - `properties` object, nullable — Optional properties of the entity (e.g., {'role': 'CEO', 'age': 42}) - `entity_resolution` EntityResolutionPromptOverride — Configuration for customizing entity resolution prompts. Entity resolution identifies and groups variant forms of the same entity. This override allows you to customize how this process works by providing a custom prompt template and/or domain-specific examples. If only examples are provided (without a prompt_template), they will be incorporated into the default prompt. If only prompt_template is provided, it will be used with default examples (if any). Required placeholders: - {entities_str}: Will be replaced with the extracted entities - {examples_json}: Will be replaced with JSON-formatted examples of entity resolution groups Example prompt template: ``` I have extracted the following entities: {entities_str} Below are examples of how different entity references can be grouped together: {examples_json} Group the above entities by resolving which mentions refer to the same entity. Return the results in JSON format. ``` - `prompt_template` string, nullable — Custom prompt template that MUST include both {entities_str} and {examples_json} placeholders. The {entities_str} placeholder will be replaced with the extracted entities, and {examples_json} will be replaced with JSON-formatted examples of entity resolution groups. - `examples` EntityResolutionExample[], nullable — Examples of entity resolution groups showing how variants of the same entity should be resolved to their canonical forms. This is particularly useful for domain-specific terminology, abbreviations, and naming conventions. - `canonical` string, required — The canonical (standard/preferred) form of the entity - `variants` string[], required — List of variant forms that should resolve to the canonical form - `query` QueryPromptOverride — Configuration for customizing query prompts. This allows you to customize how responses are generated during query operations. Query prompts guide the LLM on how to format and style responses, what tone to use, and how to incorporate retrieved information into the response. Required placeholders: - {question}: Will be replaced with the user's query - {context}: Will be replaced with the retrieved content/context Example prompt template: ``` Answer the following question based on the provided information. Question: {question} Context: {context} Answer: ``` - `prompt_template` string, nullable — Custom prompt template for generating responses to queries. REQUIRED PLACEHOLDERS: {question} and {context} must be included in the template. The {question} placeholder will be replaced with the user query, and {context} will be replaced with the retrieved content. Use this to control response style, format, and tone. - `system_prompt` string, nullable — Custom system prompt that replaces Morphik's default query agent instructions. Use this to fully control the assistant's behavior when generating responses. - `schema` union — Schema for structured output, can be a Pydantic model or JSON schema dict - unknown - object - `chat_id` string, nullable — Optional chat session ID for persisting conversation history - `stream_response` boolean, nullable — Whether to stream the response back in chunks - `llm_config` object, nullable — LiteLLM-compatible model configuration (e.g., model name, API key, base URL) - `inline_citations` boolean, nullable — Whether to include inline citations with filename and page number in the response ## Response `200` Successful Response - CompletionResponse — Response from completion generation - `completion` union, required - string - StructuredCompletion — Structured completion object for schema-based responses - `usage` object, required - `finish_reason` string, nullable - `sources` ChunkSource[] - `document_id` string, required - `chunk_number` integer, required - `score` number, nullable - `metadata` object, nullable ## Other responses - `422` — Validation Error ## Changes - **2025-11-05** `9ade02dd7b1d` — 2 info - added the new optional request property `inline_citations` - added the new optional request property `prompt_overrides/anyOf[subschema #1: QueryPromptOverrides]/query/anyOf[subschema #1: QueryPromptOverride]/system_prompt` [Change history](https://skmtc.dev/morphik-org/apis/fastapi/changes/query/post.md) --- [API](https://skmtc.dev/morphik-org/apis/fastapi.md) · [All operations](https://skmtc.dev/morphik-org/apis/fastapi/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/morphik-org/fastapi/revisions/9ade02dd7b1d/schema)