docs: enhance send-chat-message docs to also show ChatFullResponse

[ciaransweet]

Description

When developing integrations with the new send-chat-message endpoint, I noticed that currently, the Swagger docs only display the stream example ("string") whereas it can return a StreamingResponse or a ChatFullResponse when stream=false - It'd be useful to have this model in the docs for clarity.

I updated the responses field in the method definition to include both examples, for stream and not.

How Has This Been Tested?

• Fresh clone of repo
• Stood up services following CONTRIBUTING_VSCODE.md
• Found: <api-url>/docs#/public/handle_send_chat_message
• Identified missing examples:

• Made changes to method definition
• Observed updated examples:

Additional Options

• [Optional] Override Linear Check

[greptile-apps]

Greptile Summary

This PR enhances the Swagger/OpenAPI documentation for the /send-chat-message endpoint by adding explicit response models for both streaming and non-streaming modes. Previously, the docs only showed the streaming response (text/event-stream) example. Now they include both the streaming response and the ChatFullResponse schema for when stream=false, providing clearer API guidance for developers integrating with the endpoint.

The changes are purely documentation-focused:

• Added response_class=StreamingResponse parameter to indicate the default response type
• Added comprehensive responses parameter to the @router.post() decorator that documents both response modes
• Included schema reference to ChatFullResponse.model_json_schema() for non-streaming responses
• Clarified in the description when each response type is returned based on the stream parameter

Confidence Score: 5/5

• This PR is safe to merge with no concerns - it's a pure documentation improvement with zero impact on runtime behavior.
• This is a documentation-only change with zero risk. The modification adds OpenAPI/Swagger response documentation to clarify the two possible response modes (streaming vs non-streaming). The ChatFullResponse model is already fully imported and properly defined. The changes align with FastAPI best practices for documenting conditional response types and provide valuable clarity for API consumers without introducing any functional changes to the endpoint logic.
• No files require special attention - the change is straightforward and well-scoped.

Important Files Changed

Filename	Overview
backend/onyx/server/query_and_chat/chat_backend.py	Enhanced /send-chat-message OpenAPI documentation by adding explicit response models for both streaming and non-streaming modes. The endpoint now shows ChatFullResponse schema in Swagger docs when stream=false, improving API clarity for integrators. Changes are purely documentation-focused with no logic modifications.

Sequence Diagram

sequenceDiagram
    participant Client
    participant Endpoint as /send-chat-message
    participant Logic as Message Processing
    participant Response
    
    Note over Client,Response: stream=true (default)
    Client->>Endpoint: POST with stream=true
    Endpoint->>Logic: Handle stream mode
    Logic-->>Endpoint: Packet stream
    Endpoint-->>Response: StreamingResponse (text/event-stream)
    Response-->>Client: SSE stream of packets
    
    Note over Client,Response: stream=false
    Client->>Endpoint: POST with stream=false
    Endpoint->>Logic: Handle non-stream mode
    Logic-->>Endpoint: Collect all packets
    Endpoint-->>Response: ChatFullResponse (application/json)
    Response-->>Client: Complete JSON response

Loading

[greptile-apps]

Greptile's behavior is changing!

From now on, if a review finishes with no comments, we will not post an additional "statistics" comment to confirm that our review found nothing to comment on. However, you can confirm that we reviewed your changes in the status check section.

_{This feature can be toggled off in your Code Review Settings by deselecting "Create a status check for each PR".}

[cubic-dev-ai]

1 issue found across 1 file

Prompt for AI agents (all issues)

Check if these issues are valid — if so, understand the root cause of each and fix them.


<file name="backend/onyx/server/query_and_chat/chat_backend.py">

<violation number="1" location="backend/onyx/server/query_and_chat/chat_backend.py:536">
P2: Non-streaming chat response is wrapped in StreamingResponse due to response_class override, breaking JSON ChatFullResponse for stream=false</violation>
</file>

---

Since this is your first cubic review, here's how it works:

• cubic automatically reviews your code and comments on bugs and improvements
• Teach cubic by replying to its comments. cubic learns from your replies and gets better over time
• Ask questions if you need clarification on any suggestion

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[ciaransweet]

@yuhongsun96 @wenxi-onyx is there anything I can do for this?

[jmelahman]

@yuhongsun96 @wenxi-onyx is there anything I can do for this?

