REST API Overview

WPfaker provides a comprehensive REST API that exposes every piece of plugin functionality to external consumers. Every action available through the admin user interface — generating posts, managing templates, adjusting settings, reviewing history — can also be performed through a standard HTTP request. This makes the API the foundation for build automation, CI/CD pipeline integration, scripted testing workflows, and any scenario where you need to control WPfaker without opening the WordPress admin panel.

The API follows WordPress REST API conventions. All endpoints live under a dedicated namespace, return JSON responses, and enforce the same capability checks that protect the admin UI. If you have built integrations with other WordPress REST endpoints before, the WPfaker API will feel immediately familiar. If this is your first time working with the WordPress REST API, the authentication and response format sections below will get you up to speed quickly.

The endpoints are organized into logical groups that mirror the plugin's feature areas: content generation, template management, site information queries, plugin settings, generation history, license management, cleanup operations, and field detection cache management. Each group has its own dedicated documentation page with full parameter tables, curl examples, and annotated response bodies. This overview page serves as both a quick reference and a starting point for navigating to the detailed endpoint documentation.

Base URL

Every WPfaker endpoint is registered under the wpfaker/v1 namespace within the WordPress REST API:

https://yoursite.com/wp-json/wpfaker/v1/

If your WordPress installation uses a non-standard REST API prefix or runs in a subdirectory, adjust the base URL accordingly. You can always discover the correct REST URL by checking the link header on any WordPress page or by visiting https://yoursite.com/wp-json/.

Authentication

All WPfaker endpoints require the requesting user to be authenticated and to hold the manage_options capability, which in a default WordPress installation is granted only to the Administrator role. Unauthenticated requests or requests from users without sufficient privileges receive a 403 Forbidden response.

WPfaker supports three authentication methods. Choose the one that fits your use case.

Cookie + Nonce (Browser and Ajax)

When making requests from JavaScript running inside the WordPress admin (or any authenticated front-end context), use the cookie-based authentication that WordPress provides by default. The current user's authentication cookie is sent automatically by the browser; you only need to include the nonce in an X-WP-Nonce header to prove the request is intentional.

fetch('/wp-json/wpfaker/v1/settings', {
  headers: {
    'X-WP-Nonce': wpfakerData.nonce
  }
});

This is the method that WPfaker's own React admin interface uses internally. The nonce value is localized into the wpfakerData global object when the plugin's admin page loads.

Application Passwords (WordPress 5.6+)

For external tools, scripts, and services that run outside the browser, Application Passwords are the recommended authentication method. Application Passwords were introduced in WordPress 5.6 and allow you to create a dedicated password for API access without exposing your main WordPress credentials.

To create an Application Password, navigate to Users > Profile in the WordPress admin and scroll to the Application Passwords section. Enter a name for the application and click Add New Application Password. Use the generated password in HTTP Basic Auth headers:

curl -u "admin:xxxx xxxx xxxx xxxx xxxx xxxx" \
  "https://yoursite.com/wp-json/wpfaker/v1/settings"

TIP

Application Passwords contain spaces. Include them exactly as WordPress generates them — the spaces are part of the password and are required for authentication to succeed.

Basic Auth Plugin (Development Only)

For local development environments where convenience outweighs security, you can install the Basic Auth plugin and authenticate with your regular WordPress username and password:

curl -u "admin:password" \
  "https://yoursite.com/wp-json/wpfaker/v1/settings"

DANGER

Never use the Basic Auth plugin on a production server. It transmits your WordPress credentials in plain text (base64-encoded) with every request. Application Passwords are the correct choice for any environment accessible over the network.

Response Format

All WPfaker endpoints return JSON. Successful responses include a success flag set to true along with the relevant data. Depending on the endpoint, data may appear under a data key, a settings key, or directly in the response body.

Success Response

{
  "success": true,
  "data": { ... },
  "message": "Operation completed"
}

Error Response

Error responses set success to false and include a machine-readable error code alongside a human-readable message:

{
  "success": false,
  "code": "error_code",
  "message": "Error description"
}

Error Codes

WPfaker uses standard HTTP status codes combined with descriptive error codes to help you diagnose problems programmatically.

HTTP Status	Error Code	Description
400	invalid_post_type	The specified post type does not exist on this WordPress installation
400	invalid_taxonomy	The specified taxonomy does not exist
400	invalid_count	The count parameter is outside the allowed range
400	invalid_parameter	A required parameter is missing or has an invalid value
401	rest_not_logged_in	The request is not authenticated
403	rest_forbidden	The authenticated user does not have the manage_options capability
404	not_found	The requested resource (template, history entry, etc.) does not exist
500	generation_failed	An internal error occurred during content generation

Endpoint Reference

The following tables list every endpoint in the WPfaker REST API, grouped by functional category. Each endpoint links to its detailed documentation page where you will find complete parameter descriptions, curl examples, and response bodies.

Generation Endpoints

These endpoints create and delete fake content. They are the core of WPfaker's functionality.

Method	Endpoint	Description
POST	/generate/posts	Generate posts for any registered post type
POST	/generate/posts/stream	Generate posts (streaming) with real-time SSE progress
POST	/generate/posts/delete	Delete posts (chunked) with pre-generation cleanup
POST	/generate/terms	Generate taxonomy terms with optional hierarchy
POST	/generate/users	Generate WordPress users with configurable roles
POST	/generate/comments	Generate comments for existing posts
DELETE	/generate/delete	Delete generated content by ID, type, or comment

Template Endpoints

Manage the saved generation configurations that make repeatable content generation possible.

