Create an AI Index | Kibana Serverless API documentation

Create an AI Index Experimental

POST /api/context_engine/ai_index

Spaces method and path for this operation:

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

Refer to Spaces for more information.

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

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

application/json

Body

automations array[object]

Automations associated with the AI Index. Defaults to an empty array when omitted.

Not more than 100 elements. Default value is [] (empty).
Hide automations attributes Show automations attributes object
- type string Required
  
  Value is workflow.
- value string Required
  
  The workflow ID.
  
  Minimum length is 1, maximum length is 1024.
description string

Human-readable description of the AI Index.

Maximum length is 2048.
dest object Required

The data stream or index that backs the AI Index.

Additional properties are NOT allowed.
Hide dest attributes Show dest attributes object
- type string Required
  
  The type of the backing store. data_stream for a data stream, or index for an index.
  
  Values are data_stream or index.
- value string 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.
  
  Minimum length is 1, maximum length is 1024.
feedback_analysis object

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

Additional properties are NOT allowed.
Hide feedback_analysis attributes Show feedback_analysis attributes object
- agent_id string
  
  Agent Builder agent ID that runs this index’s feedback-loop analysis.
  
  Maximum length is 256.
- allowed_actions array[string]
  
  Improvement actions the analysis may propose. An empty list is observe-only.
  
  Not more than 9 elements. Values are add_ki, edit_ki, remove_ki, add_workflow, edit_workflow, remove_workflow, add_source, edit_source, or remove_source. Default value is ["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
  
  When the analysis runs.
  
  Default value is {"interval" => "24h"}. Additional properties are NOT allowed.
  Hide schedule attribute Show schedule attribute object
  
  interval string Required
  
  How often to analyze, for example 1h or 24h. At least 15 minutes.
  
  Maximum length is 16.
- signal_filter string
  
  KQL narrowing which signals this index analyzes, for example tags: query_error.
  
  Maximum length is 4096.
- signal_time_range object
  Which signals the analysis reads. A read filter only.
  
  Any of:
  object-1 object object-2 object
id string Required

The unique identifier of the AI Index.

Minimum length is 1, maximum length is 256.
memory_enabled boolean

Whether this AI index accepts memory writes. Defaults to true when omitted.
sources array[object]

Additional sources that provide context for the AI Index. Defaults to an empty array when omitted.

Not more than 100 elements. Default value is [] (empty).
Any of:
object-1 object object-2 object
Hide attributes Show attributes

type string Required

Value is esql.

value string Required

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

Minimum length is 1, maximum length is 10240.
Hide attributes Show attributes

type string Required

Value is connector.

value string Required

The source value; a connector ID when type is connector.

Minimum length is 1, maximum length is 10240.
traces array[object]

Trace sources linked to this AI Index. A write replaces the whole array. Defaults to an empty array when omitted.

Not more than 100 elements. Default value is [] (empty).
Any of:
object-1 object object-2 object object-3 object
Hide attributes Show attributes

type string Required

Value is elastic_agent.

value string Required

The Agent Builder agent ID.

Minimum length is 1, maximum length is 10240.
Hide attributes Show attributes

type string Required

Value is index.

value string Required

An index or data stream name or pattern to read traces from.

Minimum length is 1, maximum length is 10240.
Hide attributes Show attributes

type string Required

Value is esql.

value string Required

An ES|QL query to select traces.

Minimum length is 1, maximum length is 10240.

Responses

201 application/json

The AI Index was created.
Hide response attribute Show response attribute object
- status string Required
  
  Value is created.
400 application/json

The request was invalid, for example a malformed dest, an invalid ES|QL source, or an unresolvable connector source or trace.
Hide response attributes Show response attributes object
- error string
  
  The HTTP status text.
- message string Required
  
  A human-readable error message.
- statusCode number
  
  The HTTP status code.
403 application/json

Elasticsearch denied the index trace lookup outright; the caller lacks index privileges for it.
Hide response attributes Show response attributes object
- error string
  
  The HTTP status text.
- message string Required
  
  A human-readable error message.
- statusCode number
  
  The HTTP status code.
404 application/json

Context Engine is turned off in this space.
Hide response attributes Show response attributes object
- error string
  
  The HTTP status text.
- message string Required
  
  A human-readable error message.
- statusCode number
  
  The HTTP status code.
409 application/json

An AI Index with the same ID already exists, or the write conflicted.
Hide response attributes Show response attributes object
- error string
  
  The HTTP status text.
- message string Required
  
  A human-readable error message.
- statusCode number
  
  The HTTP status code.

POST /api/context_engine/ai_index

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" }
    ]
  }'

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" }
  ]
}

Request example

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

{
  "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"
    }
  ]
}

Response examples (201)

Example response after the AI Index is created

{
  "status": "created"
}

Response examples (400)

The dest value does not follow the naming convention

{
  "error": "Bad Request",
  "message": "dest.value 'support-cases' is not allowed: it must start with 'ai-index-ds-'",
  "statusCode": 400
}

Response examples (403)

The caller lacks Elasticsearch index privileges to look up an index trace

{
  "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
}

Response examples (404)

Context Engine is turned off in this space

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

Response examples (409)

An AI Index with the same ID already exists

{
  "error": "Conflict",
  "message": "AI index 'customer_support' already exists",
  "statusCode": 409
}