[question] API documentation #2168

Good day to you!

I'm developing a Python SDK to interface with the OpenCode API as an alternative to the ClaudeCode SDK.

Context:

I've generated a Python client using OpenAPI Generator and your openapi json (fetched from 127.0.0.1:4096/doc)

For now, I'm focusing only on the session endpoints, as this is the minimum needed to get some code generated.

Issue/Question
I'm unclear about the expected flow between API endpoints, particularly regarding message handling.
Current behavior:

When calling session.chat({ id, ...chatInput }) (which in my Python client translates to POST: http://127.0.0.1:4096/session/ses_72eb63d80ffe11MuiSwJ3G3wD4/message), I receive an empty response
The response contains neither the model's response nor a message ID that could be used for polling

Expected behavior (based on SDK documentation):

The documentation indicates this endpoint "returns a message."
I expected either:

The model's response directly, OR
A message ID to poll for the response

Questions:

Is the empty response from the /message endpoint expected behavior?
Should I be polling the messages list endpoint (GET /session/{id}/messages) to retrieve new messages after posting?
What is the intended flow for:

Sending a message to the model
Receiving/retrieving the model's response

Some other endpoint I also find confusing, like:
What are the APP endpoints for? Does one need to initialize the app when setting up the server?

What's the use of the File endpoints? Are they for the TUI to provide file searching capabilities in the repo for the client who is potentially on another machine? Are there other use cases?

Is there additional API documentation available that describes the endpoint interaction patterns?

Environment

Generated client using OpenAPI Generator
Python client is generated with urllib3 (synchronous)
API endpoint: http://127.0.0.1:4096

Any clarification on the proper API flow would be greatly appreciated. Happy to provide additional details if needed.