Skip to content
WP EngineDocumentation

Suggest categories and tags for content

POST
/v1/content/suggest-taxonomy
<?php


$client = new \GuzzleHttp\Client();


$response = $client->request('POST', 'https://api.ai.wpengine.com/v1/content/suggest-taxonomy', [
  'body' => '{ "model": "google/gemini-3.5-flash", "content": "example", "categories": [ "example" ], "approved_tags": [ "example" ], "new_tag_confidence_threshold": 0.5, "context": "example" }',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);


echo $response->getBody();

Analyzes content and suggests categories from a provided list and relevant tags. Tags are cross-referenced against an optional approved list and flagged as “existing” or “new”. Net-new tags are filtered by a configurable confidence threshold. Requires a valid WP Engine bearer token; API keys must carry the “chat:write” permission.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

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

Optional model identifier. Defaults to a Gemini model when omitted.

string
Example
google/gemini-3.5-flash
content
required

The content to analyze for categorization and tagging.

string
<= 100000 characters
categories
required

Fixed list of categories to select from.

Array<string>
>= 1 items <= 100 items
approved_tags

Optional list of pre-approved tags. Tags matching this list are flagged as “existing” in the response.

Array<string>
<= 500 items
new_tag_confidence_threshold

Minimum confidence for including net-new tags. Tags with source “new” below this threshold are excluded from the response.

number format: double
default: 0.5 <= 1
context

Optional context describing the content domain (e.g. “newsroom article”, “product listing”).

string

Responses

Section titled “Responses”

200

Section titled “200”

Suggested categories and tags

Media typeapplication/json
object
categories
required
Array<object>
object
name
required

Category name from the provided list.

string
confidence
required

Confidence score between 0.0 and 1.0.

number format: double
tags
required
Array<object>
object
name
required

The suggested tag.

string
confidence
required

Confidence score between 0.0 and 1.0.

number format: double
source
required

Whether the tag matched the approved list (“existing”) or was generated by the model (“new”).

string
Allowed values: existing new
model
required

The model used for generation.

string
Example
{
  "tags": [
    {
      "source": "existing"
    }
  ]
}

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"

402

Section titled “402”

The account’s credit balance is exhausted. Grant or top up credits before retrying. Distinct from 429, which is edge rate limiting.

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

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

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

502

Section titled “502”

Upstream provider returned an error

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

503

Section titled “503”

A required dependency is temporarily unavailable. Retry after a short delay with exponential back-off.

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