How to Customize the REST API Response Schema in QASummaryRestServer: 3 Methods Explained

You can customize the REST API response schema in QASummaryRestServer using request-level flags for quick tweaks, the answer_schema parameter in SummaryQuestionAnswerer for structural changes, or by subclassing the server for complete control over the FastAPI response models.

QASummaryRestServer is a FastAPI-based server included in Pathway's LLM xpack that exposes endpoints like /v2/answer and /v2/summarize. If you need to customize the REST API response schema in QASummaryRestServer to include additional metadata, change field names, or wrap responses in custom envelopes, the pathwaycom/llm-app repository provides three distinct customization levels ranging from simple request flags to full server subclassing.

Method 1: Use Request-Level Flags for Quick Customization

The fastest way to alter the response structure is to include optional flags in your JSON request payload. The server recognizes these parameters and adjusts the returned fields dynamically without requiring code changes.

Enabling Context Documents with return_context_docs

Set return_context_docs: true in your request body to include a context_documents array containing the source chunks used to generate the answer.

Switching Response Length with response_type

Use response_type: "long" to receive a detailed paragraph instead of the default concise one-sentence reply. The default schema supports both formats, so this flag simply populates the answer field with different content structures.

Here is a complete example using curl to trigger both flags:

curl -X POST http://localhost:8000/v2/answer \
  -H "Content-Type: application/json" \
  -d '{
        "prompt": "What are the GDPR articles relevant for clinical trials?",
        "response_type": "long",
        "return_context_docs": true
      }'

The server returns:

{
  "answer": "The GDPR articles … (long paragraph)",
  "context_documents": [
    {"path": ".../gdpr.pdf", "text": "..."},
    {"path": ".../clinical_trials.docx", "text": "..."}
  ]
}

These flags are documented in templates/question_answering_rag/README.md around lines 390-393, and the server implementation that parses them resides in the base QASummaryRestServer class.

Method 2: Configure the answer_schema in SummaryQuestionAnswerer

For structural changes that persist across all requests—such as adding a confidence score or renaming the answer field to response—you must configure the underlying SummaryQuestionAnswerer instance. This approach modifies the Pydantic model that the server uses to serialize responses.

You typically define this configuration in app.yaml or programmatically before instantiating the server. Here is a YAML configuration that defines a custom schema with three fields:

question_answerer: !pw.xpacks.llm.question_answering.SummaryQuestionAnswerer
  model: !pw.xpacks.llm.llms.OpenAIChat
    model: "gpt-4.1-mini"
  answer_schema:
    answer: "str"
    confidence: "float"
    sources:
      type: "list"
      items: "str"

When the server processes a query, it now returns JSON matching your custom schema:

{
  "answer": " … ",
  "confidence": 0.92,
  "sources": ["doc1.pdf", "doc2.txt"]
}

Alternatively, you can configure this programmatically in templates/question_answering_rag/app.py (around lines 35-37) before creating the server instance:

from pathway.xpacks.llm.question_answering import SummaryQuestionAnswerer

qa = SummaryQuestionAnswerer(
    model=...,
    answer_schema={
        "answer": "str",
        "confidence": "float",
        "source_ids": "list[str]",
    },
)

server = QASummaryRestServer(host, port, qa)

Method 3: Subclass QASummaryRestServer for Full Control

When you need to completely rewrite the JSON envelope—such as wrapping every response in a top-level result key or adding pagination metadata—you must subclass QASummaryRestServer and override its internal response builders. This method gives you direct access to the FastAPI route definitions while preserving Pathway's streaming and caching infrastructure.

Overriding the Response Builder

Override _build_answer_response to change how the answer dictionary is constructed before serialization:

from pathway.xpacks.llm.servers import QASummaryRestServer

class CustomQAServer(QASummaryRestServer):
    def _build_answer_response(self, answer, **extra):
        # Override the internal helper that builds the JSON payload.

        return {
            "status": "ok",
            "result": answer,               # <-- custom wrapper

            "metadata": extra,              # any extra fields you want

        }

# In your App.run():

server = CustomQAServer(self.host, self.port, self.question_answerer)

Wrapping the Endpoint Directly

Alternatively, override _answer_endpoint to intercept the entire response flow:

from pathway.xpacks.llm.servers import QASummaryRestServer

class MyRestServer(QASummaryRestServer):
    def _answer_endpoint(self, request):
        # delegate to the base implementation

        raw = super()._answer_endpoint(request)
        # wrap the answer in a custom envelope

        return {
            "status": "success",
            "payload": raw,
            "request_id": request.id,
        }

# In your main app

from custom_server import MyRestServer
server = MyRestServer(self.host, self.port, self.question_answerer)

Subclassing also allows you to register additional routes using self.app.get or self.app.post before calling the server's run() method.

Key Implementation Files

Understanding where these components live in the pathwaycom/llm-app repository helps you navigate the codebase effectively:

• templates/question_answering_rag/app.py – The entry point where QASummaryRestServer is instantiated with a SummaryQuestionAnswerer instance (see lines 35-37).

• templates/question_answering_rag/README.md – Documents the default endpoints and the optional response_type and return_context_docs flags (see lines 390-393).

• app.yaml – The configuration file where you can define custom answer_schema structures for the SummaryQuestionAnswerer without writing Python code.

• Your custom subclass file (e.g., custom_server.py) – Where you implement CustomQAServer or MyRestServer to override FastAPI response models.

Summary

• Request-level flags (return_context_docs, response_type) provide the fastest way to customize the REST API response schema in QASummaryRestServer without code changes.

• answer_schema configuration in SummaryQuestionAnswerer allows you to define custom Pydantic fields like confidence or sources via app.yaml or Python constructors.

• Subclassing QASummaryRestServer gives you total control over the FastAPI response envelope, enabling you to wrap answers in custom metadata or add entirely new endpoints.

Frequently Asked Questions

What is the fastest way to customize responses without modifying code?

Send request-level flags in your JSON payload. Set return_context_docs: true to include source documents or response_type: "long" to receive detailed paragraphs instead of concise answers. These flags work immediately with the default server configuration defined in templates/question_answering_rag/README.md.

How do I add custom fields like confidence scores to the API response?

Configure the answer_schema parameter when constructing SummaryQuestionAnswerer. In app.yaml, define your schema with fields like confidence: "float" or sources: "list[str]". This modifies the underlying Pydantic model that QASummaryRestServer uses to serialize responses, automatically including your custom fields in every JSON payload.

Can I add entirely new endpoints to QASummaryRestServer?

Yes, by subclassing QASummaryRestServer and registering new routes via self.app.get() or self.app.post() before calling run(). You can also override existing methods like _answer_endpoint to change how current endpoints behave while reusing Pathway's streaming infrastructure.

Where is the response schema defined in the source code?

The response schema is defined in the SummaryQuestionAnswerer class and consumed by QASummaryRestServer in templates/question_answering_rag/app.py (lines 35-37). The default request flags are documented in templates/question_answering_rag/README.md (lines 390-393), and the FastAPI route implementations reside in the Pathway LLM xpack server module.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}