Settings API

The settings endpoints let you read and write Faker Studio'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 Faker Studio 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 Faker Studio's default behavior and cleanup preferences. AI settings manage the AI provider integration (Google Gemini, Anthropic Claude, or OpenAI GPT) that powers Faker Studio'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 Faker Studio's default behavior.

Endpoint

GET /wp-json/faker-studio/v1/settings

Example Request

bash

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

Response

json

{
  "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 Faker Studio 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 Faker Studio'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/faker-studio/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 Faker Studio 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

bash

curl -X POST "https://yoursite.com/wp-json/faker-studio/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

json

{
  "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 (Premium)

Faker Studio Lite

AI-powered field detection is a Premium feature and its settings UI is not shown in Faker Studio Lite.

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.

Faker Studio 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/faker-studio/v1/settings/ai

Example Request

bash

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

Response

json

{
  "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 (Premium)

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/faker-studio/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

bash

curl -X POST "https://yoursite.com/wp-json/faker-studio/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)

bash

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

Response

json

{
  "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 Faker Studio usage. See the AI Field Detection guide for step-by-step setup instructions.

Test AI Connection (Premium)

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/faker-studio/v1/settings/ai/test

Example Request

bash

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

Success Response

json

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

json

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

Invalid API Key:

json

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

Network Error:

json

{
  "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. Faker Studio gracefully falls back to pattern-based detection when AI is unavailable.

Clear AI Cache (Premium)

Clear all cached AI field detection results. Faker Studio caches the AI provider's analysis for each field to avoid redundant API calls. Clearing the cache forces Faker Studio 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/faker-studio/v1/settings/ai/clear-cache

Example Request

bash

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

Response

json

{
  "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, Faker Studio 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
`faker_studio_settings`	General settings (locale, counts, cleanup behavior)
`faker_studio_ai_settings`	AI settings (provider, API key encrypted at rest)

Direct Access (Advanced)

php

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

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

WARNING

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

Settings API ​

Get All Settings ​

Endpoint ​

Example Request ​

Response ​

Response Fields ​

Save General Settings ​

Endpoint ​

Parameters ​

Example Request ​

Response ​

Get AI Settings (Premium) ​

Endpoint ​

Example Request ​

Response ​

Response Fields ​

Save AI Settings (Premium) ​

Endpoint ​

Parameters ​

Example: Enable AI with Gemini Key ​

Example: Disable AI (Keep Keys) ​

Response ​

Test AI Connection (Premium) ​

Endpoint ​

Example Request ​

Success Response ​

Error Responses ​

Clear AI Cache (Premium) ​

Endpoint ​

Example Request ​

Response ​

Settings Storage ​

Direct Access (Advanced) ​

Settings API

Get All Settings

Endpoint

Example Request

Response

Response Fields

Save General Settings

Endpoint

Parameters

Example Request

Response

Get AI Settings (Premium)

Endpoint

Example Request

Response

Response Fields

Save AI Settings (Premium)

Endpoint

Parameters

Example: Enable AI with Gemini Key

Example: Disable AI (Keep Keys)

Response

Test AI Connection (Premium)

Endpoint

Example Request

Success Response

Error Responses

Clear AI Cache (Premium)

Endpoint

Example Request

Response

Settings Storage

Direct Access (Advanced)