anomalyco/opencode
1
0
Fork 0
mirror of https://github.com/anomalyco/opencode.git synced 2026-07-22 10:15:31 -04:00
Code Issues 5.9k Packages Projects Releases 19 Wiki Activity

[question] API documentation #1438

New Issue
Closed
opened 2026-02-16 17:30:58 -05:00 by yindo · 6 comments
yindo commented 2026-02-16 17:30:58 -05:00
Owner
Copy Link
Copy Source

Originally created by @Drinect on GitHub (Aug 22, 2025).

Originally assigned to: @jayair on GitHub.

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.

Originally created by @Drinect on GitHub (Aug 22, 2025). Originally assigned to: @jayair on GitHub. 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](https://github.com/OpenAPITools/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.
yindo closed this issue 2026-02-16 17:30:58 -05:00
yindo commented 2026-02-16 17:30:58 -05:00
Author
Owner
Copy Link
Copy Source

@github-actions[bot] commented on GitHub (Aug 22, 2025):

This issue might be a duplicate of existing issues. Please check:

  • #2032: Both issues are asking for documentation and examples for implementing alternative clients that use the OpenCode server API instead of the built-in TUI

Feel free to ignore if none of these address your specific case.

@github-actions[bot] commented on GitHub (Aug 22, 2025): This issue might be a duplicate of existing issues. Please check: - #2032: Both issues are asking for documentation and examples for implementing alternative clients that use the OpenCode server API instead of the built-in TUI Feel free to ignore if none of these address your specific case.
yindo commented 2026-02-16 17:30:58 -05:00
Author
Owner
Copy Link
Copy Source

@rekram1-node commented on GitHub (Aug 22, 2025):

I think this endpoint was not properly documented, the spec should be fixed in next release

@rekram1-node commented on GitHub (Aug 22, 2025): I think this endpoint was not properly documented, the spec should be fixed in next release
yindo commented 2026-02-16 17:30:58 -05:00
Author
Owner
Copy Link
Copy Source

@rekram1-node commented on GitHub (Aug 22, 2025):

You will need to regen your sdk after that

@rekram1-node commented on GitHub (Aug 22, 2025): You will need to regen your sdk after that
yindo commented 2026-02-16 17:30:58 -05:00
Author
Owner
Copy Link
Copy Source

@Drinect commented on GitHub (Aug 25, 2025):

Thanks! I’ll regenerate the SDK after the next release.

While you’re updating the spec, could you also add OpenAPI tags to group endpoints? This lets generators produce namespaced clients (e.g., client.session.chat()) instead of flat names (client.session_chat()).
Example: for POST /session/{id}/message, add "tags": ["session"] and use "operationId": "chat" (instead of "session.chat").

Suggested tags: session, config, app, file, find, tui, event, auth.

I suspect you created the OpenAPI spec by a generator. So I'm not sure if it's possible. But it would help me (and maybe others who try to generate clients for your API) a lot.

@Drinect commented on GitHub (Aug 25, 2025): Thanks! I’ll regenerate the SDK after the next release. While you’re updating the spec, could you also add OpenAPI [tags](https://swagger.io/docs/specification/v3_0/grouping-operations-with-tags/) to group endpoints? This lets generators produce namespaced clients (e.g., client.session.chat()) instead of flat names (client.session_chat()). Example: for POST /session/{id}/message, add "tags": ["session"] and use "operationId": "chat" (instead of "session.chat"). Suggested tags: session, config, app, file, find, tui, event, auth. I suspect you created the OpenAPI spec by a generator. So I'm not sure if it's possible. But it would help me (and maybe others who try to generate clients for your API) a lot.
yindo commented 2026-02-16 17:30:58 -05:00
Author
Owner
Copy Link
Copy Source

@rekram1-node commented on GitHub (Aug 25, 2025):

good idea

@rekram1-node commented on GitHub (Aug 25, 2025): good idea
yindo commented 2026-02-16 17:30:58 -05:00
Author
Owner
Copy Link
Copy Source

@rekram1-node commented on GitHub (Dec 27, 2025):

[automated] Closing due to 90+ days of inactivity. Feel free to reopen if you still need this!

@rekram1-node commented on GitHub (Dec 27, 2025): [automated] Closing due to 90+ days of inactivity. Feel free to reopen if you still need this!
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
acp
bad
bug
discussion
docs
documentation
enhancement
extension
good first issue
growth
help-wanted
mcp
model-problem
needs:compliance
nix
opentui
perf
pull-request
Mirrored from GitHub Pull Request
 tui
web
windows
zen
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
yindo
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: anomalyco/opencode#1438
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?