The test failures seem real and being introduced by this change. You can reproduce them locally by running,

$ uv run --with onyx-devtools ods openapi all

which is a shorthand for,

$ source .venv/bin/activate
$ PYTHONPATH=backend python backend/scripts/onyx_openapi_schema.py --filename backend/generated/openapi.json
$ openapi-generator-cli generate -i backend/generated/openapi.json -g python -o backend/generated/onyx_openapi_client --package-name onyx_openapi_client --skip-validate-spec --openapi-normalizer "SIMPLIFY_ONEOF_ANYOF=true,SET_OAS3_NULLABLE=true"

[ciaransweet]

@yuhongsun96 @wenxi-onyx is there anything I can do for this?

The test failures seem real and being introduced by this change. You can reproduce them locally by running,

$ uv run --with onyx-devtools ods openapi all

which is a shorthand for,

$ source .venv/bin/activate
$ PYTHONPATH=backend python backend/scripts/onyx_openapi_schema.py --filename backend/generated/openapi.json
$ openapi-generator-cli generate -i backend/generated/openapi.json -g python -o backend/generated/onyx_openapi_client --package-name onyx_openapi_client --skip-validate-spec --openapi-normalizer "SIMPLIFY_ONEOF_ANYOF=true,SET_OAS3_NULLABLE=true"

Could you point out which test case(s) are failing?

Struggling to read the output of that command.

[ciaransweet]

For what it's worth, the command fails for me on main at d8068f0a682b5b0134d98d65541162e161c5c998...

INFO Generating OpenAPI schema and Python client  
INFO Schema output: /Users/ciaran/dev/onyx/backend/generated/openapi.json 
INFO Client output: /Users/ciaran/dev/onyx/backend/generated/onyx_openapi_client 
Traceback (most recent call last):
  File "<stdin>", line 236, in <module>
  File "<stdin>", line 225, in main
  File "<stdin>", line 36, in generate_schema
  File "/Users/ciaran/dev/onyx/backend/onyx/main.py", line 52, in <module>
    from onyx.server.auth_check import check_router_auth
  File "/Users/ciaran/dev/onyx/backend/onyx/server/auth_check.py", line 14, in <module>
    from onyx.server.onyx_api.ingestion import api_key_dep
  File "/Users/ciaran/dev/onyx/backend/onyx/server/onyx_api/ingestion.py", line 21, in <module>
    from onyx.indexing.indexing_pipeline import build_indexing_pipeline
  File "/Users/ciaran/dev/onyx/backend/onyx/indexing/indexing_pipeline.py", line 72, in <module>
    from onyx.llm.chat_llm import LLMRateLimitError
  File "/Users/ciaran/dev/onyx/backend/onyx/llm/chat_llm.py", line 39, in <module>
    from onyx.llm.llm_provider_options import CREDENTIALS_FILE_CUSTOM_CONFIG_KEY
  File "/Users/ciaran/dev/onyx/backend/onyx/llm/llm_provider_options.py", line 82, in <module>
    for model in litellm.bedrock_models + litellm.bedrock_converse_models
                 ~~~~~~~~~~~~~~~~~~~~~~~^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
TypeError: unsupported operand type(s) for +: 'set' and 'set'
CRITICAL: Exiting due to uncaught exception TypeError: unsupported operand type(s) for +: 'set' and 'set'
FATA Failed to generate OpenAPI schema and client: exit status 1 

[jmelahman]

For what it's worth, the command fails for me on main at d8068f0a682b5b0134d98d65541162e161c5c998...

