Search a knowledge base collection

POST

/v1/kb/collections/{id}/search

package main

import (
  "fmt"
  "strings"
  "net/http"
  "io"
)

func main() {

  url := "https://api.ai.wpengine.com/v1/kb/collections/example/search"

  payload := strings.NewReader("{ \"query\": \"example\", \"filters\": { \"type\": [ \"example\" ], \"uri\": [ \"example\" ], \"language\": [ \"example\" ], \"metadata\": { \"status\": [ \"publish\" ], \"category\": [ \"news\", \"guides\" ] }, \"created_at\": { \"gte\": \"2026-04-15T12:00:00Z\", \"lte\": \"2026-04-15T12:00:00Z\" }, \"modified_at\": { \"gte\": \"2026-04-15T12:00:00Z\", \"lte\": \"2026-04-15T12:00:00Z\" } }, \"sort\": [ { \"field\": \"created_at\", \"order\": \"asc\" } ], \"aggregations\": [ { \"name\": \"example\", \"field\": \"example\", \"type\": \"terms\", \"interval\": \"day\", \"size\": 1 } ], \"top_n\": 1 }")

  req, _ := http.NewRequest("POST", url, payload)

  req.Header.Add("Authorization", "Bearer <token>")
  req.Header.Add("Content-Type", "application/json")

  res, _ := http.DefaultClient.Do(req)

  defer res.Body.Close()
  body, _ := io.ReadAll(res.Body)

  fmt.Println(res)
  fmt.Println(string(body))

}

const url = 'https://api.ai.wpengine.com/v1/kb/collections/example/search';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"query":"example","filters":{"type":["example"],"uri":["example"],"language":["example"],"metadata":{"status":["publish"],"category":["news","guides"]},"created_at":{"gte":"2026-04-15T12:00:00Z","lte":"2026-04-15T12:00:00Z"},"modified_at":{"gte":"2026-04-15T12:00:00Z","lte":"2026-04-15T12:00:00Z"}},"sort":[{"field":"created_at","order":"asc"}],"aggregations":[{"name":"example","field":"example","type":"terms","interval":"day","size":1}],"top_n":1}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.ai.wpengine.com/v1/kb/collections/example/search', [
  'body' => '{ "query": "example", "filters": { "type": [ "example" ], "uri": [ "example" ], "language": [ "example" ], "metadata": { "status": [ "publish" ], "category": [ "news", "guides" ] }, "created_at": { "gte": "2026-04-15T12:00:00Z", "lte": "2026-04-15T12:00:00Z" }, "modified_at": { "gte": "2026-04-15T12:00:00Z", "lte": "2026-04-15T12:00:00Z" } }, "sort": [ { "field": "created_at", "order": "asc" } ], "aggregations": [ { "name": "example", "field": "example", "type": "terms", "interval": "day", "size": 1 } ], "top_n": 1 }',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();

curl --request POST \
  --url https://api.ai.wpengine.com/v1/kb/collections/example/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "query": "example", "filters": { "type": [ "example" ], "uri": [ "example" ], "language": [ "example" ], "metadata": { "status": [ "publish" ], "category": [ "news", "guides" ] }, "created_at": { "gte": "2026-04-15T12:00:00Z", "lte": "2026-04-15T12:00:00Z" }, "modified_at": { "gte": "2026-04-15T12:00:00Z", "lte": "2026-04-15T12:00:00Z" } }, "sort": [ { "field": "created_at", "order": "asc" } ], "aggregations": [ { "name": "example", "field": "example", "type": "terms", "interval": "day", "size": 1 } ], "top_n": 1 }'

Searches a collection. Supply a query for combined keyword and semantic matching, returning the most relevant results each with source attribution and matching snippets. Omit the query to browse, filter, sort, or aggregate the collection (no snippets are returned). Narrow results with exact-match filters on post type, URI, language, or metadata, or with created_at/modified_at date ranges. Request facet counts and metrics via aggregations. Requires a valid WP Engine bearer token with search access.

Authorizations

bearerAuth

Parameters

Path Parameters

required

string

The collection ID.

Header Parameters

Agent-Session-Id

string

Optional. The agent session this search is being performed for, when the call answers a tool request from that session. Used only to group the call with the rest of the session’s activity in observability data. It is ignored unless it names a session in the same project as the caller, and it never changes the response.

Request Body^required

application/json

A search over a collection. Supply query for ranked hybrid retrieval (results include snippets). Omit query to browse, filter, sort, or aggregate the collection; query-less results carry no snippets. Aggregations may be requested in either mode.

object

query

Optional natural-language query. When present, results are ranked by relevance and include snippets.

string

filters

Filters applied alongside the query.

object

type

Post types to include.

Array<string>

uri

Document URIs to include.

Array<string>

language

ISO 639-1 language codes to include.

Array<string>

metadata

Exact-match filters keyed by metadata field; each field maps to a list of accepted values.

object

key

additional properties

Array<string>

Example

{
  "status": [
    "publish"
  ],
  "category": [
    "news",
    "guides"
  ]
}

created_at

Inclusive date bounds (RFC-3339). Either bound may be omitted.

object

gte

string format: date-time

lte

string format: date-time

modified_at

Inclusive date bounds (RFC-3339). Either bound may be omitted.

object

gte

string format: date-time

lte

string format: date-time

sort

Order results by typed fields. Supplying sort returns field-ordered results instead of relevance-ranked ones.

Array<object>

