Generation API

The generation endpoints are the heart of WPfaker's REST API. They let you create posts, taxonomy terms, and users programmatically, with the same level of control over content configuration that the admin UI provides. Whether you are populating a staging site during a deployment script, seeding a test database before running an automated test suite, or building a custom admin tool that triggers content generation on demand, these endpoints give you full access to WPfaker's generation engine through standard HTTP requests.

Each generation endpoint accepts a JSON request body that mirrors the options available in the corresponding admin screen. You can specify the content type and count, configure image handling, control taxonomy assignment, and pass a complete field configuration inline or reference a saved template. The response includes detailed statistics about what was generated — how many items were created, which IDs were assigned, how many received featured images, and which authors or taxonomy terms were used.

The delete endpoint complements the generation endpoints by allowing you to remove generated content selectively. You can delete specific items by ID, delete all items of a given type, and control whether related media, terms, and authors are removed along with the primary content. This makes the generation endpoints a complete create-and-destroy toolkit for managing test data.

TIP

For general information about authentication, error codes, and response format, see the REST API Overview.

Generate Posts

Create fake posts for any registered post type. This endpoint supports the full range of WPfaker's generation options, including template-based configuration, inline field configuration, automatic taxonomy assignment, and automatic comment generation.

Endpoint

POST /wp-json/wpfaker/v1/generate/posts

Parameters

Parameter	Type	Required	Default	Description
`post_type`	string	No	`post`	Slug of any registered post type
`count`	integer	No	5	Number of posts to generate (1--500)
`post_status`	string	No	`publish`	Post status: `publish`, `draft`, `pending`, `private`, `future`, or `random`
`set_featured_image`	boolean	No	`true`	Whether to assign a featured image to generated posts
`download_images`	boolean	No	`true`	Download new images from the provider (`true`) or reuse existing media library images (`false`)
`image_provider`	string	No	`unsplash`	Image source: `loremflickr`, `unsplash`, `picsum`, or `placeholder`
`image_category`	string	No	—	Category hint for providers that support it (e.g., `nature`, `business`)
`image_width`	integer	No	1200	Image width in pixels (100--4000)
`image_height`	integer	No	800	Image height in pixels (100--4000)
`populate_custom_fields`	boolean	No	`true`	Populate custom fields detected by active field plugin adapters
`auto_taxonomies`	boolean	No	`true`	Automatically assign taxonomy terms to generated posts
`delete_existing_before_generate`	boolean	No	`false`	Delete all existing WPfaker-generated posts of this type before generating new ones
`delete_related_media`	boolean	No	`false`	Also delete attached media when `delete_existing_before_generate` is `true`
`delete_related_terms`	boolean	No	`false`	Also delete taxonomy terms when `delete_existing_before_generate` is `true`
`delete_related_authors`	boolean	No	`false`	Also delete author accounts when `delete_existing_before_generate` is `true`
`delete_related_comments`	boolean	No	`false`	Also delete comments when `delete_existing_before_generate` is `true`
`delete_scope`	string	No	`current_type`	Scope for pre-generation deletion: `current_type` or `all`
`taxonomy_config`	object	No	—	Taxonomy assignment configuration (same schema as template taxonomy config)
`auto_comments`	boolean	No	`false`	Generate comments on each created post
`comments_per_post_min`	integer	No	0	Minimum comments per post (when `auto_comments` is `true`)
`comments_per_post_max`	integer	No	10	Maximum comments per post (when `auto_comments` is `true`)
`enable_comment_threading`	boolean	No	`true`	Allow threaded reply chains in auto-generated comments
`comment_reply_probability`	integer	No	40	Percentage chance a comment becomes a reply (0--100)
`related_cpt_options`	object	No	—	Per-CPT overrides for auto-created related posts
`template_id`	integer	No	—	Use a saved template's configuration (see Templates)
`field_config`	object	No	—	Inline field configuration that overrides template settings

INFO

When both template_id and field_config are provided, the inline field_config takes precedence over the template's field configuration. All other template settings (image options, variation, etc.) still apply from the template unless explicitly overridden by other parameters in the request.

Example: Basic Post Generation

bash

curl -X POST "https://yoursite.com/wp-json/wpfaker/v1/generate/posts" \
  -H "X-WP-Nonce: your-nonce" \
  -H "Content-Type: application/json" \
  -d '{
    "post_type": "post",
    "count": 10,
    "post_status": "publish",
    "set_featured_image": true,
    "download_images": true,
    "image_provider": "unsplash",
    "image_width": 1200,
    "populate_custom_fields": true,
    "auto_taxonomies": true
  }'

