Create an AI Index

Base URL: https://{kibana_url}

POST /api/context_engine/ai_index
POST /s/{space_id}/api/context_engine/ai_index

Auth

Creates an AI Index record attached to a data stream or index. Fails with a 409 if an AI Index with the same ID already exists.

Returns a 404 response when Context Engine is turned off in this space (contextEngine:enabled).

For more information, refer to the Context Engine documentation.

Required privileges

Privileges contextEngine:write

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

automations object[] · max items: 100 · default: []: Automations associated with the AI Index. Defaults to an empty array when omitted.
description string · max length: 2048: Human-readable description of the AI Index.
dest object required: The data stream or index that backs the AI Index.
feedback_analysis object: The recurring feedback analysis, which reads agent signals and proposes improvement actions for the AI Index.
id string · min length: 1 · max length: 256 required: The unique identifier of the AI Index.
memory_enabled boolean: Whether this AI index accepts memory writes. Defaults to true when omitted.
sources union anyOf[] · max items: 100 · default: []: Additional sources that provide context for the AI Index. Defaults to an empty array when omitted.; Any of:
traces union anyOf[] · max items: 100 · default: []: Trace sources linked to this AI Index. A write replaces the whole array. Defaults to an empty array when omitted.; Any of:

Responses

The AI Index was created.

application/json

status enum required: Values: created

The request was invalid, for example a malformed dest, an invalid ES|QL source, or an unresolvable connector source or trace.

application/json

Elasticsearch denied the index trace lookup outright; the caller lacks index privileges for it.

application/json

Context Engine is turned off in this space.

application/json

An AI Index with the same ID already exists, or the write conflicted.

application/json

Base URL: https://{kibana_url}

Examples

Request Console 1 / 2 languages

Console Kibana Dev Tools

POST kbn:/api/context_engine/ai_index
{
  "id": "customer_support",
  "description": "Knowledge about customer support cases.",
  "dest": { "type": "data_stream", "value": "ai-index-ds-customer-support" },
  "automations": [{ "type": "workflow", "value": "8f1c2d3e-4b5a-6c7d-8e9f-0a1b2c3d4e5f" }],
  "sources": [{ "type": "esql", "value": "FROM support-cases | LIMIT 100" }],
  "traces": [
    { "type": "elastic_agent", "value": "elastic-ai-agent" },
    { "type": "index", "value": "traces-support" }
  ]
}

curl Shell

curl \
  -X POST "https://${KIBANA_URL}/api/context_engine/ai_index" \
  -H "Authorization: ApiKey ${API_KEY}" \
  -H "kbn-xsrf: true" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "customer_support",
    "description": "Knowledge about customer support cases.",
    "dest": { "type": "data_stream", "value": "ai-index-ds-customer-support" },
    "automations": [{ "type": "workflow", "value": "8f1c2d3e-4b5a-6c7d-8e9f-0a1b2c3d4e5f" }],
    "sources": [{ "type": "esql", "value": "FROM support-cases | LIMIT 100" }],
    "traces": [
      { "type": "elastic_agent", "value": "elastic-ai-agent" },
      { "type": "index", "value": "traces-support" }
    ]
  }'

Response

No example

{
  "error": "Bad Request",
  "message": "dest.value \u0027support-cases\u0027 is not allowed: it must start with \u0027ai-index-ds-\u0027",
  "statusCode": 400
}

{
  "error": "Forbidden",
  "message": "security_exception: action [indices:admin/resolve/index] is unauthorized for user [jdoe] with effective roles [support_reader] on indices [traces-support], this action is granted by the index privileges [view_index_metadata,manage,read,all]",
  "statusCode": 403
}

{
  "error": "Not Found",
  "message": "Not Found",
  "statusCode": 404
}

{
  "error": "Conflict",
  "message": "AI index \u0027customer_support\u0027 already exists",
  "statusCode": 409
}

Request Console 1 / 2 languages

Example request to create an AI Index attached to a data stream

Console Kibana Dev Tools

POST kbn:/api/context_engine/ai_index
{
  "automations": [
    {
      "type": "workflow",
      "value": "8f1c2d3e-4b5a-6c7d-8e9f-0a1b2c3d4e5f"
    }
  ],
  "description": "Knowledge about customer support cases.",
  "dest": {
    "type": "data_stream",
    "value": "ai-index-ds-customer-support"
  },
  "id": "customer_support",
  "sources": [
    {
      "type": "esql",
      "value": "FROM support-cases | LIMIT 100"
    }
  ],
  "traces": [
    {
      "type": "elastic_agent",
      "value": "elastic-ai-agent"
    },
    {
      "type": "index",
      "value": "traces-support"
    }
  ]
}

Generated from the API spec

curl Shell

curl \
  -X POST "https://${KIBANA_URL}/api/context_engine/ai_index" \
  -H "Authorization: ApiKey ${API_KEY}" \
  -H "kbn-xsrf: true" \
  -H "Content-Type: application/json" \
  -d '{
    "automations": [
      {
        "type": "workflow",
        "value": "8f1c2d3e-4b5a-6c7d-8e9f-0a1b2c3d4e5f"
      }
    ],
    "description": "Knowledge about customer support cases.",
    "dest": {
      "type": "data_stream",
      "value": "ai-index-ds-customer-support"
    },
    "id": "customer_support",
    "sources": [
      {
        "type": "esql",
        "value": "FROM support-cases | LIMIT 100"
      }
    ],
    "traces": [
      {
        "type": "elastic_agent",
        "value": "elastic-ai-agent"
      },
      {
        "type": "index",
        "value": "traces-support"
      }
    ]
  }'

Generated from the API spec

Response

Example response after the AI Index is created

{
  "status": "created"
}

{
  "error": "Bad Request",
  "message": "dest.value \u0027support-cases\u0027 is not allowed: it must start with \u0027ai-index-ds-\u0027",
  "statusCode": 400
}

{
  "error": "Forbidden",
  "message": "security_exception: action [indices:admin/resolve/index] is unauthorized for user [jdoe] with effective roles [support_reader] on indices [traces-support], this action is granted by the index privileges [view_index_metadata,manage,read,all]",
  "statusCode": 403
}

{
  "error": "Not Found",
  "message": "Not Found",
  "statusCode": 404
}

{
  "error": "Conflict",
  "message": "AI index \u0027customer_support\u0027 already exists",
  "statusCode": 409
}