Describe an AI Index

Server: https://{kibana_url}

GET /api/context_engine/ai_index/{aiIndexId}/_describe
GET /s/{space_id}/api/context_engine/ai_index/{aiIndexId}/_describe

Refer to Spaces for more information.

Returns a free-form text context block for an agent. The block describes the AI Index and its ES|QL target. It also includes up to 500 fields exposed by the backing indices, identifies which fields are semantic, provides knowledge item type and tag counts for the current space, and includes example ES|QL queries.

The API reads data as the current user. Elasticsearch index privileges limit which indices the current user can access. A caller who cannot read the backing indices gets a 403 response.

The space comes from the request URL (/s/{spaceId}/…) or defaults to the default space. It cannot be specified in any other way.

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:read.

Path Parameters

aiIndexId string · min: 1 · max: 256 required: The unique identifier of the AI Index.

Responses

A free-form text context block describing the AI Index.

application/json

The description response exceeded the size limit.

application/json

The caller cannot read the backing indices. Describing an AI Index requires the read and view_index_metadata index privileges on them.

application/json

No AI Index with the given ID exists in the current space, or Context Engine is turned off in this space.

application/json

Examples

Example response with a context block for an agent

Request Console 1 / 2 languages

Console Kibana Dev Tools

GET kbn:/api/context_engine/ai_index/customer_support/_describe

curl Shell

curl \
  -X GET "https://${KIBANA_URL}/api/context_engine/ai_index/customer_support/_describe" \
  -H "Authorization: ApiKey ${API_KEY}"

Response

{
  "response": "AI index: customer_support\nKnowledge about customer support cases.\nQuery with ES|QL against: ai-index-ds-customer-support\n\nFields\n@timestamp: date, searchable, aggregatable\ncontent: text, searchable\ncontent.semantic: semantic_text, searchable\ndescription: text, searchable\ndescription.semantic: semantic_text, searchable\ntags: keyword, searchable, aggregatable\ntitle: text, searchable\ntitle.semantic: semantic_text, searchable\ntype: keyword, searchable, aggregatable\n\nSemantic fields\ncontent.semantic\ndescription.semantic\ntitle.semantic\n\nKnowledge item types\n\u0022faq\u0022: 12\n\u0022runbook\u0022: 4\n\nTags\n\u0022billing\u0022: 7\n\u0022password\u0022: 5\n\nExample queries (adapt field names for non-canonical indices)\n\nFull text search, lexical and semantic fused together (?query)\nFROM ai-index-ds-customer-support METADATA _id, _index, _score\n| FORK\n    ( WHERE MATCH(title, ?query) OR MATCH(description, ?query) OR MATCH(content, ?query) | SORT _score DESC | LIMIT 20 )\n    ( WHERE MATCH(title.semantic, ?query) OR MATCH(description.semantic, ?query) OR MATCH(content.semantic, ?query) | SORT _score DESC | LIMIT 20 )\n| FUSE\n| SORT _score DESC, _id ASC\n| KEEP title, description, content, type, tags\n| LIMIT 5\n\nFilter by knowledge item type and tag (?type, ?tag; tags is multi-valued, so MATCH)\nFROM ai-index-ds-customer-support\n| WHERE type == ?type AND MATCH(tags, ?tag)\n| KEEP title, description, content, type, tags\n| LIMIT 20\n\nCount by type\nFROM ai-index-ds-customer-support\n| STATS count = COUNT(*) BY type\n| SORT count DESC\n| LIMIT 20"
}

{
  "error": "Bad Request",
  "message": "Field metadata for the AI index exceeded the maximum allowed size of 20MB. Point the AI index at fewer or smaller indices.",
  "statusCode": 400
}

{
  "error": "Forbidden",
  "message": "security_exception\n\tRoot causes:\n\t\tsecurity_exception: action [indices:admin/mappings/get] is unauthorized for user [jdoe] with effective roles [support_reader] on indices [ai-index-ds-customer-support], this action is granted by the index privileges [view_index_metadata,manage,all]",
  "statusCode": 403
}

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