Example: Using a Saved Template

When you have a saved template that already contains the correct field configuration, image settings, and taxonomy rules for a post type, reference it by ID:

bash

curl -X POST "https://yoursite.com/wp-json/wpfaker/v1/generate/posts" \
  -H "X-WP-Nonce: your-nonce" \
  -H "Content-Type: application/json" \
  -d '{
    "post_type": "property",
    "count": 20,
    "template_id": 5
  }'

Example: Using Inline Field Config

Pass field configuration directly in the request without creating a saved template. This is useful for one-off generation runs or scripted scenarios where the configuration changes between runs:

bash

curl -X POST "https://yoursite.com/wp-json/wpfaker/v1/generate/posts" \
  -H "X-WP-Nonce: your-nonce" \
  -H "Content-Type: application/json" \
  -d '{
    "post_type": "product",
    "count": 5,
    "field_config": {
      "core_fields": {
        "post_title": {
          "mode": "create",
          "create": {"method": "words", "word_count_min": 2, "word_count_max": 6}
        },
        "post_content": {
          "mode": "create",
          "create": {"method": "paragraphs", "paragraph_count_min": 3, "paragraph_count_max": 8}
        }
      },
      "custom_fields": {
        "price": {
          "mode": "create",
          "field_type": "number",
          "create": {"min": 10, "max": 500, "decimal_places": 2}
        },
        "sku": {
          "mode": "create",
          "field_type": "text",
          "create": {"method": "words", "word_count_min": 1, "word_count_max": 1}
        }
      }
    }
  }'

TIP

The field_config parameter uses the same schema as template field configurations. See the Field Configuration Schema section on the Templates API page for complete documentation of all available field modes and options.

Example: Pre-Generation Cleanup

Delete all existing generated posts of a type before creating new ones. Related media, terms, and authors are also removed when their respective flags are set.

bash

curl -X POST "https://yoursite.com/wp-json/wpfaker/v1/generate/posts" \
  -H "X-WP-Nonce: your-nonce" \
  -H "Content-Type: application/json" \
  -d '{
    "post_type": "post",
    "count": 25,
    "delete_existing_before_generate": true,
    "delete_related_media": true,
    "delete_related_terms": true,
    "auto_comments": true,
    "comments_per_post_min": 2,
    "comments_per_post_max": 8
  }'

Success Response

json

{
  "success": true,
  "count": 10,
  "ids": [101, 102, 103, 104, 105, 106, 107, 108, 109, 110],
  "message": "10 post generated successfully",
  "warnings": [],
  "variation_stats": {
    "with_featured_image": 7,
    "without_featured_image": 3
  },
  "auto_created": {
    "authors": 3,
    "terms": { "category": 5, "post_tag": 8 },
    "comments": 0,
    "related_posts": 0,
    "related_per_cpt": {}
  },
  "time_saved": "30 min"
}

The with_featured_image and without_featured_image counts may differ from your expectations when image providers encounter rate limits or temporary errors. WPfaker does not fail the entire generation run when an image download fails -- it creates the post without a featured image and moves on, then reports the final counts in the response.

Generate Terms

Create fake taxonomy terms for any registered taxonomy. This endpoint supports both flat term lists and hierarchical term structures, making it suitable for populating categories, tags, custom taxonomies, and deeply nested classification trees.

When generate_hierarchy is enabled, WPfaker creates a tree structure where each level contains the number of terms specified by breadth, and the tree extends to the depth specified by depth. The total number of terms created in hierarchical mode is determined by the tree structure rather than the count parameter.

Endpoint

POST /wp-json/wpfaker/v1/generate/terms

Parameters

Parameter	Type	Required	Default	Description
`taxonomy`	string	No	`category`	Taxonomy slug (e.g., `category`, `post_tag`, `product_cat`)
`count`	integer	No	5	Number of terms to generate (1--500). Ignored when `generate_hierarchy` is `true`.
`generate_hierarchy`	boolean	No	`false`	Create nested term structures instead of a flat list
`depth`	integer	No	3	Number of nesting levels (1--5). Only used when `generate_hierarchy` is `true`.
`breadth`	integer	No	3	Terms per level (1--10). Only used when `generate_hierarchy` is `true`.
`delete_existing`	boolean	No	`false`	Delete all existing WPfaker-generated terms for this taxonomy before generating new ones