object

field

required

string

Allowed values: created_at modified_at title.keyword type uri language

order

Defaults to asc.

string

Allowed values: asc desc

aggregations

Facet counts and metrics computed over the filtered result set.

Array<object>

object

name

required

Key the result is returned under.

string

field

required

Field to aggregate. terms accepts keyword fields (type, uri, language, title.keyword) or metadata.; min/max/date_histogram accept created_at or modified_at.

string

type

required

string

Allowed values: terms min max date_histogram

interval

Required for date_histogram; invalid for other types.

string

Allowed values: day week month quarter year

size

Maximum number of terms buckets to return (default 10). Valid only for terms; invalid for other types.

integer

>= 1 <= 1000

top_n

Maximum results to return (defaults to 10; must be between 1 and 50).

integer

>= 1 <= 50

Responses

200

Ranked results with source attribution

application/json

object

citations

required

Array<object>

A ranked result with its source attribution and matching snippet(s).

object

required

The document id.

string

title

string

uri

string

type

The document’s post type.

string

snippets

The matching content fragment(s).

Array<string>

score

required

The relevance score used to rank this result; higher is more relevant.

number format: double

aggregations

Present only when aggregations were requested; keyed by aggregation name.

object

key

additional properties

Buckets for terms/date_histogram; value for min/max on date fields.

object

buckets

Array<object>

object

key

string

doc_count

integer format: int64

value

RFC-3339 timestamp for min/max on date fields.

string

other_doc_count

Terms only. Documents in buckets beyond the returned size. A non-zero value means the facet was truncated; request a larger size to retrieve more buckets.

integer format: int64

Example^generated

{
  "citations": [
    {
      "id": "example",
      "title": "example",
      "uri": "example",
      "type": "example",
      "snippets": [
        "example"
      ],
      "score": 1
    }
  ],
  "aggregations": {
    "additionalProperty": {
      "buckets": [
        {
          "key": "example",
          "doc_count": 1
        }
      ],
      "value": "example",
      "other_doc_count": 1
    }
  }
}

400

Invalid request body or parameters

application/json

object

error

required

object

message

required

string

type

required

string

code

required

integer

request_id

required

Correlation ID for this request, matching the X-Request-ID response header — a 32-character trace ID behind the load balancer, otherwise a UUID. Quote it in support reports.

string

Example

{
  "error": {
    "type": "invalid_request_error",
    "request_id": "80f1e2c3a4b5c6d7e8f9a0b1c2d3e4f5"
  }
}

401

Missing or invalid bearer token

application/json

object

error

required

object

message

required

string

type

required

string

code

required

integer

request_id

required

Correlation ID for this request, matching the X-Request-ID response header — a 32-character trace ID behind the load balancer, otherwise a UUID. Quote it in support reports.

string

Example

{
  "error": {
    "type": "invalid_request_error",
    "request_id": "80f1e2c3a4b5c6d7e8f9a0b1c2d3e4f5"
  }
}

Headers

WWW-Authenticate

string

Example

Bearer realm="ai-services"

403

The token is valid, but the caller is not permitted to perform this action — either its scope/permission is insufficient or the authenticated user is not authorized for the target account (error type “permission_error”). On /v1/chat/completions specifically, a 403 with error type “content_policy_violation” instead means the request content was blocked by content moderation policy; that response never identifies which filter or category matched.

application/json

object

error

required

object

message

required

string

type

required

string

code

required

integer

request_id

required

Correlation ID for this request, matching the X-Request-ID response header — a 32-character trace ID behind the load balancer, otherwise a UUID. Quote it in support reports.

string

Example

{
  "error": {
    "type": "invalid_request_error",
    "request_id": "80f1e2c3a4b5c6d7e8f9a0b1c2d3e4f5"
  }
}

404

The requested resource was not found

application/json

object

error

required

object

message

required

string

type

required

string

code

required

integer

request_id

required

Correlation ID for this request, matching the X-Request-ID response header — a 32-character trace ID behind the load balancer, otherwise a UUID. Quote it in support reports.

string

Example

{
  "error": {
    "type": "invalid_request_error",
    "request_id": "80f1e2c3a4b5c6d7e8f9a0b1c2d3e4f5"
  }
}

429

Rate limit exceeded. The request was throttled at the edge; wait and retry later. The response body is a short HTML page generated by the load balancer, not a structured JSON error — clients should rely on the 429 status code rather than parsing the body.

text/html

string

503

The knowledge base is not currently available. Retry after a short delay.

application/json

object

error

required

object

message

required

string

type

required

string

code

required

integer

request_id

required

Correlation ID for this request, matching the X-Request-ID response header — a 32-character trace ID behind the load balancer, otherwise a UUID. Quote it in support reports.

string

Example

{
  "error": {
    "type": "invalid_request_error",
    "request_id": "80f1e2c3a4b5c6d7e8f9a0b1c2d3e4f5"
  }
}

Platforms

Product Extensions

Plugins

Tools

Search a knowledge base collection

Authorizations

Parameters

Path Parameters

Header Parameters

Request Body^required

Example

Responses

200

Example^generated

400

Example

401

Example

Headers

Example

403

Example

404

Example

429

503

Example

Authorizations

Parameters

Path Parameters

Header Parameters

Request Bodyrequired

Example

Responses

200

Examplegenerated

400

Example

401

Example

Headers

Example

403

Example

404

Example

429

503

Example

Request Body^required

Example^generated