--- title: "HTTP APIs for external systems | Grafana Cloud documentation" description: "Use HTTP APIs to integrate Grafana Assistant with external systems and automate workflows." --- > For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt). # HTTP APIs for external systems The Grafana Assistant HTTP APIs enable external systems to create conversations, fetch messages, and stream chat events programmatically. > Warning > > The HTTP APIs are experimental and subject to change. Use them for prototyping and testing, but be aware that breaking changes may occur in future releases. ## What you’ll achieve This article shows you how to authenticate and call the HTTP APIs to start chats, fetch messages, receive streamed updates, and manage supported Assistant resources: - Authenticate requests: Use a service account token in the `Authorization` header. - Start a chat: Create or continue a conversation and get a `chatId`. - Fetch messages: Retrieve chat metadata and generated responses. - Stream chat events: Subscribe to real-time updates with Server-Sent Events. - Manage feature resources: Use feature-specific endpoints, such as Assistant Watchers, when the service account has the required permissions. - Handle errors: Interpret standard error responses. ## Before you begin Confirm these prerequisites: - A Grafana Cloud stack with the Grafana Assistant app installed and enabled. - A service account token with access to the Grafana Assistant app. The token must have `plugins.app:access`, plus the Grafana permissions required by the actions you ask Assistant to perform, such as querying data sources or reading dashboards. - Your base URL for the plugin proxy path. - A tool to make HTTP requests, for example, `curl` or a language HTTP client. ## When to use the HTTP APIs Use the HTTP APIs when: - Integrating Grafana Assistant from external systems - Automating observability workflows with scripts - Building custom interfaces that interact with Assistant - Creating programmatic agents that leverage Assistant capabilities ## Authenticate requests All API requests require authentication using a Grafana service account token. ### Create a service account token 1. Sign in to Grafana as an administrator 2. Navigate to **Administration** > **Service accounts** 3. Create a new service account or select an existing one 4. Assign access to the Grafana Assistant app and any Grafana resources the Assistant should use 5. Generate a token and copy it securely ### Include the token in requests Add the token to the `Authorization` header: http ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```http Authorization: Bearer glsa_YOUR_SERVICE_ACCOUNT_TOKEN ``` > Note > > Service account tokens are not required for incoming or outgoing webhooks. Learn more in the [Grafana service accounts documentation](/docs/grafana/latest/administration/service-accounts/). ## Use API endpoints All API endpoints are accessed through the Grafana plugin proxy: ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```none https://your-stack.grafana.net/api/plugins/grafana-assistant-app/resources/api/v1/ ``` ### Start or continue a chat Create a new conversation with the Assistant or continue an existing one. **Endpoint:** `POST /assistant/chats` **Request body:** JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```json { "prompt": "How many datasources do I have?", "chatId": "optional-existing-chat-id" } ``` **Parameters:** - `prompt` (required): The task or question for the Assistant - `chatId` (optional): Continue an existing conversation Only one Assistant task can be active for an existing chat. If you submit another request while a task is running, the API returns HTTP `409 Conflict`. Wait for the active task to finish before retrying. **Example:** Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```bash curl -X POST "https://your-stack.grafana.net/api/plugins/grafana-assistant-app/resources/api/v1/assistant/chats" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_TOKEN" \ -d '{ "prompt": "How many datasources do I have?" }' ``` **Response excerpt:** JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```json { "status": "success", "data": { "chatId": "18289896-b393-4136-9014-c2630a62f67f" } } ``` Use the returned `chatId` to fetch messages or stream chat events. ### Fetch chat messages Retrieve the current chat metadata and messages. **Endpoint:** `GET /chats/{chatId}` **Example:** Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```bash curl -X GET "https://your-stack.grafana.net/api/plugins/grafana-assistant-app/resources/api/v1/chats/18289896-b393-4136-9014-c2630a62f67f" \ -H "Authorization: Bearer YOUR_TOKEN" ``` **Response excerpt:** JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```json { "status": "success", "data": { "id": "18289896-b393-4136-9014-c2630a62f67f", "name": "Assistant Conversation", "created": "2025-10-20T10:30:00Z", "modified": "2025-10-20T10:35:00Z", "userId": "user@example.com", "category": "assistant", "messages": [ { "id": "msg-1", "role": "user", "content": [ { "type": "text", "text": "How many datasources do I have?" } ] }, { "id": "msg-2", "role": "assistant", "content": [ { "type": "text", "text": "You have 5 datasources configured..." } ] } ] } } ``` ### Stream chat events Subscribe to real-time updates using Server-Sent Events (SSE). **Endpoint:** `GET /api/events/chats/{chatId}`. The SSE endpoint uses a different base path than standard APIs. **Example (JavaScript):** JavaScript ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```javascript const eventSource = new EventSource( 'https://your-stack.grafana.net/api/plugins/grafana-assistant-app/resources/api/events/chats/18289896-b393-4136-9014-c2630a62f67f' ); eventSource.addEventListener('message', (event) => { const data = JSON.parse(event.data); console.log('Event:', data.type, data.data); }); eventSource.addEventListener('error', (error) => { console.error('SSE Error:', error); eventSource.close(); }); ``` **Event types:** - `MESSAGE_CREATED`: New messages added to the conversation - `MESSAGE_UPDATED`: Streaming message updates (real-time text generation) - `AGENT_EXECUTION_STARTED`: Agent begins working on the task - `AGENT_EXECUTION_COMPLETED`: Agent finishes successfully - `AGENT_EXECUTION_FAILED`: Agent encounters an error - `REMOTE_TOOL_REQUEST`: Agent requests frontend tool execution For integration examples: 1. Open **Grafana Assistant** from the main navigation 2. Click **Integration hub** 3. Review the SDK and integration examples. Direct HTTP API testing may not be available from the Integration hub. ### Manage Assistant Watchers Use the Watchers API when an external system needs to create, list, update, calibrate, start, pause, run, or delete Assistant Watchers. Watchers are a Grafana Cloud public preview feature, and the API is experimental. **Base path:** `https://your-stack.grafana.net/api/plugins/grafana-assistant-app/resources/api/v1/watcher-agents` Common endpoints include: Expand table | Operation | Endpoint | Required permission | |-------------------------------------|--------------------------------------------|-----------------------------------------------| | List Watchers | `GET /watcher-agents` | `grafana-assistant-app.watcher-agents:read` | | Create a Watcher | `POST /watcher-agents` | `grafana-assistant-app.watcher-agents:create` | | Test Grafana-managed alert matchers | `POST /watcher-agents/alert-matchers/test` | `grafana-assistant-app.watcher-agents:write` | | Get a Watcher | `GET /watcher-agents/{id}` | `grafana-assistant-app.watcher-agents:read` | | Update a Watcher | `PUT /watcher-agents/{id}` | `grafana-assistant-app.watcher-agents:write` | | Delete a Watcher | `DELETE /watcher-agents/{id}` | `grafana-assistant-app.watcher-agents:delete` | | Calibrate a Watcher | `POST /watcher-agents/{id}/calibrate` | `grafana-assistant-app.watcher-agents:write` | | Start a Watcher | `POST /watcher-agents/{id}/start` | `grafana-assistant-app.watcher-agents:write` | | Pause a Watcher | `POST /watcher-agents/{id}/pause` | `grafana-assistant-app.watcher-agents:write` | | Run a Watcher now | `POST /watcher-agents/{id}/runs` | `grafana-assistant-app.watcher-agents:create` | | List Watcher runs | `GET /watcher-agents/{id}/runs` | `grafana-assistant-app.watcher-agents:read` | Watcher API requests also require `plugins.app:access` scoped to `plugins:id:grafana-assistant-app`. Watcher runs use the creator’s Grafana identity and can only query data sources that identity can access. For user-facing setup and behavior, refer to [Use Assistant Watchers](/docs/grafana-cloud/platform/grafana-assistant/platform/watchers). To read the current monthly Watcher token usage and active limit, call `GET /usage/limits/watchers`. This analytics endpoint requires `grafana-assistant-app.watcher-agents:read` and `plugins.app:access`. ## Handle errors API errors return standard HTTP status codes: - `400 Bad Request`: Invalid request parameters - `401 Unauthorized`: Missing or invalid authentication token - `403 Forbidden`: Insufficient permissions - `404 Not Found`: Chat ID not found - `500 Internal Server Error`: Server-side error Error responses include a message: JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```json { "status": "error", "message": "Chat not found" } ``` ## What’s next Continue exploring and testing the APIs: - Open **Grafana Assistant** and click **Integration hub** to review integration examples - Learn about [service account tokens](/docs/grafana/latest/administration/service-accounts/) - Review [Grafana HTTP API documentation](/docs/grafana/latest/developers/http_api/)