WARNING

When generate_hierarchy is true, the count parameter is ignored. The total number of terms created depends on the depth and breadth settings. For example, depth 3 and breadth 3 creates up to 39 terms (3 + 9 + 27).

Example: Flat Term List

bash

curl -X POST "https://yoursite.com/wp-json/wpfaker/v1/generate/terms" \
  -H "X-WP-Nonce: your-nonce" \
  -H "Content-Type: application/json" \
  -d '{
    "taxonomy": "post_tag",
    "count": 20
  }'

Example: Hierarchical Categories

bash

curl -X POST "https://yoursite.com/wp-json/wpfaker/v1/generate/terms" \
  -H "X-WP-Nonce: your-nonce" \
  -H "Content-Type: application/json" \
  -d '{
    "taxonomy": "category",
    "generate_hierarchy": true,
    "depth": 3,
    "breadth": 3
  }'

Success Response

json

{
  "success": true,
  "count": 39,
  "ids": [10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, 48],
  "deleted_count": 0,
  "message": "39 category terms generated successfully",
  "time_saved": "1h 30 min"
}

Generate Users

Create fake WordPress user accounts with realistic profile data. WPfaker generates complete user profiles including first name, last name, email address, biographical description, and website URL.

Generated users are never assigned the Administrator role unless you explicitly request it, and the default allowed_roles restricts generation to subscriber, contributor, and author roles.

Endpoint

POST /wp-json/wpfaker/v1/generate/users

Parameters

Parameter	Type	Required	Default	Description
`count`	integer	No	5	Number of users to generate (1--500)
`role`	string	No	—	Assign a specific role to all generated users. When empty, roles are assigned randomly from `allowed_roles`.
`allowed_roles`	array	No	`["subscriber", "contributor", "author"]`	Roles eligible for random assignment
`generate_avatars`	boolean	No	`true`	Download portrait photos as profile pictures for generated users
`avatar_provider`	string	No	`unsplash`	Image provider for avatars: `loremflickr`, `unsplash`, `picsum`, or `placeholder`
`delete_existing`	boolean	No	`false`	Delete all existing WPfaker-generated users before generating new ones

WARNING

Be cautious when including editor or administrator in allowed_roles. Generated users with elevated roles have real WordPress capabilities and can modify content, install plugins, or change settings.

Example: Random Roles

bash

curl -X POST "https://yoursite.com/wp-json/wpfaker/v1/generate/users" \
  -H "X-WP-Nonce: your-nonce" \
  -H "Content-Type: application/json" \
  -d '{
    "count": 10,
    "allowed_roles": ["subscriber", "contributor", "author"],
    "generate_avatars": true
  }'

Example: Specific Role

bash

curl -X POST "https://yoursite.com/wp-json/wpfaker/v1/generate/users" \
  -H "X-WP-Nonce: your-nonce" \
  -H "Content-Type: application/json" \
  -d '{
    "count": 5,
    "role": "author"
  }'

Success Response

json

{
  "success": true,
  "count": 10,
  "ids": [5, 6, 7, 8, 9, 10, 11, 12, 13, 14],
  "deleted_count": 0,
  "message": "10 users generated successfully",
  "time_saved": "45 min"
}

Delete Generated Content

Remove content that was previously generated by WPfaker. This endpoint provides two modes of operation: deleting specific items by their WordPress IDs, or deleting all generated items of a given type.

This endpoint works by querying WPfaker's history table and the _wpfaker_generated post meta flag to identify which items were created by the plugin. Items that were created manually or by other tools are never affected.

Endpoint

DELETE /wp-json/wpfaker/v1/generate/delete

Parameters

Parameter	Type	Required	Default	Description
`type`	string	Yes	—	Content type to delete: `post`, `term`, `user`, or `comment`
`ids`	array	No	`[]`	Array of specific WordPress item IDs to delete. When empty, deletes all generated items of the given type.
`force`	boolean	No	`false`	Permanently delete items instead of moving to trash

INFO

For fine-grained cleanup with related content deletion (media, terms, authors, comments, related CPTs), use the Delete Posts (Chunked) endpoint instead. For a complete wipe of all generated content, use the cleanup/all endpoint.

Example: Delete Specific Posts

bash

curl -X DELETE "https://yoursite.com/wp-json/wpfaker/v1/generate/delete" \
  -H "X-WP-Nonce: your-nonce" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "post",
    "ids": [101, 102, 103],
    "force": true
  }'