Method	Endpoint	Description
GET	/templates	List all templates, optionally filtered by post type
GET	/templates/{id}	Get a single template with full configuration
POST	/templates	Create a new template
PUT	/templates/{id}	Update an existing template
DELETE	/templates/{id}	Delete a template
POST	/templates/{id}/default	Set a template as default for its post type
POST	/templates/{id}/duplicate	Duplicate a template
GET	/templates/export	Export templates as portable JSON (accepts ids array or post_type filter)
POST	/templates/import	Import a template from exported JSON
GET	/templates/fields/{post_type}	Get available fields for a post type
GET	/templates/taxonomies/{post_type}	Get taxonomies registered for a post type
GET	/taxonomies/{taxonomy}/terms	Get taxonomy terms with search and pagination
GET	/field-schema/{field_type}	Get field schema for a specific field type
POST	/templates/{id}/variant	Create a variant from a parent template
GET	/templates/{id}/effective-config	Get effective config (merged for variants)
GET	/templates/stale	Get stale templates that need resync

Information Endpoints

Read-only endpoints that return information about your WordPress installation's structure and WPfaker's capabilities.

Method	Endpoint	Description
GET	/cpts/all	All registered post types with labels and settings
GET	/cpts/supports/{cpt}	Features supported by a specific post type
GET	/taxonomies/all	All registered taxonomies
GET	/fields/{post_type}	Custom fields detected for a post type
GET	/field-plugins	Active field plugin adapters and their status
GET	/detected-plugins	All detected field plugins on the installation
GET	/image-providers	Available image providers with categories and capabilities
GET	/languages	Supported locales for content generation
GET	/variation-profiles	Available variation profiles with descriptions
GET	/post-meta/{id}	Post meta for a generated item by numeric post ID
GET	/dependencies/{post_type}	Cross-CPT dependencies for a post type
GET	/urls	Plugin URLs and version information
GET	/users	Get users with role filtering and search
GET	/users/roles	Get available user roles
GET	/history/stats	Generation statistics by content type
GET	/time-saved	Time savings estimate from automated generation

Settings Endpoints

Read and write plugin configuration.

Method	Endpoint	Description
GET	/settings	Get all settings (general, defaults, related content)
POST	/settings	Save general settings
GET	/settings/ai	Get AI detection settings
POST	/settings/ai	Save AI settings (provider, API key)
POST	/settings/ai/test	Test AI connection
POST	/settings/ai/clear-cache	Clear AI detection cache
GET	/addons	Get registered addons
GET	/sync/status	Get sync status
POST	/sync/mark-seen	Mark sync result as seen

History Endpoints

Track generated content and manage the generation log.

Method	Endpoint	Description
GET	/history	Paginated history list with type filtering
GET	/history/stats	Statistics summary by content type and subtype
GET	/time-saved	Time savings calculation
DELETE	/time-saved	Reset time savings data to zero
DELETE	/history/{id}	Delete a single history entry
DELETE	/history/clear	Clear all history records (content remains)
POST	/history/cleanup	Remove orphaned entries

License Endpoints

Manage plugin license activation.

Method	Endpoint	Description
GET	/license	Get current license status
POST	/license/activate	Activate a license key
POST	/license/deactivate	Deactivate the current license
POST	/license/refresh	Refresh license status from the server

Cleanup Endpoints

Bulk deletion of generated content and cached data.

Method	Endpoint	Description
DELETE	/cleanup/all	Delete all generated content (posts, terms, users, media)
DELETE	/field-detections	Clear all field detection cache
DELETE	/field-detections/{post_type}	Clear field detection cache for a specific post type

Media Endpoints

Manage media library items related to content generation.

Method	Endpoint	Description
POST	/media/download	Download an image from a URL into the media library
GET	/media/images	Get images from the media library
GET	/media/files	Get files from the media library
POST	/media/upload-url	Upload a file from an external URL
POST	/media/upload	Upload a file from the local filesystem

Rate Limiting

WPfaker does not impose its own rate limiting on API requests. However, practical limits apply at the per-request level to prevent server overload and timeouts:

Operation	Max per Request	Reason
Post generation	500	Dynamic capacity system adjusts based on server resources
Term generation	500	Dynamic capacity system adjusts based on server resources
User generation	500	Dynamic capacity system adjusts based on server resources

INFO

External image providers (Unsplash, LoremFlickr) may impose their own rate limits on API calls. If you are generating large numbers of posts with downloaded images, you may encounter provider-side throttling. WPfaker handles these errors gracefully by skipping the featured image for affected posts and reporting the count of posts generated without images in the response.

Pagination

History endpoints support cursor-based pagination through limit and offset query parameters:

curl "https://yoursite.com/wp-json/wpfaker/v1/history?limit=50&offset=0" \
  -H "X-WP-Nonce: your-nonce"

Parameter	Type	Default	Description
limit	integer	50	Number of entries per page
offset	integer	0	Number of entries to skip

The response includes a total count so you can implement pagination in your client.

Filtering

History endpoints support filtering by content type:

# Only posts
GET /history?type=post

# Only taxonomy terms
GET /history?type=term

# Only users
GET /history?type=user

Detailed Documentation

Each endpoint category has its own page with full parameter tables, curl examples, and annotated response bodies:

• Generation Endpoints — Create posts, terms, and users; delete generated content
• Template Endpoints — Create, update, duplicate, export, import, and sync templates
• Information Endpoints — Query post types, taxonomies, fields, image providers, and languages
• Settings Endpoints — Read and write general settings, AI configuration, addons, and sync status
• History Endpoints — Browse generation history, view statistics, and clean up content