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

> Learn to customize the REST API response schema in QASummaryRestServer with 3 methods. Utilize request flags, the answer schema parameter, or subclassing for full control.

- Repository: [Pathway/llm-app](https://github.com/pathwaycom/llm-app)
- Tags: how-to-guide
- Published: 2026-03-07

---

**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:

```bash
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:

```json
{
  "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`](https://github.com/pathwaycom/llm-app/blob/main/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`](https://github.com/pathwaycom/llm-app/blob/main/app.yaml) or programmatically before instantiating the server. Here is a YAML configuration that defines a custom schema with three fields:

```yaml
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:

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

```

Alternatively, you can configure this programmatically in [`templates/question_answering_rag/app.py`](https://github.com/pathwaycom/llm-app/blob/main/templates/question_answering_rag/app.py) (around lines 35-37) before creating the server instance:

```python
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:

```python
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:

```python
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`](https://github.com/pathwaycom/llm-app/blob/main/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`](https://github.com/pathwaycom/llm-app/blob/main/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`](https://github.com/pathwaycom/llm-app/blob/main/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`](https://github.com/pathwaycom/llm-app/blob/main/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`](https://github.com/pathwaycom/llm-app/blob/main/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`](https://github.com/pathwaycom/llm-app/blob/main/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`](https://github.com/pathwaycom/llm-app/blob/main/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`](https://github.com/pathwaycom/llm-app/blob/main/templates/question_answering_rag/app.py) (lines 35-37). The default request flags are documented in [`templates/question_answering_rag/README.md`](https://github.com/pathwaycom/llm-app/blob/main/templates/question_answering_rag/README.md) (lines 390-393), and the FastAPI route implementations reside in the Pathway LLM xpack server module.