Create conversation | Kibana API documentation

Create conversation Added in 9.6.0

POST /api/agent_builder/conversations

Spaces method and path for this operation:

post /s/{space_id}/api/agent_builder/conversations

Refer to Spaces for more information.

Create an empty conversation without sending a message. Returns the created conversation immediately. Use this to obtain a conversation ID before starting a chat session. To learn more about agent conversations, refer to the agent chat documentation.

[Required authorization] Route required privileges: agentBuilder:read.

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

application/json

Body

access_control object

Optional access control settings. Defaults to private.

Additional properties are NOT allowed.
Hide access_control attributes Show access_control attributes object
- access_mode string Required
  
  Access-control mode: private (only the owner and the listed members can read and continue the conversation), public (any user with access to the conversation's agent can read and continue it).
  
  Values are private or public.
- entries array[object]
  
  Members to share the conversation with. The list replaces the stored one; submit an empty list to unshare. Entries naming the owner are ignored. Must be empty when access_mode is public; repeated ids are rejected.
  
  Not more than 100 elements.
  Hide entries attributes Show entries attributes object
  
  id string Required
  
  Stable identifier of the user to share the conversation with: a Kibana user profile uid. Users without a profile cannot be granted access.
  
  Minimum length is 1, maximum length is 1024.
  
  role string Required
  
  Role granted to the principal. member is the only role: it grants read and converse access to the conversation.
  
  Value is member.
  
  type string Required
  
  Value is user.
agent_id string

The ID of the agent to associate with the conversation. Defaults to the default Elastic AI agent.

Maximum length is 256.
conversation_id string

Optional client-supplied UUID for the conversation. Server-generated if omitted.

Maximum length is 256.
title string

Title for the conversation. Defaults to "New conversation".

Maximum length is 500.

Responses

200 application/json

Indicates a successful response

POST /api/agent_builder/conversations

curl \
  -X POST "${KIBANA_URL}/api/agent_builder/conversations" \
  -H "Authorization: ApiKey ${API_KEY}" \
  -H "kbn-xsrf: true" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My new conversation",
    "access_control": {
      "access_mode": "private",
      "entries": [{ "type": "user", "id": "u_abc123_uid", "role": "member" }]
    }
  }'

POST kbn://api/agent_builder/conversations
{
  "title": "My new conversation",
  "access_control": {
    "access_mode": "private",
    "entries": [{ "type": "user", "id": "u_abc123_uid", "role": "member" }]
  }
}

Request example

Example request for creating a private shared conversation with a custom title and two members

{
  "access_control": {
    "access_mode": "private",
    "entries": [
      {
        "id": "u_abc123_uid",
        "role": "member",
        "type": "user"
      },
      {
        "id": "u_def456_uid",
        "role": "member",
        "type": "user"
      }
    ]
  },
  "title": "My new conversation"
}

Response examples (200)

Example response returning the newly created conversation

{
  "access_control": {
    "access_mode": "private",
    "entries": [
      {
        "added_at": "2026-08-14T10:00:00.000Z",
        "id": "u_abc123_uid",
        "role": "member",
        "type": "user"
      },
      {
        "added_at": "2026-08-14T10:00:00.000Z",
        "id": "u_def456_uid",
        "role": "member",
        "type": "user"
      }
    ]
  },
  "agent_id": "elastic-ai-agent",
  "created_at": "2026-08-14T10:00:00.000Z",
  "id": "bcc176c5-38f6-40be-be0c-898e34fa1480",
  "permissions": {
    "delete": true,
    "rename": true
  },
  "rounds": [],
  "title": "My new conversation",
  "updated_at": "2026-08-14T10:00:00.000Z",
  "user": {
    "username": "elastic"
  }
}