Settings API

The settings endpoints let you read and write WPfaker's configuration programmatically. This includes general plugin settings (locale, default counts, cleanup behavior) and AI field detection settings (provider, API key, cache). Through these endpoints, you can fully configure WPfaker without ever opening the admin settings screen — which is essential for automated deployments, scripted setup workflows, and multi-site management scenarios where you need to apply consistent configuration across many WordPress installations.

Settings are organized into two groups, each with its own GET and POST endpoint pair. General settings control WPfaker's default behavior and cleanup preferences. AI settings manage the AI provider integration (Google Gemini, Anthropic Claude, or OpenAI GPT) that powers WPfaker's second-tier field detection. Additional read-only endpoints expose the addon registry and sync status.

All settings are persisted in WordPress options and take effect immediately after a successful save. There is no concept of "pending" settings — what you POST is what the plugin uses from that point forward.

TIP

For general information about authentication, error codes, and response format, see the REST API Overview. To learn about the settings from a user perspective, see the General Settings and AI Field Detection guides.

Get All Settings

Retrieve the current general settings and a summary of the AI configuration status. This endpoint returns the complete set of configurable options that control WPfaker's default behavior.

Endpoint

GET /wp-json/wpfaker/v1/settings

Example Request

curl "https://yoursite.com/wp-json/wpfaker/v1/settings" \
  -H "X-WP-Nonce: your-nonce"

Response

{
  "success": true,
  "settings": {
    "general": {
      "admin_locale": "auto",
      "locale": "auto",
      "default_post_count": 5,
      "default_term_count": 5,
      "default_user_count": 5,
      "delete_history_on_deactivate": false,
      "delete_media_with_posts": false,
      "auto_select_default_template": true,
      "delete_related_media": true,
      "delete_related_terms": true,
      "delete_related_authors": true,
      "delete_related_comments": true,
      "default_image_provider": "loremflickr",
      "telemetry_enabled": true,
      "save_and_generate_auto_run": true,
      "child_generate_behavior": "ask",
      "hourly_rate": 75,
      "text_source": "lorem"
    },
    "ai": {
      "enabled": false,
      "provider": "gemini",
      "has_api_key": false,
      "hive_enabled": false
    }
  }
}

Response Fields

Field	Type	Default	Description
general.admin_locale	string	auto	Language for the WPfaker admin UI. "auto" follows WordPress site language.
general.locale	string	auto	Default locale for content generation. "auto" uses the WordPress site locale.
general.default_post_count	integer	5	Pre-filled post count on the generation screen
general.default_term_count	integer	5	Pre-filled term count on the generation screen
general.default_user_count	integer	5	Pre-filled user count on the generation screen
general.delete_history_on_deactivate	boolean	false	Delete all history when the plugin is deactivated
general.delete_media_with_posts	boolean	false	Delete attached media when deleting generated posts
general.auto_select_default_template	boolean	true	Auto-select the default template when switching post types
general.delete_related_media	boolean	true	Delete related media during cleanup operations
general.delete_related_terms	boolean	true	Delete related terms during cleanup operations
general.delete_related_authors	boolean	true	Delete related authors during cleanup operations
general.delete_related_comments	boolean	true	Delete related comments during cleanup operations
general.default_image_provider	string	loremflickr	Default image provider for generation
general.telemetry_enabled	boolean	true	Send anonymous usage data
general.save_and_generate_auto_run	boolean	true	Auto-run generation after saving a template
general.child_generate_behavior	string	ask	Behavior for child templates: ask, child_only, or parent_chain
general.hourly_rate	number	75	Hourly rate (USD) for time-saved calculations
general.text_source	string	lorem	Text generation source: realtext (real-world text) or lorem (Lorem Ipsum)
ai.enabled	boolean	false	Whether AI field detection is turned on
ai.provider	string	gemini	Active AI provider
ai.has_api_key	boolean	—	Whether the active provider has an API key configured
ai.hive_enabled	boolean	false	Whether Hive AI detection is enabled

---

Save General Settings

Update WPfaker's general configuration. You can send any subset of the available settings — only the properties you include in the request body are updated. Omitted properties retain their current values.

Endpoint

POST /wp-json/wpfaker/v1/settings

Parameters

