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

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.

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

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 an instruction. 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"]
  }'

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.

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.