---
title: "Query Completion"
method: POST
path: "/query"
---

# Query Completion

`POST /query`

Generate completion using relevant chunks as context.

## Headers

- `authorization` string, nullable

## Request body

- CompletionQueryRequest — Request model for completion generation
  - `query` string, nullable — Natural-language query used to retrieve relevant chunks or documents.
  - `query_image` string, nullable — Base64-encoded image to use as query for Morphik multimodal retrieval. Requires use_colpali=True. Mutually exclusive with 'query'.
  - `filters` object, nullable — Metadata filters supporting logical operators ($and/$or/$not/$nor) and field predicates ($eq/$ne/$gt/$gte/$lt/$lte/$in/$nin/$exists/$type/$regex/$contains).
  - `k` integer — Maximum number of chunks or documents to return.
  - `min_score` number — Minimum similarity score a result must meet before it is returned.
  - `use_reranking` boolean, nullable — When provided, overrides the workspace reranking configuration for this request.
  - `use_colpali` boolean, nullable — When provided, uses Morphik's finetuned ColPali style embeddings (recommended to be True for high quality retrieval).
  - `output_format` 'base64' | 'url' | 'text' — Output format for image chunks in retrieval results.
  - `padding` integer — Number of additional chunks/pages to retrieve before and after matched chunks (ColPali only)
  - `folder_name` union — Optional folder scope. Accepts a folder PATH (e.g., '/Company/Reports') or list of paths.
    - string
    - string[]
  - `folder_depth` integer, nullable — Folder scope depth. 0 or None = exact folder only, -1 = include all descendants, n > 0 = include descendants up to n levels deeper.
  - `end_user_id` string, nullable — Optional end-user scope for the operation
  - `max_tokens` integer, nullable — Maximum number of tokens allowed in the generated completion.
  - `temperature` number, nullable — Sampling temperature passed to the completion model (None uses provider default).
  - `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

---

[API](https://skmtc.net/morphik-org/apis/fastapi.md) · [All operations](https://skmtc.net/morphik-org/apis/fastapi/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/morphik-org/fastapi/versions/2d9291c3821d/schema)