Introduction
The OpenCode Portal HTTP API provides programmatic access to manage OpenCode instances, sessions, and project operations. The API is organized around REST principles with predictable resource-oriented URLs.
Base URL
All API requests are made to:
http://localhost:<portal-port>/api
3000, but this may vary depending on your configuration.
Authentication
The OpenCode Portal API currently does not require authentication for local instances. All endpoints are accessible without API keys or tokens.
This API is designed for local development environments. If you expose the Portal to a network, ensure proper security measures are in place.
Port Parameter
Many endpoints include a :port parameter in the URL path. This refers to the OpenCode instance port number, not the Portal port. Each OpenCode instance runs on its own port (typically starting at 3100).
The API accepts JSON-encoded request bodies for POST requests. Include the following header:
Content-Type: application/json
{
// Response data varies by endpoint
}
{
"statusCode": 400,
"statusMessage": "Error description",
"message": "Detailed error message"
}
Error Codes
The API uses standard HTTP status codes:
| Code | Description |
|---|
| 200 | Success |
| 400 | Bad Request - Invalid parameters |
| 404 | Not Found - Resource doesn’t exist |
| 500 | Internal Server Error |
Common Errors
Invalid Port
{
"statusCode": 500,
"message": "Invalid port"
}
:port parameter is missing or not a valid number.
Session ID Required
{
"statusCode": 500,
"message": "Session ID required"
}
Message Text Required
{
"statusCode": 500,
"message": "Message text required"
}
Example Request
curl -X GET http://localhost:3000/api/instances
API Endpoints
The API is organized into the following resource groups:
- Sessions - Manage chat sessions
- Git - Git operations
- Files - File search and operations
- Instances - OpenCode instance management