Bulk-index knowledge base documents

POST

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

package main

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

func main() {

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

  payload := strings.NewReader("{ \"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\" ] }, \"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\" ] } ], \"elements_truncated\": true } ] }")

  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/documents/bulk';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  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"]},"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"]}],"elements_truncated":true}]}'
};

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/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" ] }, "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" ] } ], "elements_truncated": true } ] }',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();

curl --request POST \
  --url https://api.ai.wpengine.com/v1/kb/collections/example/documents/bulk \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "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" ] }, "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" ] } ], "elements_truncated": true } ] }'

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

required

string

The collection ID.

Request Body^required

application/json

object

documents

required

Array<object>

>= 1 items <= 100 items

object

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

elements

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.

Array<object>

<= 1000 items

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

tag

required

Lowercase tag name, such as a, img, iframe or embed.

string

/^[a-z][a-z0-9-]{0,31}$/

count

required

How many times the element occurs in the document.

integer

>= 1 <= 1000000

href

Link URL.

string

<= 2048 characters

src

Source URL.

string

<= 2048 characters

domain

Lowercase host of the URL.

string

<= 253 characters

scheme

Lowercase URL scheme, such as https or mailto.

string

/^[a-z][a-z0-9+.-]{0,31}$/

has_query

Whether the URL had a query string.

boolean

internal

Whether the URL points at the site itself.

boolean

target

Link target, such as _blank.

string

<= 64 characters

rel

Link rel tokens, lowercase.

Array<string>

<= 16 items

alt

Image alt text. An empty string means the attribute is present without text; omitted means the attribute is missing.

string

<= 1024 characters

ext

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

keyword

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

key

additional properties

One of:

string
Array<string>

string

<= 1024 characters

url

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

key

additional properties

string

<= 2048 characters

boolean

object

key

additional properties

boolean

long

Whole numbers between -2^53 and 2^53.

object

key

additional properties

integer format: int64

Example

{
  "tag": "a",
  "count": 2,
  "href": "https://example.org/page",
  "domain": "example.org",
  "scheme": "https",
  "has_query": true,
  "internal": false,
  "target": "_blank",
  "rel": [
    "nofollow",
    "noopener"
  ]
}

elements_truncated

True when the client dropped elements to stay within its limits, so the list is incomplete.

boolean

Responses

200

Per-document results, including any per-item failures

application/json

object

items

required

Array<object>

object

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. On agent create and update, error type “profile_unavailable” means the requested profile is not available to the caller.

application/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

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

error_code

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

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

application/json

object

error

required

object

message

required

string

type

required

string

error_code

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

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

error_code

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

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

413

Request body exceeds the 64 KiB limit

application/json

object

error

required

object

message

required

string

type

required

string

error_code

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

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

error_code

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

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

Thanks for the feedback!

Platforms

Product Extensions

Plugins

Tools

Was this helpful?

Bulk-index knowledge base documents

Authorizations

Parameters

Path Parameters

Request Body^required

Example

Example

Responses

200

Example

400

Example

401

Example

Headers

Example

403

Example

404

Example

413

Example

429

503

Example

Was this helpful?

Authorizations

Parameters

Path Parameters

Request Bodyrequired

Example

Example

Responses

200

Example

400

Example

401

Example

Headers

Example

403

Example

404

Example

413

Example

429

503

Example

Was this helpful?

Request Body^required