Parameter	Type	Default	Description
admin_locale	string	auto	Admin UI language. "auto" follows WordPress, or specify a locale code.
locale	string	auto	Default content generation locale. "auto" uses the WordPress site locale.
default_post_count	integer	5	Default number of posts on the generation screen
default_term_count	integer	5	Default number of terms on the generation screen
default_user_count	integer	5	Default number of users on the generation screen
delete_history_on_deactivate	boolean	false	Delete all WPfaker history when the plugin is deactivated
delete_media_with_posts	boolean	false	Delete attached media when deleting generated posts
auto_select_default_template	boolean	true	Auto-select the default template when switching post types
delete_related_media	boolean	true	Delete related media during cleanup operations
delete_related_terms	boolean	true	Delete related terms during cleanup operations
delete_related_authors	boolean	true	Delete related authors during cleanup operations
delete_related_comments	boolean	true	Delete related comments during cleanup operations
default_image_provider	string	loremflickr	Default image provider: loremflickr, unsplash, picsum, or placeholder
telemetry_enabled	boolean	true	Send anonymous usage data
save_and_generate_auto_run	boolean	true	Auto-run generation after saving a template
child_generate_behavior	string	ask	Child template behavior: ask, child_only, or parent_chain
hourly_rate	number	75	Hourly rate (USD) for time-saved calculations (minimum 1)
text_source	string	lorem	Text generation source: realtext or lorem

Example Request

curl -X POST "https://yoursite.com/wp-json/wpfaker/v1/settings" \
  -H "X-WP-Nonce: your-nonce" \
  -H "Content-Type: application/json" \
  -d '{
    "admin_locale": "de_DE",
    "locale": "de_DE",
    "default_post_count": 10,
    "default_term_count": 10,
    "default_user_count": 5,
    "delete_history_on_deactivate": false,
    "delete_related_media": true,
    "delete_related_terms": true,
    "delete_related_authors": false
  }'

Response

{
  "success": true,
  "message": "Settings saved successfully",
  "settings": {
    "admin_locale": "de_DE",
    "locale": "de_DE",
    "default_post_count": 10,
    "default_term_count": 10,
    "default_user_count": 5,
    "delete_history_on_deactivate": false,
    "delete_related_media": true,
    "delete_related_terms": true,
    "delete_related_authors": false
  }
}

INFO

The locale setting here is the default locale used when no locale parameter is explicitly provided in a generation request. Individual generation requests can always override it by passing their own locale value. See the Languages guide for the full list of supported locales.

---

Get AI Settings

Retrieve the current AI field detection configuration. This endpoint shows whether AI detection is enabled, whether it is properly configured and ready to use, and a masked version of the API key for display purposes.

WPfaker supports three AI providers for second-tier field detection: Google Gemini, Anthropic Claude, and OpenAI GPT. When pattern-based field name matching does not produce a confident result, the configured AI provider analyzes the field name, label, and context to determine the most appropriate data type. This is configured through the AI settings endpoints.

Endpoint

GET /wp-json/wpfaker/v1/settings/ai

Example Request

curl "https://yoursite.com/wp-json/wpfaker/v1/settings/ai" \
  -H "X-WP-Nonce: your-nonce"

Response

{
  "success": true,
  "settings": {
    "enabled": true,
    "provider": "gemini",
    "has_api_key": true,
    "hive_enabled": false,
    "providers": {
      "gemini": {
        "has_api_key": true,
        "masked_api_key": "AIza...****...xyz"
      },
      "anthropic": {
        "has_api_key": false,
        "masked_api_key": ""
      },
      "openai": {
        "has_api_key": false,
        "masked_api_key": ""
      }
    }
  }
}

Response Fields

Field	Type	Description
settings.enabled	boolean	Whether AI field detection is turned on in settings
settings.provider	string	Active AI provider (gemini, anthropic, or openai)
settings.has_api_key	boolean	Whether the active provider has an API key configured
settings.hive_enabled	boolean	Whether Hive AI detection is enabled
settings.providers	object	Per-provider API key status with masked keys for display

---

Save AI Settings

Update the AI field detection configuration. You can enable or disable AI detection, select a provider, and set API keys per provider. Omitting a key field preserves the existing key for that provider.

Endpoint

POST /wp-json/wpfaker/v1/settings/ai

Parameters

