---
title: "Create an AI Index"
method: POST
path: "/api/context_engine/ai_index"
tags: ["context engine"]
---

# Create an AI Index

`POST /api/context_engine/ai_index`

**Spaces method and path for this operation:**

<div><span class="operation-verb post">post</span>&nbsp;<span class="operation-path">/s/{space_id}/api/context_engine/ai_index</span></div>

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.

## Headers

- `kbn-xsrf` string, required

## Request body

- object
  - `automations` object[] — Automations associated with the AI Index. Defaults to an empty array when omitted.
    - `type` 'workflow', required
    - `value` string, required — The workflow ID.
  - `description` string — Human-readable description of the AI Index.
  - `dest` object, required — The data stream or index that backs the AI Index.
    - `type` 'data_stream' | 'index', required — The type of the backing store. `data_stream` for a data stream, or `index` for an 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.
  - `feedback_analysis` object — The recurring feedback analysis, which reads agent signals and proposes improvement actions for the AI Index.
    - `agent_id` string — Agent Builder agent ID that runs this index’s feedback-loop analysis.
    - `allowed_actions` string[] — Improvement actions the analysis may propose. An empty list is observe-only.
    - `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.
      - `interval` string, required — How often to analyze, for example `1h` or `24h`. At least 15 minutes.
    - `signal_filter` string — KQL narrowing which signals this index analyzes, for example `tags: query_error`.
    - `signal_time_range` union — Which signals the analysis reads. A read filter only.
      - object
        - `from` string, required — Date math relative to now, for example `now-30d`.
        - `type` 'relative', required
      - object
        - `from` string, required — ISO 8601 date to analyze signals since.
        - `type` 'absolute', required
  - `id` string, required — The unique identifier of the AI Index.
  - `sources` union[] — Additional sources that provide context for the AI Index. Defaults to an empty array when omitted.
    - union
      - object
        - `type` 'esql', required
        - `value` string, required — The source value; an ES|QL query when `type` is `esql`. Must be valid ES|QL.
      - object
        - `type` 'connector', required
        - `value` string, required — The source value; a connector ID when `type` is `connector`.
  - `traces` union[] — Trace sources linked to this AI Index. A write replaces the whole array. Defaults to an empty array when omitted.
    - union
      - object
        - `type` 'elastic_agent', required
        - `value` string, required — The Agent Builder agent ID.
      - object
        - `type` 'index', required
        - `value` string, required — An index or data stream name or pattern to read traces from.
      - object
        - `type` 'esql', required
        - `value` string, required — An ES|QL query to select traces.

## Response `201`

The AI Index was created.

- object — Confirms that the AI Index was created.
  - `status` 'created', required

## Other responses

- `400` — The request was invalid, for example a malformed `dest`, an invalid ES|QL source, or an unresolvable connector source or trace.
- `403` — Elasticsearch denied the `index` trace lookup outright; the caller lacks index privileges for it.
- `404` — Context Engine is turned off in this space.
- `409` — An AI Index with the same ID already exists, or the write conflicted.

---

[API](https://skmtc.dev/elastic/apis/kibana-apis.md) · [All operations](https://skmtc.dev/elastic/apis/kibana-apis/llms.txt) · [OpenAPI document](https://skmtc.dev/elastic/apis/kibana-apis/revisions/8ada0295db6b?raw)