INFO Generating OpenAPI schema and Python client  
INFO Schema output: /Users/ciaran/dev/onyx/backend/generated/openapi.json 
INFO Client output: /Users/ciaran/dev/onyx/backend/generated/onyx_openapi_client 
Traceback (most recent call last):
  File "<stdin>", line 236, in <module>
  File "<stdin>", line 225, in main
  File "<stdin>", line 36, in generate_schema
  File "/Users/ciaran/dev/onyx/backend/onyx/main.py", line 52, in <module>
    from onyx.server.auth_check import check_router_auth
  File "/Users/ciaran/dev/onyx/backend/onyx/server/auth_check.py", line 14, in <module>
    from onyx.server.onyx_api.ingestion import api_key_dep
  File "/Users/ciaran/dev/onyx/backend/onyx/server/onyx_api/ingestion.py", line 21, in <module>
    from onyx.indexing.indexing_pipeline import build_indexing_pipeline
  File "/Users/ciaran/dev/onyx/backend/onyx/indexing/indexing_pipeline.py", line 72, in <module>
    from onyx.llm.chat_llm import LLMRateLimitError
  File "/Users/ciaran/dev/onyx/backend/onyx/llm/chat_llm.py", line 39, in <module>
    from onyx.llm.llm_provider_options import CREDENTIALS_FILE_CUSTOM_CONFIG_KEY
  File "/Users/ciaran/dev/onyx/backend/onyx/llm/llm_provider_options.py", line 82, in <module>
    for model in litellm.bedrock_models + litellm.bedrock_converse_models
                 ~~~~~~~~~~~~~~~~~~~~~~~^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
TypeError: unsupported operand type(s) for +: 'set' and 'set'
CRITICAL: Exiting due to uncaught exception TypeError: unsupported operand type(s) for +: 'set' and 'set'
FATA Failed to generate OpenAPI schema and client: exit status 1 

Hmmm. d8068f0a682b5b0134d98d65541162e161c5c998 is from 8 months ago.

That looks like a python version incompatibility (if not actually broken code). We primarily test and develop on python3.11. uv also makes it convenient to setup a specific python toolchain, https://github.com/onyx-dot-app/onyx/blob/main/contributing_guides/dev_setup.md#local-set-up

[ciaransweet]

Rats, that might be a false from me, I probably didn't pull from the remote. It's been a day 😂

…

On Wed, 21 Jan 2026, 18:26 Jamison Lahman, ***@***.***> wrote: *jmelahman* left a comment (onyx-dot-app/onyx#7430) <#7430 (comment)> For what it's worth, the command fails for me on main at d8068f0... INFO Generating OpenAPI schema and Python client INFO Schema output: /Users/ciaran/dev/onyx/backend/generated/openapi.json INFO Client output: /Users/ciaran/dev/onyx/backend/generated/onyx_openapi_client Traceback (most recent call last): File "<stdin>", line 236, in <module> File "<stdin>", line 225, in main File "<stdin>", line 36, in generate_schema File "/Users/ciaran/dev/onyx/backend/onyx/main.py", line 52, in <module> from onyx.server.auth_check import check_router_auth File "/Users/ciaran/dev/onyx/backend/onyx/server/auth_check.py", line 14, in <module> from onyx.server.onyx_api.ingestion import api_key_dep File "/Users/ciaran/dev/onyx/backend/onyx/server/onyx_api/ingestion.py", line 21, in <module> from onyx.indexing.indexing_pipeline import build_indexing_pipeline File "/Users/ciaran/dev/onyx/backend/onyx/indexing/indexing_pipeline.py", line 72, in <module> from onyx.llm.chat_llm import LLMRateLimitError File "/Users/ciaran/dev/onyx/backend/onyx/llm/chat_llm.py", line 39, in <module> from onyx.llm.llm_provider_options import CREDENTIALS_FILE_CUSTOM_CONFIG_KEY File "/Users/ciaran/dev/onyx/backend/onyx/llm/llm_provider_options.py", line 82, in <module> for model in litellm.bedrock_models + litellm.bedrock_converse_models ~~~~~~~~~~~~~~~~~~~~~~~^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ TypeError: unsupported operand type(s) for +: 'set' and 'set' CRITICAL: Exiting due to uncaught exception TypeError: unsupported operand type(s) for +: 'set' and 'set' FATA Failed to generate OpenAPI schema and client: exit status 1 Hmmm. d8068f0 is from 8 months ago. That looks like a python version incompatibility (if not actually broken code). We primarily test and develop on python3.11. uv also makes it convenient to setup a specific python toolchain, https://github.com/onyx-dot-app/onyx/blob/main/contributing_guides/dev_setup.md#local-set-up — Reply to this email directly, view it on GitHub <#7430 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ACFQTJ5K2UKSNM4ZSRZDIDT4H7AHFAVCNFSM6AAAAACRZS4A4KVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTOOBQGM4DSOJXGU> . You are receiving this because you authored the thread.Message ID: ***@***.***>

[ciaransweet]

Hey @jmelahman sorry for the tired responses last night! I dived back in this morning and have resolved the failing spec generation 🙌