Skip to content
WP EngineDocumentation

Create a knowledge base collection

POST
/v1/kb/collections
<?php


$client = new \GuzzleHttp\Client();


$response = $client->request('POST', 'https://api.ai.wpengine.com/v1/kb/collections', [
  'body' => '{ "name": "Product documentation", "description": "Product documentation, API reference guides, and release changelogs.", "set_primary": true, "metadata": {} }',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);


echo $response->getBody();

Creates a new collection scoped to the caller’s project. The collection name must be unique within the project, non-empty, at most 255 characters, and free of control characters. Requires a valid WP Engine bearer token.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
name
required

Human-readable collection name. Must be non-empty (after trimming surrounding whitespace), at most 255 characters, and free of control characters. Must be unique within the project.

string
<= 255 characters
Example
Product documentation
description

Deprecated. Not used by the LLM search tool.

string
<= 8192 characters
Example
Product documentation, API reference guides, and release changelogs.
set_primary

When true and the caller is site-authenticated, the new collection is also set as the site’s primary KB collection in the same request.

boolean
metadata

Optional structured metadata bag populated by the producer plugin during collection sync. The gateway consumes selected keys when composing the description of this collection’s search tool. Must be a JSON object no larger than 64 KB; any other JSON type (array, string, number, boolean, null) is rejected with 400. Omit to store as SQL NULL.

object

Responses

Section titled “Responses”

201

Section titled “201”

The created collection

Media typeapplication/json
object
id
required

Unique identifier for the collection.

string
project_id
required

The project the collection belongs to.

string
name
required

Human-readable collection name.

string
description
required

Deprecated. Not used by the LLM search tool.

string
created_at
required

When the collection was created (UTC).

string format: date-time
updated_at
required

When the collection was last updated (UTC).

string format: date-time
metadata

Structured metadata bag populated by the producer plugin during collection sync. Omitted from the response when the collection has no metadata set.

object
Example
{
  "name": "Product documentation",
  "description": "Product documentation, API reference guides, and release changelogs."
}

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

409

Section titled “409”

The request conflicts with an existing resource

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