Documentation Grafana Cloud Platform Assistant SDK HTTP APIs

HTTP APIs for external systems

The Grafana Assistant HTTP APIs enable external systems to create conversations, fetch messages, and stream chat events programmatically.

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 and investigations, 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

Authorization: Bearer glsa_YOUR_SERVICE_ACCOUNT_TOKEN

Use API endpoints

All API endpoints are accessed through the Grafana plugin proxy:

Copy

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

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

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

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

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

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

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:

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.

Base path: https://your-stack.grafana.net/api/plugins/grafana-assistant-app/resources/api/v2/investigations

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. 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",
    "teamNames": ["Platform"]
  }'

The response returns an investigationId and a chatId. Poll GET /investigations/{id} for the investigation state and final summary, call GET /investigations/{id}/snapshot for the plan and report content, and 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:

• 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

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