---
title: "Create session"
method: POST
path: "/api/sessions"
tags: ["Sessions"]
---

# Create session

`POST /api/sessions`

## Request

- Base URL: `/api/plugins/consensys-asko11y-app/resources` (relative, and the document was published on a file host, not at the API’s origin)
- URL: `/api/plugins/consensys-asko11y-app/resources/api/sessions`
- Auth: one of:
  - API key in cookie `grafana_session`
  - HTTP bearer

Creates a new chat session. If this is the first session for the user/org, it is automatically set as the current session. Max 50 sessions per user/org; oldest sessions are auto-evicted when limit is reached.

## Headers

- `X-Grafana-Org-Id` string

## Request body

- object
  - `title` string: Session title (auto-generated from first message if not provided)
  - `messages` SessionMessage[]: Initial messages for the session
    - `role` 'user' | 'assistant', required: Message role
    - `content` string, required: Message text content
    - `toolCalls` object, nullable: Tool calls made (raw JSON)
    - `pageRefs` object, nullable: Page references (raw JSON)

## Response `201`

Session created

- ChatSession: Chat session with full message history
  - `id` string, required: Session ID (base64 URL-safe 32-byte token)
  - `title` string, required: Session title
  - `messages` SessionMessage[], required: All messages in the session
    - `role` 'user' | 'assistant', required: Message role
    - `content` string, required: Message text content
    - `toolCalls` object, nullable: Tool calls made (raw JSON)
    - `pageRefs` object, nullable: Page references (raw JSON)
  - `summary` string: Session summary
  - `createdAt` string, date-time, required
  - `updatedAt` string, date-time, required
  - `messageCount` integer, required: Total number of messages
  - `activeRunId` string: ID of currently active agent run (if any)
  - `model` 'base' | 'large': LLM app model abstraction locked to this session, if selected
  - `runCount` integer: Number of completed agent runs (turns) in this session
  - `totalIterations` integer: Sum of agent-loop iterations (LLM round-trips) across all runs
  - `toolCallCount` integer: Sum of tool calls executed across all runs
  - `promptTokens` integer: Sum of LLM prompt tokens across all runs
  - `completionTokens` integer: Sum of LLM completion tokens across all runs
  - `totalTokens` integer: Sum of LLM prompt + completion tokens across all runs

## Other responses

- `400`: Bad request (invalid parameters or malformed request body)
- `401`: Unauthorized (missing or invalid authentication)
- `500`: Internal server error

## Changes

- **2026-08-11** `9762a43a4598`: 6 info
  - added the optional property `completionTokens` to the response with the `201` status
  - added the optional property `promptTokens` to the response with the `201` status
  - added the optional property `runCount` to the response with the `201` status
  - added the optional property `toolCallCount` to the response with the `201` status
  - …2 more
- **2026-05-21** `c2ffd094cb5d`: 1 info
  - added the optional property `model` to the response with the `201` status
- **2026-02-18** `5e7e9a233e2d`: 1 warning
  - removed the optional property `model` from the response with the `201` status

[Operation history](https://skmtc.dev/consensys/apis/ask-o11y-ai-powered-observability-assistant-api/changes/api/sessions/post.md)

---

[API](https://skmtc.dev/consensys/apis/ask-o11y-ai-powered-observability-assistant-api.md) - [All operations](https://skmtc.dev/consensys/apis/ask-o11y-ai-powered-observability-assistant-api/llms.txt) - [OpenAPI document](https://skmtc.dev/consensys/apis/ask-o11y-ai-powered-observability-assistant-api/revisions/ee3ccd0f186d?raw)