Example: Delete All Generated Users

bash

curl -X DELETE "https://yoursite.com/wp-json/wpfaker/v1/generate/delete" \
  -H "X-WP-Nonce: your-nonce" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "user",
    "force": true
  }'

Example: Delete All Generated Comments

bash

curl -X DELETE "https://yoursite.com/wp-json/wpfaker/v1/generate/delete" \
  -H "X-WP-Nonce: your-nonce" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "comment"
  }'

Success Response

When ids are provided, only those items are deleted. When ids is empty, all generated items of the given type are removed.

json

{
  "success": true,
  "deleted": 3,
  "message": "3 items deleted"
}

Generate Comments

Create fake comments on existing posts. WPfaker generates realistic comment threads with optional threading, anonymous commenters, and avatar downloads. Comments target all published posts of the specified post type, or a specific set of post IDs.

Endpoint

POST /wp-json/wpfaker/v1/generate/comments

Parameters

Parameter	Type	Required	Default	Description
`post_type`	string	No	`post`	Target post type for comments
`post_ids`	array	No	`[]`	Specific post IDs to comment on. When empty, comments target all published posts of the post type.
`comments_per_post_min`	integer	No	1	Minimum comments per post (1--100)
`comments_per_post_max`	integer	No	15	Maximum comments per post (1--100)
`enable_threading`	boolean	No	`true`	Allow threaded reply chains
`reply_probability`	integer	No	40	Percentage chance a comment becomes a reply (0--100)
`pending_percentage`	integer	No	10	Percentage of comments marked as pending (0--100)
`anonymous_percentage`	integer	No	70	Percentage of comments from anonymous users (0--100)
`avatar_percentage`	integer	No	60	Percentage of commenters that receive downloaded avatars (0--100)
`avatar_provider`	string	No	`unsplash`	Image provider for commenter avatars: `loremflickr`, `unsplash`, `picsum`, or `placeholder`
`locale`	string	No	—	Content locale for comment text. Falls back to the configured default.
`delete_existing`	boolean	No	`false`	Delete all existing WPfaker-generated comments before generating new ones

Example

bash

curl -X POST "https://yoursite.com/wp-json/wpfaker/v1/generate/comments" \
  -H "X-WP-Nonce: your-nonce" \
  -H "Content-Type: application/json" \
  -d '{
    "post_type": "post",
    "comments_per_post_min": 3,
    "comments_per_post_max": 10,
    "enable_threading": true,
    "reply_probability": 40,
    "anonymous_percentage": 70
  }'

Success Response

json

{
  "success": true,
  "count": 47,
  "ids": [201, 202, 203],
  "deleted_count": 0,
  "message": "47 comments generated successfully",
  "time_saved": "20 min"
}

Delete Posts (Chunked)

Delete WPfaker-generated posts with fine-grained control over related content cleanup. This endpoint supports scoped deletion by post type or across all types. It also deletes related CPT posts when cross-CPT relationships exist.

The admin UI uses this endpoint for pre-generation cleanup in chunked workflows.

Endpoint

POST /wp-json/wpfaker/v1/generate/posts/delete

Parameters

Parameter	Type	Required	Default	Description
`post_type`	string	Yes	—	Post type slug to delete
`delete_scope`	string	No	`current_type`	Scope: `current_type` (single post type) or `all` (all generated posts)
`delete_related_media`	boolean	No	`false`	Also delete attached media
`delete_related_terms`	boolean	No	`false`	Also delete taxonomy terms created during generation
`delete_related_authors`	boolean	No	`false`	Also delete author accounts created during generation
`delete_related_comments`	boolean	No	`false`	Also delete generated comments
`delete_related_cpts`	boolean	No	`false`	Also delete related CPT posts linked through cross-CPT relationships

Example

bash

curl -X POST "https://yoursite.com/wp-json/wpfaker/v1/generate/posts/delete" \
  -H "X-WP-Nonce: your-nonce" \
  -H "Content-Type: application/json" \
  -d '{
    "post_type": "property",
    "delete_related_media": true,
    "delete_related_terms": true,
    "delete_related_cpts": true
  }'

Success Response

json

{
  "success": true,
  "deleted_count": 25,
  "deleted_stats": {
    "posts": 25,
    "media": 25,
    "terms": 12,
    "authors": 0
  },
  "deleted_related_cpts": {
    "agent": 5
  },
  "message": "Deleted 25 posts"
}

