Describe an AI Index
Base URL
https://{kibana_url}
Auth
Stack
Planned
The Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats.
Availability
Planned
We plan to add this functionality in a future Elastic Stack update. Subject to changes.
Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments.
This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes.
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 .
Privileges
contextEngine:read
Expand all
space_id
string optional
An identifier for the space. If space_id is not provided in the URL, the default space is used. Refer to Spaces for more information.
aiIndexId
string · min length: 1 · max length: 256 required
The unique identifier of the AI Index.
200
A free-form text context block describing the AI Index.
application/json
response
string required
Free-form text context block describing the AI Index for an agent.
400
The description response exceeded the size limit.
application/json
error
string
The HTTP status text.
message
string required
A human-readable error message.
statusCode
number
The HTTP status code.
403
The caller cannot read the backing indices. Describing an AI Index requires the read and view_index_metadata index privileges on them.
application/json
error
string
The HTTP status text.
message
string required
A human-readable error message.
statusCode
number
The HTTP status code.
404
No AI Index with the given ID exists in the current space, or Context Engine is turned off in this space.
application/json
error
string
The HTTP status text.
message
string required
A human-readable error message.
statusCode
number
The HTTP status code.
Thank you for your feedback.
Base URL
https://{kibana_url}
Examples
Request
Console
1 / 2 languages
‹
›
1
GET kbn:/api/context_engine/ai_index/customer_support/_describe
1
2
3
curl \
-X GET "https://${KIBANA_URL}/api/context_engine/ai_index/customer_support/_describe" \
-H "Authorization: ApiKey ${API_KEY}"
Response
Example response with a context block for an agent
Show more
The field metadata for the backing indices exceeded the size limit
Show more
The caller can read the backing indices but cannot read their mappings
Show more
Context Engine is turned off in this space
Show more
1
2
3
{
"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"
}
1
2
3
4
5
{
"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
}
1
2
3
4
5
{
"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
}
1
2
3
4
5
{
"error": "Not Found",
"message": "Not Found",
"statusCode": 404
}