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
Stack
Planned
The Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats.
Availability
Planned
We plan to add this functionality in a future Elastic Stack update. Subject to changes.
Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments.
This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes.
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 .
Privileges
contextEngine:write
Expand all
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.
A required header to protect against CSRF attacks
{
}
automations
object [] · max items: 100 · default: []
Automations associated with the AI Index. Defaults to an empty array when omitted.
+
Show 2 properties
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.
−
Hide 2 properties
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.
+
Show 6 properties
agent_id
string · max length: 256
Agent Builder agent ID that runs this index’s feedback-loop analysis.
allowed_actions
enum [] · max items: 9
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
Default:
["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.
+
Show 1 property
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:
−
Hide 2 properties
type
enum required
Values:
relative
from
string · max length: 64 required
Date math relative to now, for example now-30d.
−
Hide 2 properties
type
enum required
Values:
absolute
from
string · max length: 64 required
ISO 8601 date to analyze signals since.
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:
−
Hide 2 properties
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.
−
Hide 2 properties
type
enum required
Values:
connector
value
string · min length: 1 · max length: 10240 required
The source value; a connector ID when type is connector.
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:
−
Hide 2 properties
type
enum required
Values:
elastic_agent
value
string · min length: 1 · max length: 10240 required
The Agent Builder agent ID.
−
Hide 2 properties
type
enum required
Values:
index
value
string · min length: 1 · max length: 10240 required
An index or data stream name or pattern to read traces from.
−
Hide 2 properties
type
enum required
Values:
esql
value
string · min length: 1 · max length: 10240 required
An ES|QL query to select traces.
201
The AI Index was created.
application/json
status
enum required
Values:
created
400
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.
403
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.
404
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.
409
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.
Thank you for your feedback.
Base URL
https://{kibana_url}
Examples
Example
languages
Create an AI Index
languages
Request
Console
1 / 2 languages
‹
›
1
2
3
4
5
6
7
8
9
10
11
12
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" }
]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
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
The dest value does not follow the naming convention
Show more
The caller lacks Elasticsearch index privileges to look up an index trace
Show more
Context Engine is turned off in this space
Show more
An AI Index with the same ID already exists
Show more
1
2
3
4
5
{
"error": "Bad Request",
"message": "dest.value \u0027support-cases\u0027 is not allowed: it must start with \u0027ai-index-ds-\u0027",
"statusCode": 400
}
1
2
3
4
5
{
"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
}
1
2
3
4
5
{
"error": "Not Found",
"message": "Not Found",
"statusCode": 404
}
1
2
3
4
5
{
"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
Show more
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
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
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
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
Show more
The dest value does not follow the naming convention
Show more
The caller lacks Elasticsearch index privileges to look up an index trace
Show more
Context Engine is turned off in this space
Show more
An AI Index with the same ID already exists
Show more
1
2
3
{
"status": "created"
}
1
2
3
4
5
{
"error": "Bad Request",
"message": "dest.value \u0027support-cases\u0027 is not allowed: it must start with \u0027ai-index-ds-\u0027",
"statusCode": 400
}
1
2
3
4
5
{
"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
}
1
2
3
4
5
{
"error": "Not Found",
"message": "Not Found",
"statusCode": 404
}
1
2
3
4
5
{
"error": "Conflict",
"message": "AI index \u0027customer_support\u0027 already exists",
"statusCode": 409
}