Module @theia/ai-external-api
ECLIPSE THEIA - AI EXTERNAL API EXTENSION
Description
This package exposes an HTTP API on the Theia backend that allows external tools (control planes, dashboards, CLIs) to inspect the AI chat sessions of a running Theia instance, to follow session changes as a push stream, to open or restore sessions in the IDE, to send prompts to sessions, and to create new sessions.
Session data is provided live by the connected frontends: each frontend registers itself with
the backend and is queried on demand. Sessions that are restored (in memory) in a connected
frontend are reported with their full state; persisted sessions that have not been restored
are reported with their persisted metadata and "restored": false. If no frontend is
connected, the session list is empty. Sessions that an agent delegated to another agent are
listed alongside top-level ones and carry parentSessionId and rootSessionId, so consumers
can group them as the IDE's session list does.
Session status uses the aggregated per-session status of ChatModel.status
(@theia/ai-chat): idle, running, awaitingApproval, awaitingToolCall,
awaitingInput, or failed. Persisted sessions that are not restored report failed if
their last request ended in an error and idle otherwise.
Enabling the API
The endpoints are contributed to the external API server of @theia/external-api, which is
disabled by default and configured through the externalApi.* user preferences (delivery
mode, port, hostname, and bearer token). See the @theia/external-api README for the
configuration and its security considerations.
API Endpoints
| Endpoint | Purpose |
|---|---|
GET /api/ai/sessions |
List the sessions, most recently used first. |
POST /api/ai/sessions |
Create a session, optionally sending an initial prompt. |
GET /api/ai/sessions/events |
Follow the session list as server-sent events. |
GET /api/ai/sessions/:id |
Read one session including its conversation. |
POST /api/ai/sessions/:id/prompt |
Send a prompt to the session. |
POST /api/ai/sessions/:id/open |
Show the session in the chat view of a connected frontend. |
POST /api/ai/sessions/:id/restore |
Restore the session without focusing it. |
The endpoints, their request and response bodies, and their error responses are documented in
the API reference.
The API also describes itself: all endpoints are published, with descriptions and schemas,
in the OpenAPI document served at GET /api/openapi.json (see @theia/external-api), e.g.
to generate clients or MCP tool definitions.
Security Considerations
- Chat histories can contain sensitive workspace content. Configure an
externalApi.tokenand mind the security considerations of@theia/external-api. - The creation and prompt endpoints trigger agent execution: they start language model requests and, depending on the configured tool confirmation settings, tool calls in the user's IDE. Do not expose them without a token.
- The open and restore endpoints affect the IDE: opening raises the chat view in the user's frontend, creating switches the active session, and restoring loads persisted session data into memory.
Additional Information
License
- Eclipse Public License 2.0
- δΈ€ (Secondary) GNU General Public License, version 2 with the GNU Classpath Exception
Trademark
"Theia" is a trademark of the Eclipse Foundation https://www.eclipse.org/theia