---
type: api
title: Create conversation
description: **Spaces method and path for this operation:**
url: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/kibana/operation/operation-post-agent-builder-conversations
resource: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/kibana/operation/operation-post-agent-builder-conversations
products:
  - Kibana
---

# Create conversation

Availability: Planned

- Server: `https://{kibana_url}`

## Paths

- `POST` `/api/agent_builder/conversations`
- `POST` `/s/{space_id}/api/agent_builder/conversations`

- [Api key auth](/elastic/docs-builder/docs/4371/api/doc/kibana/authentication#apikeyauth)
- [Basic auth](/elastic/docs-builder/docs/4371/api/doc/kibana/authentication#basicauth)

## Description

Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-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](https://www.elastic.co/docs/explore-analyze/ai-features/agent-builder/chat).<br/><br/>[Required authorization] Route required privileges: agentBuilder:read.

## Request Body

`application/json`

- `access_control` (object) — optional
  Optional access control settings. Defaults to private.
  - `access_mode` (enum) — 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: `private`, `public`
  - `entries` ([] object · max: 100) — optional
    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.
    - `id` (string · min: 1 · max: 1024) — required
      Stable identifier of the user to share the conversation with: a Kibana user profile uid. Users without a profile cannot be granted access.
    - `role` (enum) — required
      Role granted to the principal. `member` is the only role: it grants read and converse access to the conversation.
      Values: `member`
    - `type` (enum) — required
      Values: `user`
- `agent_id` (string · max: 64) — optional
  The ID of the agent to associate with the conversation. Defaults to the default Elastic AI agent.
- `conversation_id` (string · max: 256) — optional
  Optional client-supplied UUID for the conversation. Server-generated if omitted.
- `metadata` (map string to string | number | boolean | string[]) — optional
  Initial metadata values. Each key must be declared by the referenced template; each value is validated against the field definition (type, options, min/max, regex, max_length). Requires `template_id`.
- `template_id` (string · min: 1 · max: 256) — optional
  Optional ID of a conversation template to apply. When set, the template seeds default metadata and any caller-supplied `metadata` is validated against the template field definitions.
- `title` (string · max: 500) — optional
  Title for the conversation. Defaults to "New conversation".

## Response

Indicates a successful response

## Code Examples

#### Console

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

#### curl

```curl
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" }]
    }
  }'
```

## Response Examples

#### Create conversation response

Example response returning the newly created conversation

```json
{
  "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"
  }
}
```