Bulk-index knowledge base documents

POST

/v1/kb/collections/{id}/documents/bulk

<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.ai.wpengine.com/v1/kb/collections/example/documents/bulk', [
  'body' => '{ "documents": [ { "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();

• Current environment

Indexes multiple documents in one request. Each item is reported independently, so one invalid document does not fail the batch. A request may contain at most 100 documents. Requires a valid WP Engine bearer token.

Authorizations

• bearerAuth

Parameters

Path Parameters

id

required

string

The collection ID.

Request Body^required

Media typeapplication/json

object

documents

required

Array<object>

>= 1 items <= 100 items

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

200

Per-document results, including any per-item failures

Media typeapplication/json

object

items

required

Array<object>

object

id

required

string

result

string

Allowed values: created updated unchanged

status

required

HTTP-style status for this item (e.g. 201, 200, 400).

integer

error

Failure reason, present only when the item failed.

string

Example

{
  "items": [
    {
      "result": "created"
    }
  ]
}

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

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

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.

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

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

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

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"
  }
}