Create conversation

Base URL: https://{kibana_url}

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

Auth

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

Privileges agentBuilder:read

Path parameters

space_id string optional: An identifier for the space. If space_id is not provided in the URL, the default space is used. Refer to Spaces for more information.

Header parameters

kbn-xsrf string required: A required header to protect against CSRF attacks

Request body

access_control object: Optional access control settings. Defaults to private.
agent_id string · max length: 64: The ID of the agent to associate with the conversation. Defaults to the default Elastic AI agent.
conversation_id string · max length: 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 length: 1 · max length: 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 length: 500: Title for the conversation. Defaults to "New conversation".

Response

200

Indicates a successful response

application/json

Base URL: https://{kibana_url}

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

Response

No example

Request Console 1 / 2 languages

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

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

Generated from the API spec

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

Generated from the API spec

Response

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

Request Console 1 / 2 languages

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

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

Generated from the API spec

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

Generated from the API spec

Response

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