Parameter	Type	Required	Description
enabled	boolean	No	Enable or disable AI field detection
provider	string	No	AI provider: gemini, anthropic, or openai. Defaults to the currently configured provider.
hive_enabled	boolean	No	Enable or disable Hive AI detection
gemini_api_key	string	No	API key for Google Gemini. Omit to keep the existing key.
anthropic_api_key	string	No	API key for Anthropic Claude. Omit to keep the existing key.
openai_api_key	string	No	API key for OpenAI GPT. Omit to keep the existing key.

Example: Enable AI with Gemini Key

curl -X POST "https://yoursite.com/wp-json/wpfaker/v1/settings/ai" \
  -H "X-WP-Nonce: your-nonce" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "provider": "gemini",
    "gemini_api_key": "AIzaSyB..."
  }'

Example: Disable AI (Keep Keys)

curl -X POST "https://yoursite.com/wp-json/wpfaker/v1/settings/ai" \
  -H "X-WP-Nonce: your-nonce" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": false
  }'

Response

{
  "success": true,
  "message": "AI settings saved successfully",
  "settings": {
    "enabled": true,
    "provider": "gemini",
    "has_api_key": true,
    "hive_enabled": false,
    "providers": {
      "gemini": {
        "has_api_key": true,
        "masked_api_key": "AIza...****...xyz"
      },
      "anthropic": {
        "has_api_key": false,
        "masked_api_key": ""
      },
      "openai": {
        "has_api_key": false,
        "masked_api_key": ""
      }
    }
  }
}

TIP

You can obtain API keys from Google AI Studio for Gemini, Anthropic Console for Claude, or OpenAI Platform for GPT. Google Gemini's free tier is sufficient for typical WPfaker usage. See the AI Field Detection guide for step-by-step setup instructions.

---

Test AI Connection

Verify that the configured AI provider is reachable and the API key is valid. This endpoint sends a lightweight test request to the selected provider's API (Google Gemini, Anthropic Claude, or OpenAI GPT) and reports the result. Use it after saving a new API key to confirm everything is working.

Endpoint

POST /wp-json/wpfaker/v1/settings/ai/test

Example Request

curl -X POST "https://yoursite.com/wp-json/wpfaker/v1/settings/ai/test" \
  -H "X-WP-Nonce: your-nonce"

Success Response

{
  "success": true,
  "message": "Connection successful! AI provider is ready to use."
}

Error Responses

The test endpoint returns specific error messages depending on what went wrong.

No API Key Configured:

{
  "success": false,
  "message": "API key is not configured"
}

Invalid API Key:

{
  "success": false,
  "message": "API Error (401): Invalid API key"
}

Network Error:

{
  "success": false,
  "message": "Connection failed: Could not reach AI provider"
}

WARNING

A successful test only verifies that the API key is valid and the provider's endpoint is reachable at the time of the test. It does not guarantee continued availability — AI services may experience temporary outages. WPfaker gracefully falls back to pattern-based detection when AI is unavailable.

---

Clear AI Cache

Clear all cached AI field detection results. WPfaker caches the AI provider's analysis for each field to avoid redundant API calls. Clearing the cache forces WPfaker to re-analyze every field the next time detection runs. This is useful after changing AI settings or providers, updating field definitions in your field plugin, or when you suspect cached results are stale.

Endpoint

POST /wp-json/wpfaker/v1/settings/ai/clear-cache

Example Request

curl -X POST "https://yoursite.com/wp-json/wpfaker/v1/settings/ai/clear-cache" \
  -H "X-WP-Nonce: your-nonce"

Response

{
  "success": true,
  "message": "AI detection cache cleared"
}

INFO

This endpoint clears the AI-specific cache. To clear the broader field detection cache (which includes pattern-based results), use the field detection cache endpoints instead.

---

Settings Storage

Under the hood, WPfaker stores settings in WordPress options. This is primarily an internal detail, but it can be useful for advanced debugging or for interacting with settings through WordPress hooks and filters.

Option Name	Contents
wpfaker_settings	General settings (locale, counts, cleanup behavior)
wpfaker_gemini_settings	AI settings (provider, API key encrypted at rest)

Direct Access (Advanced)

// Get general settings
$settings = get_option('wpfaker_settings', []);

// Get AI settings (option name is historical, supports all providers)
$ai_settings = get_option('wpfaker_gemini_settings', []);

WARNING

Modifying settings directly through update_option() bypasses WPfaker's validation logic. Invalid values may cause unexpected behavior. Always use the API endpoints when possible — they validate all inputs before persisting.