Send a message and get the answer Experimental; added in 9.6.0

POST /api/chat/message
Api key auth Basic auth

Spaces method and path for this operation:

post /s/{space_id}/api/chat/message

Refer to Spaces for more information.

Send a message to an agent and get its text answer. Use this synchronous endpoint in scripts and command-line tools. The response contains only the answer and the conversation ID. To continue the conversation, include the returned conversation_id in the next request.

The agent runs without a user, so the endpoint declines every prompt that the agent raises, such as a tool confirmation, a question, or a destructive API approval. The declined_prompts property lists these prompts. This endpoint does not support attachments.

The agentBuilder:experimentalFeatures advanced setting must be enabled. If it is disabled, the endpoint returns a 404 response.

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

Headers

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

application/json

Body

  • agent_id string

    The ID of the agent to send the message to. Defaults to the default Elastic AI agent.

    Minimum length is 1, maximum length is 64. Default value is elastic-ai-agent.

  • conversation_id string

    The ID of an existing conversation to continue. Omit it to start a new conversation; the response carries the ID to reuse on the next call.

    Maximum length is 256.

  • message string Required

    The user message to send to the agent.

    Minimum length is 1, maximum length is 100000.

Responses

  • 200 application/json

    The agent answered. The response contains the answer and the ID of the conversation that stores the exchange.

    Hide response attributes Show response attributes object
    • answer string Required

      The agent's final text answer. Empty when the agent finished without a message.

    • conversation_id string Required

      The conversation the message was added to: the one requested, or the one created for it.

    • declined_prompts array[object]

      The prompts that the endpoint declined. In an interactive conversation, these prompts pause the agent until the user answers. Examples are tool confirmations, questions to the user, and destructive API approvals. This endpoint has no user, so it declines each prompt and tells the agent why. The property is absent if the agent raised no prompts.

      At least 1 element.

      Hide declined_prompts attributes Show declined_prompts attributes object
      • message string Required

        The explanation the agent received in place of the prompt.

      • tool_id string Required

        The tool whose call was declined.
  • 400 application/json

    Bad Request: the request body is not valid. Possible causes are an empty or too long message, a conversation_id that is not a UUID, or an unsupported property such as connector_id or attachments.

  • 404 application/json

    Not Found: the conversation or agent was not found. Possible causes are a conversation_id that does not exist, an agent_id that the caller cannot use, or a disabled agentBuilder:experimentalFeatures advanced setting. If the caller cannot use the agent, the error says that the conversation was not found. This prevents callers from discovering hidden agents.

POST /api/chat/message 
curl \
  -X POST "${KIBANA_URL}/api/chat/message" \
  -H "Authorization: ApiKey ${API_KEY}" \
  -H "kbn-xsrf: true" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What is Elasticsearch?",
    "agent_id": "elastic-ai-agent"
  }'

POST kbn://api/chat/message
{
  "message": "What is Elasticsearch?",
  "agent_id": "elastic-ai-agent"
}
Request examples
Continue a conversation with the `conversation_id` returned by a previous call 
{
  "agent_id": "elastic-ai-agent",
  "conversation_id": "696ccd6d-4bff-4b26-a62e-522ccf2dcd16",
  "message": "And how does it differ from Kibana?"
}
Send a message to the default agent and start a new conversation. 
{
  "message": "What is Elasticsearch?"
}
Send a message to a specific agent 
{
  "agent_id": "elastic-ai-agent",
  "message": "What is Elasticsearch?"
}
Response examples (200)
The agent tried to call a tool that requires user confirmation. There is no user to ask on this endpoint, so the call was declined and the agent answered with what it could 
{
  "answer": "I could not run the reindex because it requires confirmation, which is not available here. You can run it from a conversation in Kibana instead.",
  "conversation_id": "696ccd6d-4bff-4b26-a62e-522ccf2dcd16",
  "declined_prompts": [
    {
      "message": "Agent running in non-interactive mode, user input not available - execution was declined",
      "tool_id": "reindex-logs"
    }
  ]
}
The agent's answer and the ID of the conversation it was stored in. `declined_prompts` is absent because the agent asked for nothing. 
{
  "answer": "Elasticsearch is a distributed, RESTful search and analytics engine capable of addressing a growing number of use cases. As the heart of the Elastic Stack, it centrally stores your data for lightning fast search, fine‑tuned relevancy, and powerful analytics that scale with ease.",
  "conversation_id": "696ccd6d-4bff-4b26-a62e-522ccf2dcd16"
}
Response examples (400)
The `message` is empty 
{
  "error": "Bad Request",
  "message": "[request body.message]: value has length [0] but it must have a minimum length of [1].",
  "statusCode": 400
}
The body carries a key this endpoint does not accept 
{
  "error": "Bad Request",
  "message": "[request body.connector_id]: Additional properties are not allowed ('connector_id' was unexpected)",
  "statusCode": 400
}
Response examples (404)
The `conversation_id` is unknown, or the `agent_id` is unknown or not usable by the caller 
{
  "attributes": {
    "trace_id": "8d4f2a3b-1c5e-4a9b-9f0d-2e6c1a3d4f5e"
  },
  "error": "Not Found",
  "message": "Conversation 696ccd6d-4bff-4b26-a62e-522ccf2dcd16 not found",
  "statusCode": 404
}