---
title: "Create or update an AI Index"
method: PUT
path: "/api/context_engine/ai_index/{aiIndexId}"
tags: ["context engine"]
---

# Create or update an AI Index

`PUT /api/context_engine/ai_index/{aiIndexId}`

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

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

Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.

Creates an AI Index with the given ID, or replaces an existing one. The request body replaces the whole record: omitted fields are removed, and omitted arrays become empty. A managed AI Index cannot be replaced and returns a 409.

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.

## Path parameters

- `aiIndexId` string, required

## 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
  - `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 `200`

The AI Index was updated.

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

## Other responses

- `201` — The AI Index was created.
- `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` — The AI Index is managed and immutable, 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/a6aad934034f?raw)