Documentation Grafana Cloud Platform Assistant SDK HTTP API Conversations

Conversations API

Use conversations to start, continue, inspect, and stream Assistant interactions.

Examples use the base URL and service account token described in Grafana Assistant HTTP API reference.

Start or continue a conversation

Create a new conversation with the Assistant or continue an existing one.

Endpoint

POST /assistant/chats

Permissions

The service account must have these Assistant RBAC permissions:

• grafana-assistant-app.chats:access

The service account also needs any Grafana RBAC permissions required by the prompt, such as data source query or dashboard read permissions.

Request

Send a JSON request body.

JSON Copy

{
  "prompt": "How many datasources do I have?",
  "chatId": "optional-existing-chat-id"
}

Response

The response includes the conversation ID to use when fetching messages or streaming events.

JSON Copy

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

Examples

Bash Copy

curl -X POST "${ASSISTANT_API_URL}/assistant/chats" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${SERVICE_ACCOUNT_TOKEN}" \
  -d '{
    "prompt": "How many datasources do I have?"
  }'

Use the returned chatId to fetch messages or stream chat events.

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.

Fetch conversation messages

Retrieve the current chat metadata and messages.

Endpoint

GET /chats/{chatId}

Permissions

The service account must have these Assistant RBAC permissions:

• grafana-assistant-app.chats:access

Request

Response

The response includes conversation metadata and messages.

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": "sa-5594@serviceaccount.grafana",
    "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..."
          }
        ]
      }
    ]
  }
}

Examples

Bash Copy

CHAT_ID="18289896-b393-4136-9014-c2630a62f67f"

curl -X GET "${ASSISTANT_API_URL}/chats/${CHAT_ID}" \
  -H "Authorization: Bearer ${SERVICE_ACCOUNT_TOKEN}"

Stream chat events

Subscribe to real-time conversation updates using SSE.

Endpoint

GET /api/events/chats/{chatId}

This endpoint uses a different base path than standard api/v1 endpoints:

Copy

https://your-stack.grafana.net/api/plugins/grafana-assistant-app/resources/api/events/chats/{chatId}

The example uses ASSISTANT_EVENTS_URL as shorthand for the events base URL:

Bash Copy

ASSISTANT_EVENTS_URL="https://your-stack.grafana.net/api/plugins/grafana-assistant-app/resources/api/events"

Permissions

The service account must have these Assistant RBAC permissions:

• grafana-assistant-app.chats:access

Request

Response

The response is an SSE stream. Listen for the event types your integration needs.

Examples

Bash Copy

CHAT_ID="18289896-b393-4136-9014-c2630a62f67f"

curl -N "${ASSISTANT_EVENTS_URL}/chats/${CHAT_ID}" \
  -H "Authorization: Bearer ${SERVICE_ACCOUNT_TOKEN}" \
  -H "Accept: text/event-stream"

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.