Create or update an AI Index

Server: https://{kibana_url}

PUT /api/context_engine/ai_index/{aiIndexId}
PUT /s/{space_id}/api/context_engine/ai_index/{aiIndexId}

Refer to Spaces for more information.

Creates an AI Index with the given ID, or replaces an existing one. The request body replaces the whole record: omitted fields are removed, and omitted arrays become empty. A managed AI Index cannot be replaced and returns a 409.

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 authorization] Route required privileges: contextEngine:write.

Path Parameters

aiIndexId string · min: 1 · max: 256 required: The unique identifier of the AI Index.

Request

automations [] object · max: 100 · default: []: Automations associated with the AI Index. Defaults to an empty array when omitted.
description string · max: 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.
memory_enabled boolean: Whether this AI index accepts memory writes. Defaults to true when omitted.
sources [] union anyOf · max: 100 · default: []: Additional sources that provide context for the AI Index. Defaults to an empty array when omitted.; Any of:
traces [] union anyOf · max: 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 updated.

application/json

The AI Index was created.

application/json

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

The AI Index is managed and immutable, or the write conflicted.

application/json

Examples

Request Console 1 / 2 languages

Console Kibana Dev Tools

PUT kbn:/api/context_engine/ai_index/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": "index", "value": "traces-support" }]
}

curl Shell

curl \
  -X PUT "https://${KIBANA_URL}/api/context_engine/ai_index/customer_support" \
  -H "Authorization: ApiKey ${API_KEY}" \
  -H "kbn-xsrf: true" \
  -H "Content-Type: application/json" \
  -d '{
    "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": "index", "value": "traces-support" }]
  }'

Response

{
  "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 is managed and cannot be modified via the API",
  "statusCode": 409
}

Example request to create or fully replace an AI Index

Request Console 1 / 2 languages

Console Kibana Dev Tools

PUT kbn:/api/context_engine/ai_index/{aiIndexId}
{
  "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"
  },
  "sources": [
    {
      "type": "esql",
      "value": "FROM support-cases | LIMIT 100"
    }
  ],
  "traces": [
    {
      "type": "index",
      "value": "traces-support"
    }
  ]
}

curl Shell

curl \
  -X PUT "https://${KIBANA_URL}/api/context_engine/ai_index/{aiIndexId}" \
  -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"
  },
  "sources": [
    {
      "type": "esql",
      "value": "FROM support-cases | LIMIT 100"
    }
  ],
  "traces": [
    {
      "type": "index",
      "value": "traces-support"
    }
  ]
}'

Response

{
  "status": "updated"
}

{
  "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 is managed and cannot be modified via the API",
  "statusCode": 409
}

Path Parameters

Request { automations , description , dest , feedback_analysis , memory_enabled , sources , traces , }

Responses

Request