Skip to content
WP EngineDocumentation

Index a knowledge base document

POST
/v1/kb/collections/{id}/documents
<?php


$client = new \GuzzleHttp\Client();


$response = $client->request('POST', 'https://api.ai.wpengine.com/v1/kb/collections/example/documents', [
  'body' => '{ "id": "example", "content": "example", "title": "example", "type": "example", "uri": "example", "language": "example", "created_at": "2026-04-15T12:00:00Z", "modified_at": "2026-04-15T12:00:00Z", "metadata": { "status": "publish", "category": "news", "tags": [ "guide", "billing" ] } }',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);


echo $response->getBody();

Indexes a single document into the collection. “content” is required and is the text indexed for search. An “id” may be supplied to make index idempotent (re-indexing the same id replaces the document); when omitted the gateway generates one. The “id” must not contain “/”. Concurrent writes to the same id are resolved last-writer-wins. Requires a valid WP Engine bearer token.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
id
required
string

The collection ID.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
id

Stable document id. Supply it to make index idempotent (re-indexing the same id replaces the document); generated when omitted.

string
content
required

The document text indexed for search.

string
title
string
type

Document type (e.g. the WordPress post type).

string
uri

Canonical URL for the document.

string
language

ISO 639-1 language code.

string
created_at
string format: date-time
modified_at
string format: date-time
metadata

Free-form metadata; values are stored as keywords for exact-match filtering.

object
key
additional properties
any
Example
{
  "status": "publish",
  "category": "news",
  "tags": [
    "guide",
    "billing"
  ]
}

Responses

Section titled “Responses”

200

Section titled “200”

An existing id was re-indexed — “updated” if the document changed, or “unchanged” if it was identical (a no-op).

Media typeapplication/json
object
id
required

The document id (supplied or generated).

string
result
required
string
Allowed values: created updated unchanged
Example
{
  "result": "created"
}

201

Section titled “201”

The document was created

Media typeapplication/json
object
id
required

The document id (supplied or generated).

string
result
required
string
Allowed values: created updated unchanged
Example
{
  "result": "created"
}

400

Section titled “400”

Invalid request body or parameters

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

Section titled “401”

Missing or invalid bearer token

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

Section titled “Headers”
WWW-Authenticate
string
Example
Bearer realm="ai-services"

403

Section titled “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.

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

Section titled “404”

The requested resource was not found

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

Section titled “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

Section titled “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
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"
  }
}