AI Assistant Resource

For an overview of the AI Assistant architecture and capabilities, see the AI Assistant page.

The AI Assistant resource provides HTTP access to the GroveStreams AI Assistant. It is the same AI Assistant available within the GroveStreams web application, exposed as a simple REST API.

The AI Assistant is an agentic system with access to over 35 built-in tools. When you send a message, the assistant autonomously reasons about your request, executes tools (queries, lookups, analysis), and returns a final response. You do not need to manage tool calls yourself — the assistant handles the entire workflow internally.

Capabilities include:

Execute GS SQL queries and return results
Find and inspect objects (components, streams, dashboards, queries, connectors, etc.)
Perform statistical analysis, correlation and clustering on stream data
Retrieve and search documentation
Navigate and browse content folders
Monitor jobs and system notifications

Note: The assistant is read-only by default — it inspects and queries your data but does not create or modify objects unless write permissions are enabled. Administrators can enable DDL execution, data writes, and entity management through AI Chat permission settings. See the AI Assistant page for details.

Chat Sessions

Each conversation is identified by a chatUid. To start a new conversation, omit the chatUid parameter and one will be created for you. To continue an existing conversation (multi-turn), pass the chatUid returned from the previous call. The assistant retains context across turns within the same chat session.

Context Items

The optional itemsSelected array allows you to provide context about items the user has selected in a UI (or any items relevant to the request). Each item is a JSON object with a uid and objectType. Omitting this field entirely indicates the request is not coming from the GroveStreams web UI, and the assistant will not make assumptions about selected items.

Integration with External AI Agents (MCP)

If you are building an AI agent or integrating with tools that support the Model Context Protocol (MCP), you can use this HTTP API as your integration point. Rather than exposing individual GroveStreams tools via MCP (which would couple your integration to internal tool interfaces that may change), we recommend calling this endpoint as a single "GroveStreams" tool from your agent. Your agent sends natural language requests and receives final answers — GroveStreams handles all tool orchestration internally.

This approach is simpler, avoids breaking changes as GroveStreams evolves, and gives your agent access to the full power of the assistant without needing to understand individual tool schemas.

POST aillm/chat

Sends a message to the AI Assistant and returns the response. This is a blocking call — it returns when the assistant has finished processing, which may take several seconds for complex requests that involve multiple tool calls. The calling user must have the AI_ASSISTANT capability enabled.	Resource Information
	Rate Limited?	Yes
	session, oauth and org tokens compatible?	Yes
	api_key token compatible?	Yes

Resource URL

http://grovestreams.com/api/aillm/chat

Parameters

chatUid

optional

The UID of an existing chat session to continue. If omitted, a new chat session is created and its UID is returned in the response. Use the returned chatUid in subsequent calls to maintain conversation context.

Request Body

userText	required	The message to send to the AI Assistant. This is natural language text describing what you want to do.
itemsSelected	optional	A JSON array of objects providing context about selected items. Each object should contain uid and objectType fields. Omit this field entirely if not applicable.

Example Requests

/aillm/chat

Request Body


					{

					  "userText": "How many components do I have?"

					}

Response Body


					{

					  "chatResponse": "You have 12 components in your organization.",

					  "chatUid": "3f2504e0-4f89-11d3-9a0c-0305e82c3301"

					}

Multi-turn example — continue the conversation using the returned chatUid:

/aillm/chat?chatUid=3f2504e0-4f89-11d3-9a0c-0305e82c3301

Request Body


					{

					  "userText": "List the names of the first 5"

					}

Response Body


					{

					  "chatResponse": "Here are the first 5 components:\n1. Garage Temperature Sensor\n2. Personal Computer\n3. Refrigerator Smart Plug\n4. Currency Exchange Rates\n5. Solar Panel",

					  "chatUid": "3f2504e0-4f89-11d3-9a0c-0305e82c3301"

					}

With context items:

/aillm/chat

Request Body


					{

					  "userText": "Show me the last 24 hours of data for this component",

					  "itemsSelected": [

					    {

					      "uid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",

					      "objectType": "component"

					    }

					  ]

					}

Error Response

If an error occurs, the response will follow the standard GroveStreams error format:


					{

					  "success": false,

					  "message": "Error description"

					}

Notes

This is a blocking call. Complex requests involving multiple tool executions may take 10-30 seconds. Set HTTP client timeouts accordingly.
The AI Assistant requires an LLM to be configured for your organization. See the GroveStreams Website Guide for configuration instructions.
The assistant runs tool calls under the calling user's security context. It can only access and query objects the user has permissions for.
Chat history is stored server-side and is accessible from the GroveStreams web application.