Create conversation

Server: https://{kibana_url}

POST /api/agent_builder/conversations
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.

Request

access_control object: Optional access control settings. Defaults to private.
agent_id string · max: 64: The ID of the agent to associate with the conversation. Defaults to the default Elastic AI agent.
conversation_id string · max: 256: Optional client-supplied UUID for the conversation. Server-generated if omitted.
metadata map string to string | number | boolean | string[]: 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 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: Title for the conversation. Defaults to "New conversation".

Response

200

Indicates a successful response

application/json

Examples

Request Console 1 / 2 languages

Console Kibana Dev Tools

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 Shell

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

Example request applying a conversation template and seeding metadata (each key must be declared by the template)

Request Console 1 / 2 languages

Console Kibana Dev Tools

POST kbn:/api/agent_builder/conversations
{
  "metadata": {
    "on_call": true,
    "services": [
      "checkout",
      "payments"
    ],
    "severity": "high"
  },
  "template_id": "incident-response",
  "title": "Incident triage"
}

curl Shell

curl \
  -X POST "${KIBANA_URL}/api/agent_builder/conversations" \
  -H "Authorization: ApiKey ${API_KEY}" \
  -H "kbn-xsrf: true" \
  -H "Content-Type: application/json" \
  -d '{
  "metadata": {
    "on_call": true,
    "services": [
      "checkout",
      "payments"
    ],
    "severity": "high"
  },
  "template_id": "incident-response",
  "title": "Incident triage"
}'

Response

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

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

Request Console 1 / 2 languages

Console Kibana Dev Tools

POST kbn:/api/agent_builder/conversations
{
  "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"
}

curl Shell

curl \
  -X POST "${KIBANA_URL}/api/agent_builder/conversations" \
  -H "Authorization: ApiKey ${API_KEY}" \
  -H "kbn-xsrf: true" \
  -H "Content-Type: application/json" \
  -d '{
  "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

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

Request { access_control , agent_id , conversation_id , metadata , template_id , title , }

Response

Request