Documentation Grafana Cloud AI and machine learning Grafana 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, and receive streamed updates:

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

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.

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