Describe an AI Index Experimental

GET /api/context_engine/ai_index/{aiIndexId}/_describe
Api key auth

Spaces method and path for this operation:

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 Required

    The unique identifier of the AI Index.

    Minimum length is 1, maximum length is 256.

Responses

  • 200 application/json

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

    Hide response attribute Show response attribute object
    • response string Required

      Free-form text context block describing the AI Index for an agent.
  • 400 application/json

    The description response exceeded the size limit.

    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

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

    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

    No AI Index with the given ID exists in the current space, or 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.
GET /api/context_engine/ai_index/{aiIndexId}/_describe 
curl \
  -X GET "https://${KIBANA_URL}/api/context_engine/ai_index/customer_support/_describe" \
  -H "Authorization: ApiKey ${API_KEY}"

GET kbn:/api/context_engine/ai_index/customer_support/_describe
Response examples (200)
Example response with a context block for an agent 
{
  "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\"faq\": 12\n\"runbook\": 4\n\nTags\n\"billing\": 7\n\"password\": 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"
}
Response examples (400)
The field metadata for the backing indices exceeded the size limit 
{
  "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
}
Response examples (403)
The caller can read the backing indices but cannot read their mappings 
{
  "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
}
The caller cannot read the backing indices of the AI Index 
{
  "error": "Forbidden",
  "message": "AI index 'customer_support' is not readable. Reading it needs the Elasticsearch 'read' and 'view_index_metadata' privileges on its backing indices.",
  "statusCode": 403
}
Response examples (404)
Context Engine is turned off in this space 
{
  "error": "Not Found",
  "message": "Not Found",
  "statusCode": 404
}
No AI Index with the given ID exists in the current space 
{
  "error": "Not Found",
  "message": "AI index 'customer_support' not found",
  "statusCode": 404
}