Query AI Indices Experimental

POST /api/context_engine/ai_index/_query
Api key auth

Spaces method and path for this operation:

post /s/{space_id}/api/context_engine/ai_index/_query

Refer to Spaces for more information.

Runs an ES|QL query as the current user. The server applies a space filter and limits the response to at most 1000 rows.

The query determines which indices it reads. Elasticsearch index privileges limit which indices the current user can access.

The space comes from the request URL (/s/{spaceId}/…) or defaults to the default space. The request body cannot change the space or replace the space filter.

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.

Headers

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

application/json

Body

  • limit number

    Maximum rows to return. Defaults to 100; a trailing LIMIT in the query is capped to this value.

    Minimum value is 1, maximum value is 1000.

  • params object

    Values for ?name placeholders in the query.

  • query string Required

    The ES|QL query to run. Its FROM decides which Elasticsearch indices are read (normally ai-index-*); the server adds the space filter and a row limit.

    Minimum length is 1, maximum length is 10000.

Responses

  • 200 application/json

    The columns and rows returned by the ES|QL query.

    Hide response attributes Show response attributes object
    • columns array[object] Required

      Column metadata for the returned rows.

      Hide columns attributes Show columns attributes object
      • name string Required

        Column name.

      • type string Required

        Column ES|QL type.

    • values array[array] Required

      Row values, aligned positionally with columns, as Elasticsearch returns them. A multi-valued field is an array; _source and flattened columns are objects.
  • 400 application/json

    The ES|QL query was invalid, or its 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

    Elasticsearch rejected the read; the caller lacks index privileges.

    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

    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.
POST /api/context_engine/ai_index/_query 
curl \
  -X POST "https://${KIBANA_URL}/api/context_engine/ai_index/_query" \
  -H "Authorization: ApiKey ${API_KEY}" \
  -H "kbn-xsrf: true" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "FROM ai-index-* | WHERE type == ?type | KEEP title, type, attributes | LIMIT 10",
    "params": { "type": "faq" },
    "limit": 10
  }'

POST kbn:/api/context_engine/ai_index/_query
{
  "query": "FROM ai-index-* | WHERE type == ?type | KEEP title, type, attributes | LIMIT 10",
  "params": { "type": "faq" },
  "limit": 10
}
Request example
Example ES|QL query with a named parameter and a row limit 
{
  "limit": 10,
  "params": {
    "type": "faq"
  },
  "query": "FROM ai-index-* | WHERE type == ?type | KEEP title, type, attributes | LIMIT 10"
}
Response examples (200)
Example response with column metadata and matching rows. `flattened` columns such as `attributes` are returned as objects. 
{
  "columns": [
    {
      "name": "title",
      "type": "text"
    },
    {
      "name": "type",
      "type": "keyword"
    },
    {
      "name": "attributes",
      "type": "flattened"
    }
  ],
  "values": [
    [
      "How to reset a password",
      "faq",
      {
        "source": "zendesk"
      }
    ],
    [
      "Billing cycle explained",
      "faq",
      {
        "source": "zendesk"
      }
    ]
  ]
}
Response examples (400)
The ES|QL query references a column that does not exist 
{
  "error": "Bad Request",
  "message": "verification_exception\n\tRoot causes:\n\t\tverification_exception: Found 1 problem\nline 1:46: Unknown column [titel], did you mean [title]?",
  "statusCode": 400
}
Response examples (403)
The caller lacks Elasticsearch index privileges 
{
  "error": "Forbidden",
  "message": "security_exception\n\tRoot causes:\n\t\tsecurity_exception: action [indices:data/read/esql] is unauthorized for user [jdoe] with effective roles [support_reader], this action is granted by the index privileges [read_cross_cluster,read,all]",
  "statusCode": 403
}
Response examples (404)
Context Engine is turned off in this space 
{
  "error": "Not Found",
  "message": "Not Found",
  "statusCode": 404
}