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 authorization

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.

type enum required
Values: workflow
value string · min length: 1 · max length: 1024 required

The workflow ID.

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.

type enum required

The type of the backing store. data_stream for a data stream, or index for an index.

Values: data_stream index
value string · min length: 1 · max length: 1024 required

The data stream or index (e.g. ai-index-ds-foo, ai-index-idx-foo) the AI Index is attached to. Must name a single data stream or index (no wildcards or comma-separated lists), match type, and start with ai-index-ds- (for data_stream) or ai-index-idx- (for index). The rest of the value must be a valid AI Index ID. System indices are not allowed.

feedback_analysis object

The recurring feedback analysis, which reads agent signals and proposes improvement actions for the AI Index.

agent_id string · max length: 256

Agent Builder agent ID that runs this index’s feedback-loop analysis.

allowed_actions enum[] · max items: 9 · default: [ "add_ki", "edit_ki", "remove_ki", "add_workflow", "edit_workflow", "remove_workflow", "add_source", "edit_source", "remove_source" ]

Improvement actions the analysis may propose. An empty list is observe-only.

Values: add_ki edit_ki remove_ki add_workflow edit_workflow remove_workflow add_source edit_source remove_source
enabled boolean required

Desired state of the recurring analysis. The scheduler stays authoritative for whether it is actually running.

schedule object · default: { "interval": "24h" }

When the analysis runs.

interval string · max length: 16 required

How often to analyze, for example 1h or 24h. At least 15 minutes.

signal_filter string · max length: 4096

KQL narrowing which signals this index analyzes, for example tags: query_error.

signal_time_range union anyOf · default: { "from": "now-30d", "type": "relative" }

Which signals the analysis reads. A read filter only.

Any of:
type enum required
Values: relative
from string · max length: 64 required

Date math relative to now, for example now-30d.

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:
type enum required
Values: esql
value string · min length: 1 · max length: 10240 required

The source value; an ES|QL query when type is esql. Must be valid ES|QL.

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:
type enum required
Values: elastic_agent
value string · min length: 1 · max length: 10240 required

The Agent Builder agent ID.

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
error string

The HTTP status text.

message string required

A human-readable error message.

statusCode number

The HTTP status code.

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

application/json
error string

The HTTP status text.

message string required

A human-readable error message.

statusCode number

The HTTP status code.

Context Engine is turned off in this space.

application/json
error string

The HTTP status text.

message string required

A human-readable error message.

statusCode number

The HTTP status code.

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

application/json
error string

The HTTP status text.

message string required

A human-readable error message.

statusCode number

The HTTP status code.

Base URL
https://{kibana_url}