--- title: "Grafana Assistant HTTP API reference | Grafana Cloud documentation" description: "Use the Grafana Assistant HTTP API to integrate 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). # Grafana Assistant HTTP API reference Use the Grafana Assistant HTTP API to interact with Assistant programmatically from scripts, services, and custom applications. > Note > > Grafana Assistant HTTP API is currently in [public preview](/docs/release-life-cycle/). Grafana Labs offers limited support, and breaking changes might occur prior to the feature being made generally available. ## Requirements Before using the API, confirm these prerequisites: - A Grafana Cloud stack with the Grafana Assistant app installed and enabled. - A Grafana service account with `plugins.app:access` scoped to `plugins:id:grafana-assistant-app`. - A token generated from that service account. - Any Grafana RBAC permissions required by the actions you ask Assistant to perform, such as querying data sources or reading dashboards. For more information, refer to [Manage Assistant access with RBAC](/docs/grafana-cloud/platform/grafana-assistant/privacy-and-security/rbac). - Your Grafana Cloud stack URL. - A tool to make HTTP requests, for example, `curl` or a language HTTP client. ## When to use the HTTP API Use the HTTP API 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 To manage supported Assistant resources declaratively, refer to [Manage Grafana Assistant with Terraform](/docs/grafana-cloud/platform/grafana-assistant/configure/terraform). ## Authenticate requests Authenticate requests with 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 the service account `plugins.app:access` scoped to `plugins:id:grafana-assistant-app`. 5. Assign any Grafana resource permissions Assistant needs for the requested workflows. Refer to the permissions listed for each endpoint below. 6. 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 ${SERVICE_ACCOUNT_TOKEN} ``` Service account identity is the caller identity for HTTP API requests. Behavior that is scoped to a user, such as ownership, attribution, saved state, usage, or “just me” access, applies to the service account, not the person who created the token or triggered the automation. > Note > > Service account tokens are not required for incoming or outgoing webhooks. To learn more, refer to the [Grafana service accounts documentation](/docs/grafana/latest/administration/service-accounts/). ## Use endpoints Standard 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/ ``` The examples use `ASSISTANT_API_URL` as shorthand for this base URL: Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```bash ASSISTANT_API_URL="https://your-stack.grafana.net/api/plugins/grafana-assistant-app/resources/api/v1" SERVICE_ACCOUNT_TOKEN="glsa_YOUR_SERVICE_ACCOUNT_TOKEN" ``` Endpoint paths in this reference are relative to `ASSISTANT_API_URL` unless otherwise noted. ## API reference pages Use the page that matches the workflow or resource you want to manage: - [Conversations API](/docs/grafana-cloud/platform/grafana-assistant/reference/http-apis/conversations/) Start or continue Assistant conversations, fetch messages, and stream chat events with the Grafana Assistant HTTP API. - [Rules API](/docs/grafana-cloud/platform/grafana-assistant/reference/http-apis/rules/) Create, list, update, and delete Grafana Assistant rules with the HTTP API. - [Skills API](/docs/grafana-cloud/platform/grafana-assistant/reference/http-apis/skills/) Create, list, update, and delete Grafana Assistant skills with the HTTP API. - [Quickstarts API](/docs/grafana-cloud/platform/grafana-assistant/reference/http-apis/quickstarts/) Create, list, update, and delete Grafana Assistant quickstart prompts with the HTTP API. - [MCP servers API](/docs/grafana-cloud/platform/grafana-assistant/reference/http-apis/mcp-servers/) Register and manage Model Context Protocol server integrations for Grafana Assistant with the HTTP API. - [Automations API](/docs/grafana-cloud/platform/grafana-assistant/reference/http-apis/automations/) Create, schedule, update, delete, and run Grafana Assistant automations with the HTTP API. - [Token limits API](/docs/grafana-cloud/platform/grafana-assistant/reference/http-apis/token-limits/) Read and manage Grafana Assistant monthly token limits with the HTTP API. ## Manage Assistant Watchers Use the Watchers API when an external system needs to create, list, update, calibrate, start, pause, run, or delete Assistant Watchers. The Watchers 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` | | Get automatic recalibration settings | `GET /watcher-agents/{id}/auto-calibration` | `grafana-assistant-app.watcher-agents:read` | | Update automatic recalibration settings | `PUT /watcher-agents/{id}/auto-calibration` | `grafana-assistant-app.watcher-agents:write` | Watcher API requests also require `plugins.app:access` scoped to `plugins:id:grafana-assistant-app`. Create and update requests can only configure data sources that the caller can query and that have no team LBAC rules, and alert checks require the caller to be able to read Grafana-managed alert instances. A data source with team LBAC rules returns `400 Bad Request`; missing access returns `403 Forbidden`. When you authenticate with a service account token, the service account’s own data source and alert permissions apply, and the service account is recorded as the Watcher’s creator. Watcher runs query the configured data sources as the stack’s Assistant service account. For user-facing setup and behavior, refer to [Use Assistant Watchers](/docs/grafana-cloud/platform/grafana-assistant/platform/watchers). Watcher create and update requests accept notification destinations in the `actions` object, including Slack and a webhook endpoint. Webhook URLs, bearer tokens, and HMAC signing secrets are write-only: responses return a sanitized URL preview and boolean configured-secret indicators instead of the stored values. Omit a secure field on update to keep its saved value, or send an empty string to clear it. An empty URL clears the endpoint only while the webhook is disabled, because an enabled webhook requires a URL. Only webhook configuration is retained when omitted: an update replaces the Slack and investigation configuration with the contents of the request, so include any existing configuration you want to keep. For the webhook delivery contract, refer to [Use Assistant Watchers](/docs/grafana-cloud/platform/grafana-assistant/platform/watchers/#receive-webhook-deliveries). To turn on automatic recalibration, send `PUT /watcher-agents/{id}/auto-calibration` with `enabled` set to `true`. Optionally set `scheduleCron` to a standard cron expression and `scheduleTimezone` to an IANA timezone. When you omit them the first time, reviews run weekly on Mondays at 09:00 UTC. Reviews can run at most once a day. Turning automatic recalibration on also requires `grafana-assistant-app.watcher-agents:read` and `grafana-assistant-app.chats:access`, and the Watcher must not be archived. Send `enabled` set to `false` to turn it off. The response includes `nextRunAt` and the latest review in `lastRun`, whose `status` is `running`, `completed`, `failed`, `cancelled`, or `skipped`, with a `skipReason` for skipped reviews. For user-facing behavior, refer to [Recalibrate a watcher automatically](/docs/grafana-cloud/platform/grafana-assistant/platform/watchers/#recalibrate-a-watcher-automatically). 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`. ## Manage investigations Use the investigations API when an external system needs to start, monitor, share, or control Assistant investigations. **Stability:** Public preview. **API base path:** `https://your-stack.grafana.net/api/plugins/grafana-assistant-app/resources/api/v2` Common endpoints include: Expand table | Operation | Endpoint | Required permission | |----------------------------------|--------------------------------------------------|-----------------------------------------------| | Create an investigation | `POST /investigations` | `grafana-assistant-app.investigations:create` | | List investigations | `GET /investigations` | `grafana-assistant-app.investigations:read` | | Get an investigation | `GET /investigations/{investigationId}` | `grafana-assistant-app.investigations:read` | | Get the plan and report snapshot | `GET /investigations/{investigationId}/snapshot` | `grafana-assistant-app.investigations:read` | | Pause an investigation | `POST /investigations/{investigationId}/pause` | `grafana-assistant-app.investigations:create` | | Resume an investigation | `POST /investigations/{investigationId}/resume` | `grafana-assistant-app.investigations:create` | | Share with teams | `POST /investigations/{investigationId}/share` | `grafana-assistant-app.investigations:create` | Investigation API requests also require `plugins.app:access` scoped to `plugins:id:grafana-assistant-app`. The Assistant Investigation User role grants these permissions together. Investigations use the service account’s Grafana identity, so also grant it the resource permissions the investigation needs: - `datasources:read` for relevant data sources - `datasources:query` for relevant data sources - `alert.rules:read` for relevant alert rule folders Service accounts can create team-scoped investigations by including `teamNames` when the token has `grafana-assistant-app.investigations:create` and `plugins.app:access`. The `teamNames` field controls who can see the created investigation in Grafana, as described below. Create an investigation by posting a nonempty `instruction` string. Include the context the investigation needs, for example, the service, time range, symptoms, and relevant data source identifiers. The optional `teamNames` field scopes visibility to the named Grafana teams, and the optional `title` overrides the derived title: 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/v2/investigations" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_TOKEN" \ -d '{ "instruction": "Investigate elevated error rates on the checkout service", "title": "Checkout service errors", "teamNames": ["Platform"] }' ``` An instruction must contain non-whitespace text. Missing, null, empty, or whitespace-only instructions return `400 Bad Request` without starting an investigation. Investigation reads return `500 Internal Server Error` when storage is unavailable; `404 Not Found` indicates a missing or inaccessible resource. The response contains identifiers for the investigation and its backing Assistant conversation: JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```json { "status": "success", "data": { "investigationId": "d2af40b6-c572-4d0e-9f5d-6e6cf09e88e6", "chatId": "c70a7f10-8e9a-4cd3-8577-e2d4b8ea4db4", "agentProfileId": "default" } } ``` Read the identifiers from `data.investigationId` and `data.chatId`: - Use `investigationId` for endpoints under `/api/v2/investigations/{investigationId}`. For example, poll `GET /investigations/{investigationId}` for lifecycle state and the final summary, or call `GET /investigations/{investigationId}/snapshot` for the plan and report content. - Use `chatId` for chat endpoints and to open the conversation in Workspace. Build the Workspace URL as `https://your-stack.grafana.net/a/grafana-assistant-app/workspace/{chatId}`. Fetch the full transcript with `GET /api/v1/chats/{chatId}/all-messages`. The `teamNames` field controls who can view the investigation. If you include `teamNames`, members of those Grafana teams and any user with the Assistant System Investigation Viewer role can view the investigation in Grafana; the service account that created it can no longer fetch it unless it’s also granted that role. If you omit `teamNames`, only the creating service account can access the investigation, and it doesn’t appear for any user in Grafana. Include `teamNames` whenever people need to see the results. For user-facing behavior, refer to [Investigations](/docs/grafana-cloud/platform/grafana-assistant/platform/investigation). ### Poll investigation status Creation returns HTTP `200 OK` with the identifiers before the investigation finishes. Poll `GET /investigations/{investigationId}` to read its lifecycle state. Successful reads also return HTTP `200 OK` with a `status: "success"` envelope and the result in `data`. Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```bash curl "https://.grafana.net/api/plugins/grafana-assistant-app/resources/api/v2/investigations/" \ -H "Authorization: Bearer " ``` Use `data.state` to decide what to do next: Expand table | State | Caller action | |----------------------------|------------------------------------------------------------------------------------------------| | `pending` or `in_progress` | Wait before polling again. Apply an overall timeout or cancellation limit in your integration. | | `completed` | Read `data.summary` and retrieve the report snapshot. | | `failed` | Read the optional `data.failureReason` and `data.errorMessage`. | | `cancelled` | Stop waiting for completion. | | `paused` | Stop automatic polling and let a user review the investigation in Grafana. | A failed investigation is still a readable resource: its status request returns HTTP `200 OK`, with `state: "failed"` in `data`. An HTTP error means the request itself failed. Handle unrecognized state values without treating them as successful completion. ### Read the investigation report Retrieve the snapshot when you need the current plan or report: Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```bash curl "https://.grafana.net/api/plugins/grafana-assistant-app/resources/api/v2/investigations//snapshot" \ -H "Authorization: Bearer " ``` The response’s `data` object includes these report fields: Expand table | Field | Meaning | |-----------------|------------------------------------------------------------------------------------------------------------------| | `reportPending` | Whether report generation has started and is still running. | | `reportSpec` | Optional structured report, with a `root` element ID and an `elements` map. | | `reportContent` | Optional raw report source. For current structured reports, this is serialized JSON; don’t assume it’s Markdown. | Report fields can be absent while an investigation starts, or when it stops without producing a report. `reportPending: false` doesn’t guarantee that a report exists. An earlier report can also remain available while a new one is being generated. The snapshot’s `sessionStatus` (`idle`, `active`, or `pause`) describes the engine session, separately from the row’s lifecycle `state`. Use the row endpoint for polling. Before the session is initialized, the snapshot can return `404 Not Found` even though the row is readable. Continue polling the known row in that case; don’t treat every `404` as retryable, because it can also mean the resource doesn’t exist or isn’t accessible. The [TypeScript SDK](/docs/grafana-cloud/platform/grafana-assistant/reference/typescript-sdk/#create-and-monitor-investigations) doesn’t currently wrap this lifecycle. Use these HTTP endpoints for creation, status, and report retrieval. ## Handle errors API errors return standard HTTP status codes. Expand table | Status code | Meaning | |-----------------------------|----------------------------------------------------------------------------------| | `400 Bad Request` | The request body or parameters are invalid. | | `401 Unauthorized` | The service account token is missing or invalid. | | `403 Forbidden` | The service account doesn’t have the required permissions. | | `404 Not Found` | The requested resource doesn’t exist or isn’t accessible to the service account. | | `500 Internal Server Error` | The server couldn’t complete the request. | 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" } ``` ## Next steps 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/).