Generate Posts (Streaming)

Generate posts with real-time progress updates via Server-Sent Events (SSE). This endpoint accepts the same parameters as Generate Posts but returns a stream of log events instead of a single JSON response.

The admin UI uses this endpoint to display live generation progress.

Endpoint

POST /wp-json/wpfaker/v1/generate/posts/stream

Parameters

Same as Generate Posts.

Response Format

The response uses text/event-stream content type. Each event is a JSON object on a data: line.

Progress events arrive during generation:

data: {"type":"info","message":"Generating post 1 of 10..."}
data: {"type":"info","message":"Downloaded featured image for post 101"}
data: {"type":"warning","message":"Image download failed for post 102, skipping"}

Final event contains the full generation result:

data: {"type":"complete","result":{"success":true,"count":10,"ids":[101,102,103],"message":"10 post generated successfully","warnings":[],"variation_stats":{},"auto_created":{},"time_saved":"30 min"}}

Error Responses

All generation endpoints return consistent error responses when something goes wrong. Here are the most common error scenarios.

Invalid Post Type

Returned when the post_type parameter refers to a post type that is not registered on the current WordPress installation.

json

{
  "success": false,
  "code": "invalid_post_type",
  "message": "Post type 'invalid' does not exist"
}

Invalid Taxonomy

Returned when the taxonomy parameter refers to a taxonomy that is not registered.

json

{
  "success": false,
  "code": "invalid_taxonomy",
  "message": "Taxonomy 'invalid_tax' does not exist"
}

Count Out of Range

Returned when the count parameter exceeds the allowed maximum for the content type.

json

{
  "success": false,
  "code": "invalid_count",
  "message": "Count must be between 1 and 500"
}

Insufficient Permissions

Returned when the authenticated user does not have the manage_options capability.

json

{
  "success": false,
  "code": "rest_forbidden",
  "message": "You do not have permission to perform this action"
}

Generation Failed

Returned when an unexpected server-side error occurs during the generation process.

json

{
  "success": false,
  "code": "generation_failed",
  "message": "Generation failed: insufficient memory to process 100 posts with images"
}

TIP

If you encounter generation_failed errors when generating large batches, try reducing the count parameter or disabling image downloads. Image processing is the most memory-intensive part of the generation pipeline. You can also increase PHP's memory_limit and max_execution_time settings on the server.

Generation API ​

Generate Posts ​

Endpoint ​

Parameters ​

Example: Basic Post Generation ​

Example: Using a Saved Template ​

Example: Using Inline Field Config ​

Example: Pre-Generation Cleanup ​

Success Response ​

Generate Terms ​

Endpoint ​

Parameters ​

Example: Flat Term List ​

Example: Hierarchical Categories ​

Success Response ​

Generate Users ​

Endpoint ​

Parameters ​

Example: Random Roles ​

Example: Specific Role ​

Success Response ​

Delete Generated Content ​

Endpoint ​

Parameters ​

Example: Delete Specific Posts ​

Example: Delete All Generated Users ​

Example: Delete All Generated Comments ​

Success Response ​

Generate Comments ​

Endpoint ​

Parameters ​

Example ​

Success Response ​

Delete Posts (Chunked) ​

Endpoint ​

Parameters ​

Example ​

Success Response ​

Generate Posts (Streaming) ​

Endpoint ​

Parameters ​

Response Format ​

Error Responses ​

Invalid Post Type ​

Invalid Taxonomy ​

Count Out of Range ​

Insufficient Permissions ​

Generation Failed ​

Generation API

Generate Posts

Endpoint

Parameters

Example: Basic Post Generation

Example: Using a Saved Template

Example: Using Inline Field Config

Example: Pre-Generation Cleanup

Success Response

Generate Terms

Endpoint

Parameters

Example: Flat Term List

Example: Hierarchical Categories

Success Response

Generate Users

Endpoint

Parameters

Example: Random Roles

Example: Specific Role

Success Response

Delete Generated Content

Endpoint

Parameters

Example: Delete Specific Posts

Example: Delete All Generated Users

Example: Delete All Generated Comments

Success Response

Generate Comments

Endpoint

Parameters

Example

Success Response

Delete Posts (Chunked)

Endpoint

Parameters

Example

Success Response

Generate Posts (Streaming)

Endpoint

Parameters

Response Format

Error Responses

Invalid Post Type

Invalid Taxonomy

Count Out of Range

Insufficient Permissions

Generation Failed