---
type: api
title: Create an AI Index
description: **Spaces method and path for this operation:**
url: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/kibana/operation/operation-post-context-engine-ai-index
resource: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/kibana/operation/operation-post-context-engine-ai-index
products:
  - Kibana
---

# Create an AI Index

Availability: Planned

- Server: `https://{kibana_url}`

## Paths

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

- [Api key auth](/elastic/docs-builder/docs/4371/api/doc/kibana/authentication#apikeyauth)
- [Basic auth](/elastic/docs-builder/docs/4371/api/doc/kibana/authentication#basicauth)

## Description

Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-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](https://www.elastic.co/docs/explore-analyze/ai-features/context-engine).**<br/><br/>[Required authorization] Route required privileges: contextEngine:write.

## Request Body

`application/json`

- `automations` ([] object · max: 100 · default: []) — optional
  Automations associated with the AI Index. Defaults to an empty array when omitted.
  - `type` (enum) — required
    Values: `workflow`
  - `value` (string · min: 1 · max: 1024) — required
    The workflow ID.
- `description` (string · max: 2048) — optional
  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: 1 · max: 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) — optional
  The recurring feedback analysis, which reads agent signals and proposes improvement actions for the AI Index.
  - `agent_id` (string · max: 256) — optional
    Agent Builder agent ID that runs this index’s feedback-loop analysis.
  - `allowed_actions` ([] enum  · max: 9 · default: [
  "add_ki",
  "edit_ki",
  "remove_ki",
  "add_workflow",
  "edit_workflow",
  "remove_workflow",
  "add_source",
  "edit_source",
  "remove_source"
]) — optional
    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"
}) — optional
    When the analysis runs.
    - `interval` (string · max: 16) — required
      How often to analyze, for example `1h` or `24h`. At least 15 minutes.
  - `signal_filter` (string · max: 4096) — optional
    KQL narrowing which signals this index analyzes, for example `tags: query_error`.
  - `signal_time_range` (union anyOf · default: {
  "from": "now-30d",
  "type": "relative"
}) — optional
    Which signals the analysis reads. A read filter only.
    - **type: relative**
      - `from` (string · max: 64) — required
        Date math relative to now, for example `now-30d`.
      - `type` (enum) — required
        Values: `relative`
    - **type: absolute**
      - `from` (string · max: 64) — required
        ISO 8601 date to analyze signals since.
      - `type` (enum) — required
        Values: `absolute`
- `id` (string · min: 1 · max: 256) — required
  The unique identifier of the AI Index.
- `memory_enabled` (boolean) — optional
  Whether this AI index accepts memory writes. Defaults to true when omitted.
- `sources` ([] union anyOf · max: 100 · default: []) — optional
  Additional sources that provide context for the AI Index. Defaults to an empty array when omitted.
  - **type: esql**
    - `type` (enum) — required
      Values: `esql`
    - `value` (string · min: 1 · max: 10240) — required
      The source value; an ES|QL query when `type` is `esql`. Must be valid ES|QL.
  - **type: connector**
    - `type` (enum) — required
      Values: `connector`
    - `value` (string · min: 1 · max: 10240) — required
      The source value; a connector ID when `type` is `connector`.
- `traces` ([] union anyOf · max: 100 · default: []) — optional
  Trace sources linked to this AI Index. A write replaces the whole array. Defaults to an empty array when omitted.
  - **type: elastic_agent**
    - `type` (enum) — required
      Values: `elastic_agent`
    - `value` (string · min: 1 · max: 10240) — required
      The Agent Builder agent ID.
  - **type: index**
    - `type` (enum) — required
      Values: `index`
    - `value` (string · min: 1 · max: 10240) — required
      An index or data stream name or pattern to read traces from.
  - **type: esql**
    - `type` (enum) — required
      Values: `esql`
    - `value` (string · min: 1 · max: 10240) — required
      An ES|QL query to select traces.

## Responses

#### `201`

The AI Index was created.

`application/json`

- `status` (enum)
  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)
  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)
  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)
  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)
  A human-readable error message.
- `statusCode` (number)
  The HTTP status code.
## Code Examples

#### Console

```console
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

```curl
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 Examples

#### AI Index created

Example response after the AI Index is created

```json
{
  "status": "created"
}
```

#### Invalid dest

The dest value does not follow the naming convention

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

#### Index trace lookup denied

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

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

#### Context Engine turned off

Context Engine is turned off in this space

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

#### AI Index already exists

An AI Index with the same ID already exists

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