---
title: Search a knowledge base collection
url: https://developers.wpengine.com/docs/ai/api/reference/operations/searchcollection/
image: https://developers.wpengine.com/og/docs/ai/api/reference/operations/searchcollection.png
---

# Search a knowledge base collection

POST

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

Select code sample

```php
<?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", "element": { "tag": "a", "conditions": [ { "attribute": "internal", "op": "eq", "value": false }, { "attribute": "target", "op": "neq", "value": "_blank" } ] }, "interval": "day", "size": 1 } ], "top_n": 1 }',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);


echo $response->getBody();
```

- Current environment

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](https://developers.wpengine.com/docs/ai/api/reference/#bearerauth)**

## Parameters

### Path Parameters

**id**

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. The call is grouped with the rest of the session’s activity in observability data. When the session has `site_ids`, a collection that is not the knowledge base of one of those sites is refused with 403 `site_not_in_scope`. A value that does not name a session in the caller’s project is refused with 403 `agent_session_invalid`.

## Request Bodyrequired

Media typeapplication/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

```json
{
  "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; element_terms accepts `tag` or an element attribute such as `domain`, `target` or a custom attribute the site indexes.

string

**type**

required

Element_terms counts documents by an element attribute among the elements `element` selects, for example the most-linked external domains. It needs element data from the site’s sync; a collection without it returns 400 `element_data_unavailable`.

string

Allowed values: terms min max date_histogram element_terms

**element**

Selects documents with at least one element of `tag` that meets every condition. Attributes a site does not index are refused with the ones it does.

object

**tag**

required

Element tag, such as `a`, `img`, `iframe`, `video`, `audio` or `embed`.

string

**conditions**

Array\<object>

<= 8 items

object

**attribute**

required

Attribute name: `href`, `src`, `domain`, `scheme`, `internal`, `has_query`, `target`, `rel`, `alt`, or a custom attribute the site indexes.

string

**op**

required

`eq` and `neq` compare with `value`; `neq` also matches elements without the attribute. `present` and `missing` test whether the attribute is set. `blank` means missing or empty, such as an image with no alt text.

string

Allowed values: eq neq missing present blank

**value**

One of:

- [string](https://developers.wpengine.com/docs/ai/api/reference/operations/searchcollection/#tab-panel-0-0)
- [boolean](https://developers.wpengine.com/docs/ai/api/reference/operations/searchcollection/#tab-panel-0-1)
- [integer](https://developers.wpengine.com/docs/ai/api/reference/operations/searchcollection/#tab-panel-0-2)

string

### Example

```json
{
  "tag": "a",
  "conditions": [
    {
      "attribute": "internal",
      "op": "eq",
      "value": false
    },
    {
      "attribute": "target",
      "op": "neq",
      "value": "_blank"
    }
  ]
}
```

**interval**

Required for date_histogram; invalid for other types.

string

Allowed values: day week month quarter year

**size**

Maximum number of buckets to return (default 10). Valid only for terms and element_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

Media typeapplication/json

object

**citations**

required

Array\<object>

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

object

**id**

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**

Number of documents in the bucket.

integer format: int64

**elements**

For element_terms, the number of element occurrences with the key.

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

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

### 400

Invalid request body or parameters. On agent create and update, error type “profile_unavailable” means the requested profile is not available to the caller.

Media typeapplication/json

object

**error**

required

object

**message**

required

string

**type**

required

string

**error_code**

Stable, machine-readable cause, set by routes that document their codes (the AI readiness and account AI routes, and an entitlement_required refusal, where it is one of not_eligible, terms_required, not_enabled or suspended); absent elsewhere and on errors from shared layers such as authentication. Clients must allow new codes.

string

**portal_url**

Where the customer can resolve the error, set on an entitlement_required refusal that has an error_code when one is configured.

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

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

### 401

Missing or invalid bearer token

Media typeapplication/json

object

**error**

required

object

**message**

required

string

**type**

required

string

**error_code**

Stable, machine-readable cause, set by routes that document their codes (the AI readiness and account AI routes, and an entitlement_required refusal, where it is one of not_eligible, terms_required, not_enabled or suspended); absent elsewhere and on errors from shared layers such as authentication. Clients must allow new codes.

string

**portal_url**

Where the customer can resolve the error, set on an entitlement_required refusal that has an error_code when one is configured.

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

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

#### Headers

**WWW-Authenticate**

string

##### Example

```
Bearer realm="ai-services"
```

### 403

The token is valid, but the request is forbidden. Error type “permission_error” means the token’s scope/permission is insufficient or the authenticated user is not authorized for the target account; “entitlement_required” means the account may not use WP Engine AI, with error_code giving why when known (not_eligible, terms_required, not_enabled or suspended) and portal_url where to fix it; “account_required” means no billing account could be resolved; and “billing_account_pending” means billing isn’t set up for the account yet, usually because its setup after AI was turned on hasn’t finished. Retry shortly. On /v1/chat/completions when content moderation is enabled, and on /v1/sessions/{session_id}/events, 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.

Media typeapplication/json

object

**error**

required

object

**message**

required

string

**type**

required

string

**error_code**

Stable, machine-readable cause, set by routes that document their codes (the AI readiness and account AI routes, and an entitlement_required refusal, where it is one of not_eligible, terms_required, not_enabled or suspended); absent elsewhere and on errors from shared layers such as authentication. Clients must allow new codes.

string

**portal_url**

Where the customer can resolve the error, set on an entitlement_required refusal that has an error_code when one is configured.

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

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

### 404

The requested resource was not found

Media typeapplication/json

object

**error**

required

object

**message**

required

string

**type**

required

string

**error_code**

Stable, machine-readable cause, set by routes that document their codes (the AI readiness and account AI routes, and an entitlement_required refusal, where it is one of not_eligible, terms_required, not_enabled or suspended); absent elsewhere and on errors from shared layers such as authentication. Clients must allow new codes.

string

**portal_url**

Where the customer can resolve the error, set on an entitlement_required refusal that has an error_code when one is configured.

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

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

### 413

Request body exceeds the 64 KiB limit

Media typeapplication/json

object

**error**

required

object

**message**

required

string

**type**

required

string

**error_code**

Stable, machine-readable cause, set by routes that document their codes (the AI readiness and account AI routes, and an entitlement_required refusal, where it is one of not_eligible, terms_required, not_enabled or suspended); absent elsewhere and on errors from shared layers such as authentication. Clients must allow new codes.

string

**portal_url**

Where the customer can resolve the error, set on an entitlement_required refusal that has an error_code when one is configured.

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

```json
{
  "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.

Media typetext/html

string

### 503

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

Media typeapplication/json

object

**error**

required

object

**message**

required

string

**type**

required

string

**error_code**

Stable, machine-readable cause, set by routes that document their codes (the AI readiness and account AI routes, and an entitlement_required refusal, where it is one of not_eligible, terms_required, not_enabled or suspended); absent elsewhere and on errors from shared layers such as authentication. Clients must allow new codes.

string

**portal_url**

Where the customer can resolve the error, set on an entitlement_required refusal that has an error_code when one is configured.

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

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

## Was this helpful?

Thanks for the feedback!

```json
{"@context":"https://schema.org","@graph":[{"@type":"WebSite","@id":"https://developers.wpengine.com/#website","name":"WP Engine Product Documentation","url":"https://developers.wpengine.com/","description":"Resources for developing, deploying, and scaling on WP Engine.","inLanguage":"en-US","keywords":["API documentation","product documentation","headless WordPress","managed WordPress hosting"],"publisher":{"@id":"https://wpengine.com/#organization"}}]}
```