Documentation Grafana Cloud Platform Assistant SDK HTTP API

Grafana Assistant HTTP API reference

Use the Grafana Assistant HTTP API to interact with Assistant programmatically from scripts, services, and custom applications.

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.
• 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.

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

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.

Use endpoints

Standard API endpoints are accessed through the Grafana plugin proxy:

Copy

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

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
  Start or continue Assistant conversations, fetch messages, and stream chat events with the Grafana Assistant HTTP API.
• Rules API
  Create, list, update, and delete Grafana Assistant rules with the HTTP API.
• Skills API
  Create, list, update, and delete Grafana Assistant skills with the HTTP API.
• Quickstarts API
  Create, list, update, and delete Grafana Assistant quickstart prompts with the HTTP API.
• MCP servers API
  Register and manage Model Context Protocol server integrations for Grafana Assistant with the HTTP API.
• Automations API
  Create, schedule, update, delete, and run Grafana Assistant automations with the HTTP API.
• Token limits API
  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:

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.

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.

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.

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:

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

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

{
  "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.

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

curl "https://<STACK>.grafana.net/api/plugins/grafana-assistant-app/resources/api/v2/investigations/<INVESTIGATION_ID>" \
  -H "Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>"

Use data.state to decide what to do next:

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

curl "https://<STACK>.grafana.net/api/plugins/grafana-assistant-app/resources/api/v2/investigations/<INVESTIGATION_ID>/snapshot" \
  -H "Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>"

The response’s data object includes these report fields:

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 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.

Error responses include a message.

JSON Copy

{
  "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.
• Review Grafana HTTP API documentation.