Get a knowledge base document
package main
import ( "fmt" "net/http" "io")
func main() {
url := "https://api.ai.wpengine.com/v1/kb/collections/example/documents/example"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
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/documents/example';const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
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('GET', 'https://api.ai.wpengine.com/v1/kb/collections/example/documents/example', [ 'headers' => [ 'Authorization' => 'Bearer <token>', ],]);
echo $response->getBody();curl --request GET \ --url https://api.ai.wpengine.com/v1/kb/collections/example/documents/example \ --header 'Authorization: Bearer <token>'Returns a single document by ID from the collection. Requires a valid WP Engine bearer token.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”The collection ID.
The document ID.
Header Parameters
Section titled “Header Parameters”Optional. The agent session this fetch 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.
Responses
Section titled “Responses”The requested document
The stored document — the indexed fields plus its id and content_hash.
object
Stable document id. Supply it to make index idempotent (re-indexing the same id replaces the document); generated when omitted.
The document text indexed for search.
Document type (e.g. the WordPress post type).
Canonical URL for the document.
ISO 639-1 language code.
Free-form metadata; values are stored as keywords for exact-match filtering.
object
The document’s HTML elements (links, images, embeds), one entry per distinct element with its occurrence count, at most 256 KiB encoded. Send the whole list with every write, or an empty list when the document has none: a write without the field stores the document without elements, removing any stored before. Elements are used by document listing and element aggregations and are not returned when a document is fetched.
One distinct HTML element of a document. href or src is the element’s main URL, without its fragment or query string (the WordPress content parameters p, page_id, attachment_id, cat, tag and author are kept, sorted by name); domain, scheme, has_query and internal describe it. A link with a non-http scheme carries only scheme.
object
Lowercase tag name, such as a, img, iframe or embed.
How many times the element occurs in the document.
Link URL.
Source URL.
Lowercase host of the URL.
Lowercase URL scheme, such as https or mailto.
Whether the URL had a query string.
Whether the URL points at the site itself.
Link target, such as _blank.
Link rel tokens, lowercase.
Image alt text. An empty string means the attribute is present without text; omitted means the attribute is missing.
Custom element attributes, grouped by type. Names are lowercase letters, digits, - and _, starting with a letter, at most 64 characters; an element has at most 16 and a request at most 64 distinct names.
object
Exact-match text values, each a string or a list of up to 16 strings of at most 1024 bytes. Values of an attribute the site declares as an enum are matched in lowercase, so send them lowercase.
object
URL values, at most 2048 bytes. An absolute http or https URL is stored as filters compare it: scheme and host lowercased, fragment and query string dropped except WordPress content parameters.
object
object
Whole numbers between -2^53 and 2^53.
object
True when the client dropped elements to stay within its limits, so the list is incomplete.
The document id.
SHA-256 of the content, set by the gateway.
Example
{ "metadata": { "status": "publish", "category": "news", "tags": [ "guide", "billing" ] }, "elements": [ { "tag": "a", "count": 2, "href": "https://example.org/page", "domain": "example.org", "scheme": "https", "has_query": true, "internal": false, "target": "_blank", "rel": [ "nofollow", "noopener" ] } ]}Missing or invalid bearer token
object
object
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.
Where the customer can resolve the error, set on an entitlement_required refusal that has an error_code when one is configured.
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.
Example
{ "error": { "type": "invalid_request_error", "request_id": "80f1e2c3a4b5c6d7e8f9a0b1c2d3e4f5" }}Headers
Section titled “Headers”Example
Bearer realm="ai-services"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.
object
object
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.
Where the customer can resolve the error, set on an entitlement_required refusal that has an error_code when one is configured.
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.
Example
{ "error": { "type": "invalid_request_error", "request_id": "80f1e2c3a4b5c6d7e8f9a0b1c2d3e4f5" }}The requested resource was not found
object
object
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.
Where the customer can resolve the error, set on an entitlement_required refusal that has an error_code when one is configured.
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.
Example
{ "error": { "type": "invalid_request_error", "request_id": "80f1e2c3a4b5c6d7e8f9a0b1c2d3e4f5" }}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.
The knowledge base is not currently available. Retry after a short delay.
object
object
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.
Where the customer can resolve the error, set on an entitlement_required refusal that has an error_code when one is configured.
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.
Example
{ "error": { "type": "invalid_request_error", "request_id": "80f1e2c3a4b5c6d7e8f9a0b1c2d3e4f5" }}