Documentation Grafana Cloud AI and machine learning Grafana Assistant SDKs and APIs HTTP APIs

HTTP APIs for external systems

The Grafana Assistant HTTP APIs enable external systems to create conversations, check status, and stream responses programmatically.

What you’ll achieve

This article shows you how to authenticate and call the HTTP APIs to start chats, check status, 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.
• Check status: Retrieve chat metadata and messages.
• Stream responses: Subscribe to real-time updates with Server-Sent Events.
• Handle errors and limits: Interpret standard error responses and rate limits.

Before you begin

Confirm these prerequisites:

• A Grafana Cloud stack with the Grafana Assistant app installed and enabled.
• A service account token with at least the Editor role.
• 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 the Editor role (required for Assistant actions)
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:

JSON Copy

{
  "status": "success",
  "data": {
    "chatId": "18289896-b393-4136-9014-c2630a62f67f"
  }
}

Use the returned chatId to check status or stream responses.

Check chat status

Retrieve the current state and messages for a chat.

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:

JSON Copy

{
  "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?"
        }
      ],
      "timestamp": "2025-10-20T10:30:00Z"
    },
    {
      "id": "msg-2",
      "role": "assistant",
      "content": [
        {
          "type": "text",
          "text": "You have 5 datasources configured..."
        }
      ],
      "timestamp": "2025-10-20T10:35:00Z"
    }
  ]
}

Stream responses

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

Test APIs interactively

For live API testing:

1. Open Grafana Assistant from the main navigation
2. Click the For developers button
3. Navigate to the HTTP API section for:
   • Live API testing directly from your browser
   • Interactive forms to test each endpoint
   • Real-time SSE streaming visualization
   • Copy-to-clipboard cURL examples

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
• 429 Too Many Requests: Rate limit exceeded
• 500 Internal Server Error: Server-side error

Error responses include a message:

JSON Copy

{
  "status": "error",
  "message": "Chat not found"
}

Understand rate limits

API requests are subject to rate limits based on your Grafana Cloud plan. Monitor the response headers for rate limit information:

• X-RateLimit-Limit: Maximum requests per window
• X-RateLimit-Remaining: Remaining requests in current window
• X-RateLimit-Reset: Time when the rate limit resets

What’s next

Continue exploring and testing the APIs:

• Open Grafana Assistant and click For developers to try interactive API examples
• Learn about service account tokens
• Review Grafana